Playwright Pro — Agent Context

You are working in a project with the Playwright Pro plugin installed. Follow these rules for all test-related work.

Golden Rules (Non-Negotiable)

1. getByRole() over CSS/XPath — resilient to markup changes, mirrors how users see the page
2. Never page.waitForTimeout() — use expect(locator).toBeVisible() or page.waitForURL()
3. Web-first assertions — expect(locator) auto-retries; expect(await locator.textContent()) does not
4. Isolate every test — no shared state, no execution-order dependencies
5. baseURL in config — zero hardcoded URLs in tests
6. Retries: 2 in CI, 0 locally — surface flakiness where it matters
7. Traces: 'on-first-retry' — rich debugging without CI slowdown
8. Fixtures over globals — share state via test.extend(), not module-level variables
9. One behavior per test — multiple related expect() calls are fine
10. Mock external services only — never mock your own app

Locator Priority

Always use the first option that works:

page.getByRole('button', { name: 'Submit' })        // 1. Role (default)
page.getByLabel('Email address')                     // 2. Label (form fields)
page.getByText('Welcome back')                       // 3. Text (non-interactive)
page.getByPlaceholder('Search...')                    // 4. Placeholder
page.getByAltText('Company logo')                    // 5. Alt text (images)
page.getByTitle('Close dialog')                      // 6. Title attribute
page.getByTestId('checkout-summary')                 // 7. Test ID (last semantic)
page.locator('.legacy-widget')                       // 8. CSS (last resort)

How to Use This Plugin

Generating Tests

When generating tests, always:

1. Use the Explore subagent to scan the project structure first
2. Check playwright.config.ts for testDir, baseURL, and project settings
3. Load relevant templates from templates/ directory
4. Match the project's language (check for tsconfig.json → TypeScript, else JavaScript)
5. Place tests in the configured testDir (default: tests/ or e2e/)
6. Include a descriptive test name that explains the behavior being verified

Reviewing Tests

When reviewing, check against:

1. All 10 golden rules above
2. The anti-patterns in skills/review/anti-patterns.md
3. Missing edge cases (empty state, error state, loading state)
4. Proper use of fixtures for shared setup

Fixing Flaky Tests

When fixing flaky tests:

1. Categorize first: timing, isolation, environment, or infrastructure
2. Use npx playwright test <file> --repeat-each=10 to reproduce
3. Use --trace=on for every attempt
4. Apply the targeted fix from skills/fix/flaky-taxonomy.md

Using Built-in Commands

Leverage Claude Code's built-in capabilities:

• Large migrations: Use /batch for parallel file-by-file conversion
• Post-generation cleanup: Use /simplify after generating a test suite
• Debugging sessions: Use /debug alongside /pw:fix for trace analysis
• Code review: Use /review for general code quality, /pw:review for Playwright-specific

Integrations

• TestRail: Configured via TESTRAIL_URL, TESTRAIL_USER, TESTRAIL_API_KEY env vars
• BrowserStack: Configured via BROWSERSTACK_USERNAME, BROWSERSTACK_ACCESS_KEY env vars
• Both are optional. The plugin works fully without them.

File Conventions

• Test files: *.spec.ts or *.spec.js
• Page objects: *.page.ts in a pages/ directory
• Fixtures: fixtures.ts or fixtures/ directory
• Test data: test-data/ directory with JSON/factory files

Playwright Pro

Production-grade Playwright testing toolkit for AI coding agents.

Generate tests, fix flaky failures, migrate from Cypress/Selenium, sync with TestRail, run on BrowserStack — all from your AI agent.

Install

# Claude Code plugin
claude plugin install pw@claude-skills

# Or load directly
claude --plugin-dir ./engineering-team/playwright-pro

Commands

Quick Start

# In Claude Code:
/pw:init                              # Set up Playwright
/pw:generate "user can log in"        # Generate your first test
# Tests are auto-validated by hooks — no extra steps

What's Inside

9 Skills

Slash commands that turn natural language into production-ready Playwright tests. Each skill leverages Claude Code's built-in capabilities (/batch for parallel work, Explore for codebase analysis, /debug for trace inspection).

3 Specialized Agents

• test-architect — Plans test strategy for complex applications
• test-debugger — Diagnoses flaky tests using a systematic taxonomy
• migration-planner — Creates file-by-file migration plans from Cypress/Selenium

55 Test Templates

Ready-to-use, parametrizable templates covering:

2 MCP Integrations

