Commandtypescript

/e2e-ui-research Command

Research UI E2E test targets and generate test scenario documentation

View Source

UI E2E Test Research Command

Prerequisites

  • ✅ Frontend server must be already running
  • ✅ Playwright MCP server must be running

User Input

$ARGUMENTS

Consider any additional context from user input (if not empty). Port and base URL will be extracted from playwright.config.ts.

Overview

This command performs comprehensive UI E2E test research including actual browser exploration via Playwright MCP.

Key Features

  • 🎭 Actual Browser Exploration: Direct app manipulation via Playwright MCP
  • 📊 Codebase Analysis: Static analysis to understand routes and components
  • 🔄 Bilingual Documentation: Simultaneous Korean/English version generation
  • 🧠 Business Domain Understanding: Backend analysis for domain context
  • 📝 Always Create Fresh: Delete existing docs and create completely new ones

Execution Steps

1. Preparation and Context Gathering

Detect Project Type and Configuration

Read playwright.config.ts (or .js) and package.json together:

From playwright.config.ts:

  • Base URL and port (from webServer.url or use.baseURL)
  • Test directory location (from testDir or testMatch)
  • Browser configuration and test settings

From package.json (in same directory as playwright.config.ts):

  • Framework detection via dependencies: next, react, vue, svelte, @angular/core, etc.
  • Build tools: vite, webpack, turbopack, etc.
  • This is more reliable than inferring from webServer command

Fallback (if playwright.config not found):

  • Analyze package.json dependencies and scripts
  • Check directory patterns to infer framework

AI should use both files together for accurate project understanding.

Understand Backend Business Domain (if applicable)

Detect Backend Presence:

  • Backend-related directories (e.g., backend/, server/, api/, or similar)
  • Server frameworks in package.json (Express, Fastify, NestJS, etc.)
  • Backend services in docker-compose.yml

AI should flexibly identify backend components regardless of specific naming conventions.

Analyze Project:

  • README.md: Project overview, architecture
  • CLAUDE.md: Domain knowledge, business rules
  • REST API or GraphQL API endpoints (if backend exists)
  • Data models (if backend exists)
  • OpenAPI/Swagger docs (if exists)

Information to Gather:

  • Main domain entities (User, Product, Order, etc.)
  • Core business flows (ordering, payment, auth, etc.)
  • Permission model (RBAC, ABAC)
  • External service integrations

2. Analyze Existing UI E2E Test Files (For Context Only)

Use playwright.config.ts to locate test files:

  • Read testDir or testMatch from playwright.config to find test location
  • If config specifies patterns, use those (e.g., tests/e2e/**/*.spec.ts)
  • Fallback: If not found in config, search with Glob (**/*.e2e.{ts,tsx,js,jsx}, e2e-ui/**/*, e2e/**/*)

Analyze existing tests:

  • Read existing test case descriptions (describe/test/it) all to understand coverage
  • Understand test patterns and structure
  • Important: Do NOT read existing docs (docs/e2e-ui/test-targets.md) - will delete and recreate

3. Static Codebase Analysis

Frontend Structure Analysis:

  • Find route definitions with Glob (adapt patterns to project structure)
    • Examples (not exhaustive):
      • Next.js: app/**/page.{ts,tsx}, pages/**/*.{ts,tsx}
      • React Router: src/routes/**/*.{ts,tsx}, src/pages/**/*.{ts,tsx}
      • Other frameworks: Analyze directory structure and adapt accordingly
  • Read main page components
  • Map user flows and interactions
  • List main UI components and features

AI should flexibly explore the codebase based on detected framework and project structure.

4. 🎭 Playwright MCP Actual Browser Exploration (Required)

This is the most important step! Code analysis alone cannot reveal actual user experience.

Get base URL from playwright.config.ts:

  • Read webServer.url or use.baseURL to get the application URL
  • Extract port number from the URL
  • If not found in config, ask user to provide base URL

4.1 Initial Access and Basic Structure Understanding

// MCP tool usage example (use URL from playwright.config.ts)
browser_navigate: {baseURL from config}
browser_snapshot: Capture initial page DOM structure
  • Analyze main page structure
  • Identify navigation menu elements
  • List main links and buttons

4.2 Major Page Traversal

Based on route list identified from code:

// For each page (use baseURL from playwright.config.ts)
browser_navigate: {baseURL}/{route}
browser_snapshot: Capture page DOM structure
  • Identify interactive elements on each page (buttons, links, forms, dropdowns)
  • Check dynamic elements (modals, toasts, dialogs)
  • Understand navigation flow between pages

