test(infra): gate protected acceptance tests and ratchet test quality (TDD 2.0 Phase 1)

docs/tdd-red/07-revamp-plan.md Phase 1 — v1.1이 문서로만 선언한 것을 게이트로 옮긴다.

보호 수용 경로 게이트 (check-protected-tests.mjs):
- 06 §5 의 보호 6경로를 base revision 과 비교한다.
- 실패 조건: 테스트/스텝 블록 감소, expect 감소, .only 추가, skip/todo 추가,
  보호 파일 삭제.
- 정당한 스펙 변경은 커밋 본문 `allow-protected-change: <사유>` 또는 --reason 으로만
  통과한다(사람 리뷰 대체 아님). CI quality 잡이 --base HEAD^ 로 실행하며
  체크아웃이 depth 2 로 바뀐다. 얕은 클론에서는 SKIP 사유를 출력한다.

품질 래칫 (check-test-quality.mjs + test-quality-baseline.json):
- 파일별 weak-assertion(toBeDefined/toBeTruthy/toBeFalsy/toBeNull)과
  ambient-time(Date.now/Math.random/performance.now) 수치를 동결하고 증가만 막는다.
- 128 / 203 건을 한 번에 고치지 않고 회귀만 차단한다. --update 는 리뷰 후 실행.

배선: verify:all 에 두 게이트 편입, CI quality 잡 단계 추가,
map/02 §10 · tdd-red/06 §5·§6 · 07 Phase 0-1 상태 갱신.

검증:
- self-test: check-protected-tests 6케이스, check-test-quality 6케이스 통과
- 실제 약화 주입 시 두 게이트가 exit 1 (smoke.spec.ts .only, 약한 단정 추가) 후 원복
- npm run test:hygiene / check:design GREEN, npm test GREEN (2800+605+31+24)
This commit is contained in:
Yun Chan 2026-11-08 21:11:12 +09:00
parent 42583cc96b
commit d3d6f34bfa
9 changed files with 658 additions and 22 deletions

View file

