분석과 설계

테스트를 작성하기 전에 두 질문에 답해야 합니다. 무엇을 검증할 것인가, 그리고 어떻게 검증할 것인가입니다. 앞은 /3-analyze-target이 받고, 뒤는 /4-design-suite가 받습니다. 두 phase의 산출물이 docs/design/e2e-spec.md와 .claude/state/e2e-suite-config.json에 기록되고, 그 위에서 /5-implement-suite가 실행됩니다.

/3-analyze-target 무엇을 검증할지

대상 시스템을 식별하고 크리티컬 플로우를 끌어내 e2e-spec.md의 §1과 §2에 적습니다. 묻는 것은 네 가지입니다.

• 이름과 한 줄 설명입니다. 무엇을 하는 앱인지 적습니다.
• 타겟 종류입니다. web, electron, mobile 중 하나 이상을 고릅니다.
• 접근법입니다. 배포 URL인지, 로컬 dev server 명령(npm run dev → :5173)인지, 빌드 바이너리 경로인지, Expo나 RN이나 네이티브 빌드인지 정합니다.
• 테스트 환경입니다. 로컬, 스테이징, 전용 테스트 중 하나를 고릅니다. 운영 환경은 거부하고 스테이징으로 유도합니다(S6).

진행 방식(user-pace.json)이 novice면 한 번에 하나씩 묻고, experienced면 묶어서 묻습니다.

크리티컬 플로우는 “이게 안 되면 사업이 멈추는 사용자 흐름”입니다. 35개를 끌어내되 우선순위를 매기고, 먼저 자동화할 12개를 smoke 후보로 표시합니다. 각 플로우는 “누가, 무엇을 하면, 어떤 결과” 한 줄로 적습니다. 이 한 줄이 나중에 테스트 한 개가 됩니다. 플로우를 과하게 늘리지 않는 것이 중요합니다. 치명적인 것부터 잡고 나머지는 spec §9에 미정으로 둡니다.

자격증명 값은 여기서 받지 않습니다(S2). 실제 키는 사용자가 .env.test.local에 직접 넣습니다.

/4-design-suite 어떻게 검증할지

세 가지를 정합니다. 타겟별 도구, 인증과 환경 전략, CI 전략입니다.

타겟별 도구

§1의 타겟 종류별로 도구를 고릅니다. 추천 기본값은 web=Playwright, electron=Playwright _electron, mobile=Maestro입니다. mobile은 앱 종류로 한 번 더 나뉩니다. Expo면 Maestro, RN bare면 Detox나 Maestro, 네이티브면 XCUITest나 Espresso, Capacitor면 Ionic E2E를 씁니다. 도구별 세부 사항은 tracks에 있습니다.

인증과 환경 전략

인증 재사용 방식을 정합니다. web은 storageState, mobile은 사전 로그인 subflow, electron은 세션 주입입니다. 매 테스트마다 UI로 로그인하면 느리고 불안정해서 1회 로그인 후 재사용이 기본입니다.

테스트 데이터는 local-reset(로컬 리셋), test-db(전용 스테이징, 고유 ID), none 중에서 고릅니다. 어느 쪽이든 운영 환경 DB는 금지입니다(S6). mobile이면 디바이스를 ios-sim, android-emu, cloud-farm 중에서 고릅니다.

대상 시스템의 스택에 따른 주의점도 여기서 안내됩니다. Supabase면 세션이 localStorage에 들어가므로 REST 로그인 후 globalSetup 주입 패턴을 권하고, Stripe 결제면 Hosted Checkout이 cross-origin이므로 webhook과 Test Clocks로 검증하는 패턴을 권합니다.

CI 전략

GitHub Actions 워크플로를 만들지 정합니다. web은 브라우저를 매번 설치하고 샤딩과 blob 머지를 씁니다. electron은 OS 매트릭스를 쓰되 Linux 잡만 xvfb로 감쌉니다. mobile은 android-emulator-runner나 simctl, Maestro Cloud를 씁니다. 로컬만 쓸 예정이면 만들지 않습니다. 구현 세부 사항은 ci에 있습니다.

e2e-suite-config.json

결정은 즉시 저장됩니다. 각 답이 바로 e2e-suite-config.json에 기록되고, implement-* 스킬과 /2-setup-base가 이 필드명을 그대로 읽습니다.

{
  "targets": ["web"],
  "tools": {
    "web": "playwright",
    "electron": "playwright-electron",
    "mobile": "maestro"
  },
  "auth_strategy": "storageState",
  "database_strategy": "local-reset",
  "devices": { "mobile": ["android-emu"] },
  "ci": {
    "provider": "github-actions",
    "web_sharding": true,
    "electron_xvfb": true,
    "mobile_runner": "emulator"
  },
  "decided_at": "<ISO>"
}

선택하지 않은 트랙의 tools 키는 생략하거나 무시합니다. 같은 phase를 다시 부르면 결정 파일이 이미 있을 때 유지할지 변경할지를 먼저 재확인합니다. 재실행해도 안전합니다.

ADR은 되돌리기 어려운 결정에만

추천 기본값을 그대로 받으면 spec 갱신만 합니다. ADR은 추천 외 선택에 답니다. web에서 Cypress를 고르거나, mobile에서 Maestro 대신 Detox나 Appium을 고른 경우입니다. docs/adr/<NNNN>-tool-<track>-<choice>.md에 왜 그 도구인지 한 장을 남깁니다. 사소한 결정까지 ADR로 쌓으면 정말 중요한 결정이 가려집니다.

다음

다음 섹션은 verification입니다. 구현된 스위트를 여섯 관점으로 보는 채점 기준, 금지 패턴, 보안 기준선 S1~S8, 그리고 두 번 막히면 어디로 가는지를 봅니다.