• TestRail — Read test cases, create runs, push pass/fail results
• BrowserStack — Trigger cross-browser runs, pull session reports with video/screenshots

Smart Hooks

• Auto-validates test quality when you write *.spec.ts files
• Auto-detects Playwright projects on session start
• Zero configuration required

Integrations Setup

TestRail (Optional)

Set environment variables:

export TESTRAIL_URL="https://your-instance.testrail.io"
export TESTRAIL_USER="[email protected]"
export TESTRAIL_API_KEY="your-api-key"

Then use /pw:testrail to sync test cases and push results.

BrowserStack (Optional)

export BROWSERSTACK_USERNAME="your-username"
export BROWSERSTACK_ACCESS_KEY="your-access-key"

Then use /pw:browserstack to run tests across browsers.

Works With

Built-in Command Integration

Playwright Pro doesn't reinvent what your AI agent already does. It orchestrates built-in capabilities:

• /pw:generate uses Claude's Explore subagent to understand your codebase before generating tests
• /pw:migrate uses /batch for parallel file-by-file conversion on large test suites
• /pw:fix uses /debug for trace analysis alongside Playwright-specific diagnostics
• /pw:review extends /review with Playwright anti-pattern detection

Reference

Based on battle-tested patterns from production test suites. Includes curated guidance on:

• Locator strategies and priority hierarchy
• Assertion patterns and auto-retry behavior
• Fixture architecture and composition
• Common pitfalls (top 20, ranked by frequency)
• Flaky test diagnosis taxonomy

License

MIT

name: migration-planner description: >- Analyzes Cypress or Selenium test suites and creates a file-by-file migration plan. Invoked by /pw:migrate before conversion starts. allowed-tools:

• Read
• Grep
• Glob
• LS

Migration Planner Agent

You are a test migration specialist. Your job is to analyze an existing Cypress or Selenium test suite and create a detailed, ordered migration plan.

Planning Protocol

Step 1: Detect Source Framework

Scan the project:

Cypress indicators:

• cypress/ directory
• cypress.config.ts or cypress.config.js
• @cypress packages in package.json
• .cy.ts or .cy.js test files

Selenium indicators:

• selenium-webdriver in dependencies
• webdriver or wdio in dependencies
• Test files importing selenium-webdriver
• chromedriver or geckodriver in dependencies
• Python files importing selenium

Step 2: Inventory All Test Files

List every test file with:

• File path
• Number of tests (count it(), test(), or test methods)
• Dependencies (custom commands, page objects, fixtures)
• Complexity (simple/medium/complex based on lines and patterns)

## Test Inventory

| # | File | Tests | Dependencies | Complexity |
|---|---|---|---|---|
| 1 | cypress/e2e/login.cy.ts | 5 | login command | Simple |
| 2 | cypress/e2e/checkout.cy.ts | 12 | api helpers, fixtures | Complex |
| 3 | cypress/e2e/search.cy.ts | 8 | none | Medium |

Step 3: Map Dependencies

Identify shared resources that need migration:

Custom commands (cypress/support/commands.ts):

• List each command and what it does
• Map to Playwright equivalent (fixture, helper function, or page object)

Fixtures (cypress/fixtures/):

• List data files
• Plan: copy to test-data/ with any format adjustments

Plugins (cypress/plugins/):

• List plugin functionality
• Map to Playwright config options or fixtures

Page Objects (if used):

• List page object files
• Plan: convert API calls (minimal structural change)

Support files (cypress/support/):

• List setup/teardown logic
• Map to playwright.config.ts or fixtures/

Step 4: Determine Migration Order

Order files by dependency graph:

1. Shared resources first: custom commands → fixtures, page objects → helpers
2. Simple tests next: files with no dependencies, few tests
3. Complex tests last: files with many dependencies, custom commands

## Migration Order

### Phase 1: Foundation (do first)
1. Convert custom commands → fixtures.ts
2. Copy fixtures → test-data/
3. Convert page objects (API changes only)

### Phase 2: Simple Tests (quick wins)
4. login.cy.ts → auth/login.spec.ts (5 tests, ~15 min)
5. about.cy.ts → static/about.spec.ts (2 tests, ~5 min)

### Phase 3: Complex Tests
6. checkout.cy.ts → checkout/checkout.spec.ts (12 tests, ~45 min)
7. search.cy.ts → search/search.spec.ts (8 tests, ~30 min)

Step 5: Estimate Effort

Step 6: Identify Risks

Flag tests that may need manual intervention:

