Playwright E2E Testing Skill

progressive_disclosure: entry_point: summary: "Modern E2E testing framework with cross-browser automation and built-in test runner" when_to_use: - "When testing web applications end-to-end" - "When needing cross-browser testing" - "When testing user flows and interactions" - "When needing screenshot/video recording" quick_start: - "npm init playwright@latest" - "Choose TypeScript and test location" - "npx playwright test" - "npx playwright show-report" token_estimate: entry: 75-90 full: 4200-5200

Overview

Playwright is a modern end-to-end testing framework that provides cross-browser automation with a built-in test runner, auto-wait mechanisms, and excellent developer experience.

Key Features

• Auto-wait: Automatically waits for elements to be ready

• Cross-browser: Chromium, Firefox, WebKit support

• Built-in runner: Parallel execution, retries, reporters

• Network control: Mock and intercept network requests

• Debugging: UI mode, trace viewer, inspector

Installation

# Initialize new Playwright project

npm init playwright@latest

# Or add to existing project

npm install -D @playwright/test

# Install browsers

npx playwright install

Configuration

// playwright.config.ts

import { defineConfig, devices } from '@playwright/test';

export default defineConfig({

  testDir: './tests',

  fullyParallel: true,

  forbidOnly: !!process.env.CI,

  retries: process.env.CI ? 2 : 0,

  workers: process.env.CI ? 1 : undefined,

  reporter: 'html',

  use: {

    baseURL: 'http://localhost:3000',

    trace: 'on-first-retry',

    screenshot: 'only-on-failure',

  },

  projects: [

    {

      name: 'chromium',

      use: { ...devices['Desktop Chrome'] },

    },

    {

      name: 'firefox',

      use: { ...devices['Desktop Firefox'] },

    },

    {

      name: 'webkit',

      use: { ...devices['Desktop Safari'] },

    },

    {

      name: 'Mobile Chrome',

      use: { ...devices['Pixel 5'] },

    },

  ],

  webServer: {

    command: 'npm run start',

    url: 'http://localhost:3000',

    reuseExistingServer: !process.env.CI,

  },

});

Fundamentals

Basic Test Structure

import { test, expect } from '@playwright/test';

test('basic test', async ({ page }) => {

  await page.goto('https://example.com');

  // Wait for element and check visibility

  const title = page.locator('h1');

  await expect(title).toBeVisible();

  await expect(title).toHaveText('Example Domain');

  // Get page title

  await expect(page).toHaveTitle(/Example/);

});

test.describe('User authentication', () => {

  test('should login successfully', async ({ page }) => {

    await page.goto('/login');

    await page.fill('[name="username"]', 'testuser');

    await page.fill('[name="password"]', 'password123');

    await page.click('button[type="submit"]');

    await expect(page).toHaveURL('/dashboard');

    await expect(page.locator('.welcome-message')).toContainText('Welcome');

  });

  test('should show error for invalid credentials', async ({ page }) => {

    await page.goto('/login');

    await page.fill('[name="username"]', 'invalid');

    await page.fill('[name="password"]', 'wrong');

    await page.click('button[type="submit"]');

    await expect(page.locator('.error-message')).toBeVisible();

    await expect(page.locator('.error-message')).toHaveText('Invalid credentials');

  });

});

Test Hooks

import { test, expect } from '@playwright/test';

test.describe('Dashboard tests', () => {

  test.beforeEach(async ({ page }) => {

    // Run before each test

    await page.goto('/dashboard');

    await page.waitForLoadState('networkidle');

  });

  test.afterEach(async ({ page }) => {

    // Cleanup after each test

    await page.close();

  });

  test.beforeAll(async ({ browser }) => {

    // Run once before all tests in describe block

    console.log('Starting test suite');

  });

  test.afterAll(async ({ browser }) => {

    // Run once after all tests

    console.log('Test suite complete');

  });

  test('displays user data', async ({ page }) => {

    await expect(page.locator('.user-name')).toBeVisible();

  });

});

Locator Strategies

Best Practice: Role-based Locators

import { test, expect } from '@playwright/test';

