d3ro-voice/docs/tdd-red/07-revamp-plan.md
Yun Chan 42583cc96b test(infra): add test-system metrics baseline (TDD 2.0 Phase 0)
docs/tdd-red/07-revamp-plan.md Phase 0 — "측정 없는 개편은 없다"의 첫 단계.
게이트가 아니라 지표다 (05 §9: 커버리지·강도는 지표, 완료 조건 아님).

추가:
- scripts/ci/test-metrics.mjs — 스위트별 파일/케이스/단정/약한 단정/ambient/스킵,
  i18n 로케일 수·키 수를 markdown 또는 JSON 으로 산출 (--write 로 날짜 문서 생성)
- scripts/ci/lib/test-files.mjs — 테스트 파일 판정·계수 공용 헬퍼
  (test:hygiene 과 같은 패턴을 쓰도록 한 곳에 모음)
- docs/tdd-red/metrics/2026-11-08.md — 오늘 기준선

측정 결과 (기준선):
- 파일 407 · 케이스 3,498 · 단정 8,958
- 약한 단정(toBeDefined/toBeTruthy/toBeFalsy/toBeNull) 128
- ambient 시계/난수(Date.now/Math.random/performance.now) 203
- skip/todo 3 · i18n 2,753키 × 12로케일

문서:
- 07-revamp-plan.md: 상태를 "Phase 0 완료"로 갱신, 측정치를 추정치(3,380/106/169)에서
  실측치로 교정
- REFACTOR_WAVE5_AUDIT.md: Wave 5 감사 결과(실행 입력) 편입

검증: node scripts/ci/test-metrics.mjs --write / --json GREEN,
      npm run test:metrics GREEN
2026-11-08 21:08:35 +09:00

13 KiB
Raw Blame History

07 · TDD 체계 개편 계획 (Plan v2.0)

작성: 2026-11-05 · 갱신: 2026-11-08 · 상태: Phase 0·1 완료 / Phase 2~5 계획 선행 정본: docs/tdd-red/00~06(프레임워크 v1.1, 2026-11-04) · AGENTS.md §3 · .claude/skills/refactor-wave/SKILL.md 본 문서는 v1.1을 폐기하지 않는다. v1.1이 문서로만 선언한 것을 측정·게이트·자동화로 승격하는 계획이다.


1. 현행 체계 (2026-11 현재 실측)

축 현재 정본
원칙 5축(행위·단정·실패이유·결정성·의도) + 12 패턴 / 10 안티패턴 02
실행 2계층(내부 루프 RED→GREEN→REFACTOR · 외부 GATE=VERIFY+REVIEW+DONE) 05 §1
TRIAGE 변경별 RED 면제/필수 선별표 05 §7
위생 게이트 npm run test:hygiene (8규칙 + --self-test) scripts/ci/check-test-hygiene.mjs
포트폴리오 정적/단위/서비스통합/계약/E2E 4계층, E2E는 임계 여정 6파일 06 §2, §5
통합 게이트 npm run verify:all + CI 5잡(quality/build/mobile/edge/api) package.json, .forgejo/workflows/ci.yml
보호 경로 CODEOWNERS 6경로 06 §5

측정된 규모 (docs/tdd-red/metrics/2026-11-08.md, npm run test:metrics): 테스트 파일 407 · 케이스 3,498 · 단정 8,958 (desktop 2,075 / core 547 / mobile 509 / edge 263 / web 46 / api-client 31 / xUnit 27) · 약한 단정 128 · ambient 시계/난수 203 · skip/todo 3 · i18n 2,753키 × 12로케일.

현재 게이트 전부 GREEN — typecheck, lint(--max-warnings=0), test:hygiene, contract/version/design.


2. 진단 — "문서는 있는데 강제되지 않는 것" 10개

