kdye2e - E2E 테스트 시나리오 도출 · 실행 · 개선

프로젝트의 레퍼런스 문서와 인수인계서를 기반으로 e2e 시나리오를 체계적으로 도출하고, Playwright로 테스트를 실행한 뒤, 실패 원인을 진단하여 코드를 수정하는 3단계 스킬입니다.

핵심 원칙

1. 추측 금지 — 반드시 레퍼런스/인수인계서를 읽고 시나리오 도출
2. 시나리오 먼저 — 코드 작성 전 시나리오 목록을 사용자에게 확인
3. 실패 → 진단 → 수정 루프 — 테스트 실패 시 자동으로 원인 분석 후 수정 제안
4. 레퍼런스 갱신 — 모든 작업 후 관련 문서를 최신 상태로 유지

인수 처리

사용자가 제공한 인수: $ARGUMENTS

Phase 0: 프로젝트 분석

모든 모드의 사전 단계. 프로젝트 상태를 완전히 파악한 뒤 다음 Phase로 진행.

Step 0-1: 프로젝트 루트 및 스택 확인

pwd
ls -la package.json pyproject.toml next.config.* vite.config.* nuxt.config.* playwright.config.* 2>/dev/null

Step 0-2: Playwright 설치 여부 확인

# package.json에서 playwright 의존성 확인
grep -q "playwright" package.json 2>/dev/null && echo "INSTALLED" || echo "NOT_INSTALLED"

# playwright.config 존재 여부
ls playwright.config.* 2>/dev/null

Playwright 미설치 시 → Phase 0-B로 분기

Step 0-3: 레퍼런스 문서 전량 수집

아래 파일을 반드시 모두 읽고 핵심 정보를 메모리에 로드합니다.

# 레퍼런스 일괄 수집 (존재하는 파일만)
Read CLAUDE.md
Read docs/status/current.md
Read docs/handover/ → 가장 최신 파일
Read docs/references/_API_REFERENCE.md
Read docs/references/_SCHEMA_REFERENCE.md
Read docs/references/_COMPONENT_MAP.md
Read docs/references/_TYPE_REFERENCE.md
Read docs/references/_ENV_REFERENCE.md
Read docs/references/_WEB_CONTRACT.md

Step 0-4: 라우트 구조 스캔

# Next.js App Router
find src/app -name "page.tsx" -o -name "page.ts" 2>/dev/null | sort

# Next.js Pages Router
find src/pages -name "*.tsx" -o -name "*.ts" 2>/dev/null | grep -v "_app\|_document\|api/" | sort

# 미들웨어
ls src/middleware.* middleware.* 2>/dev/null

Step 0-5: 인증 방식 파악

# 인증 관련 파일 탐색
find src -path "*/auth/*" -o -path "*/login/*" -o -name "*auth*" 2>/dev/null | head -20

Step 0-6: 기존 e2e 테스트 확인

# 기존 테스트 파일
find e2e tests/e2e __tests__/e2e -name "*.spec.ts" -o -name "*.test.ts" 2>/dev/null | sort

# 기존 Page Object
find e2e tests -path "*/pages/*" -name "*.ts" 2>/dev/null | sort

Step 0-7: 분석 결과 요약 출력

## 프로젝트 분석 결과

| 항목 | 값 |
|------|-----|
| 기술 스택 | Next.js 15 + Supabase + Tailwind |
| 인증 방식 | Supabase Auth (이메일/소셜) |
| 총 페이지 수 | XX개 (공개 X / 인증 X / 관리자 X) |
| API 엔드포인트 수 | XX개 |
| 핵심 엔티티 | users, posts, comments, ... |
| 사용자 권한 구분 | 게스트 / 일반 / 관리자 |
| 기존 e2e 테스트 | X개 파일 / 미설치 |
| 현재 이슈 (handover) | ... |
| Playwright 상태 | 설치됨 / 미설치 |

Phase 0-B: Playwright 초기 세팅 (미설치 시)

Playwright 미설치 감지 시 자동 분기. --setup 인수로도 강제 실행 가능.

세팅 가이드 참조: Read $GENERAL_PRO/01-dev-rules-system/03-dev-templates/e2e-setup-guide.md

세팅 순서:

1. 패키지 설치

