UI E2E 테스트 리서치 커맨드

필수 전제 조건

• ✅ 프론트엔드 서버가 이미 실행 중이어야 함
• ✅ Playwright MCP 서버가 실행 중이어야 함

사용자 입력

$ARGUMENTS

추가 컨텍스트가 있으면 고려합니다 (비어있지 않은 경우). 포트와 base URL은 playwright.config.ts에서 추출됩니다.

---

개요

이 커맨드는 Playwright MCP를 통한 실제 브라우저 탐색을 포함한 종합적인 UI E2E 테스트 리서치를 수행합니다.

핵심 특징

• 🎭 실제 브라우저 탐색: Playwright MCP로 애플리케이션 직접 조작
• 📊 코드베이스 분석: 정적 분석으로 라우트 및 컴포넌트 파악
• 🔄 이중 언어 문서: 한국어/영어 버전 동시 생성
• 🧠 비즈니스 도메인 파악: 백엔드 분석으로 도메인 컨텍스트 이해
• 📝 항상 새로 생성: 기존 문서는 삭제하고 완전히 새로운 문서 생성

---

실행 단계

1. 사전 준비 및 컨텍스트 수집

프로젝트 타입 및 설정 감지

playwright.config.ts (또는 .js)와 package.json 함께 읽기:

playwright.config.ts에서:

• Base URL 및 포트 (webServer.url 또는 use.baseURL에서)
• 테스트 디렉토리 위치 (testDir 또는 testMatch에서)
• 브라우저 설정 및 테스트 설정

package.json에서 (playwright.config.ts와 같은 디렉토리):

• dependencies를 통한 프레임워크 감지: next, react, vue, svelte, @angular/core 등
• 빌드 도구: vite, webpack, turbopack 등

2. 기존 UI E2E 테스트 파일 분석 (컨텍스트 파악용)

playwright.config.ts를 사용하여 테스트 파일 찾기:

• playwright.config에서 testDir 또는 testMatch를 읽어 테스트 위치 찾기
• config에서 패턴을 지정한 경우 해당 패턴 사용 (예: tests/e2e/**/*.spec.ts)
• 폴백: config에서 찾을 수 없는 경우, Glob으로 검색

기존 테스트 분석:

• 기존 테스트 케이스 설명(describe/test/it) 전부 읽어서 커버리지 이해
• 테스트 패턴 및 구조 파악
• 중요: 기존 문서(docs/e2e-ui/test-targets.md)는 읽지 않음 (삭제 후 새로 생성)

3. 코드베이스 정적 분석

프론트엔드 구조 분석:

• Glob으로 라우트 정의 찾기 (프로젝트 구조에 맞게 패턴 조정)
• 주요 페이지 컴포넌트 읽기
• 사용자 플로우 및 상호작용 매핑
• 주요 UI 컴포넌트 및 기능 목록화

4. 🎭 Playwright MCP 실제 브라우저 탐색 (필수)

이 단계가 가장 중요합니다! 코드 분석만으로는 실제 사용자 경험을 알 수 없습니다.

playwright.config.ts에서 base URL 가져오기:

• webServer.url 또는 use.baseURL을 읽어 애플리케이션 URL 가져오기
• URL에서 포트 번호 추출
• config에서 찾을 수 없는 경우, 사용자에게 base URL 제공 요청

4.1 초기 접속 및 기본 구조 파악

browser_navigate: {config에서 가져온 baseURL}
browser_snapshot: 초기 페이지 DOM 구조 캡처

• 메인 페이지 구조 분석
• 네비게이션 메뉴 요소 식별
• 주요 링크 및 버튼 목록화

4.2 주요 페이지 순회

코드에서 파악한 라우트 목록을 기반으로:

browser_navigate: {config에서 가져온 baseURL}/{route}
browser_snapshot: 페이지 DOM 구조 캡처

• 각 페이지의 상호작용 가능한 요소 식별
• 동적 요소 확인 (모달, 토스트, 다이얼로그)
• 페이지 간 네비게이션 흐름 파악

4.3 사용자 플로우 실험

주요 워크플로우 시뮬레이션:

• 로그인/로그아웃 (있는 경우)
• CRUD 작업
• 폼 제출 및 유효성 검사
• 모달/다이얼로그 상호작용
• 검색 및 필터링
• 페이지네이션

🐛 버그 발견 시 처리 지침

중요: Playwright MCP로 브라우저 탐색 중 버그를 발견하더라도:

❌ 하지 말 것:

• 사용자에게 버그 보고하거나 피드백
• 버그 수정 제안
• 테스트 시나리오에서 버그 회피 전략 제안

✅ 해야 할 것:

• 버그가 있는 기능도 정상적으로 작동해야 하는 방식대로 시나리오 작성
• "현재는 작동하지 않지만 작동해야 하는" 기능을 테스트 대상에 포함
• 버그는 UI E2E 테스트 실행 단계에서 자연스럽게 발견되고 수정됨

5. 테스트 시나리오 정의

코드 분석 + 브라우저 탐색 결과 통합:

각 시나리오에는 출처 표시:

• 📊 코드 분석으로 발견
• 🎭 브라우저 탐색으로 발견
• 📊🎭 양쪽에서 발견

6. 기존 테스트와 대조 검증

테스트 시나리오를 정의한 후, 기존 E2E 테스트와 교차 확인:

• 정의한 시나리오를 기존 테스트 케이스와 비교
• 시나리오를 다음과 같이 표시:
  • ✨ 새 시나리오 (커버되지 않음)
  • ✅ 이미 구현됨 (건너뛰거나 문서에 기록)
  • 🔄 부분 커버 (기존 테스트 확장)

우선순위 지정 (Critical/High/Medium):

• Critical: 실패 시 앱이 작동하지 않는 핵심 기능
• High: 자주 사용되는 중요 기능
• Medium: 있으면 좋은 기능

7. 이중 언어 문서 완전 새로 생성

생성할 파일:

• docs/e2e-ui/test-targets.ko.md (한국어)
• docs/e2e-ui/test-targets.md (영어)

중요 - 기존 문서 처리:

• 기존 문서가 있다면 완전히 삭제하고 새로 생성
• 과거 내용은 참고하지 않음 (오직 테스트 파일 케이스만 참고)
• 항상 깨끗한 상태에서 시작

---

주요 규칙

필수 단계

1. 설정 파일 먼저 읽기 - playwright.config.ts와 package.json에서 추출
2. 브라우저 탐색 - Playwright MCP로 실제 테스트
3. 새 문서 생성 - 기존 문서 삭제 후 새로 생성
4. 기존 테스트 검증 - 테스트 파일 케이스 읽어 중복 방지
5. 이중 언어 출력 - ko.md와 .md 버전 모두 생성

가이드라인

해야 할 것:

• playwright.config.ts 값 사용 (URL 하드코딩 금지)
• 프로젝트 구조에 유연하게 적응
• 페이지/기능별로 시나리오 그룹화
• 정상 경로와 에러 케이스 모두 포함
• 출처와 커버리지 상태 표시

피해야 할 것:

• 설정 파일 읽기 건너뛰기
• 기존 문서 참고 (새로 생성만)
• 리서치 중 버그 리포트 (실행 단계에서 처리)
• 모호하거나 테스트 불가능한 시나리오
• 단일 언어 문서만 생성

---

완료 보고

리서치 완료 후 사용자에게 요약 제공:

## UI E2E 테스트 리서치 완료

### 📊 발견 사항

- **프레임워크**: {React/Next.js/Vue/etc}
- **탐색한 페이지**: {X개}
- **발견한 사용자 플로우**: {Y개}
- **기존 UI E2E 테스트**: {Z개}

### 🎯 테스트 시나리오

- **Critical**: {N개}
- **High**: {M개}
- **Medium**: {K개}
- **총합**: {N+M+K개}

### 📝 생성된 문서

- `docs/e2e-ui/test-targets.ko.md` (한국어)
- `docs/e2e-ui/test-targets.md` (영어)

### 🔍 커버리지 갭

- {주요 갭 1}
- {주요 갭 2}

### 다음 단계

`/e2e-ui-execute` 커맨드로 테스트 시나리오를 실제 Playwright 테스트로 구현할 수 있습니다.

---

실행

위 가이드라인에 따라 작업을 시작하세요.