Configuration

ViSnap uses a visnap.config file in your project root to configure browsers, test sources, and execution settings.

Basic Setup

import { type VisualTestingToolConfig } from '@visnap/protocol';

const config: VisualTestingToolConfig = {
  adapters: {
    browser: { /* browser settings */ },
    testCase: [ /* what to test */ ]
  },
  screenshotDir: "visnap",
  // ... other options
};

export default config;

Configuration Files

TypeScript (recommended):

// visnap.config.ts
import { type VisualTestingToolConfig } from "@visnap/protocol";

const config: VisualTestingToolConfig = {
  // your config
};

export default config;

JavaScript:

// visnap.config.js
const config = {
  // your config
};

module.exports = config;

Environment Variables

Override configuration values for different environments:

VISNAP_SCREENSHOT_DIR=./screenshots
VISNAP_THRESHOLD=0.05

Complete Example

// visnap.config.ts
import { type VisualTestingToolConfig } from '@visnap/protocol';

const config: VisualTestingToolConfig = {
  adapters: {
    browser: {
      name: "@visnap/playwright-adapter",
      options: {
        launch: { browser: 'chromium', headless: true },
        context: { colorScheme: 'light', reducedMotion: 'reduce' },
        injectCSS: `* { animation: none !important; transition: none !important; }`
      }
    },
    testCase: [{
      name: "@visnap/storybook-adapter",
      options: {
        source: "./storybook-static",
        port: 4477,
        include: "*",
        exclude: "*-skip*"
      }
    }]
  },
  screenshotDir: "visnap",
  viewport: {
    desktop: { width: 1920, height: 1080 },
    mobile: { width: 375, height: 667 }
  },
  runtime: {
    maxConcurrency: { capture: 4, compare: 2 } // Or a number which will be applied to both
  },
  comparison: {
    core: "odiff",
    threshold: 0.1
  },
  reporter: {
    html: true,
    json: true
  }
};

export default config;

Configuration Options

`adapters`

Type: { browser: { name: string; options?: object }; testCase: Array<{ name: string; options?: object }>; }
Required: Yes

Configure browser and test source adapters. See Playwright Adapter, Storybook Adapter, and URL Adapter for details.

`screenshotDir`

Type: string
Default: "visnap"
Required: No

Directory where screenshots and reports are saved.

`viewport`

Type: Record<string, { width: number; height: number; deviceScaleFactor?: number }>
Required: No

Named viewport sizes for testing different screen sizes. Use deviceScaleFactor for high-DPI displays.

`runtime`

Type: { maxConcurrency?: number | { capture?: number; compare?: number }; quiet?: boolean }
Required: No

Control test execution parallelism and logging output.

`comparison`

Type: { core: string; threshold: number; diffColor?: string }
Required: No

Configure how screenshots are compared and what counts as a difference.

`reporter`

Type: { html?: boolean | string; json?: boolean | string }
Required: No

Choose output formats for test reports. Use strings to specify custom file paths.

Adapters

Browser Adapters

Purpose: Control how screenshots are captured
Responsibility: Launch browsers, navigate to pages, take screenshots

Currently available:

Playwright Adapter - Supports Chromium, Firefox, and WebKit

Test Source Adapters

Purpose: Discover and provide test cases
Responsibility: Find components/pages to test, provide metadata

Currently available:

Storybook Adapter - Discovers and tests your existing Storybook stories
URL Adapter - Lets you test any web page directly

Viewports

Test across different screen sizes to ensure your UI works on various devices:

viewport: {
  desktop: { width: 1920, height: 1080 },
  tablet: { width: 768, height: 1024 },
  mobile: { width: 375, height: 667 },
}

Per-Test Viewports

Override viewports for specific test cases:

Storybook: Use parameters.visualTesting.viewport
URL Adapter: Use viewport property in URL configuration

Comparison Engines

ViSnap compares images using either odiff or pixelmatch.

comparison: {
  core: 'odiff',        // or 'pixelmatch'
  threshold: 0.1,       // 0.0–1.0; higher = less strict
  diffColor: '#00ff00', // optional highlight color
}

`core`

Type: "odiff" | "pixelmatch"
Default: "odiff"
Required: No

Comparison engine. odiff is fast and robust; pixelmatch provides traditional per-pixel comparison.

`threshold`

Type: number (0.0–1.0)
Default: 0.1
Required: No

How different pixels must be to count as a change. Higher values are less strict:

0.0 — No differences allowed (very strict)
1.0 — All differences ignored (very loose)
0.1 — Recommended starting point (10% difference)

`diffColor`

Type: string (CSS color)
Required: No

Color used to highlight differences in diff images (e.g., "#ff0000" for red).

Best Practices

Start with odiff + 0.1 threshold; adjust based on test stability
Use CSS injection to disable animations during capture
Increase threshold for components with dynamic content
Decrease threshold for precise UI elements

Runtime

Control how tests execute with runtime options:

runtime: {
  maxConcurrency: 6,        // or { capture: 4, compare: 2 }
  quiet: false,             // suppress non-error logs
}

Higher concurrency = faster execution but more memory usage
Lower concurrency = slower execution but more stable on resource-constrained systems
Capture concurrency affects browser resource usage
Compare concurrency affects CPU usage for image processing

Reporters

Generate test reports in different formats:

reporter: {
  html: true,  // interactive HTML report
  json: true   // machine-readable JSON report
}

Visual diff comparison
Side-by-side baseline vs current screenshots
Test results summary
Filtering and search capabilities

JSON Report - Machine-readable data for CI/CD with:

Test results data
Diff statistics
Error information
Metadata for programmatic processing

Report Location

Reports are saved in your configured screenshot directory:

visnap/
├── base/     # Baseline screenshots
├── current/  # Current screenshots
├── diff/     # Diff images
├── report.html  # HTML report
└── report.json  # JSON report

Storage

ViSnap stores screenshots in your configured directory:

visnap/
├── base/     # Baseline screenshots (from visnap update)
├── current/  # Current screenshots (from visnap test)
└── diff/     # Diff images (generated during comparison)

The storage system is handled by the @visnap/fs-adapter package.