pnpm add -D @playwright/test
npx playwright install --with-deps chromium

2. playwright.config.ts 생성 (세팅 가이드 섹션 4 참조)

3. 디렉토리 구조 생성

e2e/
├── fixtures/
│   ├── base-page.ts
│   ├── fixtures.ts
│   └── test-data.ts
├── pages/
├── auth.setup.ts
└── smoke.spec.ts

4. base-page.ts 복사

소스: $GENERAL_PRO/02-reusable-code/13-testing-patterns/playwright/base-page.ts
대상: e2e/fixtures/base-page.ts

5. fixtures.ts 생성 (세팅 가이드 섹션 5 참조, 프로젝트 인증 방식에 맞게 조정)

6. auth.setup.ts 생성 (Step 0-5에서 파악한 인증 방식 기반)

7. package.json 스크립트 추가

{
  "test:e2e": "playwright test",
  "test:e2e:ui": "playwright test --ui",
  "test:e2e:headed": "playwright test --headed",
  "test:e2e:debug": "playwright test --debug"
}

8. .gitignore 추가

playwright/.auth/
playwright-report/
test-results/
blob-report/

세팅 완료 후 → Phase 1로 진행

Phase 1: 시나리오 도출

Phase 0에서 수집한 레퍼런스 정보를 기반으로 e2e 시나리오를 체계적으로 도출.

Step 1-1: 시나리오 카테고리 분류

5가지 카테고리로 분류하여 도출:

카테고리 A: 스모크 테스트 (P0)

• 소스: _COMPONENT_MAP.md + 라우트 스캔 결과
• 내용: 전체 페이지 접근 가능 + 핵심 요소 렌더링 확인
• 공개 페이지: 비로그인 상태로 접근
• 인증 페이지: storageState로 접근
• 관리자 페이지: admin storageState로 접근

카테고리 B: 인증 플로우 (P0)

• 소스: Step 0-5 인증 분석 + _API_REFERENCE.md 인증 엔드포인트
• 내용:
  • 로그인 성공/실패
  • 로그아웃
  • 비로그인 접근 차단 → 리다이렉트
  • 권한별 접근 제어 (일반 vs 관리자)
  • (있다면) 회원가입, 비밀번호 변경

카테고리 C: 핵심 비즈니스 플로우 (P0)

• 소스: _API_REFERENCE.md CRUD 엔드포인트 + _SCHEMA_REFERENCE.md 핵심 엔티티
• 내용: 사용자 관점의 주요 워크플로우
  • 핵심 엔티티 CRUD (생성 → 조회 → 수정 → 삭제)
  • 사용자 주요 여정 (가입 → 설정 → 핵심기능 → 결과확인)
  • 결제 플로우 (Stripe 등이 있는 경우)

카테고리 D: 에러/엣지 케이스 (P1)

• 소스: _TYPE_REFERENCE.md 입력 경계 + _API_REFERENCE.md 에러 응답
• 내용:
  • 필수값 누락 → 폼 유효성 검사
  • 잘못된 형식 입력
  • 권한 없는 리소스 접근
  • 존재하지 않는 페이지/리소스 (404)

카테고리 E: 반응형/접근성 (P2, 선택)

• 소스: _COMPONENT_MAP.md 레이아웃 분석
• 내용:
  • 모바일 뷰포트 핵심 플로우
  • 키보드 네비게이션

Step 1-2: 시나리오 목록 작성

출력 형식:

## E2E 시나리오 목록

### A. 스모크 테스트 (P0) — X개
| ID | 페이지 | 전제조건 | 검증 항목 |
|----|--------|---------|----------|
| S-01 | / (홈) | - | 히어로 섹션 표시 |
| S-02 | /dashboard | 로그인 | 통계 카드 표시 |
| S-03 | /admin | 관리자 | 관리 메뉴 표시 |

### B. 인증 플로우 (P0) — X개
| ID | 시나리오 | 전제조건 | 테스트 단계 | 기대 결과 |
|----|---------|---------|-----------|----------|
| A-01 | 로그인 성공 | 가입된 계정 | 이메일+비밀번호→로그인 | /dashboard 이동 |
| A-02 | 로그인 실패 | - | 잘못된 비밀번호 | 에러 메시지 |
| A-03 | 접근 차단 | 미인증 | /dashboard 직접 접근 | /login 리다이렉트 |

