# Quickstart

Your CI takes the screenshots. stateofpixel compares them with the last approved ones and sets a check on the pull request until someone approves the changes.

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

- [Playwright: Add the reporter. It uploads when the run ends.](https://stateofpixel.com/docs/playwright.md)
- [Storybook: One command captures every story at each width.](https://stateofpixel.com/docs/storybook.md)
- [Any screenshots: Point the CLI at a folder of PNG files.](https://stateofpixel.com/docs/any-screenshots.md)
- [Try it locally: Compare two folders. No account needed.](https://stateofpixel.com/docs/cli.md)

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

Set it up with your coding agent

```
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](https://stateofpixel.com/index.md) 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`:

```yaml .github/workflows/visual.yml
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](https://stateofpixel.com/docs/security.md#how-ci-signs-in).
- 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](https://stateofpixel.com/docs/playwright.md) and [Storybook](https://stateofpixel.com/docs/storybook.md).

## 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](https://stateofpixel.com/docs/review.md).

## 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](https://stateofpixel.com/docs/checks.md) 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](https://stateofpixel.com/docs/troubleshooting.md#no-check-on-the-pull-request).

## All docs

### Get started

- [Quickstart](https://stateofpixel.com/docs.md): Set up stateofpixel on a GitHub repository in a few minutes.
- [Moving from another tool](https://stateofpixel.com/docs/moving.md): Switch to stateofpixel from Chromatic, Argos, Percy or Lost Pixel.
- [What is visual regression testing?](https://stateofpixel.com/docs/visual-regression-testing.md): How visual regression testing works: screenshots, baselines, pixel diffs and review, and where each tool takes and compares the images.

### Capture

- [Playwright](https://stateofpixel.com/docs/playwright.md): Take snapshots in Playwright tests and upload them with the stateofpixel reporter.
- [Storybook](https://stateofpixel.com/docs/storybook.md): Capture every story of a built Storybook and upload it with one command.
- [Cypress](https://stateofpixel.com/docs/cypress.md): Take screenshots in Cypress tests and upload them to stateofpixel for review on the pull request.
- [Any screenshots](https://stateofpixel.com/docs/any-screenshots.md): Upload a folder of PNG files from any test runner.

### Run in CI

- [Other CI](https://stateofpixel.com/docs/other-ci.md): Run stateofpixel on CI other than GitHub Actions with a project token.
- [Sharding](https://stateofpixel.com/docs/sharding.md): Split a visual test run across CI jobs and get one build and one check.
- [Suites](https://stateofpixel.com/docs/suites.md): Run separate visual suites in one repository, each with its own baselines and check.

### Review

- [Reviewing changes](https://stateofpixel.com/docs/review.md): Compare, approve and reject visual changes on the build page.
- [The GitHub check](https://stateofpixel.com/docs/checks.md): What the stateofpixel check on a commit means and how to require it.
- [Baselines](https://stateofpixel.com/docs/baselines.md): How stateofpixel picks the build a new build is compared against.

### Guides

- [Stable screenshots](https://stateofpixel.com/docs/stable-screenshots.md): Keep screenshots the same between runs so only real changes need review.
- [Troubleshooting](https://stateofpixel.com/docs/troubleshooting.md): Fixes for missing checks, failed uploads, stuck builds and other common problems.
- [Screenshots that fail on CI](https://stateofpixel.com/docs/screenshots-fail-on-ci.md): Why Playwright toHaveScreenshot passes on your machine and fails on CI, and how to fix it.
- [Playwright snapshots in git](https://stateofpixel.com/docs/snapshots-in-git.md): What committing Playwright snapshot PNG files costs, and how to keep baselines out of the repository.
- [Storybook visual tests without Chromatic](https://stateofpixel.com/docs/storybook-without-chromatic.md): The ways to screenshot and compare Storybook stories in your own CI, without Chromatic.
- [Review screenshots in pull requests](https://stateofpixel.com/docs/review-in-pull-requests.md): How to review and approve visual changes from a pull request instead of a downloaded Playwright report.

### Manage

- [Accounts and projects](https://stateofpixel.com/docs/accounts.md): Accounts, members, project settings, and what happens when you delete a project or uninstall the app.
- [Billing](https://stateofpixel.com/docs/billing.md): Upgrade, change or cancel a plan, and what happens when a payment fails.
- [Security](https://stateofpixel.com/docs/security.md): How CI signs in, who can see a project, and how screenshots and tokens are stored.
- [Self-hosting](https://stateofpixel.com/docs/self-hosting.md): Run stateofpixel on a Netlify site of your own, with your own GitHub App.

### Reference

- [CLI](https://stateofpixel.com/docs/cli.md): Commands, flags, environment variables and exit codes of the stateofpixel CLI.
- [Limits and storage](https://stateofpixel.com/docs/limits.md): Limits per build and account, how storage is counted, and how long images are kept.