@ -1,7 +1,7 @@
# 02 — Repository & Infrastructure Map
> Surface: whole repo
> Last updated: 2026-11-04 — Wave 4 toolchain/CI map reconciliation; Windows 1.16.1 release evidence remains unchanged
> Last updated: 2026-11-08 — TDD 2.0 Phase 0-1 gates (test metrics, protected acceptance, quality ratchet) added to CI quality
> Source of truth for: layout, workspaces, build/test commands, CI/CD, Docker, deploy, scripts, resources
---
@ -259,6 +259,11 @@ Version sync is enforced by `scripts/ci/sync-version.mjs` and `verify-release-me
- `resources/icons/` — empty; electron-builder falls back to `build/icon.ico|png`.
- Desktop tests: `apps/desktop/tests/` — `unit/`, `main/`, `red/`, `shared/`, `integration/`, `eval/` run under Vitest; `e2e/` holds Playwright specs plus the shared `e2e/support/electron-app.ts` fixture (per-test temp user-data dir). Artifacts in `apps/desktop/test-results/`.
- Test taxonomy + hygiene gate: `docs/tdd-red/06-repo-application.md`. `npm run test:hygiene` (+ `:test`) rejects `.only`, reason-less `.skip()`, trivial assertions, `isVisible()`-gated assertions, machine-specific paths, `waitForTimeout`, and `.e2e.test.ts` names; wired into CI `quality`.
- Test-system gates (TDD 2.0 Phase 0-1, 2026-11-08):
- `npm run test:metrics` / `test:metrics:write` — suite/file/case/assertion counts plus weak-assertion and ambient-time totals; writes `docs/tdd-red/metrics/<date>.md`. Metric only, never fails.
- `npm run check:protected-tests` (+ `:test`) — `scripts/ci/check-protected-tests.mjs` diffs the six protected acceptance specs (`06 §5`) against a base revision and fails when tests, assertions, or `.only`/`.skip` change without an `allow-protected-change:` commit marker. CI runs it against `HEAD^` (the quality job fetches depth 2).
- `npm run test:quality` (+ `:test`, `:update`) — ratchet over `scripts/ci/test-quality-baseline.json`: per-file weak-assertion and ambient-time counts may only go down. `--update` is a reviewed action.
- Shared file-detection helpers live in `scripts/ci/lib/test-files.mjs` so all three gates see the same test files.
- Mobile tests: `apps/mobile-rn/__tests__/` (57 suites / 353 tests per mobile SSOT), `.maestro/` + `.maestro-output/` E2E evidence. Note: a full parallel Jest run can hit the 5s render timeout on slow machines; re-run the failing spec in isolation before treating it as a regression.
- Web tests: `apps/web/tests/` (vitest pure-logic contracts: billing catalog, Web Push client, web STT client — now part of root `npm test`) and `apps/web/e2e/` (playwright: `smoke.spec.ts` owns the unauthenticated surface contract; billing/payple/dashboard/history are fixture-based browser journeys). Web declares its own `@playwright/test` + `vitest` devDeps (2026-11-04) instead of relying on the desktop workspace's hoisted copies.
- API tests: `apps/api-server.Tests/` (xUnit).

View file

@ -19,7 +19,7 @@
| `04-long-scenarios.md` | RED를 **긴 시나리오**(행위 사양)로 재구성 | 핵심 산출물 3 |
| `05-framework.md` | 실행 프레임워크: 제어 루프·AGENTS.md·체크리스트·게이트 | 핵심 산출물 4 |
| `06-repo-application.md` | **이 저장소 적용본**: 계층·경로·명령·게이트·삭제/통폐합 기록 | 실행 정본 |
| `07-revamp-plan.md` | **v2.0 개편 계획**: v1.1이 문선만 선언한 것(보호경로·강도·결정성·i18n 계약·영향 선택)을 게이트로 옮기는 Phase 0~5 | 실행 계획(미실행) |
| `07-revamp-plan.md` | **v2.0 개편 계획**: v1.1이 문서로만 선언한 것(보호경로·강도·결정성·i18n 계약·영향 선택)을 게이트로 옮기는 Phase 0~5 | Phase 0·1 완료 / 2~5 계획 |
| `SOURCES.md` | 100개 정보 항목(약 94 외부) + 1차 소스 14개 | 증거 자료실 |
---
@ -75,7 +75,8 @@ docs/tdd-red/
├── 04-long-scenarios.md
├── 05-framework.md
├── 06-repo-application.md ← 이 저장소 경로·명령·게이트 (실행 정본)
├── 07-revamp-plan.md ← v2.0 개편 계획 (Phase 0~5, 미실행)
├── 07-revamp-plan.md ← v2.0 개편 계획 (Phase 0·1 완료)
├── metrics/ ← test-metrics 기준선 (날짜별, 게이트 아님)
└── SOURCES.md (100개 정보 항목: 약 94 외부 출처)
└── 레드팀 검증 → `scratch/tdd-red/redteam/01~05*.md` (5방면)
```

View file

