@visonaut/playwright

This guide describes the public adapter source. The current system guide owns the supported path and selected changes. Capture prepared Playwright pages with stable item and variant identities. Ariakit owns its projects, page preparation, clip geometry, and normal Playwright command. Visonaut waits for settled font faces and two consecutive equal screenshots. A failed or incomplete test run produces no manifest.

import { visual } from "@visonaut/playwright";
import { measureEnvironment } from "@visonaut/playwright/environment";

const environment = await measureEnvironment({
  outputDirectory: captureDirectory,
  appPackageFile: new URL("./package.json", import.meta.url).pathname,
  applicationFontPackage: "@fontsource-variable/inter",
});
// Set project.metadata.visonaut = { profile: environment.profile, comparisonDefaults: {} }.
await visual(page, {
  item: "dialog/open",
  variant: { key: "react-light", browser: "chromium" },
});

Configure @visonaut/playwright/reporter in the caller's normal Playwright configuration. Set outputFile, the exact GitHub run and tested commit, the shard key and source attempt, and trusted discovery options. Candidate discovery covers the complete selected suite. The reporter needs no package digest: its options have no run.planDigest and no discovery.executorDigest, and it writes one fixed digest in both manifest fields. Use the same release of visonaut, because the CLI refuses a capture bundle with another digest. Keep expected invocation and project checks explicit in the local Ariakit setup helper.

The reporter writes manifest.json and images/<sha256>.png beside environment.json. Rendering profiles contain browser, OS, fonts, viewport, locale, media, and screenshot settings. Each capture stores effective consumer comparison settings in comparison, separate from its rendering profile. The comparison engine identity belongs to the trusted comparison.

Set project.metadata.visonaut.comparisonDefaults beside profile. Share one comparison object with Playwright's expect.toHaveScreenshot configuration. The settings have the same meaning in both, but the CLI compares with pixelmatch 8, which measures color in OKLab and blends semi-transparent pixels with a checkerboard pattern. For the same images, it can count other changed pixels than Playwright. Preserve your existing tolerances; the values below show the built-in policy:

import { defineConfig } from "@playwright/test";
import type { ComparisonOptions } from "@visonaut/playwright";

const comparisonDefaults = {
  threshold: 0.2,
  maxDiffPixels: 0,
} satisfies ComparisonOptions;

export default defineConfig({
  expect: { toHaveScreenshot: comparisonDefaults },
  metadata: {
    visonaut: { profile: environment.profile, comparisonDefaults },
  },
});

Project metadata must have its own visonaut object with its own comparisonDefaults object for visual and visualBatch. Missing defaults cause a setup error, even when a capture supplies all comparison settings. For project-specific Playwright settings, put that project's shared object in both places. An explicit {} selects the built-in policy and does not inherit Playwright's screenshot defaults. The defaults must be an object with valid numeric comparison fields, or capture fails with a setup error. Only own comparison fields count, including non-enumerable fields. Override each setting on a capture:

await visual(page, {
  item: "button",
  variant: { key: "react-light", browser: "chromium" },
  maxDiffPixels: 5,
});

visualBatch accepts these settings for the batch and for each item. The order is project defaults, then batch settings, then image settings. An omitted field inherits its value. An explicit undefined clears its inherited value. Playwright uses the smaller limit when both pixel limits are set. The threshold defaults to 0.2; with no pixel limit, the allowed count is zero. These settings do not change the requirement for two consecutive identical capture images.

visual and visualBatch check the image bounds of Submit when they capture an item: 2 MiB encoded, 2.1 million pixels, and 8192 pixels for each side. An item above a bound fails the capture with its item key and variant key, for example dialog/open (react-light): 1248x1700 is 2,121,600 pixels. The limit is 2,100,000. A screenshot above the memory limits of the adapter (32 million pixels or 20 MiB) fails earlier, with no item name.

Set VISONAUT_PREVIOUS_CAPTURE to the directory of an earlier capture bundle (the directory with manifest.json that the reporter writes, for example the capture artifact of the base commit) to skip the second screenshot when the image is already known:

VISONAUT_PREVIOUS_CAPTURE="$RUNNER_TEMP/visonaut-previous" npx playwright test

The adapter reads only manifest.json, one time for each worker process, and takes the image digest of each item and variant from it. When the first screenshot of visual has that digest, the capture accepts it with no second screenshot and no wait. visualBatch accepts its first full-page screenshot only when each crop has its digest. Each other case waits for two consecutive equal screenshots as before: an item or variant with no capture in the bundle, a different digest, a missing directory or manifest, a manifest that is not a regular file, is empty, or is above 8 MiB, and a manifest that this release cannot parse (for example an unknown schema version). An unusable bundle also writes one warning and never fails a capture. The digests are only hints: a wrong digest can only cause a miss, and a match records the same image as the stability loop would for a page that renders that image. A render that changes after a matching first screenshot is not seen; the stability loop sees it when it shows before the second screenshot.

This source requires public comparison defaults and no longer reads private Playwright screenshot configuration. To migrate from the compatible adapter 0.4.1, share your existing effective screenshot settings with comparisonDefaults before installing the breaking release. Use {} only when you intend the built-in policy. The Playwright peer range is ^1.63.0. Development and CI use 1.63.0.

Starting with adapter 0.5.0, this public configuration is required. See the comparison-default migration record for the coordinated release sequence.

Capture image attachments use private 0600 attempt files outside test-results. The reporter reads one image at a time and removes those files after successful or failed attempts. It uses the public attachment array because Playwright's attach({ path }) copies bytes into diagnostic results. This keeps successful capture bytes out of the seven-day failure artifact.

Upload the complete successful capture directory as one ordinary GitHub Actions artifact per required shard. Name it visonaut-capture-<run-id>-<source-attempt>-<shard-key> and retain it for one day. Keep failure screenshots and retry traces in ordinary bounded seven-day diagnostic artifacts. Candidate jobs receive no GitHub OIDC or service upload credential.

The sole trusted Submit job runs visonaut submit --shard linux --shard safari, which starts the Visonaut App check before artifact downloads and image staging. It downloads exact verified artifacts, validates every image and rendering profile, and submits a new complete bundle. An expired inherited artifact requires a full visual rerun. Upload or submission never grants review approval.

The old @visonaut/playwright/ci export, visonaut-capture binary, second test configuration, runtime lock, dependency bootstrap, transfer encryption, and per-shard signed upload are removed. New integrations use their normal Playwright jobs and the single signed Submit path.