Skip to content

Introduction

What is CirCI?

A self-hosted visual regression testing tool, and what it does for your team.

CirCI is a visual regression testing tool you run yourself. Your tests take screenshots, CI uploads them after each run, and CirCI compares each one with the last approved version. When something looks different, your team reviews the change in a web dashboard and approves or rejects it. The result can block a pull request until someone has looked.

It's a self-hosted alternative to services such as Argos: one Docker image, a Postgres database and somewhere to keep files (local disk or any S3-compatible bucket).

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
CirCI
A project's builds list: each build with its branch, author and the number of changed screenshots.
A project's builds. Each row is one upload, with its review status.
  • Uploads from CI. The circi CLI uploads a folder of PNG screenshots. The @circi/vitest plugin takes stable screenshots in Vitest browser mode. The Argos SDKs are designed to work by changing two environment variables; this isn't yet verified with the real SDKs.
  • A fast comparison. The worker diffs each screenshot with its baseline in a native Rust engine by default. Screenshots with the same SHA-256 are never opened.
  • A review dashboard. Side-by-side, diff and slider views. Approve or reject per screenshot or per build, comment on regions, request reviews by rule, and follow it all in the Inbox, saved views and insights.
  • Flaky screenshot handling. CirCI notices screenshots that keep flipping back to an image they already had, marks them Flaky, and can let a pull request that only changes flaky screenshots pass.
  • A merge gate. With a git host linked, each build is a CirCI check with Approve and Reject buttons. Without one, the CI job fails until the changes are approved.
  • Integrations. GitHub, GitLab and Bitbucket (checks or statuses, pull request comments), Slack, Linear, Jira, Figma and signed outgoing webhooks.
  • Hosted sites. Upload a built Storybook, a Playwright report or a coverage report per commit and per branch, and open it next to the screenshots. Only members of the project's workspace can see it.

Teams that want visual review without sending screenshots of internal apps to a third party, and that are comfortable running a container. A small install is one VM with Docker: see Requirements and running costs.

  1. How a build flows: the path from upload to merge gate.
  2. Key concepts: the words the dashboard uses.
  3. Run it locally: get a stack running.