Initial commit

.claude-plugin/plugin.json

@@ -0,0 +1,12 @@
+{
+  "name": "playwright-flow-recorder",
+  "description": "Creates Playwright test scripts from natural language user flow descriptions. This skill should be used when generating E2E tests from scenarios, converting user stories to test code, recording user flows, creating test scripts from descriptions like \"user signs up and creates project\", or translating acceptance criteria into executable tests. Trigger terms include playwright test, e2e flow, user scenario, test from description, record flow, user journey, test script generation, acceptance test,",
+  "version": "1.0.0",
+  "author": {
+    "name": "Hope Overture",
+    "email": "support@worldbuilding-app-skills.dev"
+  },
+  "skills": [
+    "./skills"
+  ]
+}

README.md

@@ -0,0 +1,3 @@
+# playwright-flow-recorder
+
+Creates Playwright test scripts from natural language user flow descriptions. This skill should be used when generating E2E tests from scenarios, converting user stories to test code, recording user flows, creating test scripts from descriptions like "user signs up and creates project", or translating acceptance criteria into executable tests. Trigger terms include playwright test, e2e flow, user scenario, test from description, record flow, user journey, test script generation, acceptance test,

plugin.lock.json

@@ -0,0 +1,57 @@
+{
+  "$schema": "internal://schemas/plugin.lock.v1.json",
+  "pluginId": "gh:hopeoverture/worldbuilding-app-skills:plugins/playwright-flow-recorder",
+  "normalized": {
+    "repo": null,
+    "ref": "refs/tags/v20251128.0",
+    "commit": "0b01869052f3e9df0c27d931a6eacc767130ee99",
+    "treeHash": "dd617ec7e9aace93308648eb365af57b6c62a61c51086ddd17964c2041a32c16",
+    "generatedAt": "2025-11-28T10:17:33.943372Z",
+    "toolVersion": "publish_plugins.py@0.2.0"
+  },
+  "origin": {
+    "remote": "git@github.com:zhongweili/42plugin-data.git",
+    "branch": "master",
+    "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390",
+    "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data"
+  },
+  "manifest": {
+    "name": "playwright-flow-recorder",
+    "description": "Creates Playwright test scripts from natural language user flow descriptions. This skill should be used when generating E2E tests from scenarios, converting user stories to test code, recording user flows, creating test scripts from descriptions like \"user signs up and creates project\", or translating acceptance criteria into executable tests. Trigger terms include playwright test, e2e flow, user scenario, test from description, record flow, user journey, test script generation, acceptance test,",
+    "version": "1.0.0"
+  },
+  "content": {
+    "files": [
+      {
+        "path": "README.md",
+        "sha256": "1ab0a616e7476dedb69eedf2c066901e58c5f1a1fa44e0b703af64c78f09c2c1"
+      },
+      {
+        "path": ".claude-plugin/plugin.json",
+        "sha256": "b32a76b3a75bee22a0d35aac5832072ecf1ae74b614dc96d0964e3f64ef71cc3"
+      },
+      {
+        "path": "skills/playwright-flow-recorder/SKILL.md",
+        "sha256": "c80246032182f04e9ca11bff0fb8010917e6e4e662c649b6016ec2f31a8279ab"
+      },
+      {
+        "path": "skills/playwright-flow-recorder/references/playwright-actions.md",
+        "sha256": "92508c5491831282aaddf531ff1e56ecbf559baaeed92c2ad752aef7f4160b57"
+      },
+      {
+        "path": "skills/playwright-flow-recorder/scripts/generate_flow_test.py",
+        "sha256": "09f1f6eed898bb61302d1f230c462d818a08d59397229153f6d43d34b1ea2610"
+      },
+      {
+        "path": "skills/playwright-flow-recorder/assets/test-template.ts",
+        "sha256": "570a69b55d86bcef95db64b3accf237fe3619f14dadb780792350e9620aedd9f"
+      }
+    ],
+    "dirSha256": "dd617ec7e9aace93308648eb365af57b6c62a61c51086ddd17964c2041a32c16"
+  },
+  "security": {
+    "scannedAt": null,
+    "scannerVersion": null,
+    "flags": []
+  }
+}