• Tests using Cypress-only features (cy.origin(), cy.session())
• Tests with complex cy.intercept() patterns
• Tests relying on Cypress retry-ability semantics
• Tests using Cypress plugins with no Playwright equivalent

Step 7: Return Plan

Return the complete migration plan to /pw:migrate for execution.

name: test-architect description: >- Plans test strategy for complex applications. Invoked by /pw:generate and /pw:coverage when the app has multiple routes, complex state, or requires a structured test plan before writing tests. allowed-tools:

• Read
• Grep
• Glob
• LS

Test Architect Agent

You are a test architecture specialist. Your job is to analyze an application's structure and create a comprehensive test plan before any tests are written.

Your Responsibilities

1. Map the application surface: routes, components, API endpoints, user flows
2. Identify critical paths: the flows that, if broken, cause revenue loss or user churn
3. Design test structure: folder organization, fixture strategy, data management
4. Prioritize: which tests deliver the most confidence per effort
5. Select patterns: which template or approach fits each test scenario

How You Work

You are a read-only agent. You analyze and plan — you do not write test files.

Step 1: Scan the Codebase

• Read route definitions (Next.js app/, React Router, Vue Router, Angular routes)
• Read package.json for framework and dependencies
• Check for existing tests and their patterns
• Identify state management (Redux, Zustand, Pinia, etc.)
• Check for API layer (REST, GraphQL, tRPC)

Step 2: Catalog Testable Surfaces

Create a structured inventory:

## Application Surface

### Pages (by priority)
1. /login — Auth entry point [CRITICAL]
2. /dashboard — Main user view [CRITICAL]
3. /settings — User preferences [HIGH]
4. /admin — Admin panel [HIGH]
5. /about — Static page [LOW]

### Interactive Components
1. SearchBar — complex state, debounced API calls
2. DataTable — sorting, filtering, pagination
3. FileUploader — drag-drop, progress, error handling

### API Endpoints
1. POST /api/auth/login — authentication
2. GET /api/users — user list with pagination
3. PUT /api/users/:id — user update

### User Flows (multi-page)
1. Registration → Email Verify → Onboarding → Dashboard
2. Search → Filter → Select → Add to Cart → Checkout → Confirm

Step 3: Design Test Plan

## Test Plan

### Folder Structure
e2e/
├── auth/              # Authentication tests
├── dashboard/         # Dashboard tests
├── checkout/          # Checkout flow tests
├── fixtures/          # Shared fixtures
├── pages/             # Page object models
└── test-data/         # Test data files

### Fixture Strategy
- Auth fixture: shared `storageState` for logged-in tests
- API fixture: request context for data seeding
- Data fixture: factory functions for test entities

### Test Distribution
| Area | Tests | Template | Effort |
|---|---|---|---|
| Auth | 8 | auth/* | 1h |
| Dashboard | 6 | dashboard/* | 1h |
| Checkout | 10 | checkout/* | 2h |
| Search | 5 | search/* | 45m |
| Settings | 4 | settings/* | 30m |
| API | 5 | api/* | 45m |

### Priority Order
1. Auth (blocks everything else)
2. Core user flow (the main thing users do)
3. Payment/checkout (revenue-critical)
4. Everything else

Step 4: Return Plan

Return the complete plan to the calling skill. Do not write files.

name: test-debugger description: >- Diagnoses flaky or failing Playwright tests using systematic taxonomy. Invoked by /pw:fix when a test needs deep analysis including running tests, reading traces, and identifying root causes. allowed-tools:

• Read
• Grep
• Glob
• LS
• Bash

Test Debugger Agent

You are a Playwright test debugging specialist. Your job is to systematically diagnose why a test fails or behaves flakily, identify the root cause category, and return a specific fix.

Debugging Protocol

Step 1: Read the Test

Read the test file and understand:

• What behavior it's testing
• Which pages/URLs it visits
• Which locators it uses
• Which assertions it makes
• Any setup/teardown (fixtures, beforeEach)

Step 2: Run the Test

Run it multiple ways to classify the failure:

# Single run — get the error
npx playwright test <file> --grep "<test name>" --reporter=list 2>&1

# Burn-in — expose timing issues
npx playwright test <file> --grep "<test name>" --repeat-each=10 --reporter=list 2>&1

# Isolation check — expose state leaks
npx playwright test <file> --grep "<test name>" --workers=1 --reporter=list 2>&1

# Full suite — expose interaction
npx playwright test --reporter=list 2>&1

Step 3: Capture Trace

npx playwright test <file> --grep "<test name>" --trace=on --retries=0 2>&1

Read the trace output for:

• Network requests that failed or were slow
• Elements that weren't visible when expected
• Navigation timing issues
• Console errors

Step 4: Classify

Step 5: Identify Specific Cause

Common root causes per category:

Timing:

• Missing await on a Playwright call
• waitForTimeout() that's too short
• Clicking before element is actionable
• Asserting before data loads
• Animation interference

Isolation:

• Global variable shared between tests
• Database not cleaned between tests
• localStorage/cookies leaking
• Test creates data with non-unique identifier

Environment:

• Different viewport size in CI
• Font rendering differences affect screenshots
• Timezone affects date assertions
• Network latency in CI is higher

Infrastructure:

• Browser runs out of memory with too many workers
• File system race condition
• DNS resolution failure

Step 6: Return Diagnosis

Return to the calling skill:

## Diagnosis

**Category:** Timing/Async
**Root Cause:** Missing await on line 23 — `page.goto('/dashboard')` runs without
waiting, so the assertion on line 24 runs before navigation completes.
**Evidence:** Fails 3/10 times on `--repeat-each=10`. Trace shows assertion firing
before navigation response received.

## Fix

Line 23: Add `await` before `page.goto('/dashboard')`

## Verification

After fix: 10/10 passes on `--repeat-each=10`

Assertions Reference

Web-First Assertions (Always Use These)

Auto-retry until timeout. Safe for dynamic content.

// Visibility
await expect(locator).toBeVisible();
await expect(locator).not.toBeVisible();
await expect(locator).toBeHidden();

// Text
await expect(locator).toHaveText('exact text');
await expect(locator).toHaveText(/partial/i);
await expect(locator).toContainText('partial');

// Value (inputs)
await expect(locator).toHaveValue('entered text');
await expect(locator).toHaveValues(['option1', 'option2']);

// Attributes
await expect(locator).toHaveAttribute('href', '/dashboard');
await expect(locator).toHaveClass(/active/);
await expect(locator).toHaveId('main-nav');

// State
await expect(locator).toBeEnabled();
await expect(locator).toBeDisabled();
await expect(locator).toBeChecked();
await expect(locator).toBeEditable();
await expect(locator).toBeFocused();
await expect(locator).toBeAttached();

// Count
await expect(locator).toHaveCount(5);
await expect(locator).toHaveCount(0); // element doesn't exist

// CSS
await expect(locator).toHaveCSS('color', 'rgb(255, 0, 0)');

// Screenshots
await expect(locator).toHaveScreenshot('button.png');
await expect(page).toHaveScreenshot('full-page.png');

Page Assertions

await expect(page).toHaveURL('/dashboard');
await expect(page).toHaveURL(/\/dashboard/);
await expect(page).toHaveTitle('Dashboard - App');
await expect(page).toHaveTitle(/Dashboard/);

Anti-Patterns (Never Do This)

// BAD — no auto-retry
const text = await locator.textContent();
expect(text).toBe('Hello');

// BAD — snapshot in time, not reactive
const isVisible = await locator.isVisible();
expect(isVisible).toBe(true);

// BAD — evaluating in page context
const value = await page.evaluate(() =>
  document.querySelector('input')?.value
);
expect(value).toBe('test');

Custom Timeout

// Override timeout for slow operations
await expect(locator).toBeVisible({ timeout: 30_000 });

Soft Assertions

Continue test even if assertion fails (report all failures at end):

await expect.soft(locator).toHaveText('Expected');
await expect.soft(page).toHaveURL('/next');
// Test continues even if above fail

Common Pitfalls (Top 10)

1. waitForTimeout

Symptom: Slow, flaky tests.

// BAD
await page.waitForTimeout(3000);

// GOOD
await expect(page.getByTestId('result')).toBeVisible();

2. Non-Web-First Assertions

Symptom: Assertions fail on dynamic content.

// BAD — checks once, no retry
const text = await page.textContent('.msg');
expect(text).toBe('Done');

// GOOD — retries until timeout
await expect(page.getByText('Done')).toBeVisible();

3. Missing await

Symptom: Random passes/failures, tests seem to skip steps.

// BAD
page.goto('/dashboard');
expect(page.getByText('Welcome')).toBeVisible();

// GOOD
await page.goto('/dashboard');
await expect(page.getByText('Welcome')).toBeVisible();

4. Hardcoded URLs

Symptom: Tests break in different environments.

// BAD
await page.goto('http://localhost:3000/login');

// GOOD — uses baseURL from config
await page.goto('/login');

5. CSS Selectors Instead of Roles

Symptom: Tests break after CSS refactors.

// BAD
await page.click('#submit-btn');

// GOOD
await page.getByRole('button', { name: 'Submit' }).click();

6. Shared State Between Tests

Symptom: Tests pass alone, fail in suite.

// BAD — test B depends on test A
let userId: string;
test('create user', async () => { userId = '123'; });
test('edit user', async () => { /* uses userId */ });

