Testing React Apps with Playwright

When to use: Testing React applications built with Create React App (CRA), Vite, or custom bundlers. Covers E2E testing, experimental component testing, React Router navigation, form libraries, portals, error boundaries, and context/state verification through the UI. Prerequisites: core/configuration.md, core/locators.md

Quick Reference

# Install Playwright in a React project
npm init playwright@latest

# Install component testing (experimental)
npm install -D @playwright/experimental-ct-react

# Run E2E tests
npx playwright test

# Run component tests
npx playwright test -c playwright-ct.config.ts

# Debug a specific test
npx playwright test tests/login.spec.ts --headed --debug

Setup

Playwright Config for React (Vite)

TypeScript

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

export default defineConfig({
  testDir: './tests',
  testMatch: '**/*.spec.ts',
  fullyParallel: true,
  forbidOnly: !!process.env.CI,
  retries: process.env.CI ? 2 : 0,
  workers: process.env.CI ? '50%' : undefined,

  use: {
    baseURL: 'http://localhost:5173', // Vite default port
    trace: 'on-first-retry',
    screenshot: 'only-on-failure',
  },

  projects: [
    {
      name: 'chromium',
      use: { ...devices['Desktop Chrome'] },
    },
    {
      name: 'firefox',
      use: { ...devices['Desktop Firefox'] },
    },
    {
      name: 'mobile',
      use: { ...devices['iPhone 14'] },
    },
  ],

  webServer: {
    command: process.env.CI
      ? 'npm run build && npx serve -s build -l 5173' // CRA
      // ? 'npm run build && npx vite preview --port 5173' // Vite
      : 'npm run dev',
    url: 'http://localhost:5173',
    reuseExistingServer: !process.env.CI,
    timeout: 120_000,
  },
});

JavaScript

// playwright.config.js
const { defineConfig, devices } = require('@playwright/test');

module.exports = defineConfig({
  testDir: './tests',
  testMatch: '**/*.spec.js',
  fullyParallel: true,
  forbidOnly: !!process.env.CI,
  retries: process.env.CI ? 2 : 0,
  workers: process.env.CI ? '50%' : undefined,

  use: {
    baseURL: 'http://localhost:5173',
    trace: 'on-first-retry',
    screenshot: 'only-on-failure',
  },

  projects: [
    {
      name: 'chromium',
      use: { ...devices['Desktop Chrome'] },
    },
    {
      name: 'firefox',
      use: { ...devices['Desktop Firefox'] },
    },
    {
      name: 'mobile',
      use: { ...devices['iPhone 14'] },
    },
  ],

  webServer: {
    command: process.env.CI
      ? 'npm run build && npx serve -s build -l 5173'
      : 'npm run dev',
    url: 'http://localhost:5173',
    reuseExistingServer: !process.env.CI,
    timeout: 120_000,
  },
});

Component Testing Config

Component testing mounts individual React components in a real browser without a full dev server. This is experimental but useful for testing complex components in isolation.

TypeScript

// playwright-ct.config.ts
import { defineConfig, devices } from '@playwright/experimental-ct-react';

export default defineConfig({
  testDir: './tests/components',
  testMatch: '**/*.ct.ts',

  use: {
    trace: 'on-first-retry',
    ctPort: 3100,
  },

  projects: [
    {
      name: 'chromium',
      use: { ...devices['Desktop Chrome'] },
    },
  ],
});

JavaScript

// playwright-ct.config.js
const { defineConfig, devices } = require('@playwright/experimental-ct-react');

module.exports = defineConfig({
  testDir: './tests/components',
  testMatch: '**/*.ct.js',

  use: {
    trace: 'on-first-retry',
    ctPort: 3100,
  },

  projects: [
    {
      name: 'chromium',
      use: { ...devices['Desktop Chrome'] },
    },
  ],
});

Patterns

Component Testing with `@playwright/experimental-ct-react`

Use when: Testing complex interactive components in isolation -- data tables, form wizards, rich text editors, dropdowns with keyboard navigation. The component needs a real browser (not jsdom) but not a full application. Avoid when: The component behavior depends heavily on backend data or routing context. Use E2E tests instead.

TypeScript

// tests/components/Counter.ct.ts
import { test, expect } from '@playwright/experimental-ct-react';
import Counter from '../../src/components/Counter';

test('increments count on button click', async ({ mount }) => {
  const component = await mount(<Counter initialCount={0} />);

  await expect(component.getByText('Count: 0')).toBeVisible();
  await component.getByRole('button', { name: 'Increment' }).click();
  await expect(component.getByText('Count: 1')).toBeVisible();
});

