238 lines
16 KiB
Markdown
238 lines
16 KiB
Markdown
# 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 스크립트)의 소유자를 지정한다.
|
||
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 ~ 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 류)
|
||
|
||
```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 항목)
|