Quick Start

This guide gets you from zero to your first repeatable visual check.

1) Install and run Watchlight

Download and install Watchlight from the website.

2) Create a project

In Watchlight, create a new project and save the project JSON file.

A project stores:

• Project-level settings (executable path, capture defaults)
• Scene definitions
• Snapshot and analysis metadata

3) Configure project settings

Set these core values on project settings:

• Executable: path to your app binary
• Working directory: folder to run the process from
• Command line arguments: default args shared by scenes
• Capture type:
  • Delay (capture after N seconds)
  • StdOut pattern (capture when a configured marker string appears)

Tip: Keep project settings generic, then override scene-specific behavior only where needed.

4) Add your first scenes

Create scenes for distinct UI states, for example:

• Main menu
• Settings panel
• Login dialog

For each scene, set only what differs from project defaults:

• Scene-specific launch arguments
• Scene-specific capture timing/pattern
• Scene-specific visual diff threshold when needed

5) Capture and compare

Run snapshot capture for your scene(s), then run analysis.

Watchlight compares each non-baseline snapshot against the scene's effective baseline/reference and reports diff percentage.

• If diff is below threshold: pass
• If diff exceeds threshold: fail

6) Make it repeatable

Use stable test data and deterministic app launch flags.

Good patterns:

• Start app in a known route/state via args
• Disable random animations where possible
• Wait for known readiness output when using stdout capture
• Use a dedicated test mode with fixed data, theme, locale, and window sizing
• If possible, emit extra machine-readable state for agents in addition to screenshots

Next: move to CLI & Headless for CI automation.

Optional: if you use AI assistants, you can also connect Watchlight through MCP. See Watchlight MCP Server for setup and usage patterns.