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.

For agent-driven loops, prefer readiness markers over fixed delays whenever the app can provide them. That reduces stale screenshots and gives the agent a reliable point to observe the UI.

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
• Prefer app launch hooks that jump directly to the target state instead of navigating there manually
• If possible, expose extra machine-readable state in test mode, such as current route, selected tab, focused element, or accessibility/tree metadata

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

Watchlight treats each scene as baseline-vs-current:

• the explicit baseline snapshot is used when configured
• otherwise the first snapshot by name order is used as the effective baseline

That behavior is intentional for repeatable agent and CI loops.

Suggested CI contract

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

Recommended agent loop

1. Inspect the project and scene configuration
2. Validate the target scene launch/capture settings
3. Run or re-analyze the target scene
4. Fetch baseline/current/diff artifacts for inspection
5. Apply code changes or update the baseline when the change is intentional
6. Re-run in strict mode

Next: see Troubleshooting for common failure modes.