ViSnap provides a command-line interface for running visual tests. All commands work with your visnap.config.ts file.

Installation

Install as a dev dependency:

npm install -D @visnap/cli

Or use with npx (no installation needed):

npx visnap [command]

Global Options

All commands support these options:

• --config <path> - Path to configuration file (default: visnap.config.ts)
• --quiet - Suppress output except errors
• -h, --help - Show help for command
• -v, --version - Show version information

Commands

init

Initialize a new ViSnap project with a configuration file:

npx visnap init

Creates a visnap.config file using an interactive CLI wizard.

update

Capture baseline screenshots for all test cases:

npx visnap update [options]

Options:

• -i, --interactive - Select test cases interactively with search
• --include <pattern> - Include test cases matching pattern
• --exclude <pattern> - Exclude test cases matching pattern
• --docker - Run inside Docker container

test

Capture current screenshots and compare them with baseline screenshots:

npx visnap test [options]

Options:

• -i, --interactive - Select test cases interactively with search
• --include <pattern> - Include test cases matching pattern
• --exclude <pattern> - Exclude test cases matching pattern
• --jsonReport [path] - Output JSON report (omit path for stdout)
• --htmlReport [path] - Generate HTML report (omit path for default location)
• --docker - Run inside Docker container

validate

Validate your configuration file and check dependencies:

npx visnap validate

list

List all discovered test cases without running tests:

npx visnap list

open

Open HTML report in browser or screenshot directory:

npx visnap open

Configuration

ViSnap looks for configuration in this order:

1. --config option
2. visnap.config.ts
3. visnap.config.js

Override configuration with environment variables:

VISNAP_SCREENSHOT_DIR=./screenshots
VISNAP_THRESHOLD=0.05
visnap test

Troubleshooting

Command Not Found

Install ViSnap as a dev dependency:

npm install -D @visnap/cli

Permission Errors

Install Playwright browsers:

npx playwright install

Docker Issues

Ensure Docker is running:

docker --version

Exit Codes

• 0 - Success
• 1 - General error
• 2 - Configuration error
• 3 - Test failures
• 4 - Dependency error