Your first visual review with Difora

Pilot getting-started guide — first draft. Capture in your CI, compare in the EU, and approve the changes you intend.

CLI distribution: npm installation is temporarily unavailable. Pilot users can install a supplied release tarball with npm install --save-dev ./difora-0.4.0.tgz; the CI commands below then use that installed version. Registry distribution resumes after publication.

1. Create your account and project

Request an invitation at difora.eu, register from your invite, confirm your email and sign in at app.difora.eu. Create a project for the screenshot suite you want to review.

2. Save your project token

Copy the CI token when it is shown. Store it as a secret named DIFORA_TOKEN in your CI provider. You can issue or revoke tokens in project Settings → CI tokens. Keep tokens out of your source code and logs.

3. Capture a stable suite

Configure tests to save screenshots to a fresh screenshots directory. Use the manual Playwright or Cypress recipe, or the Playwright/Storybook helpers from the CLI 0.4.0 release package. A plain Playwright test does not save a screenshot unless you explicitly capture one.

Use deterministic test data and wait for the page to be ready. Keep names, fonts, viewport and browser consistent. For example, home@1280.png and home@640.png represent separate snapshots.

4. Add two CI steps

After installing dependencies, starting your app and configuring the capture tests, a GitHub Actions job can run:

- run: npx playwright test
- run: npx difora upload ./screenshots
  env:
    DIFORA_TOKEN: ${{ secrets.DIFORA_TOKEN }}

Difora detects the branch and commit. The first build normally exits 1 because new snapshots need review; the printed URL opens the build. Other providers and optional commit statuses are covered in the CI guide.

5. Approve the first baseline

Open the build URL, inspect each screenshot, and approve the intended result. Set the project's baseline branch (usually main) in General settings and start with an approved run on that branch. New branch builds use those baselines until branch-specific approvals override them.

Run the same suite again: unchanged screenshots should pass. Change one visible detail, run it again and inspect the comparison before approving or rejecting it. A screenshot deliberately removed from the suite appears as a removal to review.

6. Connect statuses and notifications

General settings can configure repository statuses. GitHub needs the Difora GitHub App; GitLab and Bitbucket use a repository token. Alternatively, the CLI's --post-status option uses CI credentials. Integration setup depends on the provider.

Project owners can add email, Slack or signed-webhook channels under Settings → Notifications. Start with build.unreviewed and build.error, send a test, and check delivery history. Organization members can view channels and history.

Understand the outcome

• Passed / approved: CLI exit 0.
• Needs review, rejected or comparison error: exit 1; open the review link.
• Upload or usage failure: exit 2; check the message and npx difora doctor.
• Wait timed out: exit 3; processing continues on the server.

--exit-zero-on-changes allows a pilot to upload without failing CI for pending review. --no-wait returns after upload and does not wait for the comparison.

Screenshot processing and storage use EU-owned infrastructure. Your organization controls which members can review projects and which notification or repository integrations receive build metadata.