test('accessible locators', async ({ page }) => {

  await page.goto('/form');

  // By role (BEST - accessible and stable)

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

  await page.getByRole('textbox', { name: 'Email' }).fill('user@example.com');

  await page.getByRole('checkbox', { name: 'Subscribe' }).check();

  await page.getByRole('link', { name: 'Learn more' }).click();

  // By label (good for forms)

  await page.getByLabel('Password').fill('secret123');

  // By placeholder

  await page.getByPlaceholder('Search...').fill('query');

  // By text

  await page.getByText('Welcome back').click();

  await page.getByText(/hello/i).isVisible();

  // By test ID (good for dynamic content)

  await page.getByTestId('user-profile').click();

  // By title

  await page.getByTitle('Close dialog').click();

  // By alt text (images)

  await page.getByAltText('User avatar').click();

});

CSS and XPath Locators

test('CSS and XPath locators', async ({ page }) => {

  // CSS selectors

  await page.locator('button.primary').click();

  await page.locator('#user-menu').click();

  await page.locator('[data-testid="submit-btn"]').click();

  await page.locator('div.card:first-child').click();

  // XPath (use sparingly)

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

  // Chaining locators

  const form = page.locator('form#login-form');

  await form.locator('input[name="email"]').fill('user@example.com');

  await form.locator('button[type="submit"]').click();

  // Filter locators

  await page.getByRole('listitem')

    .filter({ hasText: 'Product 1' })

    .getByRole('button', { name: 'Add to cart' })

    .click();

});

Page Object Model

Page Class Pattern

// pages/LoginPage.ts

import { Page, Locator } from '@playwright/test';

export class LoginPage {

  readonly page: Page;

  readonly usernameInput: Locator;

  readonly passwordInput: Locator;

  readonly submitButton: Locator;

  readonly errorMessage: Locator;

  constructor(page: Page) {

    this.page = page;

    this.usernameInput = page.getByLabel('Username');

    this.passwordInput = page.getByLabel('Password');

    this.submitButton = page.getByRole('button', { name: 'Log in' });

    this.errorMessage = page.locator('.error-message');

  }

  async goto() {

    await this.page.goto('/login');

  }

  async login(username: string, password: string) {

    await this.usernameInput.fill(username);

    await this.passwordInput.fill(password);

    await this.submitButton.click();

  }

  async expectErrorMessage(message: string) {

    await this.errorMessage.waitFor({ state: 'visible' });

    await expect(this.errorMessage).toHaveText(message);

  }

}

// pages/DashboardPage.ts

export class DashboardPage {

  readonly page: Page;

  readonly welcomeMessage: Locator;

  readonly logoutButton: Locator;

  constructor(page: Page) {

    this.page = page;

    this.welcomeMessage = page.locator('.welcome-message');

    this.logoutButton = page.getByRole('button', { name: 'Logout' });

  }

  async waitForLoad() {

    await this.welcomeMessage.waitFor({ state: 'visible' });

  }

  async logout() {

    await this.logoutButton.click();

  }

}

// tests/auth.spec.ts

import { test, expect } from '@playwright/test';

import { LoginPage } from '../pages/LoginPage';

import { DashboardPage } from '../pages/DashboardPage';

test('successful login flow', async ({ page }) => {

  const loginPage = new LoginPage(page);

  const dashboard = new DashboardPage(page);

  await loginPage.goto();

  await loginPage.login('testuser', 'password123');

  await dashboard.waitForLoad();

  await expect(dashboard.welcomeMessage).toContainText('Welcome');

});

Component Pattern

// components/NavigationComponent.ts

import { Page, Locator } from '@playwright/test';

export class NavigationComponent {

  readonly page: Page;

  readonly homeLink: Locator;

  readonly profileLink: Locator;

  readonly searchInput: Locator;

  constructor(page: Page) {

    this.page = page;

    const nav = page.locator('nav');

    this.homeLink = nav.getByRole('link', { name: 'Home' });

    this.profileLink = nav.getByRole('link', { name: 'Profile' });

    this.searchInput = nav.getByPlaceholder('Search...');

  }

  async navigateToProfile() {

    await this.profileLink.click();

  }

  async search(query: string) {

    await this.searchInput.fill(query);

    await this.searchInput.press('Enter');

  }

}

User Interactions

