Configure visual tests for Playwright

You can enhance your Playwright and Chromatic tests further by configuring them using the options outlined in the following sections.

Playwright options

The Chromatic Playwright Fixture can be configured with use like all Playwright options.

Setting options globally can be done in your playwright.config.js as follows:

// playwright.config.ts
import { defineConfig } from "@playwright/test";
import { ChromaticConfig } from "@chromatic-com/playwright";

export default defineConfig<ChromaticConfig>({
  use: {
    // ...

    // 👇 your option overrides
    disableAutoSnapshot: true,
  },
  // ... your other configuration
});

// playwright.config.js

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

export default defineConfig({
  use: {
    // ...

    // 👇 your global options
    disableAutoSnapshot: true,
  },
  // ... your other configuration
});

Options can also be overridden at the test level:

// mytest.spec.js

test.describe("some block", () => {
  // 👇 your option overrides
  test.use({ disableAutoSnapshot: true });

  test("some test", async ({ page }) => {
    // ...
  });
});

E2E options

These options control how the Chromatic archive fixture behaves.

Chromatic options

These options control how Chromatic behaves when capturing snapshots of your pages.

Environment variables

Some options can be configured through environment variables.

Viewports

Chromatic will capture the DOM and take snapshots at each viewport size a test is configured to run in.

Viewports in Playwright can be configured globally in you main playwright config file as follows:

import { defineConfig } from "@playwright/test";
export default defineConfig({
  projects: [
    {
      name: "chromium",
      use: {
        ...devices["Desktop Chrome"],
        viewport: { width: 1280, height: 720 },
      },
    },
    {
      name: "Mobile",
      use: {
        ...devices["Desktop Chrome"],
        viewport: { width: 500, height: 600 },
      },
    },
  ],
});

Or at the test level:

test.use({
  viewport: { width: 1600, height: 1200 },
});

test("my test", async ({ page }) => {
  // ...
});

Working in Monorepos

Often, when using a monorepo, developers tend to keep their e2e tests in a subdirectory instead of in the root of the project. At the same time, the Storybook and Chromatic configuration details live at the project’s root. In these cases, you will need to update the archive-storybook and build-archive-storybook scripts in your package.json by setting the -c flag and CHROMATIC_ARCHIVE_LOCATION environment variable. For example:

"scripts": {
  "archive-storybook": "CHROMATIC_ARCHIVE_LOCATION=path/to/test-results archive-storybook -c path/to/node_modules/@chromaui/archive-storybook/config",
  "build-archive-storybook": "CHROMATIC_ARCHIVE_LOCATION=path/to/test-results build-archive-storybook -c path/to/node_modules/@chromaui/archive-storybook/config"
}

Sharded Playwright Runs

When running your Playwright tests over multiple shared CI jobs, you’ll need to wait for all jobs to complete, ensure you save the results in ./test-archives to be accessible by the next job (for instance using an artifact in GitHub Actions), and run Chromatic in a job that depends on all of the shards.

For GitHub actions, that might look like:

# .github/workflows/chromatic.yml

name: "UI Tests"

on: push

jobs:
  test:
    name: Run Playwright
    strategy:
      matrix:
        shard: [1, 2]
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v1
        with:
          node-version: 18.x
      - name: Install dependencies
        uses: bahmutov/npm-install@v1

      - name: Install Playwright
        run: npx playwright install --with-deps

      - name: Run Playwright tests
        run: npx playwright test --shard=${{ matrix.shard }}/${{ strategy.job-total }}
      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: playwright-report-${{ matrix.shard }}_${{ strategy.job-total }}
          path: ./test-results/chromatic-archives
          retention-days: 30

  chromatic:
    name: Run Chromatic
    needs: test
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v1
        with:
          node-version: 18.x
      - name: Install dependencies
        uses: bahmutov/npm-install@v1

      - name: Download all workflow run artifacts
        uses: actions/download-artifact@v4
        with:
          path: ./test-results/chromatic-archives
          pattern: playwright-report-*
          merge-multiple: true

      - name: Run Chromatic tests
        uses: chromaui/action@latest
        with:
          projectToken: ${{ secrets.CHROMATIC_PROJECT_TOKEN }}
          playwright: true