FAQ

Why do I need pxdiff? Can’t I just use Playwright’s toMatchScreenshot?

Playwright’s built-in screenshot assertions work for basic checks, but they fall apart at scale:

• No review UI, no re-runs. When a screenshot changes, Playwright fails the test. To accept the change, you update the reference file and re-run the entire suite — burning CI minutes and slowing down your PR. With pxdiff, your tests pass normally while a separate GitHub check reports visual changes. You approve in the review UI, the check turns green, and you merge — no re-run needed.
• Baselines live in your repo. Playwright stores reference screenshots as committed files. That means binary diffs in PRs, merge conflicts on PNGs, and repo bloat. pxdiff stores baselines in the cloud, content-addressed and deduplicated.
• No CI consistency. toMatchScreenshot captures on whatever machine runs the test. Screenshots differ between macOS, Linux, and CI runners due to font rendering and anti-aliasing. pxdiff’s cloud capture worker uses a consistent Chromium environment, so results are deterministic.
• No carry-forward. If you skip a test, Playwright doesn’t know whether the old screenshot is still valid. pxdiff automatically carries forward baselines for snapshots not included in the current run.

If you only have a handful of screenshots and don’t mind managing them manually, Playwright’s built-in matcher is fine. pxdiff becomes valuable when you have dozens or hundreds of visual tests and need a proper review workflow.

Don’t visual regression tests constantly report false positives?

The most common cause of flaky visual tests is environment inconsistency — different fonts, rendering engines, or OS-level antialiasing between your local machine and CI.

pxdiff addresses this in two ways:

• Storybook and Ladle captures always run against a Linux Chromium environment — either pxdiff’s cloud infrastructure (static builds) or a local Docker container using the same Chromium image (when capturing against a running dev server via --port). The same story renders identically every time, regardless of where you triggered it.
• Diffing uses pixelmatch at threshold 0.063 (the same algorithm and threshold as Chromatic), which correctly handles anti-aliasing without flagging subpixel rendering differences as changes.

If you still see false positives, it’s usually due to non-deterministic content in your stories — animations, timestamps, random data. Use pxdiff.delay to wait for animations, and data-pxdiff="ignore" to mask dynamic elements.

Aren’t visual regression tests expensive?

pxdiff uses pay-as-you-go pricing with no subscriptions or per-seat fees. You add funds to your balance and spend them as you go:

• A typical screenshot capture costs $0.001–$0.002 — about one tenth to one fifth of a cent, depending on whether it runs on the standard (1 GB) or heavy (2 GB) Lambda tier
• Diffs are free — only captures incur charges
• Every new organization gets $10 in free trial credit — enough for thousands of captures

Your balance never expires. There are no monthly minimums, no overage fees, and no charges for viewing results or approving snapshots. See Billing & Pricing for full pricing details.

Can I use pxdiff with React / Vue / Next.js / Svelte?

Yes. pxdiff is framework-agnostic — it works with any framework that can produce screenshots:

• Component libraries: If you use Storybook or Ladle, pxdiff captures your stories regardless of the underlying framework. React, Vue, Svelte, Angular, Web Components — all work.
• End-to-end tests: The Playwright plugin and Vitest plugin integrate directly with your test runner. Any app you can open in a browser, you can test with pxdiff.
• Any URL or PNG: Use pxdiff capture --urls to screenshot any URL, or pxdiff upload to bring your own screenshots from any source.

Do I need Storybook?

No. Storybook is one of several supported integrations, but pxdiff does not require it. You can use:

• Ladle — a lightweight Storybook alternative (guide)
• Playwright — capture screenshots in your end-to-end tests (guide)
• Vitest — visual testing in Vitest Browser Mode (guide)
• URL capture — screenshot any URL with pxdiff capture --urls (guide)
• Bring your own PNGs — upload a folder of screenshots with pxdiff upload

The “bring your own screenshots” path is a first-class workflow. You can use pxdiff without ever installing Storybook.

Can I run pxdiff against my local dev server without building a static site?

Yes. pxdiff storybook --port 6006 and pxdiff ladle --port 61000 capture against a dev server you’re already running, skipping the build-storybook / ladle build step. pxdiff spins up a local Linux Docker container running the same Chromium image as cloud capture and points it at http://host.docker.internal:<port>, so your screenshots are pixel-identical to CI baselines.

# Terminal 1
npm run storybook

# Terminal 2
pxdiff storybook --port 6006

Requires Docker. Captures are always treated as local mode — ephemeral and user-scoped, even when CI is set — so use the static build path (pxdiff storybook ./storybook-static) in CI. See the Storybook guide or Ladle guide for details.

What happens when I run out of funds?

When your balance reaches zero:

• New captures are blocked. CI pipelines will fail at the capture step with a 402 Payment Required error. Diffs continue to work, since they’re free.
• Your data is safe. Screenshots, baselines, diffs, and approval history remain accessible. You can still view and review everything.
• Service resumes instantly once you add funds — no waiting, no support ticket.

You can set a monthly budget to cap spend and prevent runaway CI from burning through your balance. See Billing & Pricing for details.

Is my data safe? Where is it stored?

All screenshots and diffs are stored in encrypted cloud storage in the US. Images are content-addressed by SHA-256 hash, which means identical screenshots are automatically deduplicated and their integrity is verifiable.

All data is scoped to your organization — no other organization can access your screenshots or project data. pxdiff does not sell, share, or train on your data.

How is pxdiff different from Chromatic?

pxdiff and Chromatic solve the same problem — visual regression testing with cloud-captured screenshots. The key differences:

• Framework-agnostic. Chromatic requires Storybook. pxdiff works with Storybook, Ladle, Playwright, Vitest, raw URLs, or any PNGs you bring.
• Simpler workflow. Chromatic splits visual testing into “Tests” and “Reviews” with different approval semantics. pxdiff has one workflow: review diffs, approve snapshots, baselines update.
• Pay-as-you-go pricing. Chromatic uses monthly subscription tiers with overage fees. pxdiff charges per screenshot — you add funds and spend them as you go. No surprise bills.
• Same diffing engine. pxdiff uses pixelmatch at threshold 0.063 — the same library and threshold as Chromatic. Your diffs will look identical.
• First-class local mode. Run captures locally without affecting team baselines, from the CLI with any integration.

For a detailed migration guide, see Migrate from Chromatic.

Can I self-host pxdiff?

No. pxdiff is a hosted-only service and is not available for self-hosting.

My screenshots look different locally vs CI

This is caused by font rendering differences between macOS (Core Text) and Linux (FreeType). Use the --docker flag to run your tests inside a consistent Linux container:

pxdiff --docker -- npx vitest run
pxdiff --docker -- npx playwright test

See the Docker guide for details.

What browsers does the capture worker use?

The capture worker runs Chromium via Playwright in a cloud container. All captures run on the same browser version and environment, ensuring deterministic screenshots across runs.

Chromium is the only supported capture browser. Multi-browser visual testing (Firefox, WebKit) is not currently supported.