### C. 핵심 비즈니스 플로우 (P0) — X개
| ID | 시나리오 | 전제조건 | 테스트 단계 | 기대 결과 |
|----|---------|---------|-----------|----------|
| B-01 | [엔티티] 생성 | 로그인 | 폼 입력→저장 | 목록에 표시 |
| B-02 | [엔티티] 수정 | B-01 | 수정→저장 | 변경 반영 |
| B-03 | [엔티티] 삭제 | B-01 | 삭제→확인 | 목록에서 제거 |

### D. 에러/엣지 케이스 (P1) — X개
| ID | 시나리오 | 입력 | 기대 결과 |
|----|---------|------|----------|
| E-01 | 빈 폼 제출 | 필수값 비움 | 유효성 에러 |
| E-02 | 404 페이지 | /nonexistent | 404 페이지 표시 |

### 요약
- P0 (필수): X개 시나리오
- P1 (권장): X개 시나리오
- P2 (선택): X개 시나리오
- 총: X개 시나리오

Step 1-3: 사용자 확인

반드시 사용자에게 시나리오 목록을 보여주고 확인받기.

위 시나리오 목록을 확인해주세요.

1. 전체 승인 → P0부터 테스트 코드 작성
2. P0만 승인 → 스모크+인증+핵심만 작성
3. 수정 요청 → 시나리오 추가/제거/변경

Step 1-4: 테스트 코드 작성

승인된 시나리오를 코드로 변환. 작성 순서:

1. 스모크 테스트 → e2e/smoke.spec.ts
2. 인증 테스트 → e2e/auth/login.spec.ts
3. 비즈니스 플로우 → e2e/[도메인]/[기능].spec.ts
4. 에러 케이스 → e2e/[도메인]/error.spec.ts
5. Page Object → e2e/pages/[페이지]-page.ts (필요 시)

코드 작성 규칙:

• getByRole, getByLabel, getByText 우선 사용 (test-id는 최후 수단)
• 한국어 레이블/텍스트 기반 선택 (실제 UI에 보이는 텍스트)
• 각 테스트는 독립적 (다른 테스트 결과에 의존하지 않음)
• test.describe로 시나리오 카테고리 그룹핑

Step 1-5: 시나리오 상태 파일 기록

docs/references/_E2E_SCENARIOS.md에 시나리오 목록과 상태를 기록:

# E2E 시나리오 레퍼런스

> 최종 업데이트: YYYY-MM-DD
> 총 시나리오: XX개 (통과: X / 실패: X / 미작성: X)

## 시나리오 현황

| ID | 카테고리 | 시나리오 | 파일 | 상태 |
|----|---------|---------|------|------|
| S-01 | 스모크 | 홈 접근 | smoke.spec.ts | ✅ 통과 |
| A-01 | 인증 | 로그인 성공 | auth/login.spec.ts | ✅ 통과 |
| B-01 | 비즈니스 | 항목 생성 | items/crud.spec.ts | ❌ 실패 |
| E-01 | 에러 | 빈 폼 제출 | - | ⬜ 미작성 |

## 커버리지

| 카테고리 | 전체 | 작성 | 통과 | 실패 |
|---------|------|------|------|------|
| 스모크 (P0) | X | X | X | X |
| 인증 (P0) | X | X | X | X |
| 비즈니스 (P0) | X | X | X | X |
| 에러 (P1) | X | X | X | X |
| 반응형 (P2) | X | X | X | X |

Phase 2: 테스트 실행

작성된 테스트를 실행하고 결과를 수집.

Step 2-1: dev 서버 상태 확인

# dev 서버 실행 여부 확인
curl -s -o /dev/null -w "%{http_code}" http://localhost:3000 2>/dev/null || echo "NOT_RUNNING"

dev 서버가 꺼져 있으면:

• playwright.config.ts의 webServer 설정이 있으면 자동 실행됨
• 없으면 사용자에게 안내: pnpm dev를 별도 터미널에서 실행해주세요

Step 2-2: 테스트 실행

# 전체 실행 (headless)
npx playwright test 2>&1