# 갭 실측 증거 결과
G1 보호 경로가 문서와 코드에서 다르고, 게이트가 없다 05 §2/06 §5는 tests/acceptance/**를 보호경로라 하지만 실제 보호 대상은 apps/*/tests/e2e/*.spec.ts. grep -rn "tests/acceptance" scripts/ci → 0. CODEOWNERS는 존재하나 CI 검사 없음 에이전트가 보호 여정의 단정을 약화·삭제해도 초록
G2 결함-검출 강도 지표 없음 커버리지 설정 1개(apps/desktop/vitest.config.ts → src/main/services/** 한정), 실행·게이트 없음. 뮤테이션 도구 미설치(Stryker 없음, 05 §4는 "도입 여부 결정"으로 미결) 단정이 약해져도 알 방법이 없다
G3 약한 단정이 게이트를 통과 toBeDefined()/toBeTruthy()/not.toBeNull() 128건(2026-11-08 실측). hygiene 규칙은 "항상 참"(expect(true))만 막는다 커버리지는 오르고 검출력은 0인 테스트가 합법
G4 결정성 정책 부재 테스트 내 Date.now()/Math.random()/performance.now() 203건, setTimeout 38건. Clock/Random 포트 없음 flaky가 나도 원인 귀속 규칙이 없다
G5 flaky 격리·재시도 정책 없음 CI에 재실행/격리 목록 없음. 05 §8의 "zero-tolerance"는 선언뿐 재현 안 되는 실패가 "그냥 다시 돌리기"로 처리됨
G6 테스트 선택 실행 없음 로컬·CI 모두 전체 스위트. 영향 분석 없음(3,380 케이스) 에이전트 루프가 느려져 TDD 자체가 회피된다
G7 포트폴리오 편중 apps/web 24케이스(페이지 18개, 결제/Payple 흐름 포함) · packages/ui 0 · packages/ui-native 0 · packages/i18n 0 계약(DS/i18n) 계층이 비어 있음
G8 추적성(T-ID)이 문서에만 04-long-scenarios.md의 T-101/T-210 표는 예시. 코드/테스트에 ID 없음, 매트릭스 생성 스크립트 없음 요구 → 테스트 추적 불가. SDD 이점 미확보
G9 계약 테스트가 i18n·디자인 토큰을 안 덮음 2,753키 × 12 로케일. 로케일 parity 검사 없음(수동 sync 스크립트가 값까지 하드코딩), 고아 후보 798 번역 누락/드리프트가 조용히 배포
G10 보호 여정이 CI에서 실행되지 않음 데스크톱 E2E는 러너 X 디스플레이 없음 → 릴리스 전 로컬 수동(06 §6) "보호"가 실제로는 "미실행"

한 줄 결론: v1.1은 사양으로는 충분하고, 집행 수단이 없다. 그래서 2.0의 주제는 "새 원칙"이 아니라 **"원칙을 스크립트로 옮기기"**다.


3. 개편 목표 구조 (v2.0)

2계층 루프는 유지하고, 외부 GATE에 4개 기둥을 추가한다.

[SPEC]  수용 시나리오(+T-ID) ── 보호 경로
   │
[내부 루프] RED → GREEN → REFACTOR          ← 로컬, test:affected 로 60초 이내
   │
[GATE]
  ├─ VERIFY   : affected 스위트 + typecheck + lint + hygiene          (기존)
  ├─ CONTRACT : 보호경로 무결성 + i18n parity + DS 토큰 계약           (신규 ★)
  ├─ STRENGTH : 증분 뮤테이션(핵심 도메인) + 약한 단정 0               (신규 ★)
  ├─ REVIEW   : 테스트 diff 먼저, 약화/삭제/스킵/무관변경 탐지          (기존)
  └─ DONE     : 결정적 통과 + flaky 재시도 3회 규칙                     (강화 ★)

3-1. 신규 스크립트 (모두 --self-test 동반 = test:hygiene 패턴 준수)

스크립트 역할 최초 규칙
scripts/ci/check-protected-tests.mjs 보호 경로 diff 검사 (a) 보호 파일에서 it/test 개수 감소 시 실패 (b) expect( 감소 시 실패 (c) .skip/.only 추가 시 실패 (d) 커밋 본문/PR 라벨에 allow-protected-change: 마커 + 사유가 없으면 실패
scripts/ci/check-test-hygiene.mjs 확장 규칙 2개 추가 weak-assertion(toBeDefined/toBeTruthy/not.toBeNull 만 있는 테스트 블록), ambient-time(테스트에서 무주입 Date.now()/Math.random() — 허용 목록: 시드 계산·vi.setSystemTime 직전)
scripts/ci/check-i18n-contract.mjs 로케일 계약 키 집합 동일성(12개), t('…') 리터럴이 ko에 존재, 고아 키 리포트(게이트 아님 → 임계치 초과 시 실패)
scripts/ci/check-ds-contract.mjs DS 계약 packages/ui DS 컴포넌트가 role/aria 최소 계약을 export하고 테스트가 참조하는지
scripts/ci/test-metrics.mjs 지표 산출(게이트 아님) 스위트별 케이스/시간/약한 단정/flaky 후보/뮤테이션 점수 → docs/tdd-red/metrics/YYYY-MM-DD.md
scripts/ci/run-affected-tests.mjs 영향 선택 실행 변경 파일 → 워크스페이스·테스트 디렉터리 매핑 후 해당 스위트만 실행(안전 기본값: 매핑 실패 시 전체)

3-2. 측정 항목 (게이트 아닌 지표, 05 §9 정합)

  • 결함-검출력: 증분 뮤테이션 점수(핵심 도메인만)
  • flaky율: 3회 재실행 불일치 수
  • 리드타임: test:affected 소요(목표 < 60초), CI full suite 소요
  • 약한 단정 잔량(파일 단위 추세)
  • 보호경로 무결성 위반 수(0 유지)

4. 로드맵 (Phase 0~5)

Phase 0 — 기준선 (✅ 완료 2026-11-08)

  • scripts/ci/test-metrics.mjs (+ 공용 헬퍼 scripts/ci/lib/test-files.mjs) 작성.
  • 산출: docs/tdd-red/metrics/2026-11-08.md — 파일 407 · 케이스 3,498 · 단정 8,958 · 약한 단정 128 · ambient 203 · i18n 2,753키×12.
  • Exit 충족: 지표 문서 + npm run test:metrics / test:metrics:write 등록.

Phase 1 — 집행 수단 1: 보호경로·위생 (2~3일)

  • check-protected-tests.mjs (+ self-test fixture: 약화/삭제/skip/정당한 변경 4케이스)
  • hygiene 규칙 weak-assertion, ambient-time 추가 + self-test fixture 동시 추가(06 §8)
  • 기존 106건은 파일 단위 점진 정리: 신규/수정 파일만 0 강제(--changed 모드) → 3주 내 전량.
  • CI quality 잡에 두 게이트 추가.
  • Exit: 보호 파일을 일부러 약화한 PR이 CI에서 빨강, 정당한 변경은 마커로 통과.

Phase 2 — 집행 수단 2: 계약·i18n·DS (2~3일)

  • packages/i18n/__tests__/locale-contract.test.ts: 12로케일 키 집합 동일, {placeholders} 정합, 값이 비어있지 않음.
  • check-i18n-contract.mjs: 코드의 t('literal') 키 존재 검사 + 고아 리포트(임계치: 신규 고아 0).
  • packages/ui/__tests__/ds-contract.test.tsx: DS 컴포넌트별 role/aria 최소 계약(스냅샷 금지, 06 §3 정합).
  • scripts/ci/sync-i18n-locales.mjs 정리: 하드코딩 번역값을 locales/*.json으로 이동, --check만 남김.
  • Exit: 로케일 키 하나를 지우면 CI 빨강. i18n 고아 수가 지표로 고정.

Phase 3 — 피드백 속도: 영향 선택 실행 (1주)

  • run-affected-tests.mjs + npm run test:affected.
  • 매핑 규칙: packages/core/** → core+desktop+web+mobile / apps/desktop/src/main/** → --mode service / renderer → renderer+E2E(spec 선택) / server/** → deno / apps/mobile-rn/** → jest.
  • 안전장치: 매핑 미스 시 전체 실행, CI는 항상 full.
  • Exit: 로컬 affected 실행 < 60초(중앙값), CI full 유지.

Phase 4 — 강도: 증분 뮤테이션 + 결정성 포트 (1~2주)

  • Clock/Random 포트를 packages/core에 추가(생성자/옵션 주입, 기본값은 실제 시계) → 신규 테스트는 주입 사용.
  • Stryker(또는 vitest-mutation 계열) 도입을 desktop main/services + packages/core 핵심 모듈로 한정, PR에서는 변경 파일 증분만, nightly는 전체.
  • 대상 도메인(사용자·돈·보안): license, billing/plan-catalog, ads, dictionary-policy, entitlement, transcript-correction.
  • Exit: 해당 6개 모듈 뮤테이션 점수 기준선 기록, 목표 ≥ 60% (게이트 아닌 리포트).

Phase 5 — 보호 여정의 실제 실행 (1주, 인프라)

  • release.yml 태그 잡에 Windows 러너 E2E(test:acceptance:desktop) 추가, 실패 시 릴리스 중단.
  • 웹은 E2E_NO_SERVER=1 스모크 + Payple 계약 스펙을 CI 잡으로.
  • 설치 산출물 스모크(설치 → 기동 → 여정 1개) — R7 런타임 게이트와 연결.
  • Exit: 보호 6경로가 태그 릴리스에서 실제 실행되고 결과가 릴리스 증거에 남는다.

5. 게이트 커맨드 (개편 후 최종형)

# 커밋 전 (목표 < 90초)
npm run test:hygiene:test && npm run test:hygiene
npm run check:protected-tests
npm run test:affected

# PR / 통합
npm run verify:all                    # 기존
npm run check:i18n && npm run check:ds-contract
npm run test:metrics:check            # 약한 단정/고아 키 임계치

# 야간
npm run test:mutation -- --full

# 릴리스 전
npm run test:acceptance:desktop       # Windows 러너 또는 로컬(GUI 세션)
npm run test:acceptance:web

6. 하지 않을 것 (비목표)

  • 커버리지 퍼센트 게이트 도입 금지 (05 §9: 커버리지는 지표, 게이트 아님).
  • E2E 확대 금지 — 여전히 임계 여정 3~5개 + 웹 스모크(06 §4).
  • 스냅샷/픽셀 비교 도입 금지(이 저장소에 시각 회귀 인프라 없음).
  • .NET/Deno/모바일 Jest에 뮤테이션 적용 금지(05 §4 명시 제외 유지).
  • 테스트를 통과시키기 위한 리팩터 금지 — 약화 발견 시 테스트 보강 또는 스펙 재합의만.

7. 리스크와 완화

리스크 완화
새 게이트가 기존 3,380 테스트를 대량으로 빨강으로 만든다 Phase 1의 weak-assertion/ambient-time은 변경 파일 한정으로 시작, baseline 파일 목록을 docs/tdd-red/metrics/에 동결
보호경로 게이트가 정당한 스펙 변경을 막는다 allow-protected-change: 마커 + 사유 요구(사람 리뷰), 마커 사용 이력은 월 1회 리뷰
뮤테이션 도구가 느려 개발 루프를 막는다 PR은 증분·핵심 6모듈만, nightly 전체, 내부 루프에서 제외(05 §4)
영향 선택 실행이 회귀를 놓친다 매핑 미스 = 전체 실행, CI는 항상 full, packages/** 변경은 광범위 매핑
i18n 고아 798 삭제가 런타임 키를 지운다 동적 키(t(\settings.${x}`)`) 화이트리스트를 게이트에 내장, 삭제는 Wave 5 G5와 분리

8. 완료 정의 (v2.0)

  • Phase 0~2 완료: 보호경로·i18n·DS 게이트가 CI에서 실제로 빨강을 낸다(자기검증 fixture 포함)
  • test:affected 로컬 중앙값 < 60초
  • 핵심 6모듈 뮤테이션 점수 기준선 + 추세 기록
  • 보호 6경로가 릴리스 태그에서 실행되고 증거가 남는다
  • docs/tdd-red/00~06이 실행 결과와 일치(문서-코드 드리프트 0) — 06 §8 갱신 규칙 준수
  • docs/map/02-infrastructure.md §테스트 인프라 행 갱신