Playwright Automation Patterns

Overview

Reliable browser automation requires strategic selector choice, proper waiting, and defensive coding. This skill provides patterns that minimize test flakiness and maximize maintainability.

When to Use

Writing new Playwright scripts or tests
Debugging flaky automation
Refactoring unreliable selectors
Building web scrapers that need to handle dynamic content
Creating E2E tests that must be maintainable

When NOT to use:

Simple one-time browser tasks
When you need Playwright API documentation (use context7 MCP)

Selector Strategy

Priority Order

Use user-facing locators first (most resilient), then test IDs, then CSS/XPath as last resort:

Role-based locators (best - user-centric)

javascript

await page.getByRole('button', { name: 'Submit' }).click();
await page.getByRole('textbox', { name: 'Email' }).fill('test@example.com');

Other user-facing locators

javascript

await page.getByLabel('Password').fill('secret');
await page.getByPlaceholder('Search...').fill('query');
await page.getByText('Submit Order').click();

Test ID attributes (explicit contract)

javascript

// Default uses data-testid
await page.getByTestId('submit-button').click();

// Can customize in playwright.config.ts:
// use: { testIdAttribute: 'data-pw' }

CSS/ID selectors (fragile, avoid if possible)

javascript

await page.locator('#submit-btn').click();
await page.locator('.btn.btn-primary.submit').click();

Strictness and Specificity

Locators are strict by default - operations throw if multiple elements match:

javascript

// ERROR if 2+ buttons exist
await page.getByRole('button').click();

// Solutions:
// 1. Make locator more specific
await page.getByRole('button', { name: 'Submit' }).click();

// 2. Filter to narrow down
await page.getByRole('button')
  .filter({ hasText: 'Submit' })
  .click();

// 3. Chain locators to scope
await page.locator('.product-card')
  .getByRole('button', { name: 'Add to cart' })
  .click();

// Avoid: Using first() makes tests fragile
await page.getByRole('button').first().click(); // Don't do this

Locator Filtering and Chaining

javascript

// Filter by text content
await page.getByRole('listitem')
  .filter({ hasText: 'Product 2' })
  .getByRole('button')
  .click();

// Filter by child element
await page.getByRole('listitem')
  .filter({ has: page.getByRole('heading', { name: 'Product 2' }) })
  .getByRole('button', { name: 'Buy' })
  .click();

// Filter by NOT having text
await expect(
  page.getByRole('listitem')
    .filter({ hasNot: page.getByText('Out of stock') })
).toHaveCount(5);

// Handle "either/or" scenarios
const loginOrWelcome = await page.getByRole('button', { name: 'Login' })
  .or(page.getByText('Welcome back'))
  .first();
await expect(loginOrWelcome).toBeVisible();

Anti-Patterns to Avoid

❌ Fragile CSS paths

javascript

// BAD: Breaks when HTML structure changes
await page.click('div.container > div:nth-child(2) > button.submit');

✅ Stable semantic selectors

javascript

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

❌ XPath with positions

javascript

// BAD: Brittle
await page.locator('xpath=//div[3]/button[1]').click();

✅ XPath with content

javascript

// BETTER: More stable
await page.locator('xpath=//button[contains(text(), "Submit")]').click();

Waiting Patterns

Built-in Auto-Waiting

Playwright auto-waits before most actions. Trust it.

javascript

// Auto-waits for element to be visible, enabled, and stable
await page.click('button');
await page.fill('input[name="email"]', 'test@example.com');

What auto-waiting checks:

Element is attached to DOM
Element is visible
Element is stable (not animating)
Element is enabled
Element receives events (not obscured)

javascript

// Bypass checks (use with caution)
await page.click('button', { force: true });

// Test without acting (trial run)
await page.click('button', { trial: true });

Web-First Assertions

Use web-first assertions - they retry until condition is met:

javascript

// WRONG - no retry, immediate check
expect(await page.getByText('welcome').isVisible()).toBe(true);

// CORRECT - auto-retries until timeout
await expect(page.getByText('welcome')).toBeVisible();
await expect(page.getByText('Status')).toHaveText('Complete');
await expect(page.getByRole('listitem')).toHaveCount(5);

// Soft assertions - continue test even on failure
await expect.soft(page.getByTestId('status')).toHaveText('Success');
await page.getByRole('link', { name: 'next' }).click();
// Test continues, failures reported at end

Explicit Waits for Dynamic Content

javascript

// Wait for specific element (modern - use web-first assertions)
await expect(page.locator('.results-loaded')).toBeVisible();

// Wait for network to be idle
await page.waitForLoadState('networkidle');

// Wait for custom condition
await page.waitForFunction(() =>
  document.querySelectorAll('.item').length > 10
);