skills/playwright-flow-recorder/SKILL.md

@@ -0,0 +1,389 @@
+---
+name: playwright-flow-recorder
+description: Creates Playwright test scripts from natural language user flow descriptions. This skill should be used when generating E2E tests from scenarios, converting user stories to test code, recording user flows, creating test scripts from descriptions like "user signs up and creates project", or translating acceptance criteria into executable tests. Trigger terms include playwright test, e2e flow, user scenario, test from description, record flow, user journey, test script generation, acceptance test, behavior test, user story test.
+---
+
+# 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('user@example.com')
+    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('button', { name: /save/i }).click()
+
+    // Verify all events visible
+    await expect(page.getByText('The Founding')).toBeVisible()
+    await expect(page.getByText('The Great War')).toBeVisible()
+    await expect(page.getByText('The Alliance')).toBeVisible()
+
+    // Sort chronologically
+    await page.getByRole('button', { name: /sort/i }).click()
+    await page.getByRole('menuitem', { name: /chronological/i }).click()
+
+    // Verify order
+    const events = page.locator('[data-testid="timeline-event"]')
+    await expect(events.nth(0)).toContainText('The Founding')
+    await expect(events.nth(1)).toContainText('The Alliance')
+    await expect(events.nth(2)).toContainText('The Great War')
+  })
+})
+```
+
+## Advanced Features
+
+### Authentication Flows
+
+To handle authentication, use the setup from `references/auth-patterns.md`:
+
+```typescript
+test.describe('Authenticated Flow', () => {
+  test.use({ storageState: 'auth.json' })
+
+  test('user performs action', async ({ page }) => {
+    // Test steps with authenticated user
+  })
+})
+```
+
+### API Mocking
+
+To mock API responses, use Playwright's route handlers:
+
+```typescript
+test('displays entities from API', async ({ page }) => {
+  await page.route('**/api/entities', route => {
+    route.fulfill({
+      status: 200,
+      body: JSON.stringify([
+        { id: '1', name: 'Test Entity' }
+      ])
+    })
+  })
+
+  await page.goto('/entities')
+  await expect(page.getByText('Test Entity')).toBeVisible()
+})
+```
+
+### Error Scenarios
+
+To test error handling:
+
+```typescript
+test('handles server error gracefully', async ({ page }) => {
+  await page.route('**/api/entities', route => {
+    route.fulfill({ status: 500 })
+  })
+
+  await page.goto('/entities')
+  await expect(page.getByText(/error|failed/i)).toBeVisible()
+})
+```
+
+## Command Usage
+
+### Generate Test from Description
+
+```bash
+python scripts/generate_flow_test.py \
+  --description "User signs up and creates project" \
+  --output test/e2e/signup-flow.spec.ts
+```
+
+### Generate Test from File
+
+```bash
+python scripts/generate_flow_test.py \
+  --input flows/user-onboarding.txt \
+  --output test/e2e/onboarding.spec.ts
+```
+
+### Generate Multiple Tests
+
+```bash
+python scripts/batch_generate_tests.py \
+  --flows-dir flows/ \
+  --output-dir test/e2e/
+```
+
+## Resources
+
+Consult the following resources for detailed information:
+
+- `scripts/parse_flow.py` - Flow description parser
+- `scripts/generate_flow_test.py` - Test generator
+- `scripts/generate_fixtures.py` - Test data generator
+- `references/playwright-actions.md` - Action mapping reference
+- `references/auth-patterns.md` - Authentication patterns
+- `references/selectors.md` - Selector best practices
+- `assets/test-template.ts` - Base test template
+- `assets/action-templates/` - Action code templates
+
+## Best Practices
+
+- Use semantic selectors (role, label, text)
+- Add explicit waits for dynamic content
+- Include assertions after state changes
+- Test error scenarios
+- Keep tests independent
+- Use descriptive test names
+- Add comments for complex flows
+- Group related tests with describe blocks

skills/playwright-flow-recorder/assets/test-template.ts

@@ -0,0 +1,45 @@
+import { test, expect } from '@playwright/test'
+
+/**
+ * Template for generated Playwright E2E tests
+ *
+ * This file serves as a base template for flow-based test generation.
+ * Generated tests will follow this structure with proper setup, execution, and cleanup.
+ */
+
+test.describe('Flow Name', () => {
+  // Setup before each test
+  test.beforeEach(async ({ page }) => {
+    // Navigate to starting point
+    await page.goto('/')
+
+    // Setup any required state
+    // e.g., authentication, data seeding, etc.
+  })
+
+  test('flow description', async ({ page }) => {
+    // Test steps will be inserted here
+    // Each step includes:
+    // 1. Comment describing the action
+    // 2. Playwright code to execute the action
+    // 3. Assertions to verify expected state
+
+    // Example navigation
+    await page.goto('/entities')
+
+    // Example interaction
+    await page.getByRole('button', { name: /create/i }).click()
+
+    // Example form input
+    await page.getByLabel(/name/i).fill('Test Entity')
+
+    // Example assertion
+    await expect(page.getByText('Test Entity')).toBeVisible()
+  })
+
+  // Cleanup after each test
+  test.afterEach(async ({ page }) => {
+    // Clean up any created data or state
+    // e.g., delete test entities, clear local storage, etc.
+  })
+})

skills/playwright-flow-recorder/references/playwright-actions.md

@@ -0,0 +1,438 @@
+# Playwright Actions Reference
+
+Comprehensive mapping of natural language actions to Playwright code.
+
+## Navigation Actions
+
+### Navigate to Page
+
+**Natural Language:**
+- "navigate to X"
+- "go to X"
+- "visit X"
+- "open X"
+
+**Playwright Code:**
+```typescript
+await page.goto('/x')
+```
+
+### Navigate Back
+
+**Natural Language:**
+- "go back"
+- "navigate back"
+
+**Playwright Code:**
+```typescript
+await page.goBack()
+```
+
+### Navigate Forward
+
+**Natural Language:**
+- "go forward"
+- "navigate forward"
+
+**Playwright Code:**
+```typescript
+await page.goForward()
+```
+
+### Reload Page
+
+**Natural Language:**
+- "reload"
+- "refresh page"
+
+**Playwright Code:**
+```typescript
+await page.reload()
+```
+
+## Click Actions
+
+### Click Button
+
+**Natural Language:**
+- "click X button"
+- "click on X"
+- "press X"
+
+**Playwright Code:**
+```typescript
+await page.getByRole('button', { name: /x/i }).click()
+```
+
+### Click Link
+
+**Natural Language:**
+- "click X link"
+- "follow X link"
+
+**Playwright Code:**
+```typescript
+await page.getByRole('link', { name: /x/i }).click()
+```
+
+### Double Click
+
+**Natural Language:**
+- "double click X"
+
+**Playwright Code:**
+```typescript
+await page.getByRole('button', { name: /x/i }).dblclick()
+```
+
+### Right Click
+
+**Natural Language:**
+- "right click X"
+- "context menu on X"
+
+**Playwright Code:**
+```typescript
+await page.getByRole('button', { name: /x/i }).click({ button: 'right' })
+```
+
+## Form Input Actions
+
+### Fill Text Input
+
+**Natural Language:**
+- "fill X with Y"
+- "enter Y in X"
+- "type Y in X field"
+
+**Playwright Code:**
+```typescript
+await page.getByLabel(/x/i).fill('y')
+```
+
+### Clear Input
+
+**Natural Language:**
+- "clear X"
+- "empty X field"
+
+**Playwright Code:**
+```typescript
+await page.getByLabel(/x/i).clear()
+```
+
+### Type with Delay
+
+**Natural Language:**
+- "slowly type X"
+- "type X with delay"
+
+**Playwright Code:**
+```typescript
+await page.getByLabel(/field/i).type('x', { delay: 100 })
+```
+
+### Select Dropdown Option
+
+**Natural Language:**
+- "select X from Y"
+- "choose X in Y dropdown"
+
+**Playwright Code:**
+```typescript
+await page.getByLabel(/y/i).selectOption('x')
+```
+
+### Check Checkbox
+
+**Natural Language:**
+- "check X"
+- "enable X checkbox"
+
+**Playwright Code:**
+```typescript
+await page.getByLabel(/x/i).check()
+```
+
+### Uncheck Checkbox
+
+**Natural Language:**
+- "uncheck X"
+- "disable X checkbox"
+
+**Playwright Code:**
+```typescript
+await page.getByLabel(/x/i).uncheck()
+```
+
+### Upload File
+
+**Natural Language:**
+- "upload X file"
+- "attach X"
+
+**Playwright Code:**
+```typescript
+await page.getByLabel(/upload/i).setInputFiles('path/to/file.txt')
+```
+
+## Keyboard Actions
+
+### Press Key
+
+**Natural Language:**
+- "press Enter"
+- "hit Escape key"
+
+**Playwright Code:**
+```typescript
+await page.keyboard.press('Enter')
+await page.keyboard.press('Escape')
+```
+
+### Type Text
+
+**Natural Language:**
+- "type X"
+
+**Playwright Code:**
+```typescript
+await page.keyboard.type('x')
+```
+
+### Key Combination
+
+**Natural Language:**
+- "press Ctrl+S"
+- "use keyboard shortcut Cmd+K"
+
+**Playwright Code:**
+```typescript
+await page.keyboard.press('Control+S')
+await page.keyboard.press('Meta+K')
+```
+
+## Mouse Actions
+
+### Hover
+
+**Natural Language:**
+- "hover over X"
+- "mouse over X"
+
+**Playwright Code:**
+```typescript
+await page.getByRole('button', { name: /x/i }).hover()
+```
+
+### Drag and Drop
+
+**Natural Language:**
+- "drag X to Y"
+- "move X to Y"
+
+**Playwright Code:**
+```typescript
+await page.getByText('X').dragTo(page.getByText('Y'))
+```
+
+## Wait Actions
+
+### Wait for Element
+
+**Natural Language:**
+- "wait for X"
+- "wait until X appears"
+
+**Playwright Code:**
+```typescript
+await page.getByText(/x/i).waitFor()
+```
+
+### Wait for Navigation
+
+**Natural Language:**
+- "wait for page load"
+- "wait for navigation"
+
+**Playwright Code:**
+```typescript
+await page.waitForLoadState('networkidle')
+```
+
+### Wait for Timeout
+
+**Natural Language:**
+- "wait 2 seconds"
+- "pause for 1000ms"
+
+**Playwright Code:**
+```typescript
+await page.waitForTimeout(2000)
+```
+
+## Assertion Actions
+
+### Assert Visible
+
+**Natural Language:**
+- "see X"
+- "verify X is visible"
+- "X is displayed"
+
+**Playwright Code:**
+```typescript
+await expect(page.getByText(/x/i)).toBeVisible()
+```
+
+### Assert Not Visible
+
+**Natural Language:**
+- "X is hidden"
+- "don't see X"
+- "X not visible"
+
+**Playwright Code:**
+```typescript
+await expect(page.getByText(/x/i)).not.toBeVisible()
+```
+
+### Assert URL
+
+**Natural Language:**
+- "is redirected to X"
+- "URL is X"
+- "page is X"
+
+**Playwright Code:**
+```typescript
+await expect(page).toHaveURL(/x/)
+```
+
+### Assert Text Content
+
+**Natural Language:**
+- "X contains Y"
+- "X displays Y"
+
+**Playwright Code:**
+```typescript
+await expect(page.getByRole('x')).toContainText(/y/i)
+```
+
+### Assert Enabled/Disabled
+
+**Natural Language:**
+- "X is enabled"
+- "X is disabled"
+
+**Playwright Code:**
+```typescript
+await expect(page.getByRole('button', { name: /x/i })).toBeEnabled()
+await expect(page.getByRole('button', { name: /x/i })).toBeDisabled()
+```
+
+### Assert Checked
+
+**Natural Language:**
+- "X is checked"
+- "X is unchecked"
+
+**Playwright Code:**
+```typescript
+await expect(page.getByLabel(/x/i)).toBeChecked()
+await expect(page.getByLabel(/x/i)).not.toBeChecked()
+```
+
+### Assert Count
+
+**Natural Language:**
+- "there are X items"
+- "X items are displayed"
+
+**Playwright Code:**
+```typescript
+await expect(page.getByRole('listitem')).toHaveCount(5)
+```
+
+## Selector Patterns
+
+### By Role
+
+**Use for semantic elements:**
+```typescript
+page.getByRole('button', { name: /submit/i })
+page.getByRole('link', { name: /home/i })
+page.getByRole('heading', { name: /title/i, level: 1 })
+page.getByRole('textbox', { name: /search/i })
+```
+
+### By Label
+
+**Use for form inputs:**
+```typescript
+page.getByLabel(/email/i)
+page.getByLabel(/password/i)
+```
+
+### By Text
+
+**Use for visible text:**
+```typescript
+page.getByText(/welcome/i)
+page.getByText('Exact Text')
+```
+
+### By Test ID
+
+**Use for custom test identifiers:**
+```typescript
+page.getByTestId('entity-card')
+page.getByTestId('create-button')
+```
+
+### By Placeholder
+
+**Use for input placeholders:**
+```typescript
+page.getByPlaceholder(/enter name/i)
+```
+
+## Common Patterns
+
+### Fill Form
+
+```typescript
+await page.getByLabel(/name/i).fill('John Doe')
+await page.getByLabel(/email/i).fill('john@example.com')
+await page.getByLabel(/type/i).selectOption('character')
+await page.getByRole('button', { name: /submit/i }).click()
+```
+
+### Navigate and Verify
+
+```typescript
+await page.goto('/entities')
+await expect(page).toHaveURL(/entities/)
+await expect(page.getByRole('heading', { name: /entities/i })).toBeVisible()
+```
+
+### Conditional Actions
+
+```typescript
+const deleteButton = page.getByRole('button', { name: /delete/i })
+if (await deleteButton.isVisible()) {
+  await deleteButton.click()
+}
+```
+
+### Loop Through Items
+
+```typescript
+const items = page.getByRole('listitem')
+const count = await items.count()
+
+for (let i = 0; i < count; i++) {
+  await expect(items.nth(i)).toBeVisible()
+}
+```

skills/playwright-flow-recorder/scripts/generate_flow_test.py

@@ -0,0 +1,271 @@
+#!/usr/bin/env python3
+"""Generate Playwright test scripts from natural language flow descriptions."""
+
+import argparse
+import re
+import sys
+from pathlib import Path
+from typing import List, Dict, Tuple
+
+
+class FlowStep:
+    """Represents a single step in a user flow."""
+
+    def __init__(self, action: str, target: str, value: str = "", assertion: bool = False):
+        self.action = action
+        self.target = target
+        self.value = value
+        self.assertion = assertion
+
+
+class FlowParser:
+    """Parse natural language flow descriptions into structured steps."""
+
+    # Action patterns
+    ACTIONS = {
+        r'navigate[s]? to (.+)': ('navigate', 'page'),
+        r'click[s]? (?:on )?(?:the )?(.+?)(?:\s+button|\s+link)?$': ('click', 'button'),
+        r'fill[s]? (?:in )?(?:the )?(.+?)(?: (?:with|field))? (.+)': ('fill', 'input'),
+        r'enter[s]? (.+) in (?:the )?(.+)': ('fill', 'input'),
+        r'type[s]? (.+) in (?:the )?(.+)': ('fill', 'input'),
+        r'select[s]? (.+) from (?:the )?(.+)': ('select', 'select'),
+        r'choose[s]? (.+)': ('select', 'select'),
+        r'check[s]? (?:the )?(.+)': ('check', 'checkbox'),
+        r'uncheck[s]? (?:the )?(.+)': ('uncheck', 'checkbox'),
+        r'upload[s]? (.+)': ('upload', 'file'),
+    }
+
+    # Assertion patterns
+    ASSERTIONS = {
+        r'see[s]? (.+)': 'visible',
+        r'(?:is|are) redirected to (.+)': 'url',
+        r'(.+) displays? (.+)': 'contains',
+        r'(?:page|screen) (?:shows?|displays?) (.+)': 'visible',
+        r'verif(?:y|ies) (.+)': 'visible',
+    }
+
+    def parse(self, description: str) -> List[FlowStep]:
+        """Parse flow description into structured steps."""
+        steps = []
+
+        # Split into lines
+        lines = [line.strip() for line in description.split('\n') if line.strip()]
+
+        for line in lines:
+            # Remove numbering (1., 2., etc.)
+            line = re.sub(r'^\d+\.\s*', '', line)
+
+            # Remove Given/When/Then/And prefixes
+            line = re.sub(r'^(?:Given|When|Then|And):\s*', '', line, flags=re.IGNORECASE)
+
+            # Try to match assertion patterns first
+            matched = False
+            for pattern, assertion_type in self.ASSERTIONS.items():
+                match = re.search(pattern, line, re.IGNORECASE)
+                if match:
+                    steps.append(self._create_assertion_step(assertion_type, match))
+                    matched = True
+                    break
+
+            if matched:
+                continue
+
+            # Try to match action patterns
+            for pattern, (action, element_type) in self.ACTIONS.items():
+                match = re.search(pattern, line, re.IGNORECASE)
+                if match:
+                    steps.append(self._create_action_step(action, element_type, match))
+                    matched = True
+                    break
+
+            if not matched:
+                print(f"Warning: Could not parse line: {line}", file=sys.stderr)
+
+        return steps
+
+    def _create_action_step(self, action: str, element_type: str, match: re.Match) -> FlowStep:
+        """Create action step from regex match."""
+        if action == 'navigate':
+            return FlowStep('navigate', match.group(1))
+        elif action == 'click':
+            return FlowStep('click', match.group(1), element_type)
+        elif action == 'fill':
+            if len(match.groups()) >= 2:
+                target = match.group(2)
+                value = match.group(1)
+            else:
+                target = match.group(1)
+                value = ""
+            return FlowStep('fill', target, value)
+        elif action == 'select':
+            target = match.group(2) if len(match.groups()) >= 2 else match.group(1)
+            value = match.group(1) if len(match.groups()) >= 2 else ""
+            return FlowStep('select', target, value)
+        elif action in ['check', 'uncheck']:
+            return FlowStep(action, match.group(1))
+        elif action == 'upload':
+            return FlowStep('upload', match.group(1))
+
+        return FlowStep(action, match.group(1))
+
+    def _create_assertion_step(self, assertion_type: str, match: re.Match) -> FlowStep:
+        """Create assertion step from regex match."""
+        if assertion_type == 'url':
+            return FlowStep('assertUrl', match.group(1), assertion=True)
+        elif assertion_type == 'contains':
+            return FlowStep('assertContains', match.group(1), match.group(2), assertion=True)
+        else:  # visible
+            return FlowStep('assertVisible', match.group(1), assertion=True)
+
+
+class TestGenerator:
+    """Generate Playwright test code from flow steps."""
+
+    def __init__(self, steps: List[FlowStep], flow_name: str):
+        self.steps = steps
+        self.flow_name = flow_name
+
+    def generate(self) -> str:
+        """Generate complete test file."""
+        test_name = self._to_snake_case(self.flow_name)
+        test_description = self.flow_name
+
+        imports = "import { test, expect } from '@playwright/test'\n\n"
+
+        test_code = f"test.describe('{self.flow_name}', () => {{\n"
+        test_code += f"  test('{test_description}', async ({{ page }}) => {{\n"
+
+        for step in self.steps:
+            test_code += self._generate_step_code(step)
+
+        test_code += "  })\n"
+        test_code += "})\n"
+
+        return imports + test_code
+
+    def _generate_step_code(self, step: FlowStep) -> str:
+        """Generate code for a single step."""
+        indent = "    "
+
+        if step.action == 'navigate':
+            url = step.target if step.target.startswith('/') else f'/{step.target}'
+            return f"{indent}// Navigate to {step.target}\n{indent}await page.goto('{url}')\n\n"
+
+        elif step.action == 'click':
+            element_name = self._normalize_text(step.target)
+            return f"{indent}// Click {step.target}\n{indent}await page.getByRole('button', {{ name: /{element_name}/i }}).click()\n\n"
+
+        elif step.action == 'fill':
+            label_name = self._normalize_text(step.target)
+            value = step.value or 'test_value'
+            return f"{indent}// Fill {step.target}\n{indent}await page.getByLabel(/{label_name}/i).fill('{value}')\n\n"
+
+        elif step.action == 'select':
+            label_name = self._normalize_text(step.target)
+            value = self._to_snake_case(step.value) if step.value else 'option'
+            return f"{indent}// Select {step.value} from {step.target}\n{indent}await page.getByLabel(/{label_name}/i).selectOption('{value}')\n\n"
+
+        elif step.action == 'check':
+            label_name = self._normalize_text(step.target)
+            return f"{indent}// Check {step.target}\n{indent}await page.getByLabel(/{label_name}/i).check()\n\n"
+
+        elif step.action == 'uncheck':
+            label_name = self._normalize_text(step.target)
+            return f"{indent}// Uncheck {step.target}\n{indent}await page.getByLabel(/{label_name}/i).uncheck()\n\n"
+
+        elif step.assertion:
+            return self._generate_assertion_code(step, indent)
+
+        return f"{indent}// TODO: {step.action} {step.target}\n\n"
+
+    def _generate_assertion_code(self, step: FlowStep, indent: str) -> str:
+        """Generate assertion code."""
+        if step.action == 'assertVisible':
+            text = self._normalize_text(step.target)
+            return f"{indent}// Verify {step.target} is visible\n{indent}await expect(page.getByText(/{text}/i)).toBeVisible()\n\n"
+
+        elif step.action == 'assertUrl':
+            url = step.target if step.target.startswith('/') else f'/{step.target}'
+            return f"{indent}// Verify redirect to {step.target}\n{indent}await expect(page).toHaveURL(/{url}/)\n\n"
+
+        elif step.action == 'assertContains':
+            element = self._normalize_text(step.target)
+            text = self._normalize_text(step.value)
+            return f"{indent}// Verify {step.target} contains {step.value}\n{indent}await expect(page.getByRole('{element}')).toContainText(/{text}/i)\n\n"
+
+        return f"{indent}// TODO: Assert {step.target}\n\n"
+
+    def _normalize_text(self, text: str) -> str:
+        """Normalize text for regex patterns."""
+        # Remove articles and common words
+        text = re.sub(r'\b(the|a|an)\b', '', text, flags=re.IGNORECASE)
+        # Remove extra whitespace
+        text = ' '.join(text.split())
+        return text.strip()
+
+    def _to_snake_case(self, text: str) -> str:
+        """Convert text to snake_case."""
+        text = re.sub(r'[^\w\s]', '', text)
+        text = re.sub(r'\s+', '_', text)
+        return text.lower()
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Generate Playwright test from natural language flow description"
+    )
+    parser.add_argument(
+        '--description',
+        help='Flow description as string'
+    )
+    parser.add_argument(
+        '--input',
+        help='File containing flow description'
+    )
+    parser.add_argument(
+        '--output',
+        help='Output file path (default: stdout)'
+    )
+    parser.add_argument(
+        '--name',
+        default='User Flow',
+        help='Test name/description'
+    )
+
+    args = parser.parse_args()
+
+    # Get flow description
+    if args.description:
+        description = args.description
+    elif args.input:
+        with open(args.input, 'r') as f:
+            description = f.read()
+    else:
+        print("Error: Must provide --description or --input", file=sys.stderr)
+        sys.exit(1)
+
+    # Parse flow
+    flow_parser = FlowParser()
+    steps = flow_parser.parse(description)
+
+    if not steps:
+        print("Error: No steps parsed from description", file=sys.stderr)
+        sys.exit(1)
+
+    # Generate test
+    test_generator = TestGenerator(steps, args.name)
+    test_code = test_generator.generate()
+
+    # Output
+    if args.output:
+        output_path = Path(args.output)
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+        with open(output_path, 'w') as f:
+            f.write(test_code)
+        print(f"Test generated: {output_path}")
+    else:
+        print(test_code)
+
+
+if __name__ == '__main__':
+    main()