// GOOD — each test is independent
test('edit user', async ({ request }) => {
  const res = await request.post('/api/users', { data: { name: 'Test' } });
  const { id } = await res.json();
  // ...
});

7. Using networkidle

Symptom: Tests hang or timeout unpredictably.

// BAD — waits for all network activity to stop
await page.goto('/dashboard', { waitUntil: 'networkidle' });

// GOOD — wait for specific content
await page.goto('/dashboard');
await expect(page.getByRole('heading', { name: 'Dashboard' })).toBeVisible();

8. Not Waiting for Navigation

Symptom: Assertions run on wrong page.

// BAD — click navigates but we don't wait
await page.getByRole('link', { name: 'Settings' }).click();
await expect(page.getByRole('heading')).toHaveText('Settings');

// GOOD — wait for URL change
await page.getByRole('link', { name: 'Settings' }).click();
await expect(page).toHaveURL('/settings');
await expect(page.getByRole('heading')).toHaveText('Settings');

9. Testing Implementation, Not Behavior

Symptom: Tests break on every refactor.

// BAD — tests CSS class (implementation detail)
await expect(page.locator('.btn')).toHaveClass('btn-primary active');

// GOOD — tests what the user sees
await expect(page.getByRole('button', { name: 'Save' })).toBeEnabled();

10. No Error Case Tests

Symptom: App breaks on errors but all tests pass.

// Missing: what happens when the API fails?
test('should handle API error', async ({ page }) => {
  await page.route('**/api/data', (route) =>
    route.fulfill({ status: 500 })
  );
  await page.goto('/dashboard');
  await expect(page.getByText(/error|try again/i)).toBeVisible();
});

Fixtures Reference

What Are Fixtures

Fixtures provide setup/teardown for each test. They replace beforeEach/afterEach for shared state and are composable, type-safe, and lazy (only run when used).

Creating Custom Fixtures

// fixtures.ts
import { test as base, expect } from '@playwright/test';

// Define fixture types
type MyFixtures = {
  authenticatedPage: Page;
  testUser: { email: string; password: string };
  apiClient: APIRequestContext;
};

export const test = base.extend<MyFixtures>({
  // Simple value fixture
  testUser: async ({}, use) => {
    await use({
      email: `test-${Date.now()}@example.com`,
      password: 'Test123!',
    });
  },

  // Fixture with setup and teardown
  authenticatedPage: async ({ page, testUser }, use) => {
    // Setup: log in
    await page.goto('/login');
    await page.getByLabel('Email').fill(testUser.email);
    await page.getByLabel('Password').fill(testUser.password);
    await page.getByRole('button', { name: 'Sign in' }).click();
    await expect(page).toHaveURL('/dashboard');

    // Provide the authenticated page to the test
    await use(page);

    // Teardown: clean up (optional)
    await page.goto('/logout');
  },

  // API client fixture
  apiClient: async ({ playwright }, use) => {
    const context = await playwright.request.newContext({
      baseURL: 'http://localhost:3000',
      extraHTTPHeaders: {
        Authorization: `Bearer ${process.env.API_TOKEN}`,
      },
    });
    await use(context);
    await context.dispose();
  },
});

export { expect };

Using Fixtures in Tests

import { test, expect } from './fixtures';

test('should show dashboard for logged in user', async ({ authenticatedPage }) => {
  // authenticatedPage is already logged in
  await expect(authenticatedPage.getByRole('heading', { name: 'Dashboard' })).toBeVisible();
});

test('should create item via API', async ({ apiClient }) => {
  const response = await apiClient.post('/api/items', {
    data: { name: 'Test Item' },
  });
  expect(response.ok()).toBeTruthy();
});

Shared Auth State (storageState)

For performance, authenticate once and reuse:

// auth.setup.ts
import { test as setup } from '@playwright/test';

setup('authenticate', async ({ page }) => {
  await page.goto('/login');
  await page.getByLabel('Email').fill('[email protected]');
  await page.getByLabel('Password').fill('password');
  await page.getByRole('button', { name: 'Sign in' }).click();
  await page.waitForURL('/dashboard');
  await page.context().storageState({ path: '.auth/user.json' });
});

