Visual Checks
Compare a live screen against a Figma frame or an uploaded screenshot as part of a run.
A Visual Compare step checks what the product looks like, not just what it does. Autonomy captures the screen at that point in the journey and compares it against a reference you attached to the step.
Use it where a functional assertion cannot see the bug: a collapsed layout, a missing nav, a component that renders but with the wrong type scale, a dark-mode surface that never switched.
References
Each step can carry one or more references. Two sources are supported:
- A Figma frame. Paste the frame URL and Autonomy renders it server-side. This keeps the design as the source of truth — when the frame changes, re-resolve and the baseline follows. Requires a Figma API key; see Figma.
- An uploaded screenshot. PNG, JPG, or WebP, up to 25 MB. Use this when the reference is an approved build rather than a design, or when the design does not live in Figma.
Attach references from Test Cases → your case → Visual References. Select the step, then Add Figma frame or Upload screenshot. Each reference shows its resolution status; a failed reference has a retry control that re-resolves it.
How the comparison runs
Autonomy runs two passes and combines them:
- A deterministic pixel diff between the captured screen and the reference.
- A vision-model review of both images, grounded in design facts extracted from the reference — frame geometry, fills as hex colors, text styles, corner radii, and auto-layout padding and gaps when the reference is a Figma frame.
The second pass is what stops the check from failing on a one-pixel antialiasing difference while still catching a nav that disappeared. Visual comparison routes to a fast vision model rather than the model used for regular steps.
Tolerance
| Tolerance | Color threshold | Mismatch limit | Use for |
|---|---|---|---|
strict | 0.03 | 0.5% | Pixel-level fidelity on a stable component. |
moderate (default) | 0.10 | 2% | Layout and structure. The right default for a page. |
loose | 0.20 | 5% | General appearance where content is dynamic. |
Separately, the block mode decides what a mismatch does to the run:
major— fail the step on major or critical mismatches, such as a missing navigation or a layout shift.any— fail on any mismatch.report— record the findings and let the run continue. Use this when you are adding visual coverage to an existing suite and do not yet want it merge-blocking.
Viewport
The comparison is only meaningful at the viewport the reference was drawn for. When you record a flow, the viewport you picked on the setup screen is used for both the hosted browser and any Visual Compare step captured in that session. Set it to match the design.
Evidence
A visual step attaches the captured screen, the reference, the diff, and the model's findings to the run evidence, alongside the rest of the timeline. Reviewers can see what the product rendered, what it should have rendered, and which specific differences were judged significant.
Troubleshooting
The step reports a mismatch that is not real
Widen the tolerance one level, or switch the reference from a full page to the component you actually care about. Full-page references on a page with dynamic content — timestamps, counters, feed items — produce noise at any tolerance.
The reference will not resolve
A Figma reference needs a valid API key and a URL containing a node-id. Open the frame in Figma, copy its link, and paste the whole URL. See Figma for key setup and error states.
Everything mismatches
Check the viewport. A reference drawn at desktop width compared against a mobile capture is a total mismatch by definition, and the model will report it as one.