Guide
Visual regression testing in GitLab CI
Keep your pipeline and your test runner. Connect GitLab to Snapvisor once, upload the screenshots from a GitLab CI job, and each build posts its result as a commit status on the matching merge request. Self-managed GitLab is supported.
Connect GitLab to Snapvisor
Snapvisor talks to GitLab with a personal access token that has repository access. Add it in your team or account settings. Snapvisor updates commit statuses on behalf of the user who created the token, so use an account that should appear as the status author.
Once the token is set up, import a repository from GitLab and link it to a Snapvisor project. From then on every build posts its result as a commit status on the matching merge request.
Read more: GitLab, CI integration.
Self-managed GitLab
Running GitLab on your own infrastructure is supported. Configure the GitLab proxy URL for your instance so Snapvisor reaches your self-managed server instead of gitlab.com.
Give the job the project token
Create a project in the Snapvisor app and copy its project token (ARGOS_TOKEN) from the project settings. Store it as a CI secret, never in the repository.
Tokenless authentication is documented for GitHub Actions only, so a GitLab job needs ARGOS_TOKEN in its environment. Set it as a CI/CD variable in your GitLab project settings.
Capture screenshots with your test runner
GitLab CI only runs the command. Screenshots come from the adapter for your test runner, set up exactly as on its own guide: Playwright, Cypress, Storybook or Puppeteer. The adapter uploads when the run finishes, or you upload a folder with @snapvisor/cli.
# .gitlab-ci.yml
visual-tests:
image: mcr.microsoft.com/playwright:v1.64.0-noble # match your @playwright/test version
stage: test
script:
- npm ci
- npm run build
- npx playwright test # captures via argosScreenshot, uploads via the reporterThe job needs an image that has the Playwright browsers installed. The example uses Microsoft's official Playwright image; pick the tag that matches the @playwright/test version in your project, because the image and the package must agree.
What the SDK reads from the job
When a job runs in GitLab CI (GITLAB_CI is true), the SDK recognizes it and reads these GitLab variables, so the build is tied to the right commit without any flags:
CI_COMMIT_SHAfor the commit.CI_COMMIT_REF_NAMEfor the branch.CI_PROJECT_PATHfor the project path.CI_PIPELINE_IDas the build's nonce, the tag that parallel shards share.
Large suites can shard their uploads across jobs and be reviewed as one build.
Read more: Parallel testing, Access tokens.
What the first build does
The first build on your base branch has nothing to compare against, so it becomes the baseline and is approved automatically. Run it on a base branch that already looks right. Later builds are diffed against the last approved build on the base branch, and approving a change promotes it to the new baseline for that branch.
Read more: Baseline builds, Review workflow.
Frequently asked questions
Yes. Snapvisor uses a GitLab personal access token to update commit statuses, so each build posts its result on the matching merge request, the same way it does on GitHub pull requests.
Yes. Configure the GitLab proxy URL for your instance so Snapvisor reaches your self-managed server instead of gitlab.com.
Only team admins can configure it. If you are not an admin, ask your team owner.
No. Tokenless authentication is documented for GitHub Actions only, so a GitLab job sets ARGOS_TOKEN, your project token, as a CI/CD variable.
When GITLAB_CI is true it reads CI_COMMIT_SHA for the commit, CI_COMMIT_REF_NAME for the branch and CI_PROJECT_PATH for the project path, and it uses CI_PIPELINE_ID as the nonce that parallel shards share.
No. It means the screenshots arrived. The result is the commit status Snapvisor posts to the merge request, so check that status before you merge.
Where to go next
Sources
Every command, package name and option on this page comes from the Snapvisor documentation and the published @snapvisor packages: