Playwright Testing Skill

Playwright Testing

Write reliable, fast, maintainable Playwright tests for SPAs.

Core Concepts (Locators, Waiting, Assertions)
Test Structure → See reference/structure.md
Performance → See reference/performance.md
Debugging → See reference/debugging.md
CI Configuration → See reference/ci.md

Core principle: Test what users see and do. If a user can't find an element by its role or text, neither should your test.

Quality layers: Reliable (no flakes) → Fast (parallel, minimal waits) → Maintainable (survives refactors)

Philosophy: User-centric locators by default. Implementation details (test-ids, CSS selectors) are escape hatches, not first choices.

The Process

Identify: What user behavior are we testing?
Locate: Find elements the way users would (role, label, text)
Act: Perform user actions (click, fill, navigate)
Assert: Verify visible outcomes, not internal state
Stabilize: Handle async, add appropriate waits

Red Flags - STOP

page.locator('.btn-primary') - CSS class selectors
page.waitForTimeout(1000) - arbitrary sleeps
page.locator('[data-testid="x"]') as first choice
Testing component internals instead of user outcomes
Long test files with no page objects or fixtures

Locator Priority

digraph locator_priority {
    rankdir=TB;
    node [shape=box];

    "Need to find element" [shape=diamond];
    "Has accessible role?" [shape=diamond];
    "Has label/placeholder?" [shape=diamond];
    "Has visible text?" [shape=diamond];
    "getByRole" [style=filled fillcolor=lightgreen];
    "getByLabel/getByPlaceholder" [style=filled fillcolor=lightgreen];
    "getByText" [style=filled fillcolor=lightgreen];
    "getByTestId" [style=filled fillcolor=lightyellow];

    "Need to find element" -> "Has accessible role?";
    "Has accessible role?" -> "getByRole" [label="yes"];
    "Has accessible role?" -> "Has label/placeholder?" [label="no"];
    "Has label/placeholder?" -> "getByLabel/getByPlaceholder" [label="yes"];
    "Has label/placeholder?" -> "Has visible text?" [label="no"];
    "Has visible text?" -> "getByText" [label="yes"];
    "Has visible text?" -> "getByTestId" [label="no (last resort)"];
}

| Priority | Locator | When to Use | Example | |----------|---------|-------------|---------| | 1st | getByRole | Buttons, links, inputs, headings, lists | getByRole('button', { name: 'Submit' }) | | 2nd | getByLabel | Form inputs with labels | getByLabel('Email address') | | 3rd | getByPlaceholder | Inputs with placeholder text | getByPlaceholder('Search...') | | 4th | getByText | Static text content, paragraphs | getByText('Welcome back') | | 5th | getByAltText | Images | getByAltText('Company logo') | | Last | getByTestId | Dynamic content, no semantic meaning | getByTestId('total-price') |

Role Examples

// Buttons
page.getByRole('button', { name: 'Save changes' })
page.getByRole('button', { name: /submit/i })  // regex for flexibility

// Links
page.getByRole('link', { name: 'View profile' })

// Form inputs
page.getByRole('textbox', { name: 'Username' })
page.getByRole('checkbox', { name: 'Remember me' })
page.getByRole('combobox', { name: 'Country' })

// Structure
page.getByRole('heading', { name: 'Dashboard', level: 1 })
page.getByRole('list').getByRole('listitem')
page.getByRole('dialog', { name: 'Confirm deletion' })

// Tables
page.getByRole('table').getByRole('row', { name: /john/i })

Disambiguating Multiple Matches

// Specify which match you want
await page.getByRole('button', { name: 'Delete' }).first().click();
await page.getByRole('listitem').last().click();
await page.getByRole('row').nth(2).click();  // 0-indexed

// Filter by content or child elements
await page.getByRole('listitem').filter({ hasText: 'John' }).click();
await page.getByRole('listitem').filter({
    has: page.getByRole('button', { name: 'Edit' })
}).click();

// Chain locators to scope
await page.getByRole('dialog').getByRole('button', { name: 'Confirm' }).click();

Locator Anti-patterns

