Playwright Component Testing for React State, Events, and Routing

React component tests are valuable when a behavior needs a real browser but not an entire deployed application. A quantity control can be mounted with precise props, operated through accessible buttons, and checked for rendered state and callback output without creating a user, navigating a catalog, or depending on a checkout backend. That narrower boundary produces failures closer to the component contract.

Playwright component testing uses the familiar test runner, locators, assertions, browser contexts, and traces, then adds a mount fixture for the framework. The design challenge is deciding which providers and integrations belong inside the mounted boundary. Too few creates an artificial component; too many rebuilds end-to-end testing inside a fixture.

Place component tests between units and journeys

Use unit tests for pure calculations, reducers, formatters, and logic that does not need browser behavior. Use Playwright component tests for rendering, accessible names, focus, CSS-driven states, user events, provider interaction, and small component compositions. Keep a selective end-to-end layer for deployment, authentication, real service integration, and critical navigation.

The official Playwright component testing guide currently presents framework-specific component packages and the mount fixture. It also labels the feature experimental, so adoption should include an explicit upgrade policy and a small pilot before the suite depends on it broadly.

Define the boundary in each test. If data is mocked, state which response the component consumes. If a router provider is real but its destination page is absent, the test proves route intent rather than a complete journey. Clear boundaries make failures actionable.

Keep each mount close to its scenario

Mount inside the test that consumes the component. A broad beforeEach hides which props and providers establish the state, and it encourages tests to assume a shared default. A local mount makes the scenario legible and lets neighboring tests use different inputs without mutation.

Import test and expect from the React component package, then interact with the returned component locator. Scope locators to that root so unrelated test harness markup cannot satisfy assertions.

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

test('increments within the allowed quantity', async ({ mount }) => {
  const observed: number[] = [];
  const component = await mount(
    <QuantityPicker
      initialValue={1}
      maximum={3}
      onChange={value => observed.push(value)}
    />,
  );

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

  await expect(component.getByRole('status')).toHaveText('Quantity: 2');
  expect(observed).toEqual([2]);
});

The DOM assertion proves the rendered user outcome. The callback assertion proves the parent-facing contract. Avoid reading React state or calling a component method directly; those checks couple the test to implementation rather than browser behavior.

Test boundaries and disabled states explicitly

A counter test should not stop after one happy click. Mount at the maximum, verify the increase control is disabled, and confirm no callback is emitted. That case checks semantics and event suppression together.

Use accessible role assertions where possible. toBeDisabled() describes a user-operable constraint better than checking for a CSS class. If the component uses aria-disabled rather than native disabled, verify the intended keyboard and click behavior as well as the attribute. The browser test can expose a control that looks disabled but remains actionable.

Keep the case matrix risk-based. Minimum, ordinary, and maximum states may be enough at component level while exhaustive arithmetic belongs in unit tests. Repeating dozens of values in a browser adds cost without increasing confidence in rendering integration.

Verify prop updates without remounting

Parent components can change props while a child remains mounted. The component locator supports update, which is useful for checking transitions such as loading to success, feature disabled to enabled, or one account to another. Assert the initial state first, update the JSX, then assert the new state and any stale content that must disappear.

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

test('replaces loading state when account data arrives', async ({ mount }) => {
  const component = await mount(<AccountBanner account={null} loading />);
  await expect(component.getByRole('status')).toHaveText('Loading account');

  await component.update(
    <AccountBanner
      loading={false}
      account={{ id: 'acct-1842', displayName: 'Northwind QA' }}
    />,
  );

  await expect(component.getByRole('heading', { name: 'Northwind QA' })).toBeVisible();
  await expect(component.getByText('Loading account')).toBeHidden();
});

This test covers reconciliation through the public prop surface. It does not need to know which hook stores or derives the displayed state.

Supply routing through mount hooks

Components that render Link, call navigation hooks, or read route context need a router provider. Rather than wrapping every test manually, configure a beforeMount hook in the component-test entry point and enable routing through a typed hooksConfig. This keeps provider setup centralized while making its use explicit at each mount.

// playwright/index.tsx
import { beforeMount } from '@playwright/experimental-ct-react/hooks';
import { BrowserRouter } from 'react-router-dom';

export type HooksConfig = {
  enableRouting?: boolean;
};

beforeMount<HooksConfig>(async ({ App, hooksConfig }) => {
  if (hooksConfig?.enableRouting) {
    return (
      <BrowserRouter>
        <App />
      </BrowserRouter>
    );
  }
});

The scenario opts in and checks navigation as an observable browser result:

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