test('decrements count on button click', async ({ mount }) => {
  const component = await mount(<Counter initialCount={5} />);

  await component.getByRole('button', { name: 'Decrement' }).click();
  await expect(component.getByText('Count: 4')).toBeVisible();
});

test('calls onChange callback when count changes', async ({ mount }) => {
  const values: number[] = [];
  const component = await mount(
    <Counter initialCount={0} onChange={(val) => values.push(val)} />
  );

  await component.getByRole('button', { name: 'Increment' }).click();
  await component.getByRole('button', { name: 'Increment' }).click();

  expect(values).toEqual([1, 2]);
});

test('disables decrement at zero when min is set', async ({ mount }) => {
  const component = await mount(<Counter initialCount={0} min={0} />);

  await expect(component.getByRole('button', { name: 'Decrement' })).toBeDisabled();
});

JavaScript

// tests/components/Counter.ct.js
const { test, expect } = require('@playwright/experimental-ct-react');
const Counter = require('../../src/components/Counter');

test('increments count on button click', async ({ mount }) => {
  const component = await mount(<Counter initialCount={0} />);

  await expect(component.getByText('Count: 0')).toBeVisible();
  await component.getByRole('button', { name: 'Increment' }).click();
  await expect(component.getByText('Count: 1')).toBeVisible();
});

test('decrements count on button click', async ({ mount }) => {
  const component = await mount(<Counter initialCount={5} />);

  await component.getByRole('button', { name: 'Decrement' }).click();
  await expect(component.getByText('Count: 4')).toBeVisible();
});

test('calls onChange callback when count changes', async ({ mount }) => {
  const values = [];
  const component = await mount(
    <Counter initialCount={0} onChange={(val) => values.push(val)} />
  );

  await component.getByRole('button', { name: 'Increment' }).click();
  await component.getByRole('button', { name: 'Increment' }).click();

  expect(values).toEqual([1, 2]);
});

Testing Hooks Indirectly Through the UI

Use when: Verifying that custom hooks produce the correct UI behavior. Playwright cannot call hooks directly -- test them through the components that consume them. Avoid when: The hook logic is pure computation with no UI side effects -- use a unit testing framework for that.

TypeScript

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

test.describe('useDebounce hook (tested through SearchInput)', () => {
  test('debounced search triggers after user stops typing', async ({ page }) => {
    await page.goto('/search');

    // Set up a response interceptor to track API calls
    const apiCalls: string[] = [];
    await page.route('**/api/search*', async (route) => {
      apiCalls.push(route.request().url());
      await route.continue();
    });

    // Type quickly -- the debounce hook should batch these
    await page.getByRole('textbox', { name: 'Search' }).pressSequentially('playwright', {
      delay: 50,
    });

    // Wait for results to appear (debounce has fired)
    await expect(page.getByRole('listitem')).toHaveCount(5);

    // The debounced hook should have made 1-2 API calls, not 10 (one per keystroke)
    expect(apiCalls.length).toBeLessThanOrEqual(2);
  });
});

test.describe('usePagination hook (tested through ProductList)', () => {
  test('pagination controls navigate between pages', async ({ page }) => {
    await page.goto('/products');

    await expect(page.getByText('Page 1 of 5')).toBeVisible();

    await page.getByRole('button', { name: 'Next page' }).click();
    await expect(page.getByText('Page 2 of 5')).toBeVisible();

    await page.getByRole('button', { name: 'Previous page' }).click();
    await expect(page.getByText('Page 1 of 5')).toBeVisible();

    // First page: previous should be disabled
    await expect(page.getByRole('button', { name: 'Previous page' })).toBeDisabled();
  });
});

JavaScript

const { test, expect } = require('@playwright/test');

test.describe('useDebounce hook (tested through SearchInput)', () => {
  test('debounced search triggers after user stops typing', async ({ page }) => {
    await page.goto('/search');

    const apiCalls = [];
    await page.route('**/api/search*', async (route) => {
      apiCalls.push(route.request().url());
      await route.continue();
    });

    await page.getByRole('textbox', { name: 'Search' }).pressSequentially('playwright', {
      delay: 50,
    });

    await expect(page.getByRole('listitem')).toHaveCount(5);
    expect(apiCalls.length).toBeLessThanOrEqual(2);
  });
});

test.describe('usePagination hook (tested through ProductList)', () => {
  test('pagination controls navigate between pages', async ({ page }) => {
    await page.goto('/products');

    await expect(page.getByText('Page 1 of 5')).toBeVisible();

    await page.getByRole('button', { name: 'Next page' }).click();
    await expect(page.getByText('Page 2 of 5')).toBeVisible();

    await page.getByRole('button', { name: 'Previous page' }).click();
    await expect(page.getByText('Page 1 of 5')).toBeVisible();

    await expect(page.getByRole('button', { name: 'Previous page' })).toBeDisabled();
  });
});