// playwright.config.ts
export default defineConfig({
  projects: [
    { name: 'setup', testMatch: /.*\.setup\.ts/ },
    {
      name: 'chromium',
      use: {
        storageState: '.auth/user.json',
      },
      dependencies: ['setup'],
    },
  ],
});

When to Use What

Flaky Test Quick Reference

Diagnosis Commands

# Burn-in: expose timing issues
npx playwright test tests/checkout.spec.ts --repeat-each=10

# Isolation: expose state leaks
npx playwright test tests/checkout.spec.ts --grep "adds item" --workers=1

# Full trace: capture everything
npx playwright test tests/checkout.spec.ts --trace=on --retries=0

# Parallel stress: expose race conditions
npx playwright test --fully-parallel --workers=4 --repeat-each=5

Four Categories

Quick Fixes

Timing → Add proper waits:

// Wait for specific response
const response = page.waitForResponse('**/api/data');
await page.getByRole('button', { name: 'Load' }).click();
await response;
await expect(page.getByTestId('results')).toBeVisible();

Isolation → Unique test data:

const uniqueEmail = `test-${Date.now()}@example.com`;

Environment → Explicit viewport:

test.use({ viewport: { width: 1280, height: 720 } });

Infrastructure → CI-safe config:

export default defineConfig({
  retries: process.env.CI ? 2 : 0,
  workers: process.env.CI ? 2 : undefined,
  timeout: process.env.CI ? 60_000 : 30_000,
});

Golden Rules

1. getByRole() over CSS/XPath — resilient to markup changes, mirrors assistive technology
2. Never page.waitForTimeout() — use expect(locator).toBeVisible() or page.waitForURL()
3. Web-first assertions — expect(locator) auto-retries; expect(await locator.textContent()) does not
4. Isolate every test — no shared state, no execution-order dependencies
5. baseURL in config — zero hardcoded URLs in tests
6. Retries: 2 in CI, 0 locally — surface flakiness where it matters
7. Traces: 'on-first-retry' — rich debugging artifacts without CI slowdown
8. Fixtures over globals — share state via test.extend(), not module-level variables
9. One behavior per test — multiple related expect() calls are fine
10. Mock external services only — never mock your own app; mock third-party APIs, payment gateways, email

Locator Priority

Use the first option that works:

Role Locator Cheat Sheet

// Buttons — <button>, <input type="submit">, [role="button"]
page.getByRole('button', { name: 'Save changes' })

// Links — <a href>
page.getByRole('link', { name: 'View profile' })

// Headings — h1-h6
page.getByRole('heading', { name: 'Dashboard', level: 1 })

// Text inputs — by label association
page.getByRole('textbox', { name: 'Email' })

// Checkboxes
page.getByRole('checkbox', { name: 'Remember me' })

// Radio buttons
page.getByRole('radio', { name: 'Monthly billing' })

// Dropdowns — <select>
page.getByRole('combobox', { name: 'Country' })

// Navigation
page.getByRole('navigation', { name: 'Main' })

// Tables
page.getByRole('table', { name: 'Recent orders' })

// Rows within tables
page.getByRole('row', { name: /Order #123/ })

// Tab panels
page.getByRole('tab', { name: 'Settings' })

// Dialogs
page.getByRole('dialog', { name: 'Confirm deletion' })

// Alerts
page.getByRole('alert')

Filtering and Chaining

// Filter by text
page.getByRole('listitem').filter({ hasText: 'Product A' })

// Filter by child locator
page.getByRole('listitem').filter({
  has: page.getByRole('button', { name: 'Buy' })
})

// Chain locators
page.getByRole('navigation').getByRole('link', { name: 'Settings' })

// Nth match
page.getByRole('listitem').nth(0)
page.getByRole('listitem').first()
page.getByRole('listitem').last()

Test Case Templates

55 ready-to-use, parametrizable Playwright test templates. Each includes TypeScript and JavaScript examples with {{placeholder}} markers for customization.

Usage

Templates are loaded by /pw:generate when it detects a matching scenario. You can also reference them directly:

/pw:generate "login flow"  → loads templates/auth/login.md

Template Index

Authentication (8)

CRUD Operations (6)

Checkout (6)

Search & Filter (5)

Forms (6)

Dashboard (5)

Settings (4)

Onboarding (4)

Notifications (3)

API Testing (5)

Accessibility (3)