tomevault-io 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(영어)
중요 - 기존 문서 처리:
- 기존 문서가 있다면 완전히 삭제하고 새로 생성
- 과거 내용은 참고하지 않음 (오직 테스트 파일 케이스만 참고)
- 항상 깨끗한 상태에서 시작
주요 규칙
필수 단계
- 설정 파일 먼저 읽기 -
playwright.config.ts와package.json에서 추출 - 브라우저 탐색 - Playwright MCP로 실제 테스트
- 새 문서 생성 - 기존 문서 삭제 후 새로 생성
- 기존 테스트 검증 - 테스트 파일 케이스 읽어 중복 방지
- 이중 언어 출력 - 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 테스트로 구현할 수 있습니다.
실행
위 가이드라인에 따라 작업을 시작하세요.
Converted and distributed by TomeVault — claim your Tome and manage your conversions.