Testing Context and State Changes Through User Interactions

Use when: Verifying that React context (theme, auth, locale) and state management (Redux, Zustand, Jotai) produce correct UI changes. Avoid when: You want to assert on the raw state object -- Playwright tests the UI, not internal state. If the UI is correct, the state is correct.

TypeScript

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

test.describe('theme context', () => {
  test('dark mode toggle changes the visual theme', async ({ page }) => {
    await page.goto('/settings');

    // Verify initial light mode
    const body = page.locator('body');
    await expect(body).not.toHaveClass(/dark/);

    // Toggle dark mode
    await page.getByRole('switch', { name: 'Dark mode' }).click();

    // Verify dark mode is applied
    await expect(body).toHaveClass(/dark/);

    // Verify the toggle state persists after navigation
    await page.getByRole('link', { name: 'Home' }).click();
    await expect(page.locator('body')).toHaveClass(/dark/);
  });
});

test.describe('shopping cart state', () => {
  test('adding items updates cart badge across pages', async ({ page }) => {
    await page.goto('/products');

    // Cart badge should show 0 or be hidden
    const cartBadge = page.getByTestId('cart-count');

    // Add first item
    await page.getByRole('listitem')
      .filter({ hasText: 'Running Shoes' })
      .getByRole('button', { name: 'Add to cart' })
      .click();
    await expect(cartBadge).toHaveText('1');

    // Add second item
    await page.getByRole('listitem')
      .filter({ hasText: 'Trail Jacket' })
      .getByRole('button', { name: 'Add to cart' })
      .click();
    await expect(cartBadge).toHaveText('2');

    // Navigate to a different page -- cart count persists (global state)
    await page.getByRole('link', { name: 'About' }).click();
    await expect(cartBadge).toHaveText('2');
  });
});

test.describe('auth context', () => {
  test('login updates the UI across all components consuming auth context', async ({ page }) => {
    await page.goto('/');

    // Unauthenticated state
    await expect(page.getByRole('link', { name: 'Sign in' })).toBeVisible();
    await expect(page.getByRole('button', { name: 'Sign out' })).toBeHidden();

    // Log in
    await page.getByRole('link', { name: 'Sign in' }).click();
    await page.getByLabel('Email').fill('user@example.com');
    await page.getByLabel('Password').fill('password123');
    await page.getByRole('button', { name: 'Sign in' }).click();

    // Authenticated state -- multiple components update
    await expect(page.getByRole('link', { name: 'Sign in' })).toBeHidden();
    await expect(page.getByText('user@example.com')).toBeVisible();
    await expect(page.getByRole('button', { name: 'Sign out' })).toBeVisible();
  });
});

JavaScript

const { test, expect } = require('@playwright/test');

test.describe('theme context', () => {
  test('dark mode toggle changes the visual theme', async ({ page }) => {
    await page.goto('/settings');

    const body = page.locator('body');
    await expect(body).not.toHaveClass(/dark/);

    await page.getByRole('switch', { name: 'Dark mode' }).click();

    await expect(body).toHaveClass(/dark/);

    await page.getByRole('link', { name: 'Home' }).click();
    await expect(page.locator('body')).toHaveClass(/dark/);
  });
});

test.describe('shopping cart state', () => {
  test('adding items updates cart badge across pages', async ({ page }) => {
    await page.goto('/products');

    const cartBadge = page.getByTestId('cart-count');

    await page.getByRole('listitem')
      .filter({ hasText: 'Running Shoes' })
      .getByRole('button', { name: 'Add to cart' })
      .click();
    await expect(cartBadge).toHaveText('1');

    await page.getByRole('listitem')
      .filter({ hasText: 'Trail Jacket' })
      .getByRole('button', { name: 'Add to cart' })
      .click();
    await expect(cartBadge).toHaveText('2');

    await page.getByRole('link', { name: 'About' }).click();
    await expect(cartBadge).toHaveText('2');
  });
});

Testing React Router Navigation

Use when: Testing client-side routing with React Router v6+. Verify route transitions, URL parameters, protected routes, and browser history behavior. Avoid when: Your app uses server-side routing only (Next.js App Router handles this differently -- see core/nextjs.md).

TypeScript

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