@ -125,8 +125,11 @@ apps/web/e2e/smoke.spec.ts
규칙:
0. 저장소 루트 `CODEOWNERS` 가 이 경로들(와 `docs/tdd-red/`, hygiene 스크립트)의 소유자를 지정한다.
1. 이 파일의 **단정 삭제·약화·skip** 은 사람 승인 없이 금지(`05 §2`의 '보호' 다운그레이드).
2. 새 수용 계약이 필요하면 이 목록에 추가하고 **이 문서 §4 에 근거를 남긴다.**
— 2026-11-08부터 `npm run check:protected-tests` 가 이를 **기계적으로 막는다**(§6).
2. 새 수용 계약이 필요하면 이 목록에 추가하고 **이 문서 §4 에 근거를 남긴다**
(`scripts/ci/check-protected-tests.mjs` 의 `PROTECTED_FILES` 도 같은 커밋에서).
3. 여정이 바뀌면 먼저 "왜 사용자가 하는 일이 바뀌었는가"를 커밋 본문에 적는다. 테스트만 고치지 않는다.
커밋 본문의 `allow-protected-change: <사유>` 가 게이트를 통과시키는 유일한 경로다(사람 리뷰 대체 아님).
---
@ -135,6 +138,11 @@ apps/web/e2e/smoke.spec.ts
```bash
# 커밋 전 (빠름)
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:metrics:write
# 통합 전 (워크스페이스)
npm run verify:all
@ -156,6 +164,17 @@ npm run test:e2e --workspace=@d3ro/web
`e2e/` 밖의 `*.spec.ts`, 단정이 한 줄도 없는 테스트 파일.
규칙을 늘릴 때는 `--self-test` 에 unsafe/safe fixture 를 **함께** 추가한다(오탐 방지).
TDD 2.0 에서 추가된 게이트 (2026-11-08, `07-revamp-plan.md` Phase 0–1):
| 게이트 | 명령 | 막는 것 |
|---|---|---|
| 보호 수용 무결성 | `npm run check:protected-tests` (`--base <rev>`) | 보호 여정의 테스트·단정 감소, `.only`·`skip` 추가 — `allow-protected-change:` 커밋 마커 없이는 실패 |
| 품질 래칫 | `npm run test:quality` | 파일별 **약한 단정**(`toBeDefined/toBeTruthy/toBeFalsy/toBeNull`)과 **ambient 시계/난수**(`Date.now/Math.random/performance.now`) 증가 |
| 지표 | `npm run test:metrics[:write]` | 아무것도 막지 않는다. 추세 기록용(`docs/tdd-red/metrics/`) |
세 게이트는 테스트 파일 판정을 `scripts/ci/lib/test-files.mjs` 한 곳에서 공유한다.
`test:quality` 기준선은 `scripts/ci/test-quality-baseline.json` 이며 `npm run test:quality:update` 로만 갱신한다(사람 리뷰).
> 데스크톱 E2E 는 CI 러너에 X 디스플레이가 없어 상시 잡으로 돌리지 않는다. 릴리스 전 로컬/Windows 러너에서 돌린다.
> (이 저장소 규칙: 에이전트 서브셸에서 Electron GUI 를 백그라운드 실행하지 않는다.)

View file

@ -68,7 +68,7 @@
| 스크립트 | 역할 | 최초 규칙 |
|---|---|---|
| `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-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` |
@ -91,12 +91,17 @@
- 산출: `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 1 — 집행 수단 1: 보호경로·품질 래칫 (✅ 완료 2026-11-08)
- `scripts/ci/check-protected-tests.mjs` — 보호 6경로 diff 검사:
테스트/스텝 블록 감소 · `expect` 감소 · `.only` 추가 · `skip/todo` 추가 → 실패.
정당한 변경은 커밋 본문 `allow-protected-change: <사유>` 또는 `--reason` 으로만 통과.
CI `quality` 잡이 `--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 (2~3일)
- `packages/i18n/__tests__/locale-contract.test.ts`: 12로케일 키 집합 동일, `{placeholders}` 정합, 값이 비어있지 않음.
@ -128,15 +133,16 @@
## 5. 게이트 커맨드 (개편 후 최종형)
```bash
# 커밋 전 (목표 < 90초)
# 커밋 전 (목표 < 90초) — Phase 0·1 반영
npm run test:hygiene:test && npm run test:hygiene
npm run check:protected-tests
npm run test:affected
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
npm run test:metrics:check # 약한 단정/고아 키 임계치
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
@ -172,9 +178,11 @@ npm run test:acceptance:web
## 8. 완료 정의 (v2.0)
- [ ] Phase 0~2 완료: 보호경로·i18n·DS 게이트가 CI에서 실제로 빨강을 낸다(자기검증 fixture 포함)
- [x] Phase 0 완료: 지표 기준선(`docs/tdd-red/metrics/2026-11-08.md`) + `test:metrics`
- [x] Phase 1 완료: 보호경로·품질 래칫이 실제로 빨강을 낸다(self-test 6+6 케이스)
- [ ] Phase 2 완료: i18n·DS 계약 게이트가 CI에서 실제로 빨강을 낸다
- [ ] `test:affected` 로컬 중앙값 < 60초
- [ ] 핵심 6모듈 뮤테이션 점수 기준선 + 추세 기록
- [ ] 보호 6경로가 릴리스 태그에서 실행되고 증거가 남는다
- [ ] `docs/tdd-red/00`~`06`이 실행 결과와 일치(문서-코드 드리프트 0) — `06 §8` 갱신 규칙 준수
- [ ] `docs/map/02-infrastructure.md` §테스트 인프라 행 갱신
- [~] `docs/tdd-red/00`~`06`이 실행 결과와 일치 — `06 §5·§6` 갱신 완료, §2/§4는 Phase 2 에서
- [x] `docs/map/02-infrastructure.md` §10 테스트 인프라 행 갱신 (Phase 0·1 게이트)