d3ro-voice/docs/tdd-red/06-repo-application.md

16 KiB
Raw Permalink Blame History

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. 게이트와 명령

# 커밋 전 (빠름)
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-test fixture 와 02-meaningful-vs-meaningless-red.md 를 함께 갱신한다.
  • 맵 문서(docs/map/10, 11, 02)의 테스트 인프라 행도 같은 커밋에서 갱신한다(AGENTS.md §4).

9. 출처