Form Interactions

test('form interactions', async ({ page }) => {

  await page.goto('/form');

  // Text inputs

  await page.fill('input[name="email"]', 'user@example.com');

  await page.type('textarea[name="message"]', 'Hello', { delay: 100 });

  // Checkboxes

  await page.check('input[type="checkbox"][name="subscribe"]');

  await page.uncheck('input[type="checkbox"][name="spam"]');

  // Radio buttons

  await page.check('input[type="radio"][value="option1"]');

  // Select dropdowns

  await page.selectOption('select[name="country"]', 'US');

  await page.selectOption('select[name="color"]', { label: 'Blue' });

  await page.selectOption('select[name="size"]', { value: 'large' });

  // Multi-select

  await page.selectOption('select[multiple]', ['value1', 'value2']);

  // File uploads

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

  await page.setInputFiles('input[type="file"]', [

    'file1.jpg',

    'file2.jpg'

  ]);

  // Clear file input

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

});

Mouse and Keyboard

test('mouse and keyboard interactions', async ({ page }) => {

  // Click variations

  await page.click('button');

  await page.dblclick('button'); // Double click

  await page.click('button', { button: 'right' }); // Right click

  await page.click('button', { modifiers: ['Shift'] }); // Shift+click

  // Hover

  await page.hover('.tooltip-trigger');

  await expect(page.locator('.tooltip')).toBeVisible();

  // Drag and drop

  await page.dragAndDrop('#draggable', '#droppable');

  // Keyboard

  await page.keyboard.press('Enter');

  await page.keyboard.press('Control+A');

  await page.keyboard.type('Hello World');

  await page.keyboard.down('Shift');

  await page.keyboard.press('ArrowDown');

  await page.keyboard.up('Shift');

  // Focus

  await page.focus('input[name="email"]');

  await page.fill('input[name="email"]', 'test@example.com');

});

Waiting Strategies

test('waiting strategies', async ({ page }) => {

  // Wait for element

  await page.waitForSelector('.dynamic-content');

  await page.waitForSelector('.modal', { state: 'visible' });

  await page.waitForSelector('.loading', { state: 'hidden' });

  // Wait for load state

  await page.waitForLoadState('load');

  await page.waitForLoadState('domcontentloaded');

  await page.waitForLoadState('networkidle');

  // Wait for URL

  await page.waitForURL('**/dashboard');

  await page.waitForURL(/\/product\/\d+/);

  // Wait for function

  await page.waitForFunction(() => {

    return document.querySelectorAll('.item').length > 5;

  });

  // Wait for timeout (avoid if possible)

  await page.waitForTimeout(1000);

  // Wait for event

  await page.waitForEvent('load');

  await page.waitForEvent('popup');

});

Assertions

Common Assertions

import { test, expect } from '@playwright/test';

test('assertions', async ({ page }) => {

  await page.goto('/dashboard');

  // Visibility

  await expect(page.locator('.header')).toBeVisible();

  await expect(page.locator('.loading')).toBeHidden();

  await expect(page.locator('.optional')).not.toBeVisible();

  // Text content

  await expect(page.locator('h1')).toHaveText('Dashboard');

  await expect(page.locator('h1')).toContainText('Dash');

  await expect(page.locator('.message')).toHaveText(/welcome/i);

  // Attributes

  await expect(page.locator('button')).toBeEnabled();

  await expect(page.locator('button')).toBeDisabled();

  await expect(page.locator('input')).toHaveAttribute('type', 'email');

  await expect(page.locator('input')).toHaveValue('test@example.com');

  // CSS

  await expect(page.locator('.button')).toHaveClass('btn-primary');

  await expect(page.locator('.button')).toHaveClass(/btn-/);

  await expect(page.locator('.element')).toHaveCSS('color', 'rgb(255, 0, 0)');

  // Count

  await expect(page.locator('.item')).toHaveCount(5);

  // URL and title

  await expect(page).toHaveURL('http://localhost:3000/dashboard');

  await expect(page).toHaveURL(/dashboard$/);

  await expect(page).toHaveTitle('Dashboard - My App');

  await expect(page).toHaveTitle(/Dashboard/);

  // Screenshot comparison

  await expect(page).toHaveScreenshot('dashboard.png');

  await expect(page.locator('.widget')).toHaveScreenshot('widget.png');

});

