E2E Testing React Apps with Playwright

A comprehensive guide to e2e testing react apps with playwright with production examples and best practices.

Why Playwright Over Cypress for React E2E

Playwright has become the de facto standard for end-to-end testing of React applications in production environments. Unlike Cypress, which runs inside the browser's JavaScript context and suffers from limitations like same-origin restrictions and lack of native mobile emulation, Playwright operates at the protocol level. This gives you true multi-browser support (Chromium, Firefox, WebKit), network interception, and the ability to test scenarios like file downloads, pop-ups, and multi-tab workflows. For React apps, Playwright's auto-waiting mechanism eliminates flaky waitFor calls by automatically retrying actions until elements are stable. In production, teams at Microsoft and Google use Playwright to run thousands of tests in parallel across browsers, catching regressions before they hit users. If you're building a React app that needs to work reliably across browsers, Playwright is the right choice.

npm init playwright@latest -- --ct
# Or add to existing project:
npm install -D @playwright/test
npx playwright install

Setting Up Playwright for a React App

Start by installing Playwright Test and configuring it for your React project. The playwright.config.ts file is where you define browser projects, base URL, and global settings. For a typical React app (Vite or Create React App), set the baseURL to your dev server (e.g., http://localhost:5173). Use webServer to automatically start your dev server before tests. Configure projects for Chromium, Firefox, and WebKit to ensure cross-browser coverage. In production, we also add a project for mobile Safari using device emulation. Set retries to 2 for CI to handle transient failures. Use fullyParallel to run tests in parallel across workers. This setup catches environment-specific bugs early.

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

export default defineConfig({
  testDir: './e2e',
  fullyParallel: true,
  retries: 2,
  workers: 4,
  reporter: [['html'], ['list']],
  use: {
    baseURL: 'http://localhost:5173',
    trace: 'on-first-retry',
  },
  webServer: {
    command: 'npm run dev',
    port: 5173,
    reuseExistingServer: !process.env.CI,
  },
  projects: [
    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
    { name: 'firefox', use: { ...devices['Desktop Firefox'] } },
    { name: 'webkit', use: { ...devices['Desktop Safari'] } },
    { name: 'Mobile Safari', use: { ...devices['iPhone 13'] } },
  ],
});

Writing Your First React E2E Test

A Playwright test for a React component typically involves navigating to a page, interacting with elements, and asserting expected outcomes. Use page.goto() to navigate, page.locator() to find elements, and expect() for assertions. Playwright's auto-waiting means you don't need explicit waits for most actions. For React apps, prefer getByRole and getByText over CSS selectors to align with accessibility best practices. Write tests that mirror user behavior: click buttons, fill forms, and verify UI updates. Avoid testing implementation details like component state directly; instead, test what the user sees. This makes tests resilient to refactors.

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

test('user can log in with valid credentials', async ({ page }) => {
  await page.goto('/login');
  await page.getByLabel('Email').fill('user@example.com');
  await page.getByLabel('Password').fill('securePassword123');
  await page.getByRole('button', { name: 'Sign in' }).click();
  await expect(page.getByText('Welcome back, User!')).toBeVisible();
});

test('shows error on invalid credentials', async ({ page }) => {
  await page.goto('/login');
  await page.getByLabel('Email').fill('wrong@example.com');
  await page.getByLabel('Password').fill('wrong');
  await page.getByRole('button', { name: 'Sign in' }).click();
  await expect(page.getByText('Invalid email or password')).toBeVisible();
});

Mocking API Calls with Playwright

In E2E tests, you often need to control backend responses to test edge cases. Playwright's page.route() allows you to intercept network requests and return mock data. This is essential for testing loading states, error handling, and empty states without relying on a real backend. Use route.fulfill() to return a custom response, or route.abort() to simulate network failures. For React apps that use React Query or SWR, mocking at the network level ensures your data fetching logic is exercised. In production, we mock all external APIs in CI to make tests deterministic and fast.

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

test('displays loading state while fetching data', async ({ page }) => {
  // Delay the API response to show loading
  await page.route('**/api/dashboard', async route => {
    await new Promise(resolve => setTimeout(resolve, 2000));
    await route.fulfill({
      status: 200,
      contentType: 'application/json',
      body: JSON.stringify({ users: [] }),
    });
  });
  await page.goto('/dashboard');
  await expect(page.getByText('Loading...')).toBeVisible();
});

test('shows error message on API failure', async ({ page }) => {
  await page.route('**/api/dashboard', route => route.abort('connectionrefused'));
  await page.goto('/dashboard');
  await expect(page.getByText('Failed to load data')).toBeVisible();
});

Testing React Component Interactions

Playwright excels at testing complex user interactions like drag-and-drop, keyboard navigation, and multi-step forms. Use page.dragAndDrop() for drag-and-drop, page.keyboard.press() for keyboard shortcuts, and page.locator().selectOption() for dropdowns. For React apps with state management (Redux, Zustand), test the UI behavior rather than the store directly. For example, to test a todo list, add items, mark them complete, and verify the list updates. Playwright's locator API supports chaining and filtering, making it easy to target specific elements in lists.

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

test('user can add and complete todos', async ({ page }) => {
  await page.goto('/todos');
  const input = page.getByPlaceholder('Add a todo');
  await input.fill('Buy milk');
  await input.press('Enter');
  await expect(page.getByText('Buy milk')).toBeVisible();
  await page.getByRole('checkbox').check();
  await expect(page.getByText('Buy milk')).toHaveClass(/completed/);
});

test('user can delete a todo', async ({ page }) => {
  await page.goto('/todos');
  await page.getByPlaceholder('Add a todo').fill('Learn Playwright');
  await page.getByPlaceholder('Add a todo').press('Enter');
  await page.getByRole('button', { name: 'Delete' }).click();
  await expect(page.getByText('Learn Playwright')).not.toBeVisible();
});

Handling Authentication in Tests

Many React apps require authentication. Playwright provides browser.newContext() with storageState to persist cookies and localStorage across tests. For login flows, use page.request() to authenticate via API and save the state. This avoids repeating login steps in every test. In production, we create a global setup that logs in once and saves the storage state to a file. Each test then uses that state, reducing test time by 30%. For multi-role testing, create separate storage states for admin, user, etc. Remember to clear state between test suites to avoid cross-test contamination.

import { FullConfig } from '@playwright/test';

async function globalSetup(config: FullConfig) {
  const { baseURL, storageState } = config.projects[0].use;
  const browser = await chromium.launch();
  const page = await browser.newPage();
  await page.goto(baseURL + '/login');
  await page.getByLabel('Email').fill('admin@example.com');
  await page.getByLabel('Password').fill('admin123');
  await page.getByRole('button', { name: 'Sign in' }).click();
  await page.context().storageState({ path: storageState as string });
  await browser.close();
}

export default globalSetup;

Visual Regression Testing with Playwright

Visual regression tests catch unintended UI changes by comparing screenshots. Playwright's expect(page).toHaveScreenshot() captures a screenshot and compares it to a baseline. For React apps, this is invaluable for detecting CSS regressions, layout shifts, or icon changes. Use fullPage: true to capture the entire page. In CI, run visual tests only on changed components to save time. Playwright's built-in pixel matching handles anti-aliasing differences across browsers. In production, we run visual tests on every PR and require approval for baseline updates.

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

test('homepage matches snapshot', async ({ page }) => {
  await page.goto('/');
  await expect(page).toHaveScreenshot('homepage.png', {
    fullPage: true,
    maxDiffPixelRatio: 0.01,
  });
});

test('dashboard matches snapshot on mobile', async ({ page }) => {
  await page.setViewportSize({ width: 375, height: 812 });
  await page.goto('/dashboard');
  await expect(page).toHaveScreenshot('dashboard-mobile.png');
});

Running Tests in CI/CD Pipelines

Integrating Playwright tests into CI/CD is critical for catching regressions early. Use the Playwright Docker image (mcr.microsoft.com/playwright:v1.40.0-focal) for consistent browser environments. Configure your CI to run tests in parallel across multiple shards to reduce feedback time. For GitHub Actions, use the playwright-community/action-test action. Set retries to 2 for flaky tests. In production, we run E2E tests on every pull request and block merges if any test fails. Use --reporter=github for annotations directly on PRs. Cache browser binaries to speed up CI.

name: E2E Tests
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    container:
      image: mcr.microsoft.com/playwright:v1.40.0-focal
    strategy:
      matrix:
        shard: [1, 2, 3, 4]
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 18
      - run: npm ci
      - name: Cache Playwright browsers
        uses: actions/cache@v3
        with:
          path: ~/.cache/ms-playwright
          key: ${{ runner.os }}-playwright-${{ hashFiles('**/package-lock.json') }}
      - run: npx playwright test --shard=${{ matrix.shard }}/${{ strategy.jobs.test.strategy.matrix.shard | length }}
      - uses: actions/upload-artifact@v3
        if: always()
        with:
          name: playwright-report
          path: playwright-report/

Debugging Flaky Tests

Flaky tests are the enemy of reliable CI. Playwright provides several tools to debug them: --trace for trace viewer, --video for video recordings, and --screenshot for screenshots on failure. Enable trace: 'on-first-retry' in config to capture traces only when a test fails on retry. Use page.pause() to step through tests interactively. In production, we analyze traces to identify race conditions, network timing issues, or incorrect assertions. Common fixes include using toHaveText instead of toBeVisible, adding waitForLoadState('networkidle'), or increasing timeouts for slow API calls.

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

test('flaky test example', async ({ page }) => {
  await page.goto('/slow-page');
  // Use waitForLoadState to ensure network is idle
  await page.waitForLoadState('networkidle');
  const text = page.getByText('Loaded');
  await expect(text).toBeVisible({ timeout: 10000 });
});

test('debug with trace', async ({ page }) => {
  await page.goto('/');
  await page.getByRole('button').click();
  // page.pause(); // Uncomment to step through
  await expect(page.getByText('Success')).toBeVisible();
});

Testing Accessibility with Playwright

Accessibility testing ensures your React app is usable by people with disabilities. Playwright integrates with @axe-core/playwright to run automated accessibility audits. Use page.axe() to scan the page and assert no violations. In production, we run accessibility tests on every page and fail the build if critical violations are found. Combine with manual keyboard navigation tests using page.keyboard. For React apps, ensure all interactive elements have accessible names and roles. This catches issues like missing labels, low contrast, or missing ARIA attributes.

import { test, expect } from '@playwright/test';
import AxeBuilder from '@axe-core/playwright';

test('homepage has no accessibility violations', async ({ page }) => {
  await page.goto('/');
  const results = await new AxeBuilder({ page }).analyze();
  expect(results.violations).toEqual([]);
});

test('login form is keyboard navigable', async ({ page }) => {
  await page.goto('/login');
  await page.keyboard.press('Tab');
  await expect(page.getByLabel('Email')).toBeFocused();
  await page.keyboard.press('Tab');
  await expect(page.getByLabel('Password')).toBeFocused();
  await page.keyboard.press('Tab');
  await expect(page.getByRole('button', { name: 'Sign in' })).toBeFocused();
});

Testing React Router Navigation

Single-page applications rely on client-side routing. Playwright can test navigation without full page reloads. Use page.waitForURL() to wait for a specific route after clicking a link. For React Router, test that the correct component renders for each route. Also test error routes (404 pages) and redirects. In production, we test that protected routes redirect to login when unauthenticated. Use page.goBack() and page.goForward() to test browser history. This ensures your routing logic works correctly across browsers.

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

test('navigates to about page', async ({ page }) => {
  await page.goto('/');
  await page.getByRole('link', { name: 'About' }).click();
  await expect(page).toHaveURL('/about');
  await expect(page.getByText('About Us')).toBeVisible();
});

test('shows 404 page for unknown routes', async ({ page }) => {
  await page.goto('/nonexistent');
  await expect(page.getByText('Page Not Found')).toBeVisible();
});

test('redirects to login when accessing protected route', async ({ page }) => {
  await page.goto('/dashboard');
  await expect(page).toHaveURL('/login');
});

Performance Testing with Playwright

Playwright can capture performance metrics like page load time, time to interactive, and largest contentful paint. Use page.metrics() to get performance data. For React apps, monitor component render times and network request durations. In production, we set performance budgets in CI: fail the test if load time exceeds 3 seconds. Use page.coverage to measure JavaScript and CSS coverage. This helps identify unused code. Combine with Lighthouse CI for comprehensive performance audits. Performance tests should run on a dedicated, consistent environment to avoid variance.

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

test('homepage loads within performance budget', async ({ page }) => {
  await page.goto('/', { waitUntil: 'networkidle' });
  const metrics = await page.metrics();
  const loadTime = metrics.DomContentLoaded;
  expect(loadTime).toBeLessThan(3000); // 3 seconds
  console.log(`DomContentLoaded: ${loadTime}ms`);
});

test('measures largest contentful paint', async ({ page }) => {
  await page.goto('/');
  const lcp = await page.evaluate(() => {
    return new Promise(resolve => {
      new PerformanceObserver(list => {
        resolve(list.getEntries()[0].startTime);
      }).observe({ type: 'largest-contentful-paint', buffered: true });
    });
  });
  expect(lcp).toBeLessThan(2500);
});

Playwright Component Testing

Playwright Component Testing allows you to test individual React components in isolation using the same Playwright API. With @playwright/experimental-ct-react, you can mount components directly in a browser environment, enabling interaction and assertions without a full app. This is ideal for testing component behavior, props, and state changes. To get started, install the package and configure Playwright to use React. Then, write test files that import and mount components. For example, you can test a button component by mounting it, clicking it, and verifying the resulting state or DOM changes. This approach provides faster feedback and more focused tests compared to full-page E2E tests. Component tests run in real browsers, ensuring realistic rendering and event handling. They also support Playwright's locators and assertions, making them powerful for UI-driven development. Use component testing to complement your E2E suite, especially for complex or reusable components.

import { test, expect } from '@playwright/experimental-ct-react';
import Button from './Button';

test('should increment count on click', async ({ mount }) => {
  const component = await mount(<Button />);
  await component.click();
  await expect(component).toContainText('Clicked 1 time');
});

Playwright UI Mode

Playwright UI Mode provides an interactive interface for developing and debugging tests. Instead of running tests headlessly, you can open a browser window where tests execute step by step. This mode allows you to inspect the DOM, view locator suggestions, and see the test timeline. To use UI Mode, run npx playwright test --ui. The UI shows a list of tests, their status, and a timeline of actions. You can hover over each action to see the corresponding screenshot and DOM snapshot. This is invaluable for debugging flaky tests or writing new tests. You can also use the locator picker to generate robust selectors. UI Mode supports watch mode, re-running tests on file changes. It integrates with VS Code via the Playwright extension. For CI, you can still run tests headlessly; UI Mode is strictly for local development. Adopting UI Mode can significantly speed up test creation and debugging, especially for complex interactions.

npx playwright test --ui

Sharding and Parallel Execution

Sharding and parallel execution are essential for reducing CI test times. Playwright supports sharding by splitting tests across multiple machines. Use the --shard flag to specify the shard index and total shards. For example, npx playwright test --shard=1/4 runs the first quarter of tests. In CI, you can configure parallel jobs, each running a different shard. Playwright also supports parallel execution within a single machine using multiple workers. Set workers in the Playwright config to the number of CPU cores. For large test suites, sharding across machines provides linear scaling. Combine sharding with test retries and project dependencies for optimal CI performance. Ensure tests are independent and can run in any order. Use test.describe.configure({ mode: 'parallel' }) for within-file parallelization. Sharding is particularly useful when tests are slow or numerous. It reduces the feedback loop, allowing developers to get results faster.

import { defineConfig } from '@playwright/test';
export default defineConfig({
  workers: process.env.CI ? 4 : undefined,
  retries: process.env.CI ? 2 : 0,
});