@pixsame/playwright-visual-regression-diff 0.0.0-canary-20261113-8e3iy1gd

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2021 FRSOURCE - Let's shape your web
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,170 @@
1
+ # pixsame for Playwright
2
+
3
+ Published as `@pixsame/playwright-visual-regression-diff`. Visual regression testing for [Playwright](https://playwright.dev) with the same `matchImage` flow, baseline layout, run manifest and CI tooling as [`@frsource/cypress-plugin-visual-regression-diff`](../cypress-plugin-visual-regression-diff/README.md), plus an optional remote browser in Docker so that the pixels you approve locally are the pixels CI produces.
4
+
5
+ > Status: 0.x, published on the `next` dist-tag. The API below is small on purpose and may still change before 1.0.
6
+
7
+ ## Why another Playwright screenshot tool
8
+
9
+ Playwright ships `toHaveScreenshot()`, and it is good. This package exists for teams that already use the Cypress plugin (or its GitHub App) and want one baseline format, one manifest and one review workflow across both runners:
10
+
11
+ - The comparison is the same: `pixelmatch` with `includeAA: false`, the same padding for size mismatches, the same `<name>_#n.png` / `.actual.png` / `.diff.png` files, the same PNG marker. So a baseline recorded by the Cypress plugin is a valid baseline here and vice versa. One default differs until the plugin's 5.0: the 4.x plugin compares with `includeAA: true`, so a diff that passes here can still fail there by a few anti-aliased pixels unless you set `diffConfig: { includeAA: false }` on the Cypress side too.
12
+ - The run manifest is the same too. Every comparison lands in a `visual-regression-manifest.playwright.w<n>.json` next to Playwright's test results, written through [`visual-regression-manifest`](https://www.npmjs.com/package/visual-regression-manifest), the runner-agnostic [standard](https://visual-regression.dev/manifest) the GitHub App and other consumers read. Only the `runner` block is Playwright-specific.
13
+ - `remoteBrowser()` runs the browser inside the official Playwright image and keeps the test runner, your app and your editor native, so local and CI screenshots come from the same browser build, fonts and rasteriser.
14
+
15
+ ## Install
16
+
17
+ ```bash
18
+ npm i -D @pixsame/playwright-visual-regression-diff
19
+ ```
20
+
21
+ `@playwright/test` >= 1.40 is a peer dependency. Node.js >= 20.9. Pre-releases are published on the `next` dist-tag: `npm i -D @pixsame/playwright-visual-regression-diff@next`.
22
+
23
+ ## Use
24
+
25
+ ```ts
26
+ // tests/home.spec.ts
27
+ import { test, expect } from '@pixsame/playwright-visual-regression-diff';
28
+
29
+ test('home page', async ({ page, matchImage }) => {
30
+ await page.goto('/');
31
+ await matchImage(); // whole viewport, named after the test
32
+ await matchImage(page.getByRole('navigation'), { title: 'nav' });
33
+ });
34
+ ```
35
+
36
+ `test` is Playwright's `test` extended with a `matchImage` fixture. If you already extend `test` yourself, merge the fixtures instead:
37
+
38
+ ```ts
39
+ import { test as base } from '@playwright/test';
40
+ import { visualRegressionFixtures } from '@pixsame/playwright-visual-regression-diff';
41
+
42
+ export const test = base.extend(visualRegressionFixtures);
43
+ ```
44
+
45
+ `matchImage(target?, options?)` takes a screenshot of `target` (a `Page` or a `Locator`, the page by default), compares it with the baseline and:
46
+
47
+ - **passes** when the share of differing pixels is within `maxDiffThreshold`, leaving only the baseline on disk;
48
+ - **creates** the baseline from the screenshot when there is none (`createMissingImages`, on by default);
49
+ - **fails** the test otherwise, keeps `<name>.actual.png` and `<name>.diff.png` next to the baseline and attaches baseline, actual and diff to the Playwright report.
50
+
51
+ It resolves to `{ status, message, diffValue, imgPath, imgNewPath, imgDiffPath, img, imgNew, imgDiff }`.
52
+
53
+ ### Options
54
+
55
+ Per call, or globally through `use` in `playwright.config.ts`:
56
+
57
+ ```ts
58
+ export default defineConfig({
59
+ use: {
60
+ visualRegression: {
61
+ maxDiffThreshold: 0.01,
62
+ imagesPath: '{spec_path}/__image_snapshots__',
63
+ },
64
+ // where the manifests go (relative to rootDir), one file per worker process; `false` turns it off
65
+ // default: `<outputDir>/visual-regression-manifest.playwright.w<workerIndex>.json`
66
+ visualRegressionManifestPath: undefined,
67
+ },
68
+ });
69
+ ```
70
+
71
+ | option | default | meaning |
72
+ | ------------------------ | ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
73
+ | `imagesPath` | `'{spec_path}/__image_snapshots__'` | Where baselines live; relative paths resolve against `rootDir`. Tokens: `{spec_path}` (directory of the test file, whole segment only), `{platform}` (`{os}-{browser}`), `{os}` (`linux`, `darwin`, `win32`), `{browser}` (`chromium`, `firefox`, `webkit`). |
74
+ | `maxDiffThreshold` | `0.01` | Maximum share of differing pixels, 0..1. |
75
+ | `diffConfig` | `{}` | [pixelmatch options](https://github.com/mapbox/pixelmatch#pixelmatchimg1-img2-output-width-height-options); `includeAA: false` unless you say otherwise. |
76
+ | `createMissingImages` | `true` | Create the baseline from the first screenshot instead of failing. |
77
+ | `updateImages` | `false` | `true` overwrites every baseline without comparing; `'failures-only'` compares first and overwrites only the ones above the threshold. |
78
+ | `title` | test title path joined by spaces | Screenshot name; repeated names within a test get `_#0`, `_#1`, ... |
79
+ | `matchAgainstPath` | | Compare against this file instead of the derived baseline path (never token-expanded). |
80
+ | `screenshotConfig` | `{}` | Passed to `page.screenshot()` / `locator.screenshot()`, e.g. `{ fullPage: true, mask: [...] }`. |
81
+ | `deterministicRendering` | `true` | Disables CSS animations and hides the caret for the screenshot (`animations: 'disabled'`, `caret: 'hide'`). |
82
+ | `analysis` | `true` | Describe what changed when a comparison finds differences, e.g. "Everything below y=340 moved down by 12 px." The sentence ends the failure message and is recorded in the run manifest as `extra.pixsame.analysis`. It never changes whether the comparison passes. |
83
+
84
+ Screenshots are taken at the context's `deviceScaleFactor` (1 by default); nothing is rescaled.
85
+
86
+ ### Baselines per browser or platform
87
+
88
+ Playwright projects commonly run the same test in several browsers. Add `{browser}` (or `{platform}`) to `imagesPath` so each gets its own folder:
89
+
90
+ ```ts
91
+ use: {
92
+ visualRegression: {
93
+ imagesPath: '{spec_path}/__image_snapshots__/{browser}';
94
+ }
95
+ }
96
+ ```
97
+
98
+ ## Remote browser in Docker
99
+
100
+ Chrome hands text rasterisation to the OS, so a macOS screenshot never matches a Linux CI screenshot byte for byte. Playwright can split the runner from the browser, which is the cleanest fix: the tests, your dev server and your editor stay on the host, only the browser runs in a pinned image.
101
+
102
+ ```ts
103
+ // playwright.config.ts
104
+ import { defineConfig } from '@playwright/test';
105
+ import { remoteBrowser } from '@pixsame/playwright-visual-regression-diff/remote';
106
+
107
+ const remote = remoteBrowser({ keepAlive: true });
108
+
109
+ export default defineConfig({
110
+ globalSetup: remote.globalSetup,
111
+ globalTeardown: remote.globalTeardown,
112
+ use: {
113
+ connectOptions: remote.connectOptions,
114
+ baseURL: 'http://localhost:3000',
115
+ },
116
+ });
117
+ ```
118
+
119
+ What happens: the global setup finds or starts a container from `mcr.microsoft.com/playwright:v<your @playwright/test version>-noble` running `playwright run-server`, waits until it answers, and every test connects to it through Playwright's own `connectOptions`. `exposeNetwork: '<loopback>'` (the default) lets the remote browser reach `localhost` of the machine running the tests, so a dev server needs no changes. All three browsers are in the image, so `browserName` picks the one you want.
120
+
121
+ | option | default | |
122
+ | ------------------- | ----------------------------------------------- | --------------------------------------------------------------------------------------------------- |
123
+ | `port` | `3000` | Host port; fixed because `playwright.config` needs the endpoint before anything runs. |
124
+ | `playwrightVersion` | detected from `node_modules` | Has to equal the version your tests run with; the image tag is derived from it. |
125
+ | `image` | `mcr.microsoft.com/playwright:v<version>-noble` | Any image that can run `npx playwright run-server`. |
126
+ | `keepAlive` | `false` | Leave the container running so the next `playwright test` skips the cold start. |
127
+ | `exposeNetwork` | `'<loopback>'` | Playwright's `connectOptions.exposeNetwork`; `false` to disable (then use `host.docker.internal`). |
128
+ | `dockerArgs` | `[]` | Extra `docker run` arguments, e.g. `['--platform=linux/amd64']` for parity with an amd64 CI runner. |
129
+ | `startTimeoutMs` | `600000` | Includes the image pull on first use (about 2 GB). |
130
+
131
+ Things to know:
132
+
133
+ - The first run pulls the image, which takes minutes. `docker pull` it ahead of time or bake it into your CI image.
134
+ - Docker is detected, never launched. When the daemon is not reachable the error says so, with the fix; nothing falls back silently. Anything speaking the Docker API works (Docker Desktop, OrbStack, Colima, Podman with the docker CLI, Rancher Desktop).
135
+ - Rendering in the container has full fidelity: canvas, WebGL, video frames and cross-origin frames are all real. What you trade is the local browser's fonts and a few hundred milliseconds of connection setup.
136
+ - Keep remote baselines apart from native ones, for instance with `imagesPath: '{spec_path}/__image_snapshots__/remote-{browser}'` in the remote config. The manifest records the difference either way (see below).
137
+ - For byte-identical CI, run the same image there: on GitHub Actions, `container: { image: mcr.microsoft.com/playwright:v<version>-noble }` on the job, no `remoteBrowser()` needed.
138
+
139
+ ## Run manifest
140
+
141
+ Each worker process writes `<outputDir>/visual-regression-manifest.playwright.w<workerIndex>.json` (Playwright clears `outputDir` at the start of a run, so there are never stale files). The label is Playwright's `workerIndex`, which is unique for the whole run: after a test failure Playwright restarts the worker, and the new process gets a new file instead of overwriting the one with the failure in it. A configured `visualRegressionManifestPath: 'reports/run.json'` gets the same treatment (`reports/run.w0.json`, `reports/run.w1.json`, ...). The file is written through [`visual-regression-manifest`](https://www.npmjs.com/package/visual-regression-manifest), which owns the format: the JSON Schema, the TypeScript types, a validating reader and a merger that treats the files of several workers like the manifests of several machines. Consumers glob `**/visual-regression-manifest{,.*}.json` (`MANIFEST_FILE_GLOB` in that package), so the GitHub App and other tooling built for the Cypress plugin pick these files up unchanged.
142
+
143
+ Two blocks are worth calling out:
144
+
145
+ - `runner`: `{ name: 'playwright', version, mode: 'run', configFile, browser, baseUrl, viewport, retries, project, testDir, outputDir, workers, shard, parallelIndex, workerIndex }`.
146
+ - `renderer` (per entry): where the pixels came from. `{ backend: 'native', browser, browserVersion }` for a locally installed browser; `{ backend: 'docker', browser, browserVersion, rendererVersion, imageDigest }` when `remoteBrowser()` is in use, where `rendererVersion` is the Playwright version of the image and `imageDigest` its content digest. Entries with different renderers are different baselines; the GitHub App keys and labels them separately.
147
+
148
+ Every entry records the resolved `matchImage` options in the shared vocabulary (`imagesPath`, `maxDiffThreshold`, `diffConfig`, `createMissingImages`, `updateImages`, `title`, `matchAgainstPath`, `screenshotConfig` without callbacks). `forceDeviceScaleFactor` is always `false` here: Playwright screenshots come at the context's `deviceScaleFactor`.
149
+
150
+ The `visualRegressionManifest` worker fixture exposes the underlying `ManifestWriter` (`null` when `visualRegressionManifestPath: false`) if you want to record something yourself.
151
+
152
+ ## Relation to the Cypress plugin and what is next
153
+
154
+ This package is the Playwright adapter from the renderer design that drives v5 of the Cypress plugin. Cypress cannot drive a remote browser, so there the plan is a DOM-snapshot sidecar; Playwright can, so the remote browser came first here. Planned next, in this order:
155
+
156
+ 1. A shared core package for the comparison and the path tokens (today that code is mirrored between the two packages; the manifest is already shared through `visual-regression-manifest`).
157
+ 2. `{browser}` naming the renderer's browser explicitly once several renderers per run are possible.
158
+ 3. DOM-snapshot capture (`page.evaluate` + `page.on('response')`) for the hosted renderer and for uploading snapshots alongside images.
159
+ 4. A `toMatchImage()` matcher for people who prefer `expect(page).toMatchImage()` over the fixture.
160
+
161
+ ## Development
162
+
163
+ ```bash
164
+ pnpm --filter @pixsame/playwright-visual-regression-diff build
165
+ pnpm --filter @pixsame/playwright-visual-regression-diff test:integration # unit tests, no browser needed
166
+ pnpm --filter @pixsame/playwright-visual-regression-diff test:smoke # needs `npx playwright install chromium`
167
+ pnpm --filter @pixsame/playwright-visual-regression-diff test:smoke:remote # needs Docker; pulls the Playwright image
168
+ ```
169
+
170
+ The smoke tests write their baselines to `e2e/__image_snapshots__` (gitignored): the first run creates them, the second compares.
@@ -0,0 +1,71 @@
1
+ import type pixelmatchType from 'pixelmatch' with {
2
+ 'resolution-mode': 'import'
3
+ };
4
+ import type { Comparer } from 'visual-regression-compare' with { 'resolution-mode': 'import' };
5
+ import { ManifestWriter, type ManifestEntry, type ManifestEntryInput, type ManifestEntryPlatform, type ManifestViewport } from 'visual-regression-manifest';
6
+ export type PixelmatchOptions = NonNullable<Parameters<typeof pixelmatchType>[5]>;
7
+ export type CompareStatus = 'passed' | 'failed' | 'missing-baseline' | 'created' | 'updated';
8
+ export type CompareInput = {
9
+ /** Raw screenshot bytes as returned by Playwright. */
10
+ imgNew: Buffer;
11
+ /** Where the `.actual.png` is written (and kept when the comparison fails). */
12
+ actualPath: string;
13
+ /** The baseline to compare against and to create/update. */
14
+ baselinePath: string;
15
+ createMissingImages: boolean;
16
+ updateImages: boolean | 'failures-only';
17
+ maxDiffThreshold: number;
18
+ diffConfig: PixelmatchOptions;
19
+ /** Describe what changed when the comparison finds differences. Default `true`. */
20
+ analysis?: boolean;
21
+ /** Screenshot name recorded on the manifest entry; defaults to the baseline's file name. */
22
+ name?: string;
23
+ /** The test the screenshot belongs to, recorded on the manifest entry. */
24
+ test?: {
25
+ filePath: string;
26
+ titlePath: string[];
27
+ retry: number;
28
+ };
29
+ platform?: ManifestEntryPlatform;
30
+ viewport?: ManifestViewport;
31
+ /** Entry fields the comparer cannot know: the resolved `options` and the `renderer`. */
32
+ entry?: Pick<ManifestEntryInput, 'options' | 'renderer'>;
33
+ };
34
+ export type CompareResult = {
35
+ status: CompareStatus;
36
+ /** `true` when the test should fail. */
37
+ error: boolean;
38
+ message: string;
39
+ /** What changed, in one sentence; only for a comparison that found differences. */
40
+ description?: string;
41
+ /** Share of differing pixels, 0..1; `0` when no comparison ran. */
42
+ diffRatio: number;
43
+ threshold: number;
44
+ /** `true` whenever the baseline file was (re)written. */
45
+ baselineWritten: boolean;
46
+ /** Path of the `.diff.png` sibling of `actualPath`. */
47
+ diffPath: string;
48
+ /** The compared images (padded to a common size when they differed in size); absent when no comparison ran. */
49
+ imgNew?: Buffer;
50
+ imgOld?: Buffer;
51
+ imgDiff?: Buffer;
52
+ /** What the comparer recorded in the manifest. */
53
+ entry: ManifestEntry;
54
+ };
55
+ export declare const diffPathFor: (actualPath: string) => string;
56
+ /**
57
+ * The comparer of one worker, recording into `writer` (or, with the manifest
58
+ * disabled, into memory). Sizes that differ are padded and compared, as the
59
+ * Cypress plugin does.
60
+ */
61
+ export declare const createComparison: (writer: ManifestWriter | null, { rootDir }: {
62
+ rootDir: string;
63
+ }) => Promise<Comparer>;
64
+ /**
65
+ * Stamps the screenshot with the package marker, compares it with the
66
+ * baseline and leaves the files on disk the way the manifest contract
67
+ * describes (`.actual.png` and `.diff.png` only for failures). The comparison
68
+ * itself is `visual-regression-compare`'s; this maps `matchImage`'s options
69
+ * onto it.
70
+ */
71
+ export declare const compareImages: (cfg: CompareInput, comparer: Comparer) => Promise<CompareResult>;
@@ -0,0 +1,158 @@
1
+ "use strict";
2
+ var __importDefault = (this && this.__importDefault) || function (mod) {
3
+ return (mod && mod.__esModule) ? mod : { "default": mod };
4
+ };
5
+ Object.defineProperty(exports, "__esModule", { value: true });
6
+ exports.compareImages = exports.createComparison = exports.diffPathFor = void 0;
7
+ const analysis_1 = require("@pixsame/analysis");
8
+ const fs_1 = __importDefault(require("fs"));
9
+ const path_1 = __importDefault(require("path"));
10
+ const visual_regression_manifest_1 = require("visual-regression-manifest");
11
+ const constants_1 = require("./constants");
12
+ const image_utils_1 = require("./image.utils");
13
+ // pixelmatch 7 and visual-regression-compare are ESM-only; a dynamic import
14
+ // keeps this package usable from a CommonJS `playwright.config` on every
15
+ // supported Node version
16
+ let pixelmatchPromise;
17
+ const loadPixelmatch = () => (pixelmatchPromise ??= import('pixelmatch').then((m) => m.default));
18
+ const diffPathFor = (actualPath) => actualPath.replace(constants_1.FILE_SUFFIX.actual, constants_1.FILE_SUFFIX.diff);
19
+ exports.diffPathFor = diffPathFor;
20
+ /** The words `matchImage` users need when there is nothing to compare with: the path and the way out. */
21
+ const messages = {
22
+ 'missing-baseline': ({ baselinePath }) => `Baseline image is missing at path: "${baselinePath}". Provide a baseline image or enable "createMissingImages" option in plugin configuration.`,
23
+ };
24
+ /** A baseline of a passed comparison that was not made by this package (no marker) is refreshed from the screenshot. */
25
+ const isUnstamped = ({ input }) => input.files !== undefined &&
26
+ !(0, image_utils_1.isImageCurrentVersion)(fs_1.default.readFileSync(input.files.baseline));
27
+ /**
28
+ * What `matchImage` does differently from the comparer's defaults:
29
+ * - pixelmatch with every one of its options (`alpha`, `aaColor`, `diffColor`,
30
+ * `diffMask`, ...), not only the `threshold` and `includeAA` of the built-in
31
+ * engine, and anti-aliased pixels not counted unless asked for; registered
32
+ * under the built-in's name, so it takes its place; the compared images
33
+ * are handed to `@pixsame/analysis`, which says what changed;
34
+ * - the `.diff.png` carries the package marker, like the screenshot does;
35
+ * - a passed comparison whose baseline lacks the marker refreshes the baseline,
36
+ * so the file is rewritten once instead of by whoever runs the test next.
37
+ */
38
+ const matchImagePlugin = (pixelmatch) => ({
39
+ name: '@pixsame/playwright-visual-regression-diff',
40
+ setup: (api) => {
41
+ api.on('beforeWrite', (ctx, { write }) => ({
42
+ write: [
43
+ ...write.map((file) => file.ref.kind === 'diff'
44
+ ? { ...file, bytes: (0, image_utils_1.addPNGMetadata)(Buffer.from(file.bytes)) }
45
+ : file),
46
+ ...(ctx.decision?.status === 'passed' && isUnstamped(ctx)
47
+ ? [
48
+ {
49
+ ref: { kind: 'baseline', path: 'baseline' },
50
+ bytes: ctx.input.actual,
51
+ },
52
+ ]
53
+ : []),
54
+ ],
55
+ }));
56
+ api.addEngine('pixelmatch', (options) => ({
57
+ name: 'pixelmatch',
58
+ colorMetric: 'yiq',
59
+ colorThreshold: typeof options.threshold === 'number' ? options.threshold : 0.1,
60
+ compare(baseline, actual) {
61
+ const { width, height } = baseline;
62
+ const diff = new Uint8ClampedArray(width * height * 4);
63
+ const diffPixels = pixelmatch(baseline.data, actual.data, diff, width, height, { includeAA: false, ...options });
64
+ (0, analysis_1.captureComparison)(baseline, actual, { width, height, data: diff }, options);
65
+ return {
66
+ diffPixels,
67
+ diffRatio: width * height === 0 ? 0 : diffPixels / (width * height),
68
+ diff: { width, height, data: diff },
69
+ };
70
+ },
71
+ }));
72
+ },
73
+ });
74
+ /** A manifest writer that keeps its entries in memory: for a run with the manifest turned off. */
75
+ class MemoryManifestWriter extends visual_regression_manifest_1.ManifestWriter {
76
+ write() { }
77
+ flush() { }
78
+ }
79
+ /**
80
+ * The comparer of one worker, recording into `writer` (or, with the manifest
81
+ * disabled, into memory). Sizes that differ are padded and compared, as the
82
+ * Cypress plugin does.
83
+ */
84
+ const createComparison = async (writer, { rootDir }) => {
85
+ const [{ createComparer, fsStore }, pixelmatch] = await Promise.all([
86
+ import('visual-regression-compare'),
87
+ loadPixelmatch(),
88
+ ]);
89
+ return createComparer({
90
+ // every call names its files, so the store is never asked for a path
91
+ store: fsStore({ baselineDir: rootDir }),
92
+ onSizeMismatch: 'pad',
93
+ manifest: {
94
+ writer: writer ??
95
+ new MemoryManifestWriter(path_1.default.join(rootDir, 'unused.json'), {
96
+ projectRoot: rootDir,
97
+ runner: { name: 'playwright' },
98
+ }),
99
+ },
100
+ messages,
101
+ plugins: [matchImagePlugin(pixelmatch), (0, analysis_1.analysisPlugin)()],
102
+ });
103
+ };
104
+ exports.createComparison = createComparison;
105
+ /**
106
+ * Stamps the screenshot with the package marker, compares it with the
107
+ * baseline and leaves the files on disk the way the manifest contract
108
+ * describes (`.actual.png` and `.diff.png` only for failures). The comparison
109
+ * itself is `visual-regression-compare`'s; this maps `matchImage`'s options
110
+ * onto it.
111
+ */
112
+ const compareImages = async (cfg, comparer) => {
113
+ const diffPath = (0, exports.diffPathFor)(cfg.actualPath);
114
+ const compare = () => comparer.compare({
115
+ name: cfg.name ?? path_1.default.basename(cfg.baselinePath, '.png'),
116
+ // stamped once, so every file derived from it carries the package marker
117
+ actual: (0, image_utils_1.addPNGMetadata)(cfg.imgNew),
118
+ files: {
119
+ baseline: cfg.baselinePath,
120
+ actual: cfg.actualPath,
121
+ diff: diffPath,
122
+ },
123
+ test: cfg.test,
124
+ platform: cfg.platform,
125
+ viewport: cfg.viewport,
126
+ entry: cfg.entry,
127
+ options: {
128
+ limits: { maxDiffRatio: cfg.maxDiffThreshold },
129
+ engineOptions: { ...cfg.diffConfig },
130
+ update: cfg.updateImages === true
131
+ ? 'all'
132
+ : cfg.updateImages === 'failures-only'
133
+ ? 'failures-only'
134
+ : 'none',
135
+ onMissingBaseline: cfg.createMissingImages ? 'create' : 'fail',
136
+ },
137
+ }, { include: ['baseline', 'actual', 'diff'] });
138
+ const { entry, images } = await (cfg.analysis === false
139
+ ? compare()
140
+ : (0, analysis_1.withAnalysis)(compare));
141
+ const status = entry.status;
142
+ const buffer = (bytes) => bytes ? Buffer.from(bytes) : undefined;
143
+ return {
144
+ status,
145
+ error: status === 'failed' || status === 'missing-baseline',
146
+ message: entry.message ?? '',
147
+ description: (0, analysis_1.analysisOf)(entry)?.description,
148
+ diffRatio: entry.comparison.diffRatio,
149
+ threshold: cfg.maxDiffThreshold,
150
+ baselineWritten: entry.baselineWritten,
151
+ diffPath,
152
+ imgNew: buffer(images.actual),
153
+ imgOld: buffer(images.baseline),
154
+ imgDiff: buffer(images.diff),
155
+ entry,
156
+ };
157
+ };
158
+ exports.compareImages = compareImages;
@@ -0,0 +1,29 @@
1
+ export declare const PLUGIN_NAME = "pw-visual-regression-diff";
2
+ export declare enum FILE_SUFFIX {
3
+ diff = ".diff",
4
+ actual = ".actual"
5
+ }
6
+ export declare const PATH_VARIABLES: {
7
+ readonly specPath: "{spec_path}";
8
+ /** `{os}-{browser}`, e.g. `linux-chromium` */
9
+ readonly platform: "{platform}";
10
+ /** `process.platform`: `linux`, `darwin` or `win32` */
11
+ readonly os: "{os}";
12
+ /** The browser that rendered the screenshot: `chromium`, `firefox` or `webkit` */
13
+ readonly browser: "{browser}";
14
+ readonly unixSystemRootPath: "{unix_system_root_path}";
15
+ readonly winSystemRootPath: "{win_system_root_path}";
16
+ };
17
+ export declare const WINDOWS_LIKE_DRIVE_REGEX: RegExp;
18
+ export declare const DEFAULT_IMAGES_PATH = "{spec_path}/__image_snapshots__";
19
+ /**
20
+ * PNG metadata key and image format version, identical to the Cypress
21
+ * plugin's: both tools compare the same way, so a baseline made by one is a
22
+ * valid baseline for the other.
23
+ */
24
+ export declare const METADATA_KEY = "FRSOURCE_CPVRD_V";
25
+ export declare const DIFF_IMAGES_VERSION = "1";
26
+ /** Set by `remoteBrowser()` in `playwright.config`, read by the global setup/teardown. */
27
+ export declare const REMOTE_ENV_KEY = "PIXSAME_PLAYWRIGHT_REMOTE";
28
+ /** Set by the global setup once the container runs, read by every worker for the manifest's `renderer` block. */
29
+ export declare const REMOTE_INFO_ENV_KEY = "PIXSAME_PLAYWRIGHT_REMOTE_INFO";
@@ -0,0 +1,33 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.REMOTE_INFO_ENV_KEY = exports.REMOTE_ENV_KEY = exports.DIFF_IMAGES_VERSION = exports.METADATA_KEY = exports.DEFAULT_IMAGES_PATH = exports.WINDOWS_LIKE_DRIVE_REGEX = exports.PATH_VARIABLES = exports.FILE_SUFFIX = exports.PLUGIN_NAME = void 0;
4
+ exports.PLUGIN_NAME = 'pw-visual-regression-diff';
5
+ var FILE_SUFFIX;
6
+ (function (FILE_SUFFIX) {
7
+ FILE_SUFFIX["diff"] = ".diff";
8
+ FILE_SUFFIX["actual"] = ".actual";
9
+ })(FILE_SUFFIX || (exports.FILE_SUFFIX = FILE_SUFFIX = {}));
10
+ exports.PATH_VARIABLES = {
11
+ specPath: '{spec_path}',
12
+ /** `{os}-{browser}`, e.g. `linux-chromium` */
13
+ platform: '{platform}',
14
+ /** `process.platform`: `linux`, `darwin` or `win32` */
15
+ os: '{os}',
16
+ /** The browser that rendered the screenshot: `chromium`, `firefox` or `webkit` */
17
+ browser: '{browser}',
18
+ unixSystemRootPath: '{unix_system_root_path}',
19
+ winSystemRootPath: '{win_system_root_path}',
20
+ };
21
+ exports.WINDOWS_LIKE_DRIVE_REGEX = /^[A-Z]:$/;
22
+ exports.DEFAULT_IMAGES_PATH = '{spec_path}/__image_snapshots__';
23
+ /**
24
+ * PNG metadata key and image format version, identical to the Cypress
25
+ * plugin's: both tools compare the same way, so a baseline made by one is a
26
+ * valid baseline for the other.
27
+ */
28
+ exports.METADATA_KEY = 'FRSOURCE_CPVRD_V';
29
+ exports.DIFF_IMAGES_VERSION = '1';
30
+ /** Set by `remoteBrowser()` in `playwright.config`, read by the global setup/teardown. */
31
+ exports.REMOTE_ENV_KEY = 'PIXSAME_PLAYWRIGHT_REMOTE';
32
+ /** Set by the global setup once the container runs, read by every worker for the manifest's `renderer` block. */
33
+ exports.REMOTE_INFO_ENV_KEY = 'PIXSAME_PLAYWRIGHT_REMOTE_INFO';
@@ -0,0 +1,78 @@
1
+ import { type Fixtures, type Locator, type LocatorScreenshotOptions, type Page, type PageScreenshotOptions, type PlaywrightTestArgs, type PlaywrightTestOptions, type PlaywrightWorkerArgs, type PlaywrightWorkerOptions } from '@playwright/test';
2
+ import type { Comparer } from 'visual-regression-compare' with {
3
+ 'resolution-mode': 'import'
4
+ };
5
+ import type { ManifestWriter } from 'visual-regression-manifest';
6
+ import { type CompareStatus, type PixelmatchOptions } from './compare';
7
+ export type MatchImageOptions = {
8
+ /**
9
+ * Where baselines live. Relative paths resolve against Playwright's
10
+ * `rootDir`. Tokens: `{spec_path}` (directory of the test file, whole
11
+ * segment only), `{platform}` (`{os}-{browser}`), `{os}`, `{browser}`.
12
+ * @default '{spec_path}/__image_snapshots__'
13
+ */
14
+ imagesPath?: string;
15
+ /** Maximum share of differing pixels, 0..1. @default 0.01 */
16
+ maxDiffThreshold?: number;
17
+ /** pixelmatch options; `includeAA: false` unless overridden. @default {} */
18
+ diffConfig?: PixelmatchOptions;
19
+ /** Create the baseline from the first screenshot instead of failing. @default true */
20
+ createMissingImages?: boolean;
21
+ /** `true` overwrites every baseline, `'failures-only'` only the ones that failed. @default false */
22
+ updateImages?: boolean | 'failures-only';
23
+ /** Screenshot name; defaults to the test's title path joined with spaces. */
24
+ title?: string;
25
+ /** Compare against this file instead of the derived baseline path (never token-expanded). */
26
+ matchAgainstPath?: string;
27
+ /** Passed to `page.screenshot()` / `locator.screenshot()`. */
28
+ screenshotConfig?: PageScreenshotOptions & LocatorScreenshotOptions;
29
+ /** Disables CSS animations and hides the caret for the screenshot. @default true */
30
+ deterministicRendering?: boolean;
31
+ /**
32
+ * Describe what changed when a comparison finds differences (changed areas,
33
+ * a layout shift, rendering noise). It never changes whether the comparison
34
+ * passes. @default true
35
+ */
36
+ analysis?: boolean;
37
+ };
38
+ export type VisualRegressionOptions = MatchImageOptions;
39
+ export type MatchImageResult = {
40
+ status: CompareStatus;
41
+ message: string;
42
+ /** Share of differing pixels, or `undefined` when nothing was compared. */
43
+ diffValue: number | undefined;
44
+ /** Baseline path. */
45
+ imgPath: string;
46
+ /** `.actual.png` path (only exists on disk for failures). */
47
+ imgNewPath: string;
48
+ /** `.diff.png` path (only exists on disk for failures). */
49
+ imgDiffPath: string;
50
+ imgNew: Buffer | undefined;
51
+ img: Buffer | undefined;
52
+ imgDiff: Buffer | undefined;
53
+ };
54
+ export type MatchImage = (target?: Page | Locator, options?: MatchImageOptions) => Promise<MatchImageResult>;
55
+ export type VisualRegressionTestFixtures = {
56
+ /** Global `matchImage` defaults, set through `use` in `playwright.config`. */
57
+ visualRegression: VisualRegressionOptions;
58
+ /** Takes a screenshot of the page (or a locator) and compares it with its baseline. */
59
+ matchImage: MatchImage;
60
+ };
61
+ export type VisualRegressionWorkerFixtures = {
62
+ /**
63
+ * Where the run manifest goes (relative paths resolve against `rootDir`);
64
+ * `false` disables it. Every worker process writes its own file, so a
65
+ * configured `reports/run.json` becomes `reports/run.w0.json`,
66
+ * `reports/run.w1.json`, ... (`w<workerIndex>`, unique per process even
67
+ * when Playwright restarts a worker after a failure).
68
+ * @default '<outputDir>/visual-regression-manifest.playwright.w<workerIndex>.json'
69
+ */
70
+ visualRegressionManifestPath: string | false | undefined;
71
+ /** The worker's manifest writer from `visual-regression-manifest`; `null` when disabled. */
72
+ visualRegressionManifest: ManifestWriter | null;
73
+ /** The worker's `visual-regression-compare` comparer; records into `visualRegressionManifest`. */
74
+ visualRegressionComparer: Comparer;
75
+ };
76
+ export declare const visualRegressionFixtures: Fixtures<VisualRegressionTestFixtures, VisualRegressionWorkerFixtures, PlaywrightTestArgs & PlaywrightTestOptions, PlaywrightWorkerArgs & PlaywrightWorkerOptions>;
77
+ export declare const test: import("@playwright/test").TestType<PlaywrightTestArgs & PlaywrightTestOptions & VisualRegressionTestFixtures, PlaywrightWorkerArgs & PlaywrightWorkerOptions & VisualRegressionWorkerFixtures>;
78
+ export { expect } from '@playwright/test';