d3ro-voice/docs/tdd-red/06-repo-application.md
Yun Chan d3d6f34bfa 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)
2026-11-08 21:11:12 +09:00

234 lines
15 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 06 · 이 저장소 적용 — D3RO Voice 테스트 포트폴리오
**목적**: `01`~`05` 는 일반 프레임워크다. 이 문서는 그 프레임워크를 **실제 D3RO Voice 경로·명령·게이트**에 고정한 적용본이다.
새 테스트를 쓰거나 지울 때 이 문서가 맞는지 먼저 본다. (2026-11-04 작성)
---
## 1. 디자인 방법론 선택 (외부 조사 → 이 저장소 적용)
세 축을 조합했다. 하나로는 이 저장소를 덮지 못한다.
| 방법론 | 핵심 주장 | 이 저장소에 적용한 방식 |
|---|---|---|
| **Testing Trophy** (Kent C. Dodds) | "정적 > 단위 > **통합** > E2E" 순으로 투자 대비 신뢰도가 높다. 테스트는 소프트웨어가 쓰이는 방식에 가까울수록 신뢰를 준다. | 정적(TS strict + eslint + 디자인 토큰 검사)을 최하단에 두고, **서비스 단위**보다 **서비스+DB/IPC 경계 통합**(`tests/main`, `tests/red`)에 비중을 둔다. E2E 는 임계 여정만. |
| **Practical Test Pyramid** (Ham Vocke / Martin Fowler) | 계층마다 피드백 속도가 다르다. **E2E 는 최소**, 같은 시나리오를 전 계층에 복제하지 말 것. 경계는 **계약 테스트**로. | Supabase Edge ↔ 앱, `.NET API` ↔ 클라이언트, IPC 채널 타입은 `packages/core` 계약으로 검증. 데스크톱 E2E 는 5개 여정 파일로 축소(§4). |
| **Playwright Best Practices** (Microsoft) | 사용자에게 보이는 행위만 단정, 테스트는 서로 격리, locator 는 role/testid, 진단은 trace. | 공용 픽스처 `tests/e2e/support/electron-app.ts` 가 **테스트마다 새 user-data 디렉터리**를 만들고 창을 띄우고 trace 로 실패를 남긴다. `waitForTimeout`·스크린샷 경로 하드코딩 금지(게이트가 막는다). |
**이 저장소의 좋은 예시 (그대로 따라 쓸 것)**
| 예시 | 무엇이 좋은가 |
|---|---|
| `apps/web/e2e/dashboard-dictionary-commands.spec.ts` | Supabase fixture 사용자 2명(owner/other)으로 RLS 경계까지 검증. 데이터를 직접 시드하고 화면은 사용자 표면만 본다. |
| `apps/desktop/tests/main/db-open-atomic-redteam-r2-1.test.ts` | 결함 재현(회귀 RED) — 원자적 DB open 실패를 먼저 실패로 고정. |
| `apps/desktop/tests/red/ads/admob-ssv.test.ts` | 목업 대신 실제 ECDSA 키쌍으로 서명/위조/변조를 실측. "전부 목" 안티패턴 회피. |
| `apps/desktop/tests/e2e/navigation.spec.ts` | `test.step(route, ...)` 로 실패 지점을 경로명으로 남기고, `aria-current` 라는 사용자 표면만 단정. |
| `apps/mobile-rn/__tests__/e2e-runtime-bootstrap.test.ts` | 경계 입력(릴리스 빌드·LAN 호스트·secret key·iOS)을 표로 열거 — 경계 RED 의 좋은 형태. |
**디자인 시스템 관점**: 이 앱의 UI는 `packages/ui` 의 DS(CRT 계기판)가 SSOT다. 그래서 "디자인 검증"을 스크린샷 비교가 아니라
**토큰/구조 계약**(`npm run check:design`, role·`aria-current`·`aria-selected` 단정)으로 한다. 픽셀 비교는 flaky 비용이 크고,
이 저장소에는 시각 회귀 인프라가 없다. 시각 탐색이 필요한 변경은 `05 §7` 대로 **test-last**(컴포넌트/접근성/E2E 강조)로 처리한다.
> 2026 에이전트 시대의 결론은 "테스트를 먼저 쓰게 프롬프트하기"가 아니라 **"인간이 정한 수용 기준을 완료 게이트로 강제"** 다(`00`, `05 §2`).
> 그래서 이 문서의 산출물은 문서가 아니라 **명령**이다: `npm run test:hygiene`, `npm run verify:all`.
---
## 2. 테스트 포트폴리오 (정본 경로)
| 계층 | 도구 | 경로 | 실행 | 게이트 |
|---|---|---|---|---|
| 정적 | tsc strict, eslint, 디자인 토큰 | `apps/*/src`, `packages/*` | `npm run typecheck`, `npm run lint`, `npm run check:design` | CI `quality` |
| 테스트 위생 | node 스크립트 | 위 패턴의 모든 테스트 파일 | `npm run test:hygiene` (+ `:test` 셀프테스트) | CI `quality` |
| 단위 | Vitest | `apps/desktop/tests/{unit,main,shared,renderer}`, `apps/web/tests`, `packages/*/__tests__` | `npm --prefix apps/desktop run test:unit`, `npm --prefix apps/web run test` | CI `test` |
| 서비스 통합 | Vitest | `apps/desktop/tests/{main,red}` | `npm --prefix apps/desktop run test:service` | CI `test` |
| 계약(E2E-ish, 결정적) | Vitest | `apps/desktop/tests/red/*.test.ts`, `apps/desktop/tests/integration/*.test.ts` | `npm --prefix apps/desktop run test:integration` | CI `test` |
| E2E (데스크톱) | Playwright `_electron` | `apps/desktop/tests/e2e/*.spec.ts` | `npm --prefix apps/desktop run test:e2e` | 로컬/릴리스 전 |
| E2E (웹) | Playwright | `apps/web/e2e/*.spec.ts` | `npm --prefix apps/web run test:e2e` | 로컬/릴리스 전 |
| E2E (모바일) | Maestro + 계약 스크립트 | `apps/mobile-rn/.maestro`, `apps/mobile-rn/__tests__/*.e2e.mjs` | `docs/map/02-infrastructure.md §3` | 로컬/릴리스 전 |
| 모바일 단위 | Jest | `apps/mobile-rn/__tests__/*.test.ts(x)` | `npm run test:mobile` | CI `mobile-quality` |
| API | xUnit | `apps/api-server.Tests/` | `dotnet test` | CI |
| Edge Functions | Deno test | `server/supabase/functions/**/*.test.ts` | `docs/map/02-infrastructure.md §3` | CI `edge-functions` |
**이름 규칙**: E2E(브라우저/Electron)만 `*.spec.ts`. 나머지는 전부 `*.test.ts(x)`.
`.e2e.test.ts` 는 금지다(게이트 `misnamed-e2e`) — Vitest 로 도는 계약 테스트를 E2E 로 오해하게 만든다.
---
## 3. 이 저장소의 의미 있는 RED 기준
`02` 의 5축을 그대로 쓰되, 이 앱에서 관찰 가능한 결과는 다음으로 고정한다.
| 대상 | 관찰 가능한 결과 (단정할 것) | 단정하지 말 것 |
|---|---|---|
| 데스크톱 셸 | `aria-current="page"`, role=navigation, testid(`nav-*`, `settings-tab-*`) | CSS 클래스, 컴포넌트 내부 state |
| 설정 | `role="tab"` 개수 = `SETTINGS_TAB_ORDER.length`, `aria-selected` | MUI 내부 `.MuiTab-root` |
| 온보딩 | dialog 존재, 모드 카드 2개, 온라인 선택 → email/password 입력 노출 | 실제 로그인 성공/실패(백엔드 의존) |
| 서비스 | `EventEmitter` 로 방출된 이벤트, `IPCResult`(success/error code) | 프라이빗 메서드 호출 순서 |
| IPC | `IPC_CHANNELS` 상수와 preload 시그니처 | 문자열 채널 하드코딩 |
| i18n | `t()` 키 집합의 정합(모든 locale) | 특정 언어 문구 하드코딩 |
- 서비스 테스트는 `resetForTest()` 로 싱글톤 상태를 비운 뒤 시작한다(`05 §7`).
- UI 텍스트는 가능한 한 role/testid 로 잡는다. 텍스트가 필요하면 `t()` 키가 아니라 사용자가 보는 결과를 단정한다.
- 회귀(결함 재현)는 RED 정의의 예외다. 버그를 고치기 전에 **실패를 먼저 출력으로 남긴다.**
---
## 4. 삭제·통폐합 기록 (2026-11-04, Wave 기준)
### 4-1. 삭제 (의미 없는 RED / 죽은 테스트)
| 삭제 | 이유 (02 분류) |
|---|---|
| `apps/desktop/tests/e2e/red_team_cycle1,2,3,5.spec.ts` | 비대(#9)·비결정(#8)·인공(#4). 개발 머신 스크린샷 경로, 고정 sleep, 조건부 catch 로 "실패해도 초록". |
| `apps/web/e2e/red_team_cycle4_web.spec.ts` | `smoke.spec.ts` 와 중복(#9). 보호 라우트·/download 계약은 smoke 로 흡수. |
| `apps/desktop/tests/e2e/dashboard.spec.ts` | `navigation.spec.ts` 와 중복(#9). |
| `apps/desktop/tests/e2e/pages_crud.spec.ts` | 이름은 CRUD, 실제로는 "input 이 보인다"만 단정 — 이름이 행위를 속임(#10 설명력). |
| `apps/desktop/tests/e2e/launch_readiness.spec.ts` | 광고 문구("Cursor AI")·개발 머신 경로 의존(#8). 고객지원 계약만 `customer-support.spec.ts` 로. |
| `apps/desktop/tests/e2e/voice_pipeline.spec.ts` | `waitForEvent(...).catch(()=>null)` + `if (window) expect(...)` — 실패 경로가 없다(#1 가짜). |
| `apps/desktop/tests/e2e/onboarding.spec.ts` (구) | v4 온보딩(모드 선택)과 불일치 + `isVisible()` 조건부 단정(#3/#1). 새 계약으로 재작성. |
| `apps/desktop/tests/e2e/history.spec.ts` | 시드 없이 "전체 삭제"를 검증 — 실제로는 아무것도 지우지 않는다(#1). |
| `tests/e2e/*` (루트) | 어떤 설정도 실행하지 않는 고아 사본. 앱 내 스펙과 중복 + .NET API 스펙은 `apps/api-server.Tests` 와 중복. |
| `scripts/e2e-desktop-app.js`, `e2e-desktop-settings.js`, `e2e-desktop-full-journey.js`, `real-app-multi-tab-e2e.js`, `capture-launch-sandbox-e2e.js` | 참조 없는 일회성 스크립트. 하드코딩된 `C:/Users/.../.gemini/...` 스크린샷 경로. Playwright 스펙이 대체. |
| `apps/desktop/run_e2e_cdp.cjs`, `run_e2e_full_suite.cjs` | 수동 CDP 러너. 위 Playwright 스펙이 대체. |
### 4-2. 통폐합
| 이전 | 이후 |
|---|---|
| 9개 스펙에 복붙된 Electron launch/온보딩 우회/창 탐색 | `tests/e2e/support/electron-app.ts` 픽스처 하나 |
| dashboard + navigation | `navigation.spec.ts` (노출 계약 + aria-current 이동) |
| 설정 모달 탭 순회(구 settings) | `settings.spec.ts` (정본 `SETTINGS_TAB_ORDER` import, 딥링크, 탭 전환) |
| onboarding(구) + red_team_cycle5 온보딩 | `onboarding.spec.ts` |
| launch_readiness 고객지원 부분 | `customer-support.spec.ts` |
| history(구) | `records.spec.ts` (새 설치 빈 상태만 — 삭제 흐름은 훅/서비스 테스트가 이미 덮음) |
| web cycle4 + smoke | `apps/web/e2e/smoke.spec.ts` |
| `tests/red/ads/*.e2e.test.ts` | `*.test.ts` (Vitest 계약 테스트임을 이름에 맞춤) |
| 웹 순수 로직 스펙 3개(`billing-catalog`, `web-push`, `web-stt-client`) | `apps/web/tests/*.test.ts` + Vitest. 브라우저가 필요 없는데 Playwright 로만 돌아 **CI 에서 아예 실행되지 않던** 테스트였다. 이제 `npm test` 에 포함. |
| `tests/unit/AdMediationEngine.spec.ts`, `license-open-billing.spec.ts` | `*.test.ts` (Vitest 인데 spec 이름을 쓰던 마지막 2건) |
---
## 5. 보호 수용 경로 (에이전트가 약화·삭제 금지)
임계 여정 5개만 보호한다. 나머지 스펙은 일반 리뷰 대상.
```
apps/desktop/tests/e2e/navigation.spec.ts
apps/desktop/tests/e2e/settings.spec.ts
apps/desktop/tests/e2e/onboarding.spec.ts
apps/desktop/tests/e2e/customer-support.spec.ts
apps/desktop/tests/e2e/records.spec.ts
apps/web/e2e/smoke.spec.ts
```
규칙:
0. 저장소 루트 `CODEOWNERS` 가 이 경로들(와 `docs/tdd-red/`, hygiene 스크립트)의 소유자를 지정한다.
1. 이 파일의 **단정 삭제·약화·skip** 은 사람 승인 없이 금지(`05 §2`의 '보호' 다운그레이드).
— 2026-11-08부터 `npm run check:protected-tests` 가 이를 **기계적으로 막는다**(§6).
2. 새 수용 계약이 필요하면 이 목록에 추가하고 **이 문서 §4 에 근거를 남긴다**
(`scripts/ci/check-protected-tests.mjs` 의 `PROTECTED_FILES` 도 같은 커밋에서).
3. 여정이 바뀌면 먼저 "왜 사용자가 하는 일이 바뀌었는가"를 커밋 본문에 적는다. 테스트만 고치지 않는다.
커밋 본문의 `allow-protected-change: <사유>` 가 게이트를 통과시키는 유일한 경로다(사람 리뷰 대체 아님).
---
## 6. 게이트와 명령
```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
# 보호 수용 경로만 (릴리스 전)
npm run test:acceptance:web # smoke: 인증 없는 표면 계약
npm run test:acceptance:desktop # 5개 보호 여정 (빌드 산출물 + GUI 세션 필요)
# 전체 E2E
npm run build --workspace=@d3ro/desktop
npm run test:e2e --workspace=@d3ro/desktop
# 웹 E2E (서버 없이: E2E_NO_SERVER=1, 대상 지정: E2E_BASE_URL=...)
npm run test:e2e --workspace=@d3ro/web
```
`test:hygiene` 가 막는 것: `.only`, 이유 없는 `.skip()`, 항상 참인 단정, `isVisible()` 조건부 단정,
개발 머신 경로(Antigravity/.gemini/AppData Temp), `waitForTimeout`, `.e2e.test.ts` 오명명,
`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 를 백그라운드 실행하지 않는다.)
---
## 7. 예시 — 같은 여정, 다른 품질
### 삭제된 형태 (red_team_cycle 류)
```ts
// 하드코딩된 개발 머신 경로, 앱당 1회만 실행, 조건부 단정
const SCREENSHOT_DIR = 'C:/Users/<user>/.gemini/antigravity/.../screenshots'
test.beforeAll(async () => { /* launch + 1.5s sleep + reload */ })
test('RT-16: ...', async () => {
if (await navButton.isVisible()) {
await navButton.click()
await window.waitForTimeout(300)
}
expect(uncaughtExceptions).toEqual([]) // 아무 것도 증명하지 않는 단정
})
```
### 보호되는 형태
```ts
// 격리된 앱, 사용자 표면(aria-current), 실패 시 trace
import { expect, expectNoRuntimeErrors, goToRoute, test } from './support/electron-app'
test('각 항목을 누르면 현재 화면 표시가 정확히 하나로 옮겨간다', async ({ mainWindow }) => {
const nav = mainWindow.window.getByRole('navigation')
for (const route of NAV_ROUTES) {
await test.step(route, async () => {
await goToRoute(mainWindow, route)
await expect(nav.locator('[aria-current="page"]')).toHaveCount(1)
})
}
expectNoRuntimeErrors(mainWindow)
})
```
---
## 8. 갱신 규칙
- 테스트 계층/경로/명령이 바뀌면 이 문서 §2 를 먼저 고친다.
- E2E 여정을 추가·삭제하면 §4(이유)와 §5(보호 목록)를 같은 커밋에서 갱신한다.
- `test:hygiene` 규칙을 추가하면 `--self-test` fixture 와 `02-meaningful-vs-meaningless-red.md` 를 함께 갱신한다.
- 맵 문서(`docs/map/10`, `11`, `02`)의 테스트 인프라 행도 같은 커밋에서 갱신한다(`AGENTS.md §4`).
---
## 9. 출처
- Kent C. Dodds, *The Testing Trophy and Testing Classifications* — https://kentcdodds.com/blog/the-testing-trophy-and-testing-classifications
- Ham Vocke / Martin Fowler, *The Practical Test Pyramid* — https://martinfowler.com/articles/practical-test-pyramid.html
- Microsoft, *Playwright Best Practices* — https://playwright.dev/docs/best-practices
- 저장소 내부: `docs/tdd-red/01`~`05`, `docs/tdd-red/SOURCES.md` (2026 RED 원론·증거 94 항목)