Custom Assertions

test('custom matchers', async ({ page }) => {

  // Soft assertions (continue test on failure)

  await expect.soft(page.locator('.title')).toHaveText('Welcome');

  await expect.soft(page.locator('.subtitle')).toBeVisible();

  // Multiple elements

  const items = page.locator('.item');

  await expect(items).toHaveCount(3);

  await expect(items.nth(0)).toContainText('First');

  await expect(items.nth(1)).toContainText('Second');

  // Poll assertions

  await expect(async () => {

    const response = await page.request.get('/api/status');

    expect(response.ok()).toBeTruthy();

  }).toPass({

    timeout: 10000,

    intervals: [1000, 2000, 5000],

  });

});

Authentication Patterns

Storage State Pattern

// auth.setup.ts - Run once to save auth state

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

const authFile = 'playwright/.auth/user.json';

setup('authenticate', async ({ page }) => {

  await page.goto('/login');

  await page.fill('[name="username"]', 'testuser');

  await page.fill('[name="password"]', 'password123');

  await page.click('button[type="submit"]');

  await page.waitForURL('/dashboard');

  // Save authentication state

  await page.context().storageState({ path: authFile });

});

// playwright.config.ts

export default defineConfig({

  projects: [

    {

      name: 'setup',

      testMatch: /.*\.setup\.ts/,

    },

    {

      name: 'chromium',

      use: {

        ...devices['Desktop Chrome'],

        storageState: authFile,

      },

      dependencies: ['setup'],

    },

  ],

});

// tests/dashboard.spec.ts - Already authenticated

test('view dashboard', async ({ page }) => {

  await page.goto('/dashboard');

  // Already logged in!

  await expect(page.locator('.user-menu')).toBeVisible();

});

Multiple User Roles

// fixtures/auth.ts

import { test as base } from '@playwright/test';

type Fixtures = {

  adminPage: Page;

  userPage: Page;

};

export const test = base.extend<Fixtures>({

  adminPage: async ({ browser }, use) => {

    const context = await browser.newContext({

      storageState: 'playwright/.auth/admin.json',

    });

    const page = await context.newPage();

    await use(page);

    await context.close();

  },

  userPage: async ({ browser }, use) => {

    const context = await browser.newContext({

      storageState: 'playwright/.auth/user.json',

    });

    const page = await context.newPage();

    await use(page);

    await context.close();

  },

});

// tests/permissions.spec.ts

import { test } from '../fixtures/auth';

test('admin can access admin panel', async ({ adminPage }) => {

  await adminPage.goto('/admin');

  await expect(adminPage.locator('.admin-panel')).toBeVisible();

});

test('regular user cannot access admin panel', async ({ userPage }) => {

  await userPage.goto('/admin');

  await expect(userPage.locator('.access-denied')).toBeVisible();

});

Network Control

Request Mocking

test('mock API responses', async ({ page }) => {

  // Mock API response

  await page.route('**/api/users', route => {

    route.fulfill({

      status: 200,

      contentType: 'application/json',

      body: JSON.stringify({

        users: [

          { id: 1, name: 'John Doe' },

          { id: 2, name: 'Jane Smith' },

        ],

      }),

    });

  });

  await page.goto('/users');

  await expect(page.locator('.user-list')).toContainText('John Doe');

});

test('mock with conditions', async ({ page }) => {

  await page.route('**/api/**', route => {

    const url = route.request().url();

    if (url.includes('/users/1')) {

      route.fulfill({

        status: 200,

        body: JSON.stringify({ id: 1, name: 'Test User' }),

      });

    } else if (url.includes('/users')) {

      route.fulfill({

        status: 200,

        body: JSON.stringify({ users: [] }),

      });

    } else {

      route.continue();

    }

  });

});

test('simulate network errors', async ({ page }) => {

  await page.route('**/api/data', route => {

    route.abort('failed');

  });

  await page.goto('/data');

  await expect(page.locator('.error-message')).toBeVisible();

});

Request Interception