Handling Asynchronous Updates

javascript

// Known count - assert exact number
await expect(page.locator('.item')).toHaveCount(5);

// Unknown count - wait for container, then extract
await expect(page.locator('.search-results')).toBeVisible();
const items = await page.locator('.item').all();

// Loading spinner - wait for absence then presence
await expect(page.locator('.loading-spinner')).not.toBeVisible();
await expect(page.locator('.results')).toBeVisible();

// Wait for text content to appear
await expect(page.locator('.status')).toHaveText('Complete');

// At least one result (reject zero results)
await expect(page.locator('.item').first()).toBeVisible();

Data Extraction Patterns

Single Element

javascript

// textContent() - Gets all text including hidden elements
const title = await page.locator('h1').textContent();

// innerText() - Gets only visible text (respects CSS display)
const price = await page.locator('.price').innerText();

// getAttribute() - Get attribute value
const href = await page.locator('a.product').getAttribute('href');

// For assertions, prefer web-first assertions
await expect(page.locator('.price')).toHaveText('$99');

Multiple Elements

javascript

// IMPORTANT: locator.all() doesn't wait for elements
// This can be flaky if list is still loading

// Known count - assert first, then extract
await expect(page.locator('.item')).toHaveCount(5);
const items = await page.locator('.item').all();
const data = await Promise.all(
  items.map(async item => ({
    title: await item.locator('.title').textContent(),
    price: await item.locator('.price').textContent(),
  }))
);

// Unknown count - wait for container, then extract
await expect(page.locator('.results-container')).toBeVisible();
const data = await page.locator('.item').evaluateAll(items =>
  items.map(el => ({
    title: el.querySelector('.title')?.textContent?.trim(),
    price: el.querySelector('.price')?.textContent?.trim(),
  }))
);

// BEST: Use evaluateAll for batch extraction (single round-trip)
// Use when: extracting from locator-scoped elements (most common)
const data = await page.locator('.item').evaluateAll(items =>
  items.map(el => ({
    title: el.querySelector('.title')?.textContent?.trim(),
    price: el.querySelector('.price')?.textContent?.trim(),
  }))
);

Complex Extraction with evaluate()

javascript

// Use evaluate() when you need global page context
// (e.g., checking window variables, document state)
const data = await page.evaluate(() => {
  return {
    items: Array.from(document.querySelectorAll('.item')).map(el => ({
      title: el.querySelector('.title')?.textContent?.trim(),
      price: el.querySelector('.price')?.textContent?.trim(),
      url: el.querySelector('a')?.href,
      available: !el.classList.contains('out-of-stock')
    })),
    totalCount: window.productCount, // Access global variables
    filters: window.appliedFilters   // Page-level state
  };
});

// Prefer evaluateAll() for locator-scoped extraction (more focused)
const items = await page.locator('.item').evaluateAll(els =>
  els.map(el => ({ /* ... */ }))
);

Error Handling

Graceful Fallbacks

javascript

// Check if element exists before interacting
const cookieBanner = page.locator('.cookie-banner');
if (await cookieBanner.isVisible()) {
  await cookieBanner.getByRole('button', { name: 'Accept' }).click();
}

Retry Logic

javascript

// Playwright retries automatically, but you can customize
await expect(async () => {
  const status = await page.locator('.status').textContent();
  expect(status).toBe('Complete');
}).toPass({ timeout: 10000, intervals: [1000] });

Timeout Configuration

javascript

// Set timeout for specific action
await page.click('button', { timeout: 5000 });

// Set timeout for entire test
test.setTimeout(60000);

// Set default timeout for page
page.setDefaultTimeout(10000);

Navigation Patterns

Wait for Navigation

javascript

// Modern pattern - click auto-waits for navigation
await page.click('a.next-page');
await page.waitForLoadState('networkidle'); // Only if needed

// Using modern locator
await page.getByRole('link', { name: 'Next Page' }).click();

Multi-Page Workflows

javascript

// Open new tab
const [newPage] = await Promise.all([
  context.waitForEvent('page'),
  page.click('a[target="_blank"]')
]);

await newPage.waitForLoadState();
// Work with newPage
await newPage.close();

Form Interaction Patterns

Basic Form Filling

javascript

// fill() - Recommended for most inputs (fast, atomic operation)
await page.fill('input[name="email"]', 'user@example.com');
await page.fill('input[name="password"]', 'secret123');

// type() - For keystroke-sensitive inputs (slower, fires each key event)
await page.locator('input.search').type('Product', { delay: 100 });

