Quickstart

Pick where your screenshots come from, or follow the steps below. They use GitHub Actions and need no secret.

PlaywrightAdd the reporter. It uploads when the run ends.StorybookOne command captures every story at each width.Any screenshotsPoint the CLI at a folder of PNG files.Try it locallyCompare two folders. No account needed.

To let a coding agent do the setup, give it this prompt:

Add visual regression testing to this repository with stateofpixel.
Read https://stateofpixel.com/llms.txt, then the quickstart it links, and follow it:
1. Find where the tests write screenshots, or set up Playwright or Storybook capture.
2. Add the upload step to the GitHub Actions workflow with id-token: write and fetch-depth: 0.
3. Run it on pushes to main and on pull requests.
Do not add a secret. Tell me which command takes the screenshots.

1. Install the GitHub App#

Sign in on stateofpixel.com with GitHub, connect your GitHub account, and install the GitHub App on your account or organization. stateofpixel works with GitHub repositories only. Pick the repositories to test. Each repository becomes a project, and its project page shows the setup steps until the first build arrives.

2. Add the workflow#

Add a step that runs after your tests write their screenshots. This example runs Playwright tests that save PNG files into screenshots:

name: Visual

on:
  push:
    branches: [main]
  pull_request:

permissions:
  contents: read
  id-token: write

jobs:
  visual:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v7
        with:
          node-version: 22
      - run: npm ci
      - run: npx playwright install --with-deps chromium
      - run: npx playwright test
      - run: npx stateofpixel upload screenshots

• id-token: write lets the CLI sign in with the GitHub Actions OIDC token, so you do not need a secret. See Security.
• Run it on pushes to main too. Builds on your default branch are approved on their own and become the baseline that pull requests compare against.
• fetch-depth: 0 gives the CLI the git history it uses to find the baseline. With a shallow clone the server asks the GitHub compare API instead.

With the Playwright integration you skip the upload step, and with Storybook one command captures every story. See Playwright and Storybook.

3. Push to main#

The first build has nothing to compare with, so every snapshot is added and the build is approved on its own. It becomes the first baseline, and the check says "Baseline created".

4. Open a pull request#

When a pull request changes how something looks, the stateofpixel check waits with "2 changes to review". Details opens the build page, where anyone with write access to the repository approves or rejects each change. When every change is approved, the check turns green. See Reviewing changes.

5. Require the check#

The check only blocks merges when GitHub requires it. In the repository settings on GitHub, add a branch protection rule or a ruleset for main that requires status checks to pass, and pick stateofpixel. See The GitHub check for every state it can be in.

Pull requests from forks never get the check, because GitHub gives them no token to sign in with. Once the check is required, they cannot merge until an admin bypasses the rule. See No check on the pull request.