test.describe('React Router navigation', () => {
  test('client-side navigation does not cause full page reload', async ({ page }) => {
    await page.goto('/');

    // Store a marker in window to detect full reload
    await page.evaluate(() => {
      (window as any).__testMarker = 'no-reload';
    });

    // Navigate via a React Router Link
    await page.getByRole('link', { name: 'Products' }).click();
    await page.waitForURL('/products');

    // If the page fully reloaded, the marker would be gone
    const marker = await page.evaluate(() => (window as any).__testMarker);
    expect(marker).toBe('no-reload');
  });

  test('URL params update the page content', async ({ page }) => {
    await page.goto('/products?category=electronics');

    await expect(page.getByRole('heading', { name: 'Electronics' })).toBeVisible();

    // Change category via UI interaction (which updates the URL param)
    await page.getByRole('link', { name: 'Clothing' }).click();
    await page.waitForURL('/products?category=clothing');

    await expect(page.getByRole('heading', { name: 'Clothing' })).toBeVisible();
  });

  test('nested routes render parent and child layouts', async ({ page }) => {
    await page.goto('/settings/profile');

    // Parent layout (Settings)
    await expect(page.getByRole('heading', { name: 'Settings' })).toBeVisible();
    await expect(page.getByRole('navigation', { name: 'Settings' })).toBeVisible();

    // Child route (Profile)
    await expect(page.getByRole('heading', { name: 'Profile', level: 2 })).toBeVisible();

    // Navigate to sibling route
    await page.getByRole('link', { name: 'Notifications' }).click();
    await page.waitForURL('/settings/notifications');

    // Parent layout persists
    await expect(page.getByRole('heading', { name: 'Settings' })).toBeVisible();
    await expect(page.getByRole('heading', { name: 'Notifications', level: 2 })).toBeVisible();
  });

  test('browser back button works with client-side routing', async ({ page }) => {
    await page.goto('/');
    await page.getByRole('link', { name: 'Products' }).click();
    await page.waitForURL('/products');
    await page.getByRole('link', { name: 'About' }).click();
    await page.waitForURL('/about');

    // Go back
    await page.goBack();
    await expect(page).toHaveURL(/\/products/);

    await page.goBack();
    await expect(page).toHaveURL(/\/$/);
  });

  test('protected route redirects unauthenticated users', async ({ page }) => {
    await page.goto('/admin');

    // React Router's protected route should redirect to login
    await expect(page).toHaveURL(/\/login/);
    await expect(page.getByRole('heading', { name: 'Sign in' })).toBeVisible();
  });

  test('404 route shows not found page', async ({ page }) => {
    await page.goto('/this-route-does-not-exist');

    await expect(page.getByRole('heading', { name: 'Page Not Found' })).toBeVisible();
    await expect(page.getByRole('link', { name: 'Go home' })).toBeVisible();
  });
});

JavaScript

const { test, expect } = require('@playwright/test');

test.describe('React Router navigation', () => {
  test('client-side navigation does not cause full page reload', async ({ page }) => {
    await page.goto('/');

    await page.evaluate(() => {
      window.__testMarker = 'no-reload';
    });

    await page.getByRole('link', { name: 'Products' }).click();
    await page.waitForURL('/products');

    const marker = await page.evaluate(() => window.__testMarker);
    expect(marker).toBe('no-reload');
  });

  test('URL params update the page content', async ({ page }) => {
    await page.goto('/products?category=electronics');

    await expect(page.getByRole('heading', { name: 'Electronics' })).toBeVisible();

    await page.getByRole('link', { name: 'Clothing' }).click();
    await page.waitForURL('/products?category=clothing');

    await expect(page.getByRole('heading', { name: 'Clothing' })).toBeVisible();
  });

  test('browser back button works with client-side routing', async ({ page }) => {
    await page.goto('/');
    await page.getByRole('link', { name: 'Products' }).click();
    await page.waitForURL('/products');
    await page.getByRole('link', { name: 'About' }).click();
    await page.waitForURL('/about');

    await page.goBack();
    await expect(page).toHaveURL(/\/products/);

    await page.goBack();
    await expect(page).toHaveURL(/\/$/);
  });

  test('protected route redirects unauthenticated users', async ({ page }) => {
    await page.goto('/admin');

    await expect(page).toHaveURL(/\/login/);
    await expect(page.getByRole('heading', { name: 'Sign in' })).toBeVisible();
  });
});

Testing Form Libraries (React Hook Form, Formik)

Use when: Testing forms built with react-hook-form, Formik, or similar libraries. Playwright interacts with the DOM, so the form library is transparent -- test the user experience, not the library internals. Avoid when: Testing the form library itself. You are testing YOUR form behavior.

