recordingtest/docs/contracts/test-runner.md

Sprint Contract — test-runner

Owner: Generator Depends on: sut-prober, normalizer, player, diff-reporter (all pass) Issue: #8

Goal

5개 PoC 모듈을 엮어 시나리오 일괄 회귀 파이프라인을 제공한다. 한 번의 CLI 호출로: 시나리오 디렉터리 스캔 → player로 각 시나리오 재생 → 결과 저장 파일을 normalizer 적용 → baseline과 diff-reporter로 비교 → 종합 리포트 생성. player/SUT 상호작용은 fake host로 교체 가능해야 단위 테스트가 라이브 SUT 없이 통과한다.

Definition of Done

• Recordingtest.Runner 콘솔 exe — --scenarios <dir> --baselines <dir> --out <dir> [--profile <name>] [--no-launch]
• 시나리오 디렉터리의 모든 *.yaml 을 로드 → 각각 실행 → <out>/<scenario>/ 하위에 산출물 저장
• 각 시나리오 실행 순서: player → normalizer(결과 파일) → diff-reporter(vs baseline)
• 정규화 프로파일 기본 default, --profile로 오버라이드 가능
• <out>/report.json 집계 리포트 스키마: { runAt, total, passed, failed, errored, scenarios: [{ name, status, hunks, checkpointCount, artifactDir }] }
• <out>/report.md 사람용 요약 (pass/fail 표 + 실패 시나리오당 diff 링크)
• Exit code: 0 = all pass, 1 = any fail, 2 = any error
• IPlayerHost를 DI로 주입 가능하게 하여 fake host로 단위 테스트 실행
• xUnit 테스트 ≥ 5:
  • 2개 시나리오(모두 identical) → all pass, exit 0
  • 1개 시나리오가 baseline과 다름 → fail, exit 1, report.json 해당 항목에 hunks ≥ 1
  • 1개 시나리오 player에서 예외 → error, exit 2, artifactDir 생성
  • 빈 시나리오 디렉터리 → exit 0 (total=0)
  • --profile 변경 시 normalizer가 해당 프로파일로 호출됨 확인 (spy)
• dotnet build green, dotnet test all pass
• 고정 sleep 0건 (player 원칙 상속)

Interfaces

• Inputs: 시나리오 디렉터리, baseline 디렉터리, 출력 디렉터리, 정규화 프로파일
• Outputs: <out>/<scenario>/ (체크포인트, 아티팩트), <out>/report.json, <out>/report.md
• Side effects: player host의 입력 전달 (fake 또는 UIA)

Out of scope

• 실제 SUT 실행 안정성 (recorder/player의 몫)
• 병렬 시나리오 실행 (v2)
• CI 통합 (별도 작업)

Evaluation plan

1. dotnet build + dotnet test tests/Recordingtest.Runner.Tests — count passed/failed
2. xUnit 테스트 5개 모두 pass 확인
3. report.json 스키마 검증 (테스트 안에서)
4. grep Thread.Sleep\\| Task.Delay in Runner source → 0건
5. DI 관점: IPlayerHost 생성자 주입 가능 확인
6. CLI exit code 확인 (0/1/2)

Risks

• normalizer의 파일 경로 vs 문자열 API — runner가 바이트 스트림으로 전달할지 파일로 flush 할지 결정 필요
• 체크포인트 처리 복잡도 — v1은 마지막 저장 파일만 diff, 체크포인트 diff는 v2로 연기 가능