playwright-flow-recorder

What this skill does

# Playwright Flow Recorder

Generate Playwright test scripts from natural language scenario descriptions.

## Overview

To create E2E tests from user flow descriptions, this skill translates natural language scenarios into executable Playwright test code with proper assertions, error handling, and best practices.

## When to Use

Use this skill when:
- Converting user stories to E2E tests
- Generating tests from acceptance criteria
- Creating test scripts from flow descriptions
- Translating business requirements into tests
- Documenting user journeys as executable tests
- Building test coverage for critical user paths

## Flow Description Format

### Simple Flow

```
User signs up with email and password
```

### Detailed Flow

```
1. User navigates to signup page
2. User fills in email field
3. User fills in password field
4. User clicks signup button
5. User sees success message
6. User is redirected to dashboard
```

### Acceptance Criteria Format

```
Given: User is on the homepage
When: User clicks "Get Started"
And: User fills in registration form
And: User submits the form
Then: User sees "Welcome" message
And: User is on the dashboard page
```

## Generation Process

### 1. Parse Flow Description

To analyze the scenario, use `scripts/parse_flow.py`:

```bash
python scripts/parse_flow.py --input "user creates entity and adds relationships"
```

The script identifies:
- Actions (navigate, click, fill, select, etc.)
- Elements (buttons, inputs, links, etc.)
- Assertions (sees, redirected, displays, etc.)
- Data inputs (form values, selections, etc.)

### 2. Map to Playwright Actions

To convert parsed steps to Playwright code, use the action mapping:

**Navigation:**
- "navigates to X" → `await page.goto('/x')`
- "clicks X" → `await page.getByRole('button', { name: /x/i }).click()`
- "selects X from Y" → `await page.getByLabel(/y/i).selectOption('x')`

**Form Input:**
- "fills X with Y" → `await page.getByLabel(/x/i).fill('y')`
- "enters X" → `await page.getByLabel(/x/i).fill('x')`
- "types X" → `await page.getByLabel(/x/i).type('x')`

**Assertions:**
- "sees X" → `await expect(page.getByText(/x/i)).toBeVisible()`
- "is redirected to X" → `await expect(page).toHaveURL(/x/)`
- "X displays Y" → `await expect(page.getByRole('x')).toContainText(/y/i)`

### 3. Generate Test Structure

To create the test file, use the template from `assets/test-template.ts`:

```typescript
import { test, expect } from '@playwright/test'

test.describe('Flow Name', () => {
  test.beforeEach(async ({ page }) => {
    // Setup steps
  })

  test('scenario description', async ({ page }) => {
    // Test steps
  })

  test.afterEach(async ({ page }) => {
    // Cleanup steps
  })
})
```

### 4. Add Assertions and Waits

To ensure test reliability, add:
- Explicit waits for dynamic content
- Assertions after state changes
- Error state checks
- Loading state handling

### 5. Generate Data Fixtures

To create test data, use `scripts/generate_fixtures.py`:

```bash
python scripts/generate_fixtures.py --entity character --count 5
```

## Usage Examples

### Example 1: User Signup Flow

**Input Description:**
```
User signs up with email and password, then creates their first project
```

**Generated Test:**
```typescript
import { test, expect } from '@playwright/test'

test.describe('User Signup and Project Creation', () => {
  test('user signs up and creates first project', async ({ page }) => {
    // Navigate to signup page
    await page.goto('/signup')

    // Fill in signup form
    await page.getByLabel(/email/i).fill('[email protected]')
    await page.getByLabel(/password/i).fill('SecurePass123!')
    await page.getByLabel(/confirm password/i).fill('SecurePass123!')

    // Submit signup
    await page.getByRole('button', { name: /sign up/i }).click()

    // Verify success message
    await expect(page.getByText(/welcome|success/i)).toBeVisible()

    // Verify redirect to dashboard
    await expect(page).toHaveURL(/\/dashboard/)

    // Create first project
    await page.getByRole('button', { name: /create project/i }).click()

    // Fill project form
    await page.getByLabel(/project name/i).fill('My First World')
    await page.getByLabel(/description/i).fill('An epic fantasy realm')

    // Submit project
    await page.getByRole('button', { name: /create|save/i }).click()

    // Verify project created
    await expect(page.getByText('My First World')).toBeVisible()
    await expect(page.getByText(/project created/i)).toBeVisible()
  })
})
```

### Example 2: Entity Relationship Flow

**Input Description:**
```
User creates a character entity, then creates a location, and links them with "lives in" relationship
```

**Generated Test:**
```typescript
import { test, expect } from '@playwright/test'

test.describe('Entity and Relationship Creation', () => {
  test('creates character and location with relationship', async ({ page }) => {
    await page.goto('/entities')

    // Create character
    await page.getByRole('button', { name: /create entity/i }).click()
    await page.getByLabel(/name/i).fill('Aria Shadowblade')
    await page.getByLabel(/type/i).selectOption('character')
    await page.getByLabel(/description/i).fill('A skilled rogue')
    await page.getByRole('button', { name: /save|create/i }).click()

    // Verify character created
    await expect(page.getByText('Aria Shadowblade')).toBeVisible()

    // Navigate back to entity list
    await page.getByRole('link', { name: /entities/i }).click()

    // Create location
    await page.getByRole('button', { name: /create entity/i }).click()
    await page.getByLabel(/name/i).fill('Shadowfen City')
    await page.getByLabel(/type/i).selectOption('location')
    await page.getByLabel(/description/i).fill('A dark urban settlement')
    await page.getByRole('button', { name: /save|create/i }).click()

    // Open character details
    await page.getByText('Aria Shadowblade').click()

    // Add relationship
    await page.getByRole('button', { name: /add relationship/i }).click()
    await page.getByLabel(/related entity/i).fill('Shadowfen')
    await page.keyboard.press('ArrowDown')
    await page.keyboard.press('Enter')
    await page.getByLabel(/relationship type/i).selectOption('lives_in')
    await page.getByRole('button', { name: /create|save/i }).click()

    // Verify relationship
    await expect(page.getByText(/lives in.*shadowfen/i)).toBeVisible()
  })
})
```

### Example 3: Timeline Flow

**Input Description:**
```
User creates a timeline, adds three events, and reorders them chronologically
```

**Generated Test:**
```typescript
import { test, expect } from '@playwright/test'

test.describe('Timeline Creation and Management', () => {
  test('creates timeline with events and reorders them', async ({ page }) => {
    await page.goto('/timelines')

    // Create timeline
    await page.getByRole('button', { name: /create timeline/i }).click()
    await page.getByLabel(/name/i).fill('Age of Heroes')
    await page.getByRole('button', { name: /create/i }).click()

    // Verify timeline created
    await expect(page.getByText('Age of Heroes')).toBeVisible()

    // Click to open timeline
    await page.getByText('Age of Heroes').click()

    // Add first event
    await page.getByRole('button', { name: /add event/i }).click()
    await page.getByLabel(/event name/i).fill('The Founding')
    await page.getByLabel(/date/i).fill('Year 0')
    await page.getByRole('button', { name: /save/i }).click()

    // Add second event
    await page.getByRole('button', { name: /add event/i }).click()
    await page.getByLabel(/event name/i).fill('The Great War')
    await page.getByLabel(/date/i).fill('Year 150')
    await page.getByRole('button', { name: /save/i }).click()

    // Add third event
    await page.getByRole('button', { name: /add event/i }).click()
    await page.getByLabel(/event name/i).fill('The Alliance')
    await page.getByLabel(/date/i).fill('Year 75')
    await page.getByRole('butt