workbench-visual-evidence

# Visual evidence Use the destination's existing visual vocabulary and collection tools. Prefer a shared fixture builder over separate fake state for previews, snapshots, agent captures, and CI. Whole-screen fixtures and captures of a running interaction serve different purposes. ## Select the evidence - **Deterministic fixture:** render a known product state with controlled data, time, randomness, locale, appearance, dimensions, and isolated storage where relevant. Share its model data with native previews and snapshot tests. - **Interaction evidence:** run the product, perform the requested operation, and capture what actually happened. Preserve the launch/run identity and the interaction's expected resulting state. - **Component preview:** expose useful normal, selected, empty, disabled, long-content, or accessibility states through the platform's ordinary preview mechanism. Preview broadly; add regression snapshots selectively. A fixture capture proves that state can render. It does not prove navigation, input, persistence, or asynchronous loading reaches that state. Choose the evidence required by the user's claim. ## Capture actual content Use native screenshot, accessibility/DOM, and test-result collection primitives. Wait for an observable readiness condition where possible. A delay or successful PNG write alone does not establish that asynchronous artwork, a map, video, or a native rendering surface is present. Check the expected content independently of chrome: meaningful rendered pixels, a loaded image, an item count, or a relevant semantic state. Then inspect the actual image. Prefer a whole-display capture when an application-scoped capture crops a presented surface. Confirm orientation and coordinate spaces before evaluating a region. Read [failure patterns](references/failure-patterns.md) when a capture is blank, cropped, inconsistent with the interaction, or attributed to the wrong run. These are diagnostic examples from Apple development, not universal platform workarounds. ## Compare without hiding changes Retain the original reference, current PNG, and difference image with a browsable summary when the existing system supports it. Preserve dimensions and color/normalization details that affect comparison. Resized web previews help viewing; they should not silently become the comparison inputs. The snapshot framework's configured policy determines test acceptance. The difference report shows evidence. Report small accepted differences accurately rather than calling a passing comparison pixel-identical. Inspect changes before recording an intentional new baseline; retain failed captures and the original reference. Correlate the artifact with its fixture or interaction, source/build, environment, target device/browser, and run. Save expected and observed state when an assertion fails. Reuse existing metadata before defining another evidence schema or screenshot system. ## CI and review Use the same rendering and test paths locally and in CI. Let CI own artifact retention and access. Keep fixture baselines in version control where appropriate; retain per-run screenshots, differences, logs, and test results even on failure. Captures can contain user data, so use isolated fixtures for shareable evidence and inspect artifacts before public distribution. Report what the images establish and what they leave untested. Name the current/baseline environment and any deliberate baseline update. Do not describe screenshot review as a completed accessibility audit or performance measurement.