# E2e UI Research

> UI E2E 테스트 대상 리서치 및 테스트 시나리오 문서 생성. 프론트엔드 앱을 분석하고 종합적인 E2E 테스트 계획 생성. Use when this capability is needed.

- Skill: `tomevault-io/e2e-ui-research-3` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/e2e-ui-research-3`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/e2e-ui-research-3/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Research & Search
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/e2e-ui-research-3

---


# UI E2E 테스트 리서치 커맨드

## 필수 전제 조건

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

## 사용자 입력

```text
$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 초기 접속 및 기본 구조 파악

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

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

#### 4.2 주요 페이지 순회

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

```javascript
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 하드코딩 금지)
- 프로젝트 구조에 유연하게 적응
- 페이지/기능별로 시나리오 그룹화
- 정상 경로와 에러 케이스 모두 포함
- 출처와 커버리지 상태 표시

**피해야 할 것:**

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

---

## 완료 보고

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

```markdown
## 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](https://tomevault.io/claim/kubrickcode) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-13 -->