✨ Align Vitest and Ember SDKs

[Robdel12]

Why

This PR aligns the test-runner SDKs: Vitest and Ember. These integrations are close to the user’s actual test code, so the contract has to be exact. When someone calls expect(...).toMatchScreenshot(...) or vizzlyScreenshot(...), they need to know which options affect browser capture, which options affect Vizzly comparison/routing, which options are metadata, and when a visual diff fails the test.

Before this pass, that boundary was fuzzy. Vitest could pass Vizzly-only options toward browser screenshot APIs. Element captures could receive page-only fullPage behavior. Ember could not reliably bridge build ID, request timeout, viewport, threshold, and min-cluster settings from browser test code to the node screenshot server and then to Vizzly.

The goal here is boring parity: Vitest, Ember, the JS client, and the CLI should describe the same screenshot in the same conceptual way.

What changed

Vitest

• Discovers failOnDiff from .vizzly/server.json and exposes it to the browser context with server URL and build ID.
• Removes unused plugin options from vizzlyPlugin() so screenshot behavior lives on matcher calls.
• Supports both named and options-only matcher call shapes.
• Strips Vizzly-only fields before calling Playwright/Vitest screenshot APIs: properties, threshold, minClusterSize, failOnDiff, buildId, and requestTimeout.
• Prevents element screenshots from receiving page-only fullPage.
• Adds stable screenshot metadata for framework, browser, URL, viewport, viewport dimensions, threshold, min cluster size, full-page mode, and user properties.
• Treats new baselines as successful captures.
• Fails assertions for real visual diffs only when failOnDiff resolves to true.
• Updates matcher types for supported Playwright screenshot options plus Vizzly comparison/request options.

Ember

• Injects screenshot URL, build ID, and fail-on-diff settings into the test page before navigation.
• Forwards buildId and requestTimeout from the screenshot server to Vizzly.
• Sets viewport before capture when the helper asks for a specific size.
• Keeps fullPage on page captures and strips it from selector captures.
• Forwards threshold, minClusterSize, buildId, requestTimeout, viewport, and user properties in a stable payload.
• Allows per-screenshot failOnDiff to override launcher/server settings.
• Improves the no-server error so users are pointed to vizzly tdd start or vizzly run.
• Keeps the Chromium CI stability args small and directly tested.

Properties and options

This PR follows the core contract from #283. properties is the user metadata bag. Options that change capture, comparison, routing, request timeout, build grouping, or failure behavior stay as explicit options.

That is why the bridge code strips Vizzly-only fields before calling browser screenshot APIs and forwards them separately to Vizzly. It keeps browser capture behavior, comparison behavior, and metadata from quietly bleeding into one another.

Testing

• Vitest plugin discovery of local server config and failOnDiff.
• Vitest matcher argument normalization, browser detection, metadata generation, element/page capture behavior, and option filtering.
• Ember launcher injection of build/fail settings.
• Ember screenshot-server request payloads, viewport handling, request timeout forwarding, selector/full-page behavior, and error handling.
• Ember test-support payload construction, reserved metadata behavior, injected/per-call build IDs, request timeout, and per-screenshot diff behavior.

This is good boundary coverage for option flow. It still does not replace a product-level E2E visual-diff fixture that proves the whole CLI/API/UI loop with a real changed screenshot.

Verification

• pnpm --dir clients/vitest test: 23 passed.
• Ember package tests were verified in the preservation branch: 49 passed.
• Covered by the full preservation branch verification before the stack was split.
• Stack cleanup verification: git diff --check and PR file-list checks for ✨ Align core SDK option contracts #283 through 📝 Document aligned SDK workflows #287.

[vizzly-testing]

Vizzly - Visual Test Results

CLI Reporter - Waiting for build

No builds received yet for this pull request.

CLI TUI - Approved

5 comparisons, no changes detected.

View build

---

_{rd/sdk-vitest-ember · e267dc0b}