test('intercept and modify requests', async ({ page }) => {

  // Modify request headers

  await page.route('**/api/**', route => {

    const headers = route.request().headers();

    route.continue({

      headers: {

        ...headers,

        'X-Custom-Header': 'test-value',

      },

    });

  });

  // Modify POST data

  await page.route('**/api/submit', route => {

    const postData = route.request().postDataJSON();

    route.continue({

      postData: JSON.stringify({

        ...postData,

        timestamp: Date.now(),

      }),

    });

  });

});

test('wait for API response', async ({ page }) => {

  // Wait for specific request

  const responsePromise = page.waitForResponse('**/api/users');

  await page.click('button#load-users');

  const response = await responsePromise;

  expect(response.status()).toBe(200);

  const data = await response.json();

  expect(data.users).toHaveLength(10);

});

Test Organization

Custom Fixtures

// fixtures/todos.ts

import { test as base } from '@playwright/test';

type TodoFixtures = {

  todoPage: TodoPage;

  createTodo: (title: string) => Promise<void>;

};

export const test = base.extend<TodoFixtures>({

  todoPage: async ({ page }, use) => {

    const todoPage = new TodoPage(page);

    await todoPage.goto();

    await use(todoPage);

  },

  createTodo: async ({ page }, use) => {

    const create = async (title: string) => {

      await page.fill('.new-todo', title);

      await page.press('.new-todo', 'Enter');

    };

    await use(create);

  },

});

// tests/todos.spec.ts

import { test } from '../fixtures/todos';

test('can create new todo', async ({ todoPage, createTodo }) => {

  await createTodo('Buy groceries');

  await expect(todoPage.todoItems).toHaveCount(1);

  await expect(todoPage.todoItems).toHaveText('Buy groceries');

});

Test Tags and Filtering

test('smoke test', { tag: '@smoke' }, async ({ page }) => {

  await page.goto('/');

  await expect(page).toHaveTitle('Home');

});

test('regression test', { tag: ['@regression', '@critical'] }, async ({ page }) => {

  // Complex test

});

// Run: npx playwright test --grep @smoke

// Run: npx playwright test --grep-invert @slow

Visual Testing

Screenshot Comparison

test('visual regression', async ({ page }) => {

  await page.goto('/dashboard');

  // Full page screenshot

  await expect(page).toHaveScreenshot('dashboard.png', {

    maxDiffPixels: 100,

  });

  // Element screenshot

  await expect(page.locator('.widget')).toHaveScreenshot('widget.png');

  // Full page with scroll

  await expect(page).toHaveScreenshot('full-page.png', {

    fullPage: true,

  });

  // Mask dynamic elements

  await expect(page).toHaveScreenshot('masked.png', {

    mask: [page.locator('.timestamp'), page.locator('.avatar')],

  });

  // Custom threshold

  await expect(page).toHaveScreenshot('comparison.png', {

    maxDiffPixelRatio: 0.05, // 5% difference allowed

  });

});

Video and Trace

// playwright.config.ts

export default defineConfig({

  use: {

    video: 'retain-on-failure',

    trace: 'on-first-retry',

    screenshot: 'only-on-failure',

  },

});

// Programmatic video

test('record video', async ({ page }) => {

  await page.goto('/');

  // Test actions...

  // Video saved automatically to test-results/

});

// View trace: npx playwright show-trace trace.zip

Parallel Execution

Test Sharding

// playwright.config.ts

export default defineConfig({

  fullyParallel: true,

  workers: process.env.CI ? 4 : undefined,

});

// Run shards in CI

// npx playwright test --shard=1/4

// npx playwright test --shard=2/4

// npx playwright test --shard=3/4

// npx playwright test --shard=4/4

Serial Tests

test.describe.configure({ mode: 'serial' });

test.describe('order matters', () => {

  let orderId: string;

  test('create order', async ({ page }) => {

    // Create order

    orderId = await createOrder(page);

  });

  test('verify order', async ({ page }) => {

    // Use orderId from previous test

    await verifyOrder(page, orderId);

  });

});

CI/CD Integration

GitHub Actions

# .github/workflows/playwright.yml

name: Playwright Tests

on:

  push:

    branches: [main, master]

  pull_request:

    branches: [main, master]