TypeScript

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

test.describe('registration form (react-hook-form)', () => {
  test.beforeEach(async ({ page }) => {
    await page.goto('/register');
  });

  test('shows validation errors on submit with empty fields', async ({ page }) => {
    await page.getByRole('button', { name: 'Create account' }).click();

    // react-hook-form shows errors after submit attempt
    await expect(page.getByText('Email is required')).toBeVisible();
    await expect(page.getByText('Password is required')).toBeVisible();
  });

  test('shows inline validation on blur', async ({ page }) => {
    const emailInput = page.getByLabel('Email');
    await emailInput.fill('not-an-email');
    await emailInput.blur();

    // react-hook-form with mode: 'onBlur' validates immediately
    await expect(page.getByText('Invalid email address')).toBeVisible();
  });

  test('password requirements update in real time', async ({ page }) => {
    const passwordInput = page.getByLabel('Password', { exact: true });

    await passwordInput.fill('short');
    await expect(page.getByText('At least 8 characters')).toHaveClass(/text-red/);

    await passwordInput.fill('longenough');
    await expect(page.getByText('At least 8 characters')).toHaveClass(/text-green/);

    await passwordInput.fill('LongEnough1!');
    await expect(page.getByText('Contains uppercase')).toHaveClass(/text-green/);
    await expect(page.getByText('Contains number')).toHaveClass(/text-green/);
    await expect(page.getByText('Contains special character')).toHaveClass(/text-green/);
  });

  test('successful registration submits form and redirects', async ({ page }) => {
    await page.getByLabel('Full name').fill('Jane Doe');
    await page.getByLabel('Email').fill('jane@example.com');
    await page.getByLabel('Password', { exact: true }).fill('Str0ng!Pass');
    await page.getByLabel('Confirm password').fill('Str0ng!Pass');
    await page.getByLabel('I agree to the terms').check();

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

    await page.waitForURL('/dashboard');
    await expect(page.getByText('Welcome, Jane')).toBeVisible();
  });

  test('disables submit button while form is submitting', async ({ page }) => {
    // Slow down the API to observe the submitting state
    await page.route('**/api/register', async (route) => {
      await new Promise((resolve) => setTimeout(resolve, 1000));
      await route.fulfill({
        status: 201,
        contentType: 'application/json',
        body: JSON.stringify({ id: 1, email: 'jane@example.com' }),
      });
    });

    await page.getByLabel('Full name').fill('Jane Doe');
    await page.getByLabel('Email').fill('jane@example.com');
    await page.getByLabel('Password', { exact: true }).fill('Str0ng!Pass');
    await page.getByLabel('Confirm password').fill('Str0ng!Pass');
    await page.getByLabel('I agree to the terms').check();

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

    // Button should show loading state
    await expect(page.getByRole('button', { name: /Creating|Loading|Submitting/ })).toBeDisabled();
  });
});

JavaScript

const { test, expect } = require('@playwright/test');

test.describe('registration form (react-hook-form)', () => {
  test.beforeEach(async ({ page }) => {
    await page.goto('/register');
  });

  test('shows validation errors on submit with empty fields', async ({ page }) => {
    await page.getByRole('button', { name: 'Create account' }).click();

    await expect(page.getByText('Email is required')).toBeVisible();
    await expect(page.getByText('Password is required')).toBeVisible();
  });

  test('shows inline validation on blur', async ({ page }) => {
    const emailInput = page.getByLabel('Email');
    await emailInput.fill('not-an-email');
    await emailInput.blur();

    await expect(page.getByText('Invalid email address')).toBeVisible();
  });

  test('successful registration submits form and redirects', async ({ page }) => {
    await page.getByLabel('Full name').fill('Jane Doe');
    await page.getByLabel('Email').fill('jane@example.com');
    await page.getByLabel('Password', { exact: true }).fill('Str0ng!Pass');
    await page.getByLabel('Confirm password').fill('Str0ng!Pass');
    await page.getByLabel('I agree to the terms').check();

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

    await page.waitForURL('/dashboard');
    await expect(page.getByText('Welcome, Jane')).toBeVisible();
  });
});

Testing React Portals (Modals, Tooltips, Dropdowns)

Use when: Testing components rendered via ReactDOM.createPortal() -- modals, dialogs, tooltips, dropdown menus, toast notifications. These render outside the parent DOM hierarchy, but Playwright sees the full document. Avoid when: The component is not a portal -- it renders inline.

TypeScript

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