4.3 User Flow Experiments

Simulate main workflows:

// Example: Login flow
browser_click: "login button selector";
browser_type: ("email input", "test@example.com");
browser_type: ("password input", "password123");
browser_click: "submit button";
browser_wait_for: "dashboard loaded";
browser_snapshot: "after login state";

Flows to Explore:

  • Login/logout (if exists)
  • CRUD operations (create, read, update, delete)
  • Form submission and validation
  • Modal/dialog interactions
  • Search and filtering
  • Pagination
  • File upload (if exists)

Capture snapshots at each step to record state changes

4.4 Edge Case Exploration

  • Empty state: UI when no data
  • Loading state: During network requests
  • Error state: Validation failures, API errors
  • Unauthorized page access
  • Invalid input handling
  • Long text, special character input

4.5 Responsive and Accessibility Check (briefly)

  • Various viewport sizes (mobile, tablet, desktop)
  • Keyboard navigation availability
  • Focus state verification

🐛 Bug Discovery Handling Guidelines

Important: Even if bugs are found during Playwright MCP browser exploration:

❌ DON'T:

  • Report bugs or provide feedback to user
  • Suggest bug fixes
  • Suggest bug workarounds in test scenarios

✅ DO:

  • Write scenarios for buggy features as they should work normally
  • Include "currently broken but should work" features in test targets
  • Bugs will be naturally discovered and fixed during UI E2E test execution phase

Reason:

  • Research phase is for defining "what to test"
  • Bug discovery and fixing proceeds in execution phase
  • Test scenarios should be complete even with bugs (TDD mindset)

5. Define Test Scenarios

Integrate Code Analysis + Browser Exploration Results:

Mark source for each scenario:

  • 📊 Found via code analysis
  • 🎭 Found via browser exploration
  • 📊🎭 Found via both

6. Verify Against Existing Tests

After defining test scenarios, cross-check with existing E2E tests:

  • Compare defined scenarios with existing test cases (describe/test/it)
  • Identify duplicates or overlapping coverage
  • Mark scenarios as:
    • ✨ New scenario (not covered)
    • ✅ Already implemented (skip or note in docs)
    • 🔄 Partial coverage (extend existing test)

This prevents duplicate test implementation and helps identify coverage gaps accurately.

Prioritize (Critical/High/Medium):

Critical: Core functionality where failure breaks the app

  • User authentication
  • Main feature workflows
  • Data integrity operations

High: Important features used frequently

  • Secondary workflows
  • Common user interactions
  • UI component behaviors

Medium: Nice-to-have features

  • Visual regression
  • Performance checks
  • Accessibility tests

Each Scenario Should Include:

  1. Clear Description: What is being tested
  2. Source: 📊 Code Analysis | 🎭 Browser Exploration
  3. Coverage Status: ✨ New | ✅ Already Implemented | 🔄 Partial
  4. Test Steps: Detailed user actions
  5. Expected Results: What should happen
  6. Verification Points: What to check with MCP tools
  7. Priority Level: Critical/High/Medium
  8. Dependencies: Required setup or previous tests

7. Generate Completely Fresh Bilingual Documentation

Files to Create:

  • docs/e2e-ui/test-targets.ko.md (Korean)
  • docs/e2e-ui/test-targets.md (English)

Document Synchronization:

  • Content identical except language
  • Code examples, technical terms identical on both sides
  • Language switch links at top of file

Important - Existing Document Handling:

  • If existing docs exist, completely delete and recreate
  • Do not reference past content (only reference test file cases)
  • Always start from clean slate

Key Rules

Required Steps

  1. Read configuration first - Extract from playwright.config.ts and package.json:

    • Base URL and port (webServer.url or use.baseURL)
    • Test directory (testDir or testMatch)
    • Framework (from package.json dependencies: next, react, vue, etc.)

  2. Browser exploration - Use Playwright MCP for actual testing (code analysis alone misses UX issues)

  3. Fresh documentation - Delete existing docs and create new ones. Do not merge with old content.

  4. Verify against existing tests - Read test file cases (describe/test/it) to prevent duplicates

  5. Bilingual output - Generate both ko.md and .md versions

Guidelines

Do:

  • Use values from playwright.config.ts (not hardcoded URLs)
  • Adapt flexibly to project structure
  • Group scenarios by page/feature
  • Include both happy paths and error cases
  • Mark source (📊 code analysis, 🎭 browser) and coverage status

