Quick Start Guide

Vizzly catches visual bugs by comparing screenshots against baselines. You can upload existing screenshots or integrate directly into your test framework.

What You Need

• Node.js 22 or newer
• A Vizzly account (sign up free at vizzly.dev)

Two Ways to Authenticate

Local development: Use vizzly login for OAuth authentication. No tokens to manage.

CI/CD: Use an API token from your project settings. Pass it via VIZZLY_TOKEN environment variable.

Check the Authentication guide for details.

Method 1: Upload Screenshots

Already have screenshots? Start here.

1. Install the CLI

   npm install -g @vizzly-testing/cli

2. Authenticate

   Pick one:

   OAuth (local work)

   vizzly login

   API Token (CI/CD)

   export VIZZLY_TOKEN=your-api-token

   Get your API token: Project Settings → API Tokens → Create Token

3. Upload

   # Directory of screenshots
   vizzly upload ./screenshots --build-name "First build"
   
   # Single image
   vizzly upload homepage.png --build-name "Homepage test"

4. View results

   The CLI prints a URL. Open it to see your screenshots in the dashboard.

Method 2: Test Framework Integration

Capture screenshots during test runs.

1. Install and authenticate

   # Install as dev dependency
   npm install -D @vizzly-testing/cli
   
   # Pick authentication method
   vizzly login  # OAuth
   # OR
   echo "VIZZLY_TOKEN=your-api-token" >> .env  # Token (for CI)

2. Add to your tests

   import { vizzlyScreenshot } from '@vizzly-testing/cli/client';
   
   // Playwright, Puppeteer, etc.
   const screenshot = await page.screenshot();
   await vizzlyScreenshot('homepage', screenshot, {
     properties: {
       browser: 'chrome',
       viewport: '1280x800'
     }
   });

   Properties are optional. Use them to organize screenshots by browser, viewport, or any metadata you need.

3. Run with Vizzly

   npx vizzly run "npm test" --wait

   The --wait flag holds until comparisons finish, so you get immediate feedback.

4. Review changes

   The CLI prints your build URL. Open it to see what changed.

Understanding Your First Build

1. Open your build in the web UI

2. Review screenshots - Everything appears as “new” since there’s no baseline yet

3. Baseline selection - Vizzly uses Git mode by default, which automatically picks baselines based on your Git workflow

4. Next builds - Future builds from your main branch will use this build as the baseline

Next Build

Once you have a baseline, your next build shows:

• Identical - Screenshots that match the baseline
• Changed - Visual differences highlighted
• New - Screenshots not in the baseline
• Missing - Baseline screenshots not in current build

CI/CD Integration

Add visual testing to your CI pipeline:

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

Troubleshooting

What’s Next?

• Core Concepts - Understand builds, baselines, and workflows
• CLI Documentation - Complete CLI reference and guides
• SDK Documentation - Detailed framework integration
• Baseline Management - Configure baseline strategies
• Team Management - Set up team workflows and reviews