Skip to content

Getting started

First upload

Upload a folder of screenshots with the CLI and see the build appear.

You need three things: a folder of PNG screenshots (any test tool will do; Playwright's page.screenshot({ path: 'screenshots/home.png' }) is enough), your CirCI address and the project's CI token.

  1. Set your address and token. The project's Settings › CI token page shows this snippet with your address filled in.

    Terminal window
    export CIRCI_API_URL=http://localhost:3000
    export CIRCI_TOKEN=circi_…
  2. Upload the folder and wait for the result.

    npx circi upload ./screenshots --wait
  3. Open the project in the dashboard. The build is there, with its screenshots counted by state.

  • Every *.png under the folder is a screenshot, named by its path: settings/profile.png becomes settings/profile. Hidden folders and node_modules are skipped; symbolic links are followed.
  • An optional <file>.png.json next to a screenshot adds metadata (browser, viewport, test name).
  • A screenshot can be at most 25 MB.
  • On a CI it recognizes, it reads the commit, branch and pull request itself. Locally it uses git. Override with CIRCI_COMMIT, CIRCI_BRANCH, CIRCI_PR_NUMBER and CIRCI_BASE_BRANCH.
  • It retries network errors and server errors (5xx) with growing waits, and prints how many screenshots it found.

With --wait it then waits for the result and exits 0 (passed), 1 (changes need review) or 2 (error). Every flag is in the CLI reference.

The first build of a project has nothing to compare with, so every screenshot is Added and the build waits for review. With no git host linked, --wait exits 1 until you approve.

How a build flowsFour stages in order. Upload: CI sends screenshots with circi upload. Compare: the worker diffs each screenshot against the baseline. Review: people approve or reject changes in the dashboard. Merge gate: the check on the pull request, or the CI job when no repository is linked, passes once everything is approved.UploadCI sends screenshotscirci uploadCompareThe worker diffs each oneagainst the baselineReviewPeople approve or rejectin the dashboardMerge gateApproval decidespasses when approvedHow a build flowsFour stages in order. Upload: CI sends screenshots with circi upload. Compare: the worker diffs each screenshot against the baseline. Review: people approve or reject changes in the dashboard. Merge gate: the check on the pull request, or the CI job when no repository is linked, passes once everything is approved.UploadCI sends screenshotscirci uploadCompareThe worker diffs each oneagainst the baselineReviewPeople approve or rejectin the dashboardMerge gateApproval decidespasses when approved

Next: First review.