test.describe('portals', () => {
  test('modal opens and is accessible', async ({ page }) => {
    await page.goto('/products');

    await page.getByRole('button', { name: 'Delete product' }).first().click();

    // Modal is rendered via a portal to document.body, but Playwright
    // sees it like any other element
    const modal = page.getByRole('dialog', { name: 'Confirm deletion' });
    await expect(modal).toBeVisible();

    // Verify focus is trapped inside the modal
    await expect(modal.getByRole('button', { name: 'Cancel' })).toBeFocused();

    // Verify backdrop/overlay blocks interaction with elements behind
    // (Playwright will auto-wait for the element to be actionable)
    await modal.getByRole('button', { name: 'Delete' }).click();
    await expect(modal).toBeHidden();
  });

  test('modal closes on Escape key', async ({ page }) => {
    await page.goto('/products');
    await page.getByRole('button', { name: 'Delete product' }).first().click();

    const modal = page.getByRole('dialog', { name: 'Confirm deletion' });
    await expect(modal).toBeVisible();

    await page.keyboard.press('Escape');
    await expect(modal).toBeHidden();
  });

  test('tooltip shows on hover and hides on leave', async ({ page }) => {
    await page.goto('/dashboard');

    const triggerButton = page.getByRole('button', { name: 'Info' });
    await triggerButton.hover();

    // Tooltip rendered via portal
    await expect(page.getByRole('tooltip')).toBeVisible();
    await expect(page.getByRole('tooltip')).toContainText('Click for more details');

    // Move mouse away
    await page.mouse.move(0, 0);
    await expect(page.getByRole('tooltip')).toBeHidden();
  });

  test('toast notifications stack and auto-dismiss', async ({ page }) => {
    await page.goto('/settings');

    // Trigger multiple toasts
    await page.getByRole('button', { name: 'Save' }).click();
    await expect(page.getByText('Settings saved')).toBeVisible();

    // Toast should auto-dismiss after a delay
    await expect(page.getByText('Settings saved')).toBeHidden({ timeout: 10_000 });
  });

  test('dropdown menu rendered via portal positions correctly', async ({ page }) => {
    await page.goto('/dashboard');

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

    const menu = page.getByRole('menu');
    await expect(menu).toBeVisible();
    await expect(menu.getByRole('menuitem', { name: 'Edit' })).toBeVisible();
    await expect(menu.getByRole('menuitem', { name: 'Delete' })).toBeVisible();

    // Click a menu item
    await menu.getByRole('menuitem', { name: 'Edit' }).click();
    await expect(menu).toBeHidden();
  });
});

JavaScript

const { test, expect } = require('@playwright/test');

test.describe('portals', () => {
  test('modal opens and is accessible', async ({ page }) => {
    await page.goto('/products');

    await page.getByRole('button', { name: 'Delete product' }).first().click();

    const modal = page.getByRole('dialog', { name: 'Confirm deletion' });
    await expect(modal).toBeVisible();
    await expect(modal.getByRole('button', { name: 'Cancel' })).toBeFocused();

    await modal.getByRole('button', { name: 'Delete' }).click();
    await expect(modal).toBeHidden();
  });

  test('modal closes on Escape key', async ({ page }) => {
    await page.goto('/products');
    await page.getByRole('button', { name: 'Delete product' }).first().click();

    const modal = page.getByRole('dialog', { name: 'Confirm deletion' });
    await expect(modal).toBeVisible();

    await page.keyboard.press('Escape');
    await expect(modal).toBeHidden();
  });

  test('tooltip shows on hover and hides on leave', async ({ page }) => {
    await page.goto('/dashboard');

    await page.getByRole('button', { name: 'Info' }).hover();
    await expect(page.getByRole('tooltip')).toBeVisible();

    await page.mouse.move(0, 0);
    await expect(page.getByRole('tooltip')).toBeHidden();
  });
});

Testing Error Boundaries

Use when: Verifying that React error boundaries catch rendering errors gracefully and show fallback UI instead of a white screen. Avoid when: You are testing error handling in event handlers or async code -- error boundaries only catch rendering errors.

TypeScript

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