jobs:

  test:

    timeout-minutes: 60

    runs-on: ubuntu-latest

    steps:

      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4

        with:

          node-version: 20

      - name: Install dependencies

        run: npm ci

      - name: Install Playwright Browsers

        run: npx playwright install --with-deps

      - name: Run Playwright tests

        run: npx playwright test

      - uses: actions/upload-artifact@v4

        if: always()

        with:

          name: playwright-report

          path: playwright-report/

          retention-days: 30

Docker

FROM mcr.microsoft.com/playwright:v1.40.0-jammy

WORKDIR /app

COPY package*.json ./

RUN npm ci

COPY . .

CMD ["npx", "playwright", "test"]

Debugging

UI Mode

# Interactive debugging

npx playwright test --ui

# Debug specific test

npx playwright test --debug login.spec.ts

# Step through test

npx playwright test --headed --slow-mo=1000

Trace Viewer

// Generate trace

test('with trace', async ({ page }) => {

  await page.context().tracing.start({ screenshots: true, snapshots: true });

  // Test actions

  await page.goto('/');

  await page.context().tracing.stop({ path: 'trace.zip' });

});

// View: npx playwright show-trace trace.zip

Console Logs

test('capture console', async ({ page }) => {

  page.on('console', msg => console.log(`Browser: ${msg.text()}`));

  page.on('pageerror', error => console.error(`Error: ${error.message}`));

  await page.goto('/');

});

Best Practices

1. Use Stable Locators

// ✅ Good - Role-based, stable

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

await page.getByLabel('Email').fill('test@example.com');

// ❌ Bad - Fragile, implementation-dependent

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

await page.fill('div > form > input:nth-child(3)');

2. Leverage Auto-Waiting

// ✅ Good - Auto-waits

await page.click('button');

await expect(page.locator('.result')).toBeVisible();

// ❌ Bad - Manual waits

await page.waitForTimeout(2000);

await page.click('button');

3. Use Page Object Model

// ✅ Good - Reusable, maintainable

const loginPage = new LoginPage(page);

await loginPage.login('user', 'pass');

// ❌ Bad - Duplicated selectors

await page.fill('[name="username"]', 'user');

await page.fill('[name="password"]', 'pass');

4. Parallel-Safe Tests

// ✅ Good - Isolated

test('user signup', async ({ page }) => {

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

  await signUp(page, uniqueEmail);

});

// ❌ Bad - Shared state

test('user signup', async ({ page }) => {

  await signUp(page, 'test@test.com'); // Conflicts in parallel

});

5. Handle Flakiness

// ✅ Good - Wait for network idle

await page.goto('/', { waitUntil: 'networkidle' });

await expect(page.locator('.data')).toBeVisible();

// Configure retries

test.describe(() => {

  test.use({ retries: 2 });

  test('flaky test', async ({ page }) => {

    // Test with auto-retry

  });

});

Common Patterns

Multi-Page Scenarios

test('popup handling', async ({ page, context }) => {

  // Listen for new page

  const popupPromise = context.waitForEvent('page');

  await page.click('a[target="_blank"]');

  const popup = await popupPromise;

  await popup.waitForLoadState();

  await expect(popup).toHaveTitle('New Window');

  await popup.close();

});

Conditional Logic

test('handle optional elements', async ({ page }) => {

  await page.goto('/');

  // Close modal if present

  const modal = page.locator('.modal');

  if (await modal.isVisible()) {

    await page.click('.modal .close-button');

  }

  // Or use count

  const cookieBanner = page.locator('.cookie-banner');

  if ((await cookieBanner.count()) > 0) {

    await page.click('.accept-cookies');

  }

});

Data-Driven Tests

const testCases = [

  { input: 'hello', expected: 'HELLO' },

  { input: 'World', expected: 'WORLD' },

  { input: '123', expected: '123' },

];

for (const { input, expected } of testCases) {

  test(`transforms "${input}" to "${expected}"`, async ({ page }) => {

    await page.goto('/transform');

    await page.fill('input', input);

    await page.click('button');

    await expect(page.locator('.result')).toHaveText(expected);

  });

}

Resources

• Playwright Documentation

• Best Practices Guide

• API Reference

• GitHub Examples