test('opens the selected product route', async ({ mount, page }) => {
  const component = await mount<HooksConfig>(
    <ProductSummary product={{ id: '42', name: 'Test Console' }} />,
    { hooksConfig: { enableRouting: true } },
  );

  await component.getByRole('link', { name: 'Test Console' }).click();
  await expect(page).toHaveURL(/\/products\/42$/);
});

This proves that the component generates and activates the expected route. It does not prove the destination page loads its real data, which belongs in a broader integration or end-to-end test.

Keep providers representative and configurable

Theme, localization, state stores, feature flags, and dependency injection can also be supplied through mount hooks. Include a provider when it changes component behavior under test, not simply because the production application has it. A giant universal wrapper makes hidden defaults difficult to reason about and can cause unrelated provider failures in every component test.

Type hooksConfig and choose explicit options such as locale, route, or feature state. Avoid passing production singleton stores whose data survives between mounts. Build a fresh store or provider value per scenario, and expose only the configuration the test needs.

Global styles matter for layout, visibility, and interaction. Load the same foundational styles as the application, then keep page-specific dependencies local. If a component only works when an undocumented ancestor stylesheet is present, the test has uncovered a coupling worth making explicit.

Control network data at the component boundary

A component that fetches data can be tested with deterministic network handlers. Playwright component testing provides routing support, including an experimental router fixture described in the component guide. Stub successful, empty, error, and delayed responses that drive distinct rendered states.

Assert the request details when they are part of the contract, then assert the UI outcome. Do not reproduce the entire backend in handlers. Contract validation and real service behavior need API or integration tests; the component test checks how React responds to representative responses.

One-off handlers should stay next to the scenario. Shared handlers are appropriate for stable application conventions, but a global success response can make error states impossible to express and hide the data each test relies on.

Use semantic locators and web assertions

The component root supports the same locator style used in page tests. Prefer roles, labels, text, and intentional test ids. This validates the rendered accessibility surface and survives structural refactoring better than class chains.

Use auto-retrying assertions for asynchronous rendering. An immediate JavaScript equality check can race an effect or state update. await expect(locator).toHaveText(...) waits for the user-visible contract while preserving a useful timeout error and trace.

Scope repeated controls by their semantic container. A list of cards can be narrowed by a heading, then its button can be selected by role. Avoid .nth() unless order itself is the requirement.

Diagnose mount, event, and routing failures by layer

A mount-time compilation error points to the component-test bundler, aliases, unsupported imports, or entry-point setup. A blank mounted root with console errors points to a runtime provider or component exception. Inspect the trace and browser console before changing assertions.

If a click does not update state, determine whether the locator reached the intended control, whether the callback fired, and whether controlled props require the parent to send an updated value. A controlled component may correctly emit onChange without changing its own display until the test updates its prop.

Routing errors usually mean the provider is absent, the hook configuration was not passed, or the generated destination is wrong. Separate provider setup from route intent. A failing destination request is outside a test that only promises to verify the link.

React development behavior can expose effects that are not idempotent. Fix side effects rather than weakening callback assertions, and configure the test harness consistently with the application mode being modeled.

Preserve the limits of component confidence

Component tests run in a browser, but that does not make them end to end. They may use mocked data, a test router, and a mount harness instead of the deployed shell. They do not automatically prove content security policy, server rendering, production asset paths, authentication, or cross-page state.

Keep at least one assembled journey for critical wiring. Conversely, do not force every visual or event permutation through that journey. Move focused React state and accessibility behavior into component tests, leave pure logic below, and reserve broad tests for boundaries only the assembled system can expose.

Operational React component checklist

• Define why the behavior needs a browser rather than a unit test.
• Mount inside each test with explicit props and hook configuration.
• Interact through roles, labels, and other public semantics.
• Assert rendered state and callback arguments when both matter.
• Test important disabled, error, empty, and update transitions.
• Build fresh provider state for each scenario.
• Configure routing through a typed mount hook.
• Keep network handlers small and scenario-specific.
• Read trace and console evidence for mount-time failures.
• Retain end-to-end coverage for deployment and real integration.

Adopt component testing with one bounded pilot

Choose a React component with meaningful browser behavior and expensive end-to-end setup, such as a form control, menu, or routed summary. Add tests for initial state, one user event, a boundary, and a prop transition. Introduce only the providers that behavior requires, then run the pilot in CI and review upgrade friction because the component feature is experimental. Expand when the failures remain local and the boundary is clearer than the journey it replaces. That is the signal that component testing is reducing uncertainty rather than creating another oversized test layer.