Skip to content
Latest

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:

  1. Run tests and wait for visual results.
  2. Upload screenshots that were generated elsewhere.
  3. 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" --wait

Parallel 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" --wait

If 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-test

Upload-only pipelines

If your test framework already captured screenshots:

Terminal window
npx vizzly upload ./screenshots --wait --json

That 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:

Terminal window
npm run build
npx vizzly preview ./dist

vizzly preview uses the current session or an explicit build ID:

Terminal window
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"
fi

This 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 --wait to fail on visual differences, and check upload results for missing screenshots.
  • Use vizzly finalize after all parallel shards finish.
  • Save the JSON output if later jobs need the build ID or URL.

See also