@compare-ui/playwright-test-fixture

Playwright helpers for component-level design comparison.

This package provides:

• a full fixture for registering Playwright component-test comparisons
• a smaller helper for taking a screenshot from the current Playwright page or target

Installation

pnpm add @compare-ui/playwright-test-fixture
pnpm add @playwright/test @playwright/experimental-ct-react react react-dom

If you author shared comparison config directly with @compare-ui/core, also install it explicitly:

pnpm add @compare-ui/core

If your app already has Playwright and React installed, add only the missing packages.

Peer dependencies

The package expects the consuming app to provide:

• @playwright/test
• @playwright/experimental-ct-react
• react
• react-dom

Supported peer ranges:

• @playwright/test >=1.40.0 <2
• @playwright/experimental-ct-react >=1.40.0 <2
• react ^18.0.0 || ^19.0.0
• react-dom ^18.0.0 || ^19.0.0

Playwright package setup

This package uses the consuming app's Playwright installation.

Keep these packages on the exact same version:

• @playwright/test
• @playwright/experimental-ct-react

This is a workspace package setup requirement. The package docs and workspace validation should keep these versions aligned; the fixture does not need extra runtime enforcement for this.

The workspace also runs tarball compatibility smoke tests in CI so the published package is revalidated against more than one consumer dependency shape.

What it exports

Main public APIs:

• designComparison(...)
• capturePageScreenshot(...)

Published entrypoint:

• @compare-ui/playwright-test-fixture

That entrypoint is intended to resolve from the published build output, and the workspace verifies it through a tarball smoke test.

Full fixture

designComparison(...) is the main high-level fixture.

It registers one Playwright test per design file and handles:

• viewport setup
• component mounting
• screenshot capture
• comparison execution
• report and artifact logging
• failure reporting

The public contract of designComparison(...) is:

• register tests
• fail tests when comparison does not pass

It is not a result-returning API.

Call designComparison(...) directly in a Playwright component-test spec file.

Example:

import { designComparison } from '@compare-ui/playwright-test-fixture';

import { ExampleScreen } from '../../src/example-screen';

import comparisonConfig from '../../design-comparison.config.mts';

designComparison({
  config: comparisonConfig,
  name: 'example-screen',
  renderComponent: () => <ExampleScreen />,
  designFiles: [
    {
      viewport: { x: 320, y: 640 },
      path: './tests/fixtures/example-screen-reference-padded.png',
      crop: {
        bottom: 20,
      },
    },
  ],
});

Design files

Each design file entry describes one comparison case.

type ViewportSize = {
  x: number;
  y: number;
};

type DesignComparisonDesignFile = {
  viewport: ViewportSize;
  path?: string;
  url?: string;
  crop?: {
    top?: number;
    right?: number;
    bottom?: number;
    left?: number;
  };
};

viewport represents the original design viewport. If the reference is cropped, the effective comparison viewport is derived from the cropped reference size.

Comparison behavior such as:

• crop handling
• explicit size normalization
• explicit transparent-background flattening

comes from the shared @compare-ui/core and @compare-ui/runner flow, not from fixture-specific image rules in this package.

Screenshot helper

capturePageScreenshot(...) is the smaller helper for writing a screenshot to disk from the current Playwright page or a selected screenshot target.

Example shape:

type CapturePageScreenshotOptions = {
  page: {
    setViewportSize(viewport: { width: number; height: number }): Promise<void>;
  };
  target: {
    screenshot(args: { path: string }): Promise<void>;
  };
  viewport: ViewportSize;
  screenshotPath: string;
};

Example:

await capturePageScreenshot({
  page,
  target: mountedComponent,
  viewport: { x: 320, y: 620 },
  screenshotPath: testInfo.outputPath('actual.png'),
});

Typical use cases:

• capture a mounted component
• capture the current page
• capture a selected Playwright locator-like target

For the comparison step after a screenshot already exists, use @compare-ui/runner.

Typical workflow

At the package level, the common workflows are:

1. Use designComparison(...) when you want the full Playwright component-test flow.
2. Use capturePageScreenshot(...) when you only need screenshot capture.
3. Use @compare-ui/runner when you already have a screenshot and want to run the comparison step explicitly.

When a comparison needs size normalization or transparent-background alignment, configure that through the shared core/runner comparison flow rather than through fixture-specific screenshot behavior.

Recipe: Component Test Against A Local Reference PNG

Use this package when you already know how to mount the component in Playwright component tests and want the fixture to handle the comparison flow.

import { designComparison } from '@compare-ui/playwright-test-fixture';

import comparisonConfig from '../../design-comparison.config.mts';
import { ExampleScreen } from '../../src/example-screen';

designComparison({
  config: comparisonConfig,
  name: 'example-screen',
  renderComponent: () => <ExampleScreen />,
  designFiles: [
    {
      viewport: { x: 320, y: 640 },
      path: './tests/fixtures/example-screen-reference.png',
      crop: {
        bottom: 20,
      },
    },
  ],
});

This recipe gives you:

• one registered Playwright component test
• automatic screenshot capture
• comparison execution through the shared runner/core flow
• report and artifact output when the comparison fails

Notes

• This package is intended for Playwright-based usage.
• It supports React 18 and React 19 component-test consumers within the documented peer range.
• It is designed to be used with shared config from design-comparison.config.mts.
• The workspace includes a dedicated example consumer at apps/playwright-example.