playwright-expert Checked

Use when writing E2E tests with Playwright, setting up test infrastructure, or debugging flaky browser tests. Invoke to write test scripts, create page objects, configure test fixtures, set up reporters, add CI integration, implement API mocking, or perform visual regression testing. Trigger terms: Playwright, E2E test, end-to-end, browser testing, automation, UI testing, visual testing, Page Object Model, test flakiness.

Playwright Expert

E2E testing specialist with deep expertise in Playwright for robust, maintainable browser automation.

Use when writing E2E tests with Playwright, setting up test infrastructure, or debugging flaky browser tests. Invoke to write test scripts, create page objects, configure test fixtures, set up reporters, add CI integration, implement API mocking, or perform visual regression testing. Trigger terms: Playwright, E2E test, end-to-end, browser testing, automation, UI testing, visual testing, Page Object Model, test flakiness.

Playwright Expert

E2E testing specialist with deep expertise in Playwright for robust, maintainable browser automation.

Core Workflow

1. **Analyze requirements** - Identify user flows to test

2. **Setup** - Configure Playwright with proper settings

3. **Write tests** - Use POM pattern, proper selectors, auto-waiting

4. **Debug** - Run test → check trace → identify issue → fix → verify fix

5. **Integrate** - Add to CI/CD pipeline

Reference Guide

Load detailed guidance based on context:

| Topic | Reference | Load When |

|-------|-----------|-----------|

| Selectors | references/selectors-locators.md | Writing selectors, locator priority |

| Page Objects | references/page-object-model.md | POM patterns, fixtures |

| API Mocking | references/api-mocking.md | Route interception, mocking |

| Configuration | references/configuration.md | playwright.config.ts setup |

| Debugging | references/debugging-flaky.md | Flaky tests, trace viewer |

Constraints

### MUST DO

• Use role-based selectors when possible
• Leverage auto-waiting (don't add arbitrary timeouts)
• Keep tests independent (no shared state)
• Use Page Object Model for maintainability
• Enable traces/screenshots for debugging
• Run tests in parallel

### MUST NOT DO

• Use waitForTimeout() (use proper waits)
• Rely on CSS class selectors (brittle)
• Share state between tests
• Ignore flaky tests
• Use first(), nth() without good reason

Code Examples

### Selector: Role-based (correct) vs CSS class (brittle)

// ✅ Role-based selector — resilient to styling changes
await page.getByRole('button', { name: 'Submit' }).click();
await page.getByLabel('Email address').fill('user@example.com');

// ❌ CSS class selector — breaks on refactor
await page.locator('.btn-primary.submit-btn').click();
await page.locator('.email-input').fill('user@example.com');

### Page Object Model + Test File

// pages/LoginPage.ts
import { type Page, type Locator } from '@playwright/test';

export class LoginPage {
  readonly page: Page;
  readonly emailInput: Locator;
  readonly passwordInput: Locator;
  readonly submitButton: Locator;
  readonly errorMessage: Locator;

  constructor(page: Page) {
    this.page = page;
    this.emailInput = page.getByLabel('Email address');
    this.passwordInput = page.getByLabel('Password');
    this.submitButton = page.getByRole('button', { name: 'Sign in' });
    this.errorMessage = page.getByRole('alert');
  }

  async goto() {
    await this.page.goto('/login');
  }