CI/CD automation
Use these examples to run visual tests, upload existing screenshots, or combine parallel shards in CI.
The core pattern
Choose the workflow your job needs:
- Run tests and wait for visual results.
- Upload screenshots that were generated elsewhere.
- Finalize a parallel build after all shards finish.
Use --allow-no-token for jobs that should run tests without cloud access. This skips Vizzly capture and doesn’t create a cloud build.
GitHub Actions
Fail when visual changes need review
name: Visual Tests
on: [push, pull_request]
jobs: visual-tests: runs-on: ubuntu-latest steps: - uses: actions/checkout@v6 - uses: actions/setup-node@v6 with: node-version: '24'
- run: npm ci
- name: Run visual tests env: VIZZLY_TOKEN: ${{ secrets.VIZZLY_TOKEN }} run: npx vizzly run "npm test" --waitParallel shards
Use a shared parallel-id across shards, then finalize once at the end.
jobs: visual-tests: runs-on: ubuntu-latest strategy: matrix: shard: [1, 2, 3, 4] steps: - uses: actions/checkout@v6 - uses: actions/setup-node@v6 with: node-version: '24' - run: npm ci - name: Run shard env: VIZZLY_TOKEN: ${{ secrets.VIZZLY_TOKEN }} run: | npx vizzly run "npm test -- --shard=${{ matrix.shard }}/4" \ --parallel-id "${{ github.run_id }}"
finalize: needs: visual-tests if: ${{ always() }} runs-on: ubuntu-latest steps: - uses: actions/checkout@v6 - uses: actions/setup-node@v6 with: node-version: '24' - run: npm ci - name: Finalize Vizzly build env: VIZZLY_TOKEN: ${{ secrets.VIZZLY_TOKEN }} run: npx vizzly finalize "${{ github.run_id }}"GitLab CI
visual-tests: stage: test image: node:24 variables: VIZZLY_TOKEN: $VIZZLY_TOKEN script: - npm ci - npx vizzly run "npm test" --waitIf your script uses jq, install it in the CI image first. You can also parse JSON with Node.js.
CircleCI
version: 2.1
jobs: visual-test: docker: - image: cimg/node:24.0 steps: - checkout - run: npm ci - run: name: Run visual tests command: npx vizzly run "npm test" --wait
workflows: test: jobs: - visual-testUpload-only pipelines
If your test framework already captured screenshots:
npx vizzly upload ./screenshots --wait --jsonThat works well when screenshot capture and Vizzly upload happen in separate steps.
Preview uploads
If you also want a static preview tied to the build:
npm run buildnpx vizzly preview ./distvizzly preview uses the current session or an explicit build ID:
npx vizzly preview ./dist --build <build-id>Shell script example
#!/bin/bash
result=$(npx vizzly run "npm test" --wait --json)exit_code=$?
echo "$result"
if echo "$result" | jq -e '.data.uploads.failed > 0' >/dev/null; then echo "Vizzly is missing screenshots:" echo "$result" | jq -r '.data.uploads.failures[] | "\(.name): \(.error)"'fi
if [ "$exit_code" -ne 0 ]; then url=$(echo "$result" | jq -r '.data.url // empty') echo "The Vizzly run did not pass" [ -n "$url" ] && echo "$url" exit "$exit_code"fiThis script reports missing uploads without changing the test result. vizzly run preserves your test command’s exit code when uploads fail; --wait can still fail the job for visual differences after successful uploads. A zero exit code alone doesn’t confirm a complete visual build.
Comparison counts are included only when the API returned them, so scripts should not invent missing counts as zero.
Tips
- Use Node.js 22.18+ on Node 22, or Node.js 24+.
- Use
vizzly run --waitto fail on visual differences, and check upload results for missing screenshots. - Use
vizzly finalizeafter all parallel shards finish. - Save the JSON output if later jobs need the build ID or URL.