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
npx vizzly run "npm test" --waitSet VIZZLY_TOKEN in your CI secrets and inject it into the job environment.
For jobs without a cloud token, use vizzly run "npm test" --allow-no-token. It runs your tests with Vizzly capture disabled and doesn’t create 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 Testson: [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 - run: npx vizzly run "npm test" --wait env: VIZZLY_TOKEN: ${{ secrets.VIZZLY_TOKEN }}Upload mode in CI
If another tool already wrote screenshots:
npx vizzly upload ./screenshots --waitPreview hosting
If your app produces a static build, attach it after the test run:
npx vizzly preview ./distUse --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:
npx vizzly run "npm test -- --shard=1/4" --parallel-id "$RUN_ID"npx vizzly run "npm test -- --shard=2/4" --parallel-id "$RUN_ID"npx vizzly finalize "$RUN_ID"Good overrides for CI
VIZZLY_BUILD_NAMEVIZZLY_BRANCHVIZZLY_COMMIT_SHAVIZZLY_COMMIT_MESSAGEVIZZLY_PARALLEL_ID