Playwright

Add visual regression assertions to your Playwright tests.

Prerequisites

npm install --save-dev @pxdiff/playwright

Setup

Create a global setup file, a test fixture, and reference both in your Playwright config:

global-setup.ts

import { pxdiffSetup } from "@pxdiff/playwright/setup";

export default function setup(): void {
  pxdiffSetup();
}

fixtures.ts

import { test as base } from "@playwright/test";
import { createPxdiffFixture } from "@pxdiff/playwright";

export const test = base.extend(
  createPxdiffFixture({
    suite: "my-app",
  })
);

export { expect } from "@playwright/test";

playwright.config.ts

import { defineConfig } from "@playwright/test";

export default defineConfig({
  globalSetup: "./global-setup.ts",
});

Write Tests

import { test, expect } from "./fixtures";

test("homepage", async ({ page }) => {
  await page.goto("/");
  await expect(page).toMatchPxdiff("homepage");
});

Local Development

One-time setup — authenticate and link your project:

pxdiff login
pxdiff project set myorg/myproject

Run your tests with pxdiff:

pxdiff local -- npx playwright test

CI

Create an API key for your project and set it as a repository secret.

.github/workflows/visual.yml

name: Visual Regression
on: pull_request

jobs:
  visual:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 24
          cache: npm

      - run: npm ci
      - run: npx playwright install --with-deps chromium

      - name: Visual Regression
        run: pxdiff run -- npx playwright test
        env:
          PXDIFF_API_KEY: ${{ secrets.PXDIFF_API_KEY }}

pxdiff run creates a GitHub check run, groups all screenshots into one session, and reports results back to the PR.

Cross-platform consistency

If your screenshots differ between macOS and Linux due to font rendering, use --docker to run tests in a consistent container:

pxdiff run --docker -- npx playwright test
pxdiff local --docker -- npx playwright test

See the Docker guide for details.

See the Playwright plugin reference for all matcher options.