# 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`의 '보호' 다운그레이드). 2. 새 수용 계약이 필요하면 이 목록에 추가하고 **이 문서 §4 에 근거를 남긴다.** 3. 여정이 바뀌면 먼저 "왜 사용자가 하는 일이 바뀌었는가"를 커밋 본문에 적는다. 테스트만 고치지 않는다. --- ## 6. 게이트와 명령 ```bash # 커밋 전 (빠름) npm run test:hygiene:test && npm run test:hygiene # 통합 전 (워크스페이스) 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 를 **함께** 추가한다(오탐 방지). > 데스크톱 E2E 는 CI 러너에 X 디스플레이가 없어 상시 잡으로 돌리지 않는다. 릴리스 전 로컬/Windows 러너에서 돌린다. > (이 저장소 규칙: 에이전트 서브셸에서 Electron GUI 를 백그라운드 실행하지 않는다.) --- ## 7. 예시 — 같은 여정, 다른 품질 ### 삭제된 형태 (red_team_cycle 류) ```ts // 하드코딩된 개발 머신 경로, 앱당 1회만 실행, 조건부 단정 const SCREENSHOT_DIR = 'C:/Users//.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 항목)