Integration Guide

This guide explains how to design stable scenes and command arguments in your app so visual tests stay reliable.

Design scenes around user-observable states

Treat each scene as one meaningful UI state, for example:

• Shell loaded
• Authenticated dashboard
• Settings open with known tab selected

Avoid mixing multiple transitions into one scene. Smaller scenes are easier to diagnose.

Use launch arguments to force deterministic state

Prefer app flags or test hooks that directly open the target state:

my-app.exe --ui-test settings --seed 42 --disable-animations

Then wire these args in Watchlight project/scene settings.

Compose project and scene arguments intentionally

Recommended pattern:

• Put global arguments in project settings (--seed, environment mode)
• Put scene-specific arguments on scenes (--ui-test dashboard)
• Enable argument prepend/merge behavior only when intentionally layering parent + child args

Pick the right capture trigger

Use Delay when startup timing is consistent and short.

Use StdOut pattern when readiness is event-based. Emit a stable marker from your app, for example:

WATCHLIGHT_READY:settings

Then configure scene capture to wait for that marker with a timeout.

Keep output stable

To reduce false positives:

• Disable non-deterministic animation and clock widgets in test mode
• Use fixed locale, font scaling, and window size
• Use deterministic test data fixtures
• Keep GPU/backend settings consistent across environments

Baselines and review flow

A practical workflow:

1. Create/update baseline snapshots on a trusted environment
2. Run routine checks in CI with headless JSON output
3. Inspect failures and approve intentional UI changes by updating baselines

Suggested CI contract

• Input: versioned project file + deterministic app build
• Process: watchlight run --format json <project_path>
• Output: pass/fail status + diff artifacts for review

Next: see Troubleshooting for common failure modes.