16 KiB
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/*, site/src |
npm run typecheck, npm run typecheck:site, npm run lint, npm run lint:site, npm run check:design |
CI quality |
| 테스트 위생·계약 | node 스크립트 | 모든 테스트·로케일·DS 컴포넌트 | npm run test:hygiene, npm run check:protected-tests, npm run test:quality, npm run check:i18n, npm run check:ds-contract |
CI quality |
| 단위 | Vitest | apps/desktop/tests/{unit,main,shared,renderer}, apps/web/tests, packages/{core,api-client,i18n,ui}/__tests__ |
npm run test (또는 npm run test:affected) |
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 스크립트)의 소유자를 지정한다.
- 이 파일의 단정 삭제·약화·skip 은 사람 승인 없이 금지(
05 §2의 '보호' 다운그레이드). — 2026-11-08부터npm run check:protected-tests가 이를 기계적으로 막는다(§6). - 새 수용 계약이 필요하면 이 목록에 추가하고 이 문서 §4 에 근거를 남긴다
(
scripts/ci/check-protected-tests.mjs의PROTECTED_FILES도 같은 커밋에서). - 여정이 바뀌면 먼저 "왜 사용자가 하는 일이 바뀌었는가"를 커밋 본문에 적는다. 테스트만 고치지 않는다.
커밋 본문의
allow-protected-change: <사유>가 게이트를 통과시키는 유일한 경로다(사람 리뷰 대체 아님).
6. 게이트와 명령
# 커밋 전 (빠름)
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 ~ 2026-11-13, 07-revamp-plan.md Phase 0–5):
| 게이트 | 명령 | 막는 것 |
|---|---|---|
| 보호 수용 무결성 | 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) 증가 (미추적 신규 테스트 파일 포함) |
| i18n 계약 | npm run check:i18n (+ :test) |
12개 로케일 키 집합·{placeholder} 불일치, 빈 값, 코드 내 미존재 t('literal') 키, 미참조 고아 키 임계치 초과(<= 35) |
| DS 계약 | npm run check:ds-contract (+ :test) |
packages/ui DS 컴포넌트 barrel export 누락, 대화형 컴포넌트 ARIA/role 계약 누락, ds-contract.test.tsx 미참조 |
| 영향 선택 실행 | npm run test:affected (+ :test) |
변경 파일 기반 워크스페이스/스위트 선택 실행 (매핑 미스 시 전체 스위트 폴백; CI는 항상 전체 실행) |
| 설치본 스모크 | npm run release:installer:smoke (+ :test) |
릴리스 산출물(.exe, .blockmap, latest.yml, Ed25519 .sig, app.asar, 렌더러 HTML/에셋, 네이티브 ABI) 누락·불일치 |
| 지표 | 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 류)
// 하드코딩된 개발 머신 경로, 앱당 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([]) // 아무 것도 증명하지 않는 단정
})
보호되는 형태
// 격리된 앱, 사용자 표면(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-testfixture 와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 항목)