CI Integration

ViSnap works great in CI/CD pipelines, providing consistent visual testing across different environments. This guide shows you how to integrate ViSnap with popular CI platforms.

Docker Setup

ViSnap supports Docker for consistent testing environments. Use the --docker flag to run tests in a containerized environment:

# Run tests inside Docker
npx visnap test --docker

# Update baselines inside Docker
npx visnap update --docker

Using the Official Image

You can also use the ViSnap Docker image directly:

# Run tests using the image directly
docker run --rm -v $(pwd):/workspace -w /workspace visnap/visnap:latest test

# Update baselines using the image directly
docker run --rm -v $(pwd):/workspace -w /workspace visnap/visnap:latest update

GitHub Actions

Create a .github/workflows/visual-tests.yml file:

name: Visual Tests

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

jobs:
  visual-tests:
    runs-on: ubuntu-latest
    
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
        
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '18'
          cache: 'npm'
          
      - name: Install dependencies
        run: npm ci
        
      - name: Build Storybook (if using Storybook adapter)
        run: npm run build-storybook
        
      - name: Run visual tests
        run: npx visnap test --docker
        
      - name: Upload test results
        uses: actions/upload-artifact@v4
        if: always()
        with:
          name: visual-test-results
          path: visnap/

Advanced GitHub Actions

For more control, you can use the Docker image directly:

name: Visual Tests

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  visual-tests:
    runs-on: ubuntu-latest
    
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
        
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '18'
          cache: 'npm'
          
      - name: Install dependencies
        run: npm ci
        
      - name: Build Storybook
        run: npm run build-storybook
        
      - name: Run visual tests with Docker
        run: |
          docker run --rm \
            -v $(pwd):/workspace \
            -w /workspace \
            visnap/visnap:latest \
            test
            
      - name: Upload test results
        uses: actions/upload-artifact@v4
        if: always()
        with:
          name: visual-test-results
          path: visnap/

GitLab CI

Create a .gitlab-ci.yml file:

stages:
  - test

visual-tests:
  stage: test
  image: node:18
  services:
    - docker:dind
  before_script:
    - npm ci
    - npm run build-storybook
  script:
    - npx visnap test --docker
  artifacts:
    when: always
    paths:
      - visnap/
  only:
    - main
    - develop
    - merge_requests

Jenkins

Create a Jenkinsfile:

pipeline {
    agent any
    
    stages {
        stage('Checkout') {
            steps {
                checkout scm
            }
        }
        
        stage('Install Dependencies') {
            steps {
                sh 'npm ci'
            }
        }
        
        stage('Build Storybook') {
            steps {
                sh 'npm run build-storybook'
            }
        }
        
        stage('Visual Tests') {
            steps {
                sh 'npx visnap test --docker'
            }
            post {
                always {
                    archiveArtifacts artifacts: 'visnap/**', fingerprint: true
                    publishHTML([
                        allowMissing: false,
                        alwaysLinkToLastBuild: true,
                        keepAll: true,
                        reportDir: 'visnap',
                        reportFiles: 'report.html',
                        reportName: 'Visual Test Report'
                    ])
                }
            }
        }
    }
}

Always use the --docker flag in CI to ensure consistent results across different environments. This prevents issues where tests pass locally but fail in CI due to different browser versions or system configurations.

Visual tests need the built assets to capture screenshots, so this step is essential.

Upload Artifacts

Always upload test results as artifacts so you can review them later:

- name: Upload test results
  uses: actions/upload-artifact@v4
  if: always()
  with:
    name: visual-test-results
    path: visnap/

This lets you download and review the HTML report even when tests fail.

Handle Failures Gracefully

Upload artifacts even when tests fail, so you can debug issues. Without this, you won't be able to see what went wrong.

Next Steps

Learn about Interactive Testing for more advanced test scenarios
Explore Configuration Reference for all available options
Check out Storybook Setup for component testing workflows