Playwright E2E Testing Guide

The complete reference for Playwright — Microsoft's modern end-to-end testing framework. Covers locators, auto-wait, fixtures, trace viewer, codegen, multi-browser support, and API testing.

What is Playwright?

Playwright is a modern end-to-end browser automation framework developed by Microsoft. Released in 2020, it quickly became the preferred choice for teams that needed reliable cross-browser E2E tests without Selenium's verbosity or Cypress's single-tab limitation. Playwright controls real browser instances through low-level protocols — the Chrome DevTools Protocol for Chromium, Firefox's Remote Protocol, and WebKit's inspector — giving it deep access to browser internals.

The framework's killer features are auto-waiting (no more flaky explicit waits), resilient locators (CSS selectors, ARIA roles, text), and first-class tooling: Trace Viewer for post-mortem debugging, Codegen for recording interactions as test code, and a VS Code extension for running and debugging tests with full IDE integration.

Installation

# Install Playwright with browser binaries
npm init playwright@latest

# Or manually
npm install --save-dev @playwright/test
npx playwright install

# playwright.config.ts
import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
  testDir: './tests/e2e',
  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'] } },
  ],
});

Core Test Structure: page.goto & Locators

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

test('user can log in', async ({ page }) => {
  await page.goto('/login');

  // Prefer ARIA-role locators for resilience
  await page.getByLabel('Email').fill('[email protected]');
  await page.getByLabel('Password').fill('secret');
  await page.getByRole('button', { name: 'Sign in' }).click();

  // Assert navigation happened
  await expect(page).toHaveURL('/dashboard');
  await expect(page.getByRole('heading', { name: 'Dashboard' })).toBeVisible();
});

test('shows validation error for empty email', async ({ page }) => {
  await page.goto('/login');
  await page.getByRole('button', { name: 'Sign in' }).click();
  await expect(page.getByText('Email is required')).toBeVisible();
});

Fixtures: Sharing Setup Across Tests

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

type Fixtures = { authenticatedPage: Page };

export const test = base.extend<Fixtures>({
  authenticatedPage: async ({ page }, use) => {
    // Reusable login before each test
    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 use(page); // test runs here

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

export { expect };

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

test('dashboard loads user data', async ({ authenticatedPage: page }) => {
  await expect(page.getByText('Welcome back')).toBeVisible();
});

Network Interception & API Testing

// Intercept network requests
test('handles API error gracefully', async ({ page }) => {
  await page.route('/api/users', route =>
    route.fulfill({ status: 500, body: 'Internal Server Error' })
  );

  await page.goto('/users');
  await expect(page.getByText('Something went wrong')).toBeVisible();
});

// Pure API testing (no browser)
test('POST /api/products returns 201', async ({ request }) => {
  const response = await request.post('/api/products', {
    data: { name: 'Widget', price: 9.99 },
    headers: { Authorization: `Bearer ${process.env.API_TOKEN}` },
  });

  expect(response.status()).toBe(201);
  const body = await response.json();
  expect(body).toMatchObject({ id: expect.any(String), name: 'Widget' });
});

Key Features

• Auto-wait — all actions wait for element readiness automatically, eliminating flaky sleeps
• Trace Viewer — replay failing tests with full DOM snapshots and network logs
• Codegen — record manual interactions as test code with npx playwright codegen
• Multi-browser — Chromium, Firefox, and WebKit in a single test file
• Mobile emulation — device descriptors for responsive testing
• Parallel execution — tests run in parallel workers by default
• API testing — HTTP requests without a browser via request fixture
• VS Code extension — run, debug, and record tests from the editor

Use Cases

• Authentication flows — login, OAuth, session management, MFA
• Form submissions — validation, file uploads, multi-step wizards
• Cross-browser regression — ensure features work in Chrome, Firefox, and Safari
• API contract testing — verify backend responses as part of E2E suite
• Visual regression — screenshot comparison with toHaveScreenshot()
• Accessibility testing — ARIA role locators catch missing accessibility attributes

Comparison: Playwright vs Alternatives

Pros & Cons