| Bad | Why | Good | |-----|-----|------| | .locator('.submit-btn') | Breaks on class rename | getByRole('button', { name: 'Submit' }) | | .locator('#email-input') | Coupled to implementation | getByLabel('Email') | | .locator('div > span:nth-child(2)') | Extremely brittle | getByText('...') or add test-id | | getByTestId everywhere | Misses accessibility bugs | Use semantic locators first | | Unscoped locator with multiple matches | Flaky, might click wrong element | Use .first(), .filter(), or scope with parent |

Waiting & Async

Playwright auto-waits for most actions. Don't add manual waits unless you have a specific reason.

digraph waiting {
    rankdir=TB;
    node [shape=box];

    "What are you waiting for?" [shape=diamond];
    "Element to appear" [shape=diamond];
    "Auto-wait (built-in)" [style=filled fillcolor=lightgreen];
    "expect + toBeVisible" [style=filled fillcolor=lightgreen];
    "waitForResponse" [style=filled fillcolor=lightyellow];
    "waitForURL" [style=filled fillcolor=lightyellow];
    "NEVER waitForTimeout" [style=filled fillcolor=lightpink];

    "What are you waiting for?" -> "Auto-wait (built-in)" [label="clicking/filling"];
    "What are you waiting for?" -> "Element to appear" [label="element"];
    "What are you waiting for?" -> "waitForResponse" [label="API call"];
    "What are you waiting for?" -> "waitForURL" [label="navigation"];
    "Element to appear" -> "expect + toBeVisible" [label="use assertion"];
    "Element to appear" -> "NEVER waitForTimeout" [label="don't guess"];
}

Built-in Auto-Waiting

These actions auto-wait - no manual wait needed:

// All of these wait automatically for element to be actionable
await page.getByRole('button', { name: 'Submit' }).click();
await page.getByLabel('Email').fill('test@example.com');
await page.getByRole('checkbox').check();
await page.getByRole('combobox').selectOption('US');

Explicit Waits (When Needed)

// Wait for element state (prefer assertions)
await expect(page.getByText('Success')).toBeVisible();
await expect(page.getByRole('button')).toBeEnabled();
await expect(page.getByRole('list')).not.toBeEmpty();

// Wait for navigation
await page.waitForURL('**/dashboard');
await page.waitForURL(url => url.searchParams.has('token'));

// Wait for API response (useful for loading states)
await page.getByRole('button', { name: 'Load data' }).click();
await page.waitForResponse(resp =>
    resp.url().includes('/api/data') && resp.status() === 200
);

// Wait for network idle (use sparingly - can be slow)
await page.waitForLoadState('networkidle');

// Wait for specific request to complete before asserting
const responsePromise = page.waitForResponse('/api/users');
await page.getByRole('button', { name: 'Refresh' }).click();
await responsePromise;
await expect(page.getByRole('list')).toContainText('John');

// Promise.all pattern - click and wait simultaneously
await Promise.all([
    page.waitForResponse(resp => resp.url().includes('/api/data')),
    page.getByRole('button', { name: 'Submit' }).click()
]);

Waiting Anti-patterns

| Bad | Why | Good | |-----|-----|------| | waitForTimeout(2000) | Arbitrary, slow, still flaky | Wait for specific condition | | waitForTimeout(100) in loop | Polling manually | Use expect with auto-retry | | waitForLoadState('networkidle') everywhere | Slow, unreliable with polling | Wait for specific response | | No wait + immediate assert | Race condition | expect auto-retries assertions |

Assertion Auto-Retry

Playwright assertions auto-retry until timeout. Use this instead of manual waits:

// BAD: manual wait then check
await page.waitForTimeout(1000);
const text = await page.getByTestId('status').textContent();
expect(text).toBe('Complete');

// GOOD: auto-retrying assertion
await expect(page.getByText('Complete')).toBeVisible();

Soft Assertions

Use expect.soft() to continue testing after assertion failure (collect multiple failures):

test('validates all form fields', async ({ page }) => {
    await page.goto('/profile');

    // Soft assertions don't stop the test - useful for checking multiple things
    await expect.soft(page.getByLabel('Name')).toHaveValue('John');
    await expect.soft(page.getByLabel('Email')).toHaveValue('john@example.com');
    await expect.soft(page.getByLabel('Phone')).toHaveValue('555-1234');

    // Test continues even if some assertions fail
    // All failures reported at end
});

Handling Overlays and Popups

Use addLocatorHandler when overlays might interfere with test actions:

// Setup handler for cookie consent popup
await page.addLocatorHandler(
    page.getByRole('dialog', { name: 'Cookie consent' }),
    async () => {
        await page.getByRole('button', { name: 'Accept' }).click();
    }
);

// Now write test normally - handler auto-dismisses popup if it appears
await page.goto('/dashboard');
await page.getByRole('button', { name: 'Settings' }).click();

Test Structure

For page objects, fixtures, and test organization, see reference/structure.md.

Quick tips:

Page objects encapsulate interactions, not assertions
Fixtures handle common setup/teardown
One behavior per test
Use test.describe for grouping related tests

Performance

For parallel execution, auth optimization, and API shortcuts, see reference/performance.md.

Quick tips:

Reuse auth state via storageState
Create test data via API, not UI
Use fullyParallel: true
Avoid waitForLoadState('networkidle')

Debugging

For debug mode, traces, and common scenarios, see reference/debugging.md.

Quick tips:

npx playwright test --debug for local debugging
View traces for CI failures: npx playwright show-trace trace.zip
Use await page.pause() to stop and inspect

CI Configuration

For GitHub Actions, sharding, and CI-specific config, see reference/ci.md.

Quick tips:

forbidOnly: !!process.env.CI prevents test.only in CI
retries: 2 for CI to handle transient failures
Upload artifacts for debugging failures

Quality Checklist

Create TodoWrite items for each applicable check before finalizing tests.

Layer 1: Reliable (No Flakes)

[ ] No waitForTimeout() calls - using condition-based waits
[ ] Assertions use expect() with auto-retry, not manual checks
[ ] Tests are independent - no shared state between tests
[ ] Waiting for specific API responses, not networkidle
[ ] Locators are specific enough (single element match)
[ ] Tests pass consistently (run 5x locally before committing)

Layer 2: Fast

[ ] Authentication reused via storageState
[ ] Test data created via API, not UI
[ ] Tests run in parallel (fullyParallel: true)
[ ] No unnecessary waitForLoadState('networkidle')
[ ] Heavy setup in fixtures, not repeated per test
[ ] Sharding configured for large test suites

Layer 3: Maintainable

[ ] Locators use roles/labels, not CSS selectors
[ ] Page objects encapsulate interactions
[ ] Test names describe user action + expected outcome
[ ] One behavior per test - not testing multiple things
[ ] Fixtures handle common setup/teardown
[ ] No magic strings - constants for repeated values

Common Patterns Reference

| Need | Pattern | |------|---------| | Authenticated user | storageState fixture | | Test data setup | API calls in beforeEach or fixture | | Wait for data load | waitForResponse('/api/...') | | Click + wait for response | Promise.all([waitForResponse(...), click()]) | | Multiple similar tests | test.describe + parameterized data | | Slow operation | Increase timeout for specific test | | Modal/dialog | getByRole('dialog') then scope within | | Dropdown selection | getByRole('combobox').selectOption() | | File upload | setInputFiles() on file input | | Hover menu | locator.hover() then click revealed item | | Drag and drop | locator.dragTo(target) | | iframes | frameLocator() then scope within | | New tab/window | page.waitForEvent('popup') | | Multiple matches | .first(), .last(), .nth(n), .filter() | | Check multiple things | expect.soft() for non-blocking assertions | | Dismiss popups/overlays | addLocatorHandler() |

When to Add data-testid

Use data-testid as escape hatch when:

Element has no semantic role (decorative container)
Dynamic content with no stable text (generated IDs, prices)
Multiple identical elements where position matters
Third-party components without accessible markup

// Acceptable: price that changes dynamically
<span data-testid="cart-total">{formatCurrency(total)}</span>
page.getByTestId('cart-total')

// Still prefer scoping with semantic locators
page.getByRole('region', { name: 'Cart' }).getByTestId('total')

Quick Reference Commands

# Run all tests
npx playwright test

# Run specific file
npx playwright test login.spec.ts

# Run tests matching name
npx playwright test -g "login"

# Run in headed mode
npx playwright test --headed

# Debug mode with inspector
npx playwright test --debug

# Update snapshots
npx playwright test --update-snapshots

# Generate test from recording
npx playwright codegen localhost:3000

# Show last HTML report
npx playwright show-report

Agent Skills: Playwright Testing

Install this agent skill to your local

Skill Files