15 KiB
15 KiB
07 · TDD 체계 개편 계획 (Plan v2.0)
작성: 2026-11-05 · 갱신: 2026-11-13 · 상태: Phase 0~3·5 완료 / Phase 4 결정성 포트 완료(Stryker 미설치 선택) 선행 정본:
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-quality.mjs |
래칫 게이트(파일별 기준선 동결) | weak-assertion(toBeDefined/toBeTruthy/toBeFalsy/toBeNull), ambient-time(무주입 Date.now/Math.random/performance.now). 기준선 scripts/ci/test-quality-baseline.json |
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: 보호경로·품질 래칫 (✅ 완료 2026-11-08)
scripts/ci/check-protected-tests.mjs— 보호 6경로 diff 검사: 테스트/스텝 블록 감소 ·expect감소 ·.only추가 ·skip/todo추가 → 실패. 정당한 변경은 커밋 본문allow-protected-change: <사유>또는--reason으로만 통과. CIquality잡이--base HEAD^로 실행(체크아웃 depth 2). 얕은 클론에서는 SKIP 사유를 출력.scripts/ci/check-test-quality.mjs+scripts/ci/test-quality-baseline.json— 래칫 게이트. 오늘 수치(weak 128 / ambient 203)를 파일별로 동결하고 증가만 막는다.--update는 사람 리뷰 후에만.npm run verify:all에 두 게이트 편입.- Exit 충족:
.only를 보호 여정에 넣으면 CI/로컬이 빨강(수동 검증 완료), 새 약한 단정을 넣으면test:quality가 빨강(수동 검증 완료).
Phase 2 — 집행 수단 2: 계약·i18n·DS (✅ 완료 2026-11-13)
packages/i18n/__tests__/locale-contract.test.ts: 12로케일 2,500키 집합 동일,{placeholders}정합, 값이 비어있지 않음 (15/15 PASS).scripts/ci/check-i18n-contract.mjs(npm run check:i18n+:test): 코드의t('literal')키 존재 검사 + 동적 prefix 화이트리스트 + 고아 상한 게이트(unreferenced=8 <= 35; 253개 죽은 키 정리 완료).packages/ui/__tests__/ds-contract.test.tsx(4/4 PASS) +scripts/ci/check-ds-contract.mjs(npm run check:ds-contract+:test): 13개 DS 컴포넌트 barrel export 및SegmentControl(role="tablist"/role="tab"/aria-selected/키보드Enter·Space),InlineAlert,EmptyState,InstrumentPanel의미 계약 강제.scripts/ci/sync-i18n-locales.mjs정리: 하드코딩 번역값 전부 제거,--check검증 전용으로 전환.- Exit 충족: 로케일 키 삭제·오타 또는 DS ARIA 계약 회귀 시
verify:all및 CIquality빨강(--self-test검증 완료).
Phase 3 — 피드백 속도: 영향 선택 실행 (✅ 완료 2026-11-13)
scripts/ci/run-affected-tests.mjs+npm run test:affected(+ :test).- 매핑 규칙:
packages/core/**→ core+api-client+desktop+web+mobile /packages/i18n/**→ i18n+desktop+web+mobile /packages/ui/**→ ui+desktop+web /apps/desktop/**→ desktop /apps/web/**→ web /apps/mobile-rn/**→ mobile Jest /apps/api-server*/**→dotnet test/site/**→typecheck:site+lint:site. - 안전장치: 매핑 미스 시 전체 스위트 폴백, CI는 항상 full.
- Exit 충족:
--plan/--self-test및 로컬 부분 실행 < 60초 확인, CI full 유지.
Phase 4 — 강도: 결정성 포트 + 증분 뮤테이션 (✅ 결정성 포트 완료 2026-11-13 / Stryker 선택 보류)
packages/core/src/ports.ts(@d3ro/core/ports):Clock,FakeClock,Random,systemClock,systemRandom,createFakeClock,createSeededRandom(seed)추가 및ports.test.ts(4/4 PASS) 고정.scripts/ci/lib/test-files.mjs가git ls-files --cached --others --exclude-standard로 미추적 신규 테스트 파일까지test:quality래칫에 포함하도록 보강.- Stryker 뮤테이션 러너는 lockfile 비대화 및 네이티브 의존성 충돌을 피하기 위해 패키지 설치를 보류하고, 필요 시 별도 로컬/야간 실험 도구로만 검토한다.
Phase 5 — 릴리스 산출물 스모크 및 CI 배선 (✅ 완료 2026-11-13)
scripts/ci/verify-desktop-installer-smoke.mjs(npm run release:installer:smoke+:test, 음성 케이스 8종 포함) 작성 및scripts/ci/release-desktop.mjs·.forgejo/workflows/release.yml배선 (verify-release-metadata.mjs계약 고정)..forgejo/workflows/ci.yml에check:i18n,check:ds-contract,typecheck:site,lint:site,site프로덕션 빌드 추가.- 대화형 Electron GUI 여정(
test:acceptance:desktop)은 Linux CI 러너에 디스플레이가 없어 릴리스 전 로컬/Windows 인터랙티브 게이트로 유지(06 §6).
5. 게이트 커맨드 (개편 후 최종형)
# 커밋 전 (목표 < 90초) — Phase 0·1 반영
npm run test:hygiene:test && npm run test:hygiene
npm run check:protected-tests:test && npm run check:protected-tests
npm run test:quality:test && npm run test:quality
npm run test:affected # Phase 3
# PR / 통합
npm run verify:all # 위 두 게이트 포함
npm run check:i18n && npm run check:ds-contract # Phase 2
npm run test:metrics:write # 지표 스냅샷(게이트 아님)
# 야간
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 완료: 지표 기준선(
docs/tdd-red/metrics/2026-11-08.md→2026-11-13.md) +test:metrics - Phase 1 완료: 보호경로·품질 래칫이 실제로 빨강을 낸다(self-test 6+6 케이스, 미추적 신규 테스트 스캔 포함)
- Phase 2 완료: i18n(
check:i18n+locale-contract.test.ts15/15)·DS(check:ds-contract+ds-contract.test.tsx4/4) 계약 게이트가verify:all·CI에서 실제로 빨강을 낸다 - Phase 3 완료:
test:affected(run-affected-tests.mjs+--self-test) 구현 및 로컬 선택 실행 < 60초 - [~] Phase 4:
@d3ro/core/ports(Clock/Random/FakeClock) 완료; Stryker 뮤테이션 러너는 lockfile 보존을 위해 미설치 유지 - [~] Phase 5:
release:installer:smoke(verify-desktop-installer-smoke.mjs)가release-desktop.mjs·release.yml에 배선됨; 대화형 Electron GUI E2E(test:acceptance:desktop)는 헤드리스 Linux 러너 제약으로 로컬/Windows 릴리스 전 실행 유지 docs/tdd-red/00~06이 실행 결과와 일치 (06 §2·§6갱신 완료)docs/map/02-infrastructure.md§10 테스트 인프라 행 갱신 (Phase 0~5 게이트 및2026-11-13지표 반영)