# --smoke 인수인 경우
npx playwright test e2e/smoke.spec.ts 2>&1

Step 2-3: 결과 파싱

실행 결과에서 아래 정보를 추출:

## 실행 결과

| 항목 | 값 |
|------|-----|
| 총 테스트 | XX개 |
| 통과 | XX개 (XX%) |
| 실패 | XX개 |
| 건너뜀 | XX개 |
| 실행 시간 | XX초 |

### 실패 목록
| # | 테스트 | 파일:라인 | 에러 유형 | 에러 메시지 |
|---|--------|----------|----------|-----------|
| 1 | 로그인 성공 | auth/login.spec.ts:15 | TimeoutError | getByLabel('이메일') 찾을 수 없음 |
| 2 | 항목 생성 | items/crud.spec.ts:32 | AssertionError | '테스트 항목' 텍스트 미표시 |

Step 2-4: 결과를 시나리오 상태에 반영

docs/references/_E2E_SCENARIOS.md의 상태 컬럼을 업데이트.

Step 2-5: 분기 판단

• 전체 통과 → Phase 2 완료, 결과 보고
• 실패 있음 → Phase 3으로 진행

Phase 3: 문제점 개선

실패한 테스트를 분석하고 원인을 진단하여 수정.

Step 3-1: 실패 원인 분류

각 실패를 아래 유형으로 분류:

Step 3-2: 실패별 진단

각 실패에 대해:

1. 에러 메시지 분석 — 정확한 실패 지점 파악
2. 스크린샷 확인 (있으면) — test-results/ 디렉토리
3. 소스 코드 확인 — 테스트가 검증하려는 실제 코드 읽기
4. 원인 결정 — 위 유형 중 해당 유형 판정

진단 출력 형식은 references/output-templates.md 참조

Step 3-3: 사용자 확인

수정 계획 출력 형식은 references/output-templates.md 참조

AskUserQuestion으로 수정 범위 선택: 전체/테스트만/개별

Step 3-4: 수정 실행

사용자 승인에 따라:

1. 테스트 코드 수정 — 선택자, 타이밍, 데이터 문제 수정
2. 소스 코드 수정 — 실제 버그/미구현 수정
3. 설정 수정 — 인증/환경 설정 수정

Step 3-5: 재실행

# 실패한 테스트만 재실행
npx playwright test --last-failed 2>&1

Step 3-6: 반복 판단

• 전체 통과 → Step 3-7 결과 보고
• 아직 실패 있음 → Step 3-2로 돌아감 (최대 3회 반복)
• 3회 초과 → 남은 실패를 별도 태스크로 분리하고 결과 보고

Step 3-7: 최종 결과 보고

최종 결과 보고서 형식은 references/output-templates.md 참조

Phase 4: 레퍼런스 갱신

모든 Phase 완료 후 반드시 실행.

갱신 대상

모드별 실행 흐름

/kdye2e (기본)
  Phase 0 → Phase 1 → Phase 2 → Phase 3 → Phase 4

/kdye2e --scenario
  Phase 0 → Phase 1 → Phase 4

/kdye2e --run
  Phase 0 (간소) → Phase 2 → Phase 3 → Phase 4

/kdye2e --fix
  Phase 0 (간소) → Phase 3 → Phase 4

/kdye2e --resume
  Phase 0 (간소) → _E2E_SCENARIOS.md 미완료/실패 로드 → Phase 3 → Phase 4

/kdye2e --setup
  Phase 0 → Phase 0-B → Phase 4

/kdye2e --smoke
  Phase 0 (간소) → Phase 2 (smoke만) → Phase 3 → Phase 4

연쇄 발동 규칙

사용 예시

상세 예시는 references/output-templates.md 참조

/kdye2e                # 전체 흐름
/kdye2e --scenario     # 시나리오만 도출
/kdye2e --run          # 기존 테스트 실행 + 수정
/kdye2e --fix          # 실패 수정만
/kdye2e --resume       # 이전 세션 미완료/실패부터 재개 (--fix 별칭)
/kdye2e --setup        # Playwright 초기 세팅
/kdye2e --smoke        # 스모크 테스트만

Superpowers 연계

이 스킬 실행 중 아래 superpowers 원칙을 적용한다.

관련 스킬/리소스