test.describe('error boundaries', () => {
  test('error boundary shows fallback UI when child crashes', async ({ page }) => {
    // Capture console errors to verify the error was thrown
    const consoleErrors: string[] = [];
    page.on('console', (msg) => {
      if (msg.type() === 'error') {
        consoleErrors.push(msg.text());
      }
    });

    await page.goto('/dashboard');

    // Trigger an action that causes a component to throw during render
    // (e.g., a component that crashes on specific data)
    await page.route('**/api/dashboard/widgets', (route) => {
      route.fulfill({
        status: 200,
        contentType: 'application/json',
        body: JSON.stringify({ widgets: null }), // null causes .map() to throw
      });
    });

    await page.reload();

    // Error boundary should catch the error and show fallback
    await expect(page.getByText('Something went wrong')).toBeVisible();
    await expect(page.getByRole('button', { name: 'Try again' })).toBeVisible();

    // The rest of the page should still be functional
    await expect(page.getByRole('navigation', { name: 'Main' })).toBeVisible();
  });

  test('retry button in error boundary recovers the component', async ({ page }) => {
    let requestCount = 0;
    await page.route('**/api/dashboard/widgets', (route) => {
      requestCount++;
      if (requestCount === 1) {
        // First request: return bad data that crashes the component
        route.fulfill({
          status: 200,
          contentType: 'application/json',
          body: JSON.stringify({ widgets: null }),
        });
      } else {
        // Subsequent requests: return good data
        route.fulfill({
          status: 200,
          contentType: 'application/json',
          body: JSON.stringify({ widgets: [{ id: 1, name: 'Sales' }] }),
        });
      }
    });

    await page.goto('/dashboard');

    // Error boundary shows fallback
    await expect(page.getByText('Something went wrong')).toBeVisible();

    // Click retry -- component re-mounts with good data
    await page.getByRole('button', { name: 'Try again' }).click();

    // Component recovers
    await expect(page.getByText('Something went wrong')).toBeHidden();
    await expect(page.getByText('Sales')).toBeVisible();
  });
});

JavaScript

const { test, expect } = require('@playwright/test');

test.describe('error boundaries', () => {
  test('error boundary shows fallback UI when child crashes', async ({ page }) => {
    const consoleErrors = [];
    page.on('console', (msg) => {
      if (msg.type() === 'error') {
        consoleErrors.push(msg.text());
      }
    });

    await page.route('**/api/dashboard/widgets', (route) => {
      route.fulfill({
        status: 200,
        contentType: 'application/json',
        body: JSON.stringify({ widgets: null }),
      });
    });

    await page.goto('/dashboard');

    await expect(page.getByText('Something went wrong')).toBeVisible();
    await expect(page.getByRole('button', { name: 'Try again' })).toBeVisible();
    await expect(page.getByRole('navigation', { name: 'Main' })).toBeVisible();
  });

  test('retry button in error boundary recovers the component', async ({ page }) => {
    let requestCount = 0;
    await page.route('**/api/dashboard/widgets', (route) => {
      requestCount++;
      if (requestCount === 1) {
        route.fulfill({
          status: 200,
          contentType: 'application/json',
          body: JSON.stringify({ widgets: null }),
        });
      } else {
        route.fulfill({
          status: 200,
          contentType: 'application/json',
          body: JSON.stringify({ widgets: [{ id: 1, name: 'Sales' }] }),
        });
      }
    });

    await page.goto('/dashboard');

    await expect(page.getByText('Something went wrong')).toBeVisible();
    await page.getByRole('button', { name: 'Try again' }).click();

    await expect(page.getByText('Something went wrong')).toBeHidden();
    await expect(page.getByText('Sales')).toBeVisible();
  });
});

Framework-Specific Tips

CRA vs Vite: Key Differences

Aspect	Create React App (CRA)	Vite
Default port	`3000`	`5173`
Build output	`build/`	`dist/`
Serve production build	`npx serve -s build -l 3000`	`npx vite preview --port 5173`
Environment variables	`REACT_APP_*` prefix	`VITE_*` prefix
Dev server start time	Slow (Webpack)	Fast (esbuild)

Adjust your webServer.command and baseURL accordingly.

React Strict Mode and Double Effects

React Strict Mode in development runs effects twice. This can cause unexpected behavior in tests (e.g., double API calls). Your tests should be resilient to this:

Do not assert on exact API call counts in development mode
If you test API call counts, run against a production build or account for double invocations

Testing Suspense and Lazy Components

// React.lazy() components show a fallback while loading
test('lazy-loaded route shows spinner then content', async ({ page }) => {
  await page.goto('/');

  // Navigate to a lazy route
  await page.getByRole('link', { name: 'Reports' }).click();

  // The reports module loads lazily -- you may briefly see a spinner
  // Playwright auto-waits for the final content
  await expect(page.getByRole('heading', { name: 'Reports' })).toBeVisible();
});

Component Testing: When to Use It vs E2E

Scenario	Use Component Testing	Use E2E
Complex dropdown with keyboard navigation	Yes -- test in isolation with mount()	Also yes -- verify it works within the page
Data table with sorting, filtering, pagination	Yes -- control props directly	Also yes -- verify API integration
Button that submits a form	No -- trivial in isolation	Yes -- test the full form flow
Theme toggle component	Yes -- verify visual changes	Also yes -- verify persistence
Login form connected to auth context	No -- too many dependencies	Yes -- test the real flow

