Concepts

Captures

A capture is a set of screenshots taken at a point in time. Every time you run pxdiff storybook, pxdiff ladle, pxdiff capture, pxdiff upload, or a test with toMatchPxdiff, pxdiff creates a capture tied to your current branch and commit.

Diffs

A diff compares a capture against baselines and produces a report. Each snapshot is classified as unchanged, changed, or new. Changed snapshots show a pixel-level diff overlay highlighting exactly what’s different.

Run pxdiff diff after a capture to generate the comparison, or use pxdiff run which handles it automatically.

Baselines

A baseline is the expected screenshot for a given snapshot name. When you approve a changed or new snapshot (via the review UI or pxdiff approve), that screenshot becomes the new baseline. Future diffs compare against it.

Baselines are scoped per-suite and resolved from the baseline ref — typically your main branch. When a snapshot isn’t captured in the current run, the previous baseline carries forward automatically.

Auto-baseline

Pass --auto-baseline to capture commands (pxdiff storybook, pxdiff ladle, pxdiff capture, pxdiff upload) to set baselines directly from captured screenshots without running a diff. Useful for initial setup or when merging to the default branch.

Auto-approve

Pass --auto-approve to pxdiff diff to automatically approve all changes and set baselines. Unlike --auto-baseline, this still runs the diff so you can see what changed, but all changes are approved immediately.

Suites

A suite groups snapshots with independent baselines. For example, you might have a storybook suite and a playwright suite — each with their own set of baselines that don’t interfere with each other.

Set the suite name via --suite on CLI commands, or in plugin configuration.

Authentication

Local development: Run pxdiff login to authenticate via your browser, then pxdiff project set myorg/myproject to link your directory to a project.

CI: Use a project-scoped API key. Create one from your project settings, then set it as a repository secret:

export PXDIFF_API_KEY=pxd_your_key_here

API keys are prefixed with pxd_ and scoped to a single project. See API Keys for setup, rotation, and security best practices.

Local vs CI

CI mode

CI captures are tied to a branch and commit. Diffs compare against baselines from the baseline ref (usually main). Approvals update baselines for the whole team. This is the authoritative workflow — when a PR’s visual tests pass, everyone can trust the result.

Local mode

Local captures are ephemeral — they don’t affect baselines for other users and are displayed separately in the review UI. Use local mode to iterate quickly without impacting the team’s baselines.

Enable local mode with --local on CLI commands, or wrap your command with pxdiff local:

# Storybook / Ladle
pxdiff storybook ./storybook-static --local

# Test frameworks
pxdiff local -- npx playwright test

Local behavior by integration

Storybook and Ladle captures happen on pxdiff’s cloud infrastructure, so screenshots are pixel-identical regardless of your local OS. This means local Storybook/Ladle runs can diff against CI baselines from any branch — you get real baseline comparison locally.

Test framework plugins (Playwright, Vitest) capture screenshots on your machine. Because different operating systems render fonts and pixels differently, CI baselines (captured on Linux in GitHub Actions) aren’t directly comparable to local screenshots — unless you use the --docker flag.

Without --docker: Local test runs compare against your own previous local runs:

1. Run tests locally — first run establishes your local baselines (everything is “new”)
2. Make changes, run again — diffs show what changed since your last local run
3. Push to CI — the authoritative diff against team baselines happens here

With --docker: Tests run inside a consistent Linux container, producing pixel-identical screenshots to CI. Local runs can diff directly against CI baselines:

pxdiff local --docker -- npx playwright test

See the Docker guide for setup details.