Skip to content
Vizzly Docs

CI/CD Integration

Add Vizzly to your CI pipeline to catch visual regressions before they reach production.

Quick Setup

  1. Add VIZZLY_TOKEN to your CI environment variables
  2. Run vizzly run "your-test-command" in your pipeline
  3. Use --wait to fail the build on visual differences

All examples assume you’ve installed the CLI in your project.

Core Commands

vizzly run

Runs your tests with Vizzly screenshot capture:

Terminal window
# Basic - uploads screenshots, doesn't block on results
vizzly run "npm test"


# With --wait - fails build if visual differences detected
vizzly run "npm test" --wait


# Custom build metadata
vizzly run "npm test" \
  --build-name "PR-${PR_NUMBER}" \
  --environment "staging" \
  --wait

vizzly upload

Upload screenshots directly:

Terminal window
# Upload existing screenshots
vizzly upload ./screenshots --wait


# With metadata
vizzly upload ./screenshots \
  --build-name "Release v2.1.0" \
  --environment "production"

Exit Codes

When using --wait, commands exit with:

  • 0 - Success (no visual changes or all approved)
  • 1 - Visual differences detected (requires review)
  • 2 - Build failed or configuration error

Without --wait, the command exits with your test command’s exit code.

CI Provider Examples

GitHub Actions

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: '20'


      - name: Install dependencies
        run: npm ci


      - name: Run visual tests
        run: npx vizzly run "npm test" --wait
        env:
          VIZZLY_TOKEN: ${{ secrets.VIZZLY_TOKEN }}

Enhanced Git Information

GitHub Actions provides limited git info by default. Override with GitHub context:

- name: Run visual tests
  run: npx vizzly run "npm test" --wait
  env:
    VIZZLY_TOKEN: ${{ secrets.VIZZLY_TOKEN }}
    VIZZLY_COMMIT_MESSAGE: ${{ github.event.pull_request.head.commit.message || github.event.head_commit.message }}
    VIZZLY_COMMIT_SHA: ${{ github.event.pull_request.head.sha || github.event.head_commit.id }}
    VIZZLY_BRANCH: ${{ github.head_ref || github.ref_name }}
    VIZZLY_PR_NUMBER: ${{ github.event.pull_request.number }}

GitLab CI

stages:
  - test


visual-tests:
  stage: test
  image: node:20
  script:
    - npm ci
    - npx vizzly run "npm test" --wait
  variables:
    VIZZLY_TOKEN: $VIZZLY_TOKEN

CircleCI

version: 2.1


jobs:
  visual-tests:
    docker:
      - image: cimg/node:20.16
    steps:
      - checkout
      - run: npm ci
      - run: npx vizzly run "npm test" --wait
        environment:
          VIZZLY_TOKEN: $VIZZLY_TOKEN


workflows:
  test:
    jobs:
      - visual-tests

Jenkins

pipeline {
    agent any
    stages {
        stage('Visual Tests') {
            steps {
                sh 'npm ci'
                sh 'npx vizzly run "npm test" --wait'
            }
        }
    }
    environment {
        VIZZLY_TOKEN = credentials('vizzly-token')
    }
}

Azure DevOps

trigger:
  - main


pool:
  vmImage: 'ubuntu-latest'


steps:
  - task: NodeTool@0
    inputs:
      versionSpec: '20.x'
  - script: npm ci
    displayName: 'Install dependencies'
  - script: npx vizzly run "npm test" --wait
    displayName: 'Run visual tests'
    env:
      VIZZLY_TOKEN: $(VIZZLY_TOKEN)

Bitbucket Pipelines

pipelines:
  default:
    - step:
        name: Visual Tests
        image: node:20
        script:
          - npm ci
          - npx vizzly run "npm test" --wait

Travis CI

language: node_js
node_js:
  - '20'


script:
  - npx vizzly run "npm test" --wait


env:
  secure: # encrypted VIZZLY_TOKEN

For parallel builds, see the Parallel Builds guide.

Parallel Testing

Split large test suites across multiple CI jobs. Each job uses the same --parallel-id, then you finalize after all jobs complete:

Terminal window
# In parallel jobs (use same parallel-id for all)
vizzly run "npm test -- --shard=1/4" --parallel-id="${{ github.run_id }}"
vizzly run "npm test -- --shard=2/4" --parallel-id="${{ github.run_id }}"


# After all jobs complete
vizzly finalize "${{ github.run_id }}"

See the Parallel Builds guide for complete setup.

Environment Variables

Authentication

Required:

  • VIZZLY_TOKEN - API authentication token (project token from dashboard)

Configuration

Optional:

  • VIZZLY_API_URL - Override API base URL (default: https://app.vizzly.dev)
  • VIZZLY_LOG_LEVEL - Logging level: debug, info, warn, error (default: info)

Parallel Builds

  • VIZZLY_PARALLEL_ID - Unique identifier for parallel test execution (same as --parallel-id)

Git Information Overrides

The CLI auto-detects git info from your CI provider. Override when needed:

  • VIZZLY_COMMIT_SHA - Commit SHA
  • VIZZLY_COMMIT_MESSAGE - Commit message
  • VIZZLY_BRANCH - Branch name
  • VIZZLY_PR_NUMBER - Pull request number

Auto-Detection

Vizzly detects these CI providers automatically:

  • GITHUB_ACTIONS - GitHub Actions
  • GITLAB_CI - GitLab CI
  • CIRCLECI - CircleCI
  • TRAVIS - Travis CI
  • JENKINS_URL - Jenkins
  • TF_BUILD - Azure DevOps
  • CODEBUILD_BUILD_ID - AWS CodeBuild
  • APPVEYOR - AppVeyor
  • BUILDKITE - Buildkite
  • DRONE - Drone CI
  • BITBUCKET_BUILD_NUMBER - Bitbucket Pipelines
  • SEMAPHORE - Semaphore
  • WERCKER - Wercker
  • HEROKU_TEST_RUN_ID - Heroku CI

Next Steps