Avoid:

  • Skipping configuration file reading
  • Referencing old docs (create fresh)
  • Reporting bugs during research (save for execution phase)
  • Vague or untestable scenarios
  • Single language documentation

🎯 Test Scenario Quality

Each scenario should include:

  1. Clear Description: What is being tested
  2. Source: 📊 Code Analysis | 🎭 Browser Exploration
  3. Coverage Status: ✨ New | ✅ Already Implemented | 🔄 Partial
  4. Test Steps: Detailed user actions
  5. Expected Results: What should happen
  6. Verification Points: What to check with MCP tools
  7. Priority Level: Critical/High/Medium
  8. Dependencies: Required setup or previous tests

Document Template

Korean Version: docs/e2e-ui/test-targets.ko.md

# UI E2E Test Targets

[**한국어**](./test-targets.ko.md) | [English](./test-targets.md)

> **Created**: {YYYY-MM-DD HH:mm}
> **Research Method**: Code Analysis + Playwright Browser Exploration

---

---

## 📊 Current Coverage Analysis

### Existing UI E2E Tests

- `{test-file-1}`: {what it covers}
- `{test-file-2}`: {what it covers}

### Codebase Analysis

- **Framework**: {React/Next.js/Vue/etc}
- **Main Routes**: {X count}
- **Components**: {Y count}

### 🎭 Playwright Browser Exploration Results

- **Pages Explored**: {Z count}
- **User Flows Found**: {W count}
- **Interactive Elements**: {V count}
- **Testable Edge Cases**: {U count}

### Coverage Gaps

- {gap 1}
- {gap 2}

---

## 🎯 Test Scenarios by Priority

### Critical Priority

#### Test 1: {scenario name}

**Source**: 📊 Code Analysis | 🎭 Browser Exploration

**Page/Feature**: {page name or feature area}

**Description**: {what this test verifies}

**Test Steps**:

1. {step 1}
2. {step 2}
3. {step 3}

**Expected Results**:

- {expected result 1}
- {expected result 2}

**Verification Points** (Playwright MCP):

- `browser_snapshot`: {DOM elements to check}
- `browser_take_screenshot`: {what to verify via screenshot}

**Priority**: Critical

**Dependencies**: {none / previous test N}

---

#### Test 2: {scenario name}

{same structure}

---

### High Priority

#### Test 3: {scenario name}

{same structure}

---

### Medium Priority

#### Test 4: {scenario name}

{same structure}

---

## 🔧 Technical Considerations

### Playwright MCP Tools

- **Navigation**: `browser_navigate`
- **Interaction**: `browser_click`, `browser_type`, `browser_select_option`
- **Verification**: `browser_snapshot`, `browser_take_screenshot`
- **Waiting**: `browser_wait_for`

### Test Environment

- **Base URL**: {from playwright.config.ts - webServer.url or use.baseURL}
- **Test Directory**: {from playwright.config.ts - testDir or testMatch}
- **Required Services**: {backend, database, etc}

### Test Data

- {required test accounts (by role)}
- {required sample data}
- {external service mocking requirements}

---

## 🚨 Cautions

- {known bugs or unstable behaviors}
- {environment-specific considerations}
- {performance-related cautions}

---

## 📋 Test Implementation Order

Recommended execution order (considering dependencies):

1. Test N: {name} (Critical - no dependencies)
2. Test M: {name} (Critical - depends on Test N)
3. Test K: {name} (High - no dependencies)
   ...

English Version: docs/e2e-ui/test-targets.md

Same structure as Korean version, content translated to English.

Language links at top of file:

[한국어](./test-targets.ko.md) | [**English**](./test-targets.md)

Completion Report

After research completion, provide summary to user:

## UI E2E Test Research Complete

### 📊 Findings

- **Framework**: {React/Next.js/Vue/etc}
- **Pages Explored**: {X count}
- **User Flows Found**: {Y count}
- **Existing UI E2E Tests**: {Z count}

### 🎯 Test Scenarios

- **Critical**: {N count}
- **High**: {M count}
- **Medium**: {K count}
- **Total**: {N+M+K count}

### 📝 Generated Documents

- `docs/e2e-ui/test-targets.ko.md` (Korean)
- `docs/e2e-ui/test-targets.md` (English)

### 🔍 Coverage Gaps

- {main gap 1}
- {main gap 2}

### Next Steps

You can implement test scenarios as actual Playwright tests with `/e2e-ui:execute` command.

Execute

Start working according to the guidelines above.