Difora › Guides

Migrate from Lost Pixel with a verified first baseline.

Keep the screenshot generation you can reproduce, establish new baselines in Difora and verify the next build before replacing your existing CI gate. Review history and approvals are not automatically imported.

Create the project and upload token Start free

1. Inventory what your current setup produces

Lost Pixel’s repository was archived on April 22, 2026; its README announces the team joining Figma and a product sunset. This guide does not assume that your particular account remains accessible. Preserve any records you can legitimately export before changing your workflow.

List screenshot names, browser/viewport/theme variants, baseline branch, capture dependencies, masks and thresholds. Record which states the full suite must include. Identify the directory containing current captures, separately from old baselines, diffs and test-failure images.

2. Keep or replace the capture step

Custom PNGs: if your existing Playwright/Cypress tests already write current PNGs, keep that capture step and select only those files for upload.
Storybook: if Lost Pixel was doing the capture, keep the stories but configure Difora’s Storybook test-runner hook.
Page lists: translate the intended URLs and ready states into Playwright capture tests. Difora does not execute a Lost Pixel configuration.

Start each run with a clean generated directory. Preserve relative names, or deliberately document the new name mapping. Browser/theme variants need distinct names. Difora treats relative PNG paths as identities; it does not infer identity from the old tool’s history.

screenshots/
  checkout-desktop.png
  checkout-mobile.png

This is an illustrative manifest layout, not customer evidence. Capture the complete intended suite, wait for success, and keep any Difora metadata sidecars with their matching PNGs. Do not combine old baselines and current images in one upload directory.

3. Establish new baselines deliberately

Create a Free account, verify your email, accept Agreements as the organization owner, create the project and obtain its upload token. Install difora as a development dependency (Node 20+); keep DIFORA_TOKEN in your CI secret store, never in a committed config or command.

Check out the intended baseline branch and set the same baseline branch in the project. For a repository whose baseline branch is main, upload its complete current captures:

npx difora upload ./screenshots --branch main

Replace main with your actual branch. The first build is unreviewed and exits 1. Open the printed build link, inspect names and every image, then approve the baseline. Do not enable automatic approval simply to get a green migration run.

Previously exported baseline PNGs may be uploaded as a separately reviewed first build if you know their source and name mapping. They are not imported approvals or review history, and a different renderer can produce broad changes. A fresh capture in your intended CI environment is the recommended starting point.

4. Prove the next build

Clear the generated directory and capture the same suite again in the same environment. An unchanged build should pass (exit 0). Next, make one intentional UI change on a test branch and confirm that it produces a visible diff and review requirement (exit 1). Restore that test change after the check. Usage or upload errors use exit 2; comparison errors use exit 1, and a wait timeout uses exit 3. Investigate failures instead of ignoring the exit code.

Difora’s thresholds and masks have their own semantics. Recreate only the rules you need using the configuration guide; do not assume numeric settings translate directly. Missing names may be removals, not skipped tests. Use environment evidence to explain large renderer differences.

5. Switch the CI gate and keep a rollback path

Keep the old configuration and its recorded dependencies until the Difora baseline, unchanged repeat and intentional-change check work. During the trial, keep the new job separate from required merge checks. Then deliberately make the new job required and remove the superseded job. Do not publish or duplicate captures to a service you are no longer authorized to use.

The CLI exit code works independently of repository-host integration. Difora’s GitHub App is not currently configured; use the documented CLI-side GitHub status recipe if you need it. Check your branch-protection settings separately.

If the trial fails, retain or restore the previous CI configuration only where it still works and remains authorized. A copy of an archived runner is not a guarantee of hosted-service availability. Revoke retired tokens and remove obsolete generated artifacts after accepting the migration, preserving records under your own retention policy.

Common migration failures

Everything looks new: check relative names, variants and baseline branch before approving.
Many visual differences: compare browser build, OS, fonts, DPR, viewport, locale and data; do not suppress them with a blanket threshold.
Unexpected removals: verify the whole suite finished and that the upload directory contains all intended captures.
Authentication or agreement error: confirm the project token and owner acceptance; never paste the secret into a support screenshot.

Source checked September 20, 2026: Lost Pixel’s repository and sunset notice. For product fit, read the Lost Pixel comparison.

Start free Create the project and upload token

Difora is an independent service. Product names identify the tools discussed; no affiliation or endorsement is implied.