Detecting Memory Leaks in Long-Running Tests

If your React app has unmounted component state updates (the "Can't perform a React state update on an unmounted component" warning), catch them:

test('no state-update-on-unmounted warnings during navigation', async ({ page }) => {
  const warnings: string[] = [];
  page.on('console', (msg) => {
    if (msg.type() === 'warning' && msg.text().includes('unmounted')) {
      warnings.push(msg.text());
    }
  });

  // Rapid navigation to trigger unmount edge cases
  await page.goto('/dashboard');
  await page.getByRole('link', { name: 'Settings' }).click();
  await page.goBack();
  await page.getByRole('link', { name: 'Profile' }).click();
  await page.goBack();

  expect(warnings).toEqual([]);
});

Anti-Patterns

Don't Do This	Problem	Do This Instead
`page.evaluate(() => store.getState())` to assert Redux state	Couples tests to implementation; state shape changes break tests	Assert on the UI that the state produces: `expect(cartBadge).toHaveText('3')`
Import React components in E2E test files	E2E tests run in Node.js, not the browser; component imports fail	Use `@playwright/experimental-ct-react` for component testing, E2E for full-app tests
`page.waitForTimeout(500)` after React state changes	React batches updates; timing varies across machines	Use `expect(locator).toHaveText('new value')` which auto-retries
Test internal component state with `page.evaluate`	Fragile; breaks on refactors; tests implementation, not behavior	Interact through the UI and assert on visible output
Mock `useState` or `useEffect` in Playwright tests	Playwright runs in the browser context, not the React component tree	Let hooks run naturally; control inputs (API responses, props via component testing)
Use `page.locator('.MuiButton-root')` for Material UI	Class names change between MUI versions and are generated dynamically	`page.getByRole('button', { name: 'Submit' })` works regardless of the component library
Test every component with `@playwright/experimental-ct-react`	Overhead of browser mounting for simple components; duplicates unit tests	Use component testing for complex interactive widgets; unit tests for pure logic; E2E for flows
Skip testing keyboard navigation on custom components	Accessibility regressions are common in custom dropdowns, modals, tabs	Test `Tab`, `Enter`, `Escape`, `ArrowDown` interactions in component tests
Assert on React DevTools or `__REACT_FIBER__` internals	Internal React properties are not stable across versions	Only interact with and assert on the rendered DOM

core/locators.md -- locator strategies that work with any React component library
core/assertions-and-waiting.md -- auto-waiting assertions for React state changes
core/forms-and-validation.md -- form testing patterns applicable to react-hook-form and Formik
core/component-testing.md -- in-depth component testing guide
core/accessibility.md -- testing ARIA patterns in React component libraries
core/test-architecture.md -- when to use E2E vs component vs unit tests
core/nextjs.md -- Next.js-specific patterns for React apps with SSR

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Testing React Apps with Playwright

Quick Reference

Setup

Playwright Config for React (Vite)

Component Testing Config

Patterns

Component Testing with `@playwright/experimental-ct-react`

Testing Hooks Indirectly Through the UI

Testing Context and State Changes Through User Interactions

Testing React Router Navigation

Testing Form Libraries (React Hook Form, Formik)

Testing React Portals (Modals, Tooltips, Dropdowns)

Testing Error Boundaries

Framework-Specific Tips

CRA vs Vite: Key Differences

React Strict Mode and Double Effects

Testing Suspense and Lazy Components

Component Testing: When to Use It vs E2E

Detecting Memory Leaks in Long-Running Tests

Anti-Patterns

Related

FilesExpand file tree

react.md

Latest commit

History

react.md

File metadata and controls

Testing React Apps with Playwright

Quick Reference

Setup

Playwright Config for React (Vite)

Component Testing Config

Patterns

Component Testing with @playwright/experimental-ct-react

Testing Hooks Indirectly Through the UI

Testing Context and State Changes Through User Interactions

Testing React Router Navigation

Testing Form Libraries (React Hook Form, Formik)

Testing React Portals (Modals, Tooltips, Dropdowns)

Testing Error Boundaries

Framework-Specific Tips

CRA vs Vite: Key Differences

React Strict Mode and Double Effects

Testing Suspense and Lazy Components

Component Testing: When to Use It vs E2E

Detecting Memory Leaks in Long-Running Tests

Anti-Patterns

Related

Component Testing with `@playwright/experimental-ct-react`