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).
What you get
Section titled “What you get”- Uploads from CI. The
circiCLI uploads a folder of PNG screenshots. The@circi/vitestplugin 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.
Who it's for
Section titled “Who it's for”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.
Where to go next
Section titled “Where to go next”- How a build flows: the path from upload to merge gate.
- Key concepts: the words the dashboard uses.
- Run it locally: get a stack running.