Skip to content
Vizzly Docs

CI/CD Integration

Use vizzly run in CI when your tests capture screenshots during execution. Use vizzly upload when screenshots already exist on disk.

The basic pattern

Terminal window
npx vizzly run "npm test" --wait

Set VIZZLY_TOKEN in your CI secrets and inject it into the job environment.

For jobs that intentionally have no cloud token, use vizzly run "npm test" --allow-no-token. It runs the tests locally and skips creating a cloud build.

What --wait does

Once uploads finish successfully, --wait keeps the command running until comparisons finish. If Vizzly finds failed visual comparisons, run --wait exits non-zero so your job can fail.

If any screenshots fail to upload, run reports an incomplete visual build and skips that wait. It preserves your test command’s exit code, so an upload outage won’t fail passing tests. Check the upload summary or upload failure details as well as the job status.

GitHub Actions example

name: Visual Tests
on: [push, pull_request]


jobs:
  visual-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '22'
      - run: npm ci
      - run: npx vizzly run "npm test" --wait
        env:
          VIZZLY_TOKEN: ${{ secrets.VIZZLY_TOKEN }}

Upload mode in CI

If another tool already wrote screenshots:

Terminal window
npx vizzly upload ./screenshots --wait

Preview hosting

If your app produces a static build, attach it after the test run:

Terminal window
npx vizzly preview ./dist

Use --build <build-id> if the preview upload happens in a separate job or step. preview does not accept a parallel ID directly; finalize the parallel build first and pass the resulting build ID.

Parallel jobs

Use the same parallel ID across shards, then finalize once everything finishes.

RUN_ID here stands in for any unique value per workflow run, like a GitHub Actions run ID or a GitLab pipeline ID:

Terminal window
vizzly run "npm test -- --shard=1/4" --parallel-id "$RUN_ID"
vizzly run "npm test -- --shard=2/4" --parallel-id "$RUN_ID"
vizzly finalize "$RUN_ID"

Good overrides for CI

  • VIZZLY_BUILD_NAME
  • VIZZLY_BRANCH
  • VIZZLY_COMMIT_SHA
  • VIZZLY_COMMIT_MESSAGE
  • VIZZLY_PARALLEL_ID

Next steps