// Modern approach with role-based locators
await page.getByLabel('Email').fill('user@example.com');
await page.getByLabel('Password').fill('secret123');
await page.getByRole('combobox', { name: 'Country' }).selectOption('US');
await page.getByRole('checkbox', { name: 'I agree' }).check();
await page.getByRole('button', { name: 'Submit' }).click();

File Uploads

javascript

await page.setInputFiles('input[type="file"]', '/path/to/file.pdf');

// Multiple files
await page.setInputFiles('input[type="file"]', [
  '/path/to/file1.pdf',
  '/path/to/file2.pdf'
]);

Autocomplete/Search Inputs

javascript

// Type and wait for suggestions (modern approach)
await page.getByPlaceholder('Search products').fill('Product Name');
await expect(page.locator('.suggestions')).toBeVisible();

// Click specific suggestion using role-based locator
await page.getByRole('option', { name: 'Product Name - Premium' }).click();

// Or filter suggestions
await page.locator('.suggestions')
  .getByText('Product Name', { exact: false })
  .first()
  .click();

Screenshot and Debugging

Strategic Screenshots

javascript

// Full page screenshot
await page.screenshot({ path: 'screenshot.png', fullPage: true });

// Element screenshot
await page.locator('.chart').screenshot({ path: 'chart.png' });

// Screenshot on failure (in test)
test.afterEach(async ({ page }, testInfo) => {
  if (testInfo.status !== testInfo.expectedStatus) {
    await page.screenshot({
      path: `failure-${testInfo.title}.png`,
      fullPage: true
    });
  }
});

Debug Mode

javascript

// Pause execution for debugging
await page.pause();

// Slow down actions for observation
const browser = await chromium.launch({ slowMo: 1000 });

Common Patterns Reference

Task	Pattern
Click button	`await page.getByRole('button', { name: 'Text' }).click()`
Fill input	`await page.getByLabel('Field').fill('value')`
Select option	`await page.getByRole('combobox').selectOption('value')`
Check checkbox	`await page.getByRole('checkbox', { name: 'Label' }).check()`
Wait for element	`await expect(page.locator('.el')).toBeVisible()`
Assert text	`await expect(page.locator('.el')).toHaveText('text')`
Extract text	`const text = await page.locator('.el').textContent()`
Extract multiple	`await expect(locator).toHaveCount(5); const els = await locator.all()`
Batch extract	`const data = await page.locator('.el').evaluateAll(els => ...)`
Run JS in page	`await page.evaluate(() => /* JS code */)`
Take screenshot	`await page.screenshot({ path: 'shot.png' })`
Handle new tab	`const newPage = await context.waitForEvent('page', () => page.click('a'))`

Anti-Pattern Checklist

Avoid these common mistakes:

❌ Using
```
page.waitForTimeout(5000)
```
instead of web-first assertions
❌ Using CSS class names or nth-child selectors instead of role-based locators

❌ Using

expect(await locator.isVisible()).toBe(true)

instead of

await expect(locator).toBeVisible()

❌ Using deprecated
```
waitForNavigation()
```
- clicks auto-wait now
❌ Using
```
locator.all()
```
without asserting count first
❌ Using
```
first()
```
when locator should be more specific
❌ Not handling popups or cookie banners
❌ Hardcoding delays instead of waiting for conditions
❌ Taking screenshots for data extraction (use evaluate instead)

Remember

Robust automation priorities:

User-facing locators first - Role, label, placeholder, text (not CSS)

Web-first assertions -

await expect(locator).toBeVisible()

not

expect(await ...)

Trust auto-waiting - Don't add manual delays or deprecated patterns
Strictness is your friend - Fix ambiguous locators, don't use
```
first()
```
Batch extraction wisely - Assert count before
```
all()
```
, use
```
evaluateAll()
```
for efficiency

Browser automation is inherently asynchronous and timing-dependent. Build in resilience from the start.

playwright-patterns

NPX Install

Tags

SKILL.md Content

Playwright Automation Patterns

Overview

When to Use

Selector Strategy

Priority Order

Strictness and Specificity

Locator Filtering and Chaining

Anti-Patterns to Avoid

Waiting Patterns

Built-in Auto-Waiting

Web-First Assertions

Explicit Waits for Dynamic Content

Handling Asynchronous Updates

Data Extraction Patterns

Single Element

Multiple Elements

Complex Extraction with evaluate()

Error Handling

Graceful Fallbacks

Retry Logic

Timeout Configuration

Navigation Patterns

Wait for Navigation

Multi-Page Workflows

Form Interaction Patterns

Basic Form Filling

File Uploads

Autocomplete/Search Inputs

Screenshot and Debugging

Strategic Screenshots

Debug Mode

Common Patterns Reference

Anti-Pattern Checklist

Remember