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 run on pxdiff’s cloud infrastructure using a consistent Chromium browser. 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 credit-based pricing with no subscriptions or per-seat fees. You buy credits and spend them as you go:

• A typical screenshot capture costs ~10 credits
• A typical diff costs ~0.5 credits
• Every new organization gets 50,000 free credits — enough for thousands of captures

Credits never expire. There are no monthly minimums, no overage fees, and no charges for viewing results or approving snapshots. See Billing & Credits 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.

What happens when I run out of credits?

When your credit balance reaches zero:

• New captures and diffs are blocked. CI pipelines will fail at the capture/diff step with a 402 error.
• Your data is safe. Screenshots, baselines, diffs, and approval history remain accessible. You can still view and review everything.
• Service resumes instantly once you deposit more credits — no waiting, no support ticket.

You can set a monthly budget to cap consumption and prevent runaway CI from burning through your balance. See Billing & Credits 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.
• Credit-based pricing. Chromatic uses monthly subscription tiers with overage fees. pxdiff charges per screenshot — you buy credits 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 local --docker -- npx vitest run
pxdiff run --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.