@pixsame/playwright-visual-regression-diff 0.0.0-stage → 0.0.0
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 +21 -0
- package/README.md +168 -2
- package/dist/compare.d.ts +67 -0
- package/dist/compare.js +151 -0
- package/dist/constants.d.ts +29 -0
- package/dist/constants.js +33 -0
- package/dist/fixture.d.ts +72 -0
- package/dist/fixture.js +157 -0
- package/dist/fs.utils.d.ts +5 -0
- package/dist/fs.utils.js +35 -0
- package/dist/image.utils.d.ts +13 -0
- package/dist/image.utils.js +29 -0
- package/dist/index.d.ts +4 -0
- package/dist/index.js +16 -0
- package/dist/manifest.utils.d.ts +76 -0
- package/dist/manifest.utils.js +128 -0
- package/dist/remote.d.ts +104 -0
- package/dist/remote.global-setup.d.ts +2 -0
- package/dist/remote.global-setup.js +14 -0
- package/dist/remote.global-teardown.d.ts +2 -0
- package/dist/remote.global-teardown.js +12 -0
- package/dist/remote.js +263 -0
- package/dist/screenshotPath.d.ts +30 -0
- package/dist/screenshotPath.js +55 -0
- package/package.json +80 -3
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
CHANGED
|
@@ -1,3 +1,169 @@
|
|
|
1
|
-
#
|
|
1
|
+
# pixsame for Playwright
|
|
2
2
|
|
|
3
|
-
|
|
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: options may still change. The API below is small on purpose and may still move 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
|
+
- **Same comparison.** `pixelmatch` with `includeAA: false`, the same padding for size mismatches, the same `<name>_#n.png` / `.actual.png` / `.diff.png` files, the same PNG marker. 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
|
+
- **Same run manifest.** 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
|
+
- **Drift-free pixels without leaving your machine.** `remoteBrowser()` runs the browser inside the official Playwright image and keeps the test runner, your app and your editor native. Local and CI screenshots then 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
|
+
|
|
83
|
+
Screenshots are taken at the context's `deviceScaleFactor` (1 by default); nothing is rescaled.
|
|
84
|
+
|
|
85
|
+
### Baselines per browser or platform
|
|
86
|
+
|
|
87
|
+
Playwright projects commonly run the same test in several browsers. Add `{browser}` (or `{platform}`) to `imagesPath` so each gets its own folder:
|
|
88
|
+
|
|
89
|
+
```ts
|
|
90
|
+
use: {
|
|
91
|
+
visualRegression: {
|
|
92
|
+
imagesPath: '{spec_path}/__image_snapshots__/{browser}';
|
|
93
|
+
}
|
|
94
|
+
}
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
## Remote browser in Docker
|
|
98
|
+
|
|
99
|
+
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.
|
|
100
|
+
|
|
101
|
+
```ts
|
|
102
|
+
// playwright.config.ts
|
|
103
|
+
import { defineConfig } from '@playwright/test';
|
|
104
|
+
import { remoteBrowser } from '@pixsame/playwright-visual-regression-diff/remote';
|
|
105
|
+
|
|
106
|
+
const remote = remoteBrowser({ keepAlive: true });
|
|
107
|
+
|
|
108
|
+
export default defineConfig({
|
|
109
|
+
globalSetup: remote.globalSetup,
|
|
110
|
+
globalTeardown: remote.globalTeardown,
|
|
111
|
+
use: {
|
|
112
|
+
connectOptions: remote.connectOptions,
|
|
113
|
+
baseURL: 'http://localhost:3000',
|
|
114
|
+
},
|
|
115
|
+
});
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
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.
|
|
119
|
+
|
|
120
|
+
| option | default | |
|
|
121
|
+
| ------------------- | ----------------------------------------------- | --------------------------------------------------------------------------------------------------- |
|
|
122
|
+
| `port` | `3000` | Host port; fixed because `playwright.config` needs the endpoint before anything runs. |
|
|
123
|
+
| `playwrightVersion` | detected from `node_modules` | Has to equal the version your tests run with; the image tag is derived from it. |
|
|
124
|
+
| `image` | `mcr.microsoft.com/playwright:v<version>-noble` | Any image that can run `npx playwright run-server`. |
|
|
125
|
+
| `keepAlive` | `false` | Leave the container running so the next `playwright test` skips the cold start. |
|
|
126
|
+
| `exposeNetwork` | `'<loopback>'` | Playwright's `connectOptions.exposeNetwork`; `false` to disable (then use `host.docker.internal`). |
|
|
127
|
+
| `dockerArgs` | `[]` | Extra `docker run` arguments, e.g. `['--platform=linux/amd64']` for parity with an amd64 CI runner. |
|
|
128
|
+
| `startTimeoutMs` | `600000` | Includes the image pull on first use (about 2 GB). |
|
|
129
|
+
|
|
130
|
+
Things to know:
|
|
131
|
+
|
|
132
|
+
- The first run pulls the image, which takes minutes. `docker pull` it ahead of time or bake it into your CI image.
|
|
133
|
+
- 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).
|
|
134
|
+
- 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.
|
|
135
|
+
- 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).
|
|
136
|
+
- 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.
|
|
137
|
+
|
|
138
|
+
## Run manifest
|
|
139
|
+
|
|
140
|
+
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.
|
|
141
|
+
|
|
142
|
+
Two blocks are worth calling out:
|
|
143
|
+
|
|
144
|
+
- `runner`: `{ name: 'playwright', version, mode: 'run', configFile, browser, baseUrl, viewport, retries, project, testDir, outputDir, workers, shard, parallelIndex, workerIndex }`.
|
|
145
|
+
- `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.
|
|
146
|
+
|
|
147
|
+
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`.
|
|
148
|
+
|
|
149
|
+
The `visualRegressionManifest` worker fixture exposes the underlying `ManifestWriter` (`null` when `visualRegressionManifestPath: false`) if you want to record something yourself.
|
|
150
|
+
|
|
151
|
+
## Relation to the Cypress plugin and what is next
|
|
152
|
+
|
|
153
|
+
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:
|
|
154
|
+
|
|
155
|
+
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`).
|
|
156
|
+
2. `{browser}` naming the renderer's browser explicitly once several renderers per run are possible.
|
|
157
|
+
3. DOM-snapshot capture (`page.evaluate` + `page.on('response')`) for the hosted renderer and for uploading snapshots alongside images.
|
|
158
|
+
4. A `toMatchImage()` matcher for people who prefer `expect(page).toMatchImage()` over the fixture.
|
|
159
|
+
|
|
160
|
+
## Development
|
|
161
|
+
|
|
162
|
+
```bash
|
|
163
|
+
pnpm --filter @pixsame/playwright-visual-regression-diff build
|
|
164
|
+
pnpm --filter @pixsame/playwright-visual-regression-diff test:integration # unit tests, no browser needed
|
|
165
|
+
pnpm --filter @pixsame/playwright-visual-regression-diff test:smoke # needs `npx playwright install chromium`
|
|
166
|
+
pnpm --filter @pixsame/playwright-visual-regression-diff test:smoke:remote # needs Docker; pulls the Playwright image
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
The smoke tests write their baselines to `e2e/__image_snapshots__` (gitignored): the first run creates them, the second compares.
|
|
@@ -0,0 +1,67 @@
|
|
|
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
|
+
/** Screenshot name recorded on the manifest entry; defaults to the baseline's file name. */
|
|
20
|
+
name?: string;
|
|
21
|
+
/** The test the screenshot belongs to, recorded on the manifest entry. */
|
|
22
|
+
test?: {
|
|
23
|
+
filePath: string;
|
|
24
|
+
titlePath: string[];
|
|
25
|
+
retry: number;
|
|
26
|
+
};
|
|
27
|
+
platform?: ManifestEntryPlatform;
|
|
28
|
+
viewport?: ManifestViewport;
|
|
29
|
+
/** Entry fields the comparer cannot know: the resolved `options` and the `renderer`. */
|
|
30
|
+
entry?: Pick<ManifestEntryInput, 'options' | 'renderer'>;
|
|
31
|
+
};
|
|
32
|
+
export type CompareResult = {
|
|
33
|
+
status: CompareStatus;
|
|
34
|
+
/** `true` when the test should fail. */
|
|
35
|
+
error: boolean;
|
|
36
|
+
message: string;
|
|
37
|
+
/** Share of differing pixels, 0..1; `0` when no comparison ran. */
|
|
38
|
+
diffRatio: number;
|
|
39
|
+
threshold: number;
|
|
40
|
+
/** `true` whenever the baseline file was (re)written. */
|
|
41
|
+
baselineWritten: boolean;
|
|
42
|
+
/** Path of the `.diff.png` sibling of `actualPath`. */
|
|
43
|
+
diffPath: string;
|
|
44
|
+
/** The compared images (padded to a common size when they differed in size); absent when no comparison ran. */
|
|
45
|
+
imgNew?: Buffer;
|
|
46
|
+
imgOld?: Buffer;
|
|
47
|
+
imgDiff?: Buffer;
|
|
48
|
+
/** What the comparer recorded in the manifest. */
|
|
49
|
+
entry: ManifestEntry;
|
|
50
|
+
};
|
|
51
|
+
export declare const diffPathFor: (actualPath: string) => string;
|
|
52
|
+
/**
|
|
53
|
+
* The comparer of one worker, recording into `writer` (or, with the manifest
|
|
54
|
+
* disabled, into memory). Sizes that differ are padded and compared, as the
|
|
55
|
+
* Cypress plugin does.
|
|
56
|
+
*/
|
|
57
|
+
export declare const createComparison: (writer: ManifestWriter | null, { rootDir }: {
|
|
58
|
+
rootDir: string;
|
|
59
|
+
}) => Promise<Comparer>;
|
|
60
|
+
/**
|
|
61
|
+
* Stamps the screenshot with the package marker, compares it with the
|
|
62
|
+
* baseline and leaves the files on disk the way the manifest contract
|
|
63
|
+
* describes (`.actual.png` and `.diff.png` only for failures). The comparison
|
|
64
|
+
* itself is `visual-regression-compare`'s; this maps `matchImage`'s options
|
|
65
|
+
* onto it.
|
|
66
|
+
*/
|
|
67
|
+
export declare const compareImages: (cfg: CompareInput, comparer: Comparer) => Promise<CompareResult>;
|
package/dist/compare.js
ADDED
|
@@ -0,0 +1,151 @@
|
|
|
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 fs_1 = __importDefault(require("fs"));
|
|
8
|
+
const path_1 = __importDefault(require("path"));
|
|
9
|
+
const visual_regression_manifest_1 = require("visual-regression-manifest");
|
|
10
|
+
const constants_1 = require("./constants");
|
|
11
|
+
const image_utils_1 = require("./image.utils");
|
|
12
|
+
// pixelmatch 7 and visual-regression-compare are ESM-only; a dynamic import
|
|
13
|
+
// keeps this package usable from a CommonJS `playwright.config` on every
|
|
14
|
+
// supported Node version
|
|
15
|
+
let pixelmatchPromise;
|
|
16
|
+
const loadPixelmatch = () => (pixelmatchPromise ??= import('pixelmatch').then((m) => m.default));
|
|
17
|
+
const diffPathFor = (actualPath) => actualPath.replace(constants_1.FILE_SUFFIX.actual, constants_1.FILE_SUFFIX.diff);
|
|
18
|
+
exports.diffPathFor = diffPathFor;
|
|
19
|
+
/** The words `matchImage` users need when there is nothing to compare with: the path and the way out. */
|
|
20
|
+
const messages = {
|
|
21
|
+
'missing-baseline': ({ baselinePath }) => `Baseline image is missing at path: "${baselinePath}". Provide a baseline image or enable "createMissingImages" option in plugin configuration.`,
|
|
22
|
+
};
|
|
23
|
+
/** A baseline of a passed comparison that was not made by this package (no marker) is refreshed from the screenshot. */
|
|
24
|
+
const isUnstamped = ({ input }) => input.files !== undefined &&
|
|
25
|
+
!(0, image_utils_1.isImageCurrentVersion)(fs_1.default.readFileSync(input.files.baseline));
|
|
26
|
+
/**
|
|
27
|
+
* What `matchImage` does differently from the comparer's defaults:
|
|
28
|
+
* - pixelmatch with every one of its options (`alpha`, `aaColor`, `diffColor`,
|
|
29
|
+
* `diffMask`, ...), not only the `threshold` and `includeAA` of the built-in
|
|
30
|
+
* engine, and anti-aliased pixels not counted unless asked for; registered
|
|
31
|
+
* under the built-in's name, so it takes its place;
|
|
32
|
+
* - the `.diff.png` carries the package marker, like the screenshot does;
|
|
33
|
+
* - a passed comparison whose baseline lacks the marker refreshes the baseline,
|
|
34
|
+
* so the file is rewritten once instead of by whoever runs the test next.
|
|
35
|
+
*/
|
|
36
|
+
const matchImagePlugin = (pixelmatch) => ({
|
|
37
|
+
name: '@pixsame/playwright-visual-regression-diff',
|
|
38
|
+
setup: (api) => {
|
|
39
|
+
api.on('beforeWrite', (ctx, { write }) => ({
|
|
40
|
+
write: [
|
|
41
|
+
...write.map((file) => file.ref.kind === 'diff'
|
|
42
|
+
? { ...file, bytes: (0, image_utils_1.addPNGMetadata)(Buffer.from(file.bytes)) }
|
|
43
|
+
: file),
|
|
44
|
+
...(ctx.decision?.status === 'passed' && isUnstamped(ctx)
|
|
45
|
+
? [
|
|
46
|
+
{
|
|
47
|
+
ref: { kind: 'baseline', path: 'baseline' },
|
|
48
|
+
bytes: ctx.input.actual,
|
|
49
|
+
},
|
|
50
|
+
]
|
|
51
|
+
: []),
|
|
52
|
+
],
|
|
53
|
+
}));
|
|
54
|
+
api.addEngine('pixelmatch', (options) => ({
|
|
55
|
+
name: 'pixelmatch',
|
|
56
|
+
colorMetric: 'yiq',
|
|
57
|
+
colorThreshold: typeof options.threshold === 'number' ? options.threshold : 0.1,
|
|
58
|
+
compare(baseline, actual) {
|
|
59
|
+
const { width, height } = baseline;
|
|
60
|
+
const diff = new Uint8ClampedArray(width * height * 4);
|
|
61
|
+
const diffPixels = pixelmatch(baseline.data, actual.data, diff, width, height, { includeAA: false, ...options });
|
|
62
|
+
return {
|
|
63
|
+
diffPixels,
|
|
64
|
+
diffRatio: width * height === 0 ? 0 : diffPixels / (width * height),
|
|
65
|
+
diff: { width, height, data: diff },
|
|
66
|
+
};
|
|
67
|
+
},
|
|
68
|
+
}));
|
|
69
|
+
},
|
|
70
|
+
});
|
|
71
|
+
/** A manifest writer that keeps its entries in memory: for a run with the manifest turned off. */
|
|
72
|
+
class MemoryManifestWriter extends visual_regression_manifest_1.ManifestWriter {
|
|
73
|
+
write() { }
|
|
74
|
+
flush() { }
|
|
75
|
+
}
|
|
76
|
+
/**
|
|
77
|
+
* The comparer of one worker, recording into `writer` (or, with the manifest
|
|
78
|
+
* disabled, into memory). Sizes that differ are padded and compared, as the
|
|
79
|
+
* Cypress plugin does.
|
|
80
|
+
*/
|
|
81
|
+
const createComparison = async (writer, { rootDir }) => {
|
|
82
|
+
const [{ createComparer, fsStore }, pixelmatch] = await Promise.all([
|
|
83
|
+
import('visual-regression-compare'),
|
|
84
|
+
loadPixelmatch(),
|
|
85
|
+
]);
|
|
86
|
+
return createComparer({
|
|
87
|
+
// every call names its files, so the store is never asked for a path
|
|
88
|
+
store: fsStore({ baselineDir: rootDir }),
|
|
89
|
+
onSizeMismatch: 'pad',
|
|
90
|
+
manifest: {
|
|
91
|
+
writer: writer ??
|
|
92
|
+
new MemoryManifestWriter(path_1.default.join(rootDir, 'unused.json'), {
|
|
93
|
+
projectRoot: rootDir,
|
|
94
|
+
runner: { name: 'playwright' },
|
|
95
|
+
}),
|
|
96
|
+
},
|
|
97
|
+
messages,
|
|
98
|
+
plugins: [matchImagePlugin(pixelmatch)],
|
|
99
|
+
});
|
|
100
|
+
};
|
|
101
|
+
exports.createComparison = createComparison;
|
|
102
|
+
/**
|
|
103
|
+
* Stamps the screenshot with the package marker, compares it with the
|
|
104
|
+
* baseline and leaves the files on disk the way the manifest contract
|
|
105
|
+
* describes (`.actual.png` and `.diff.png` only for failures). The comparison
|
|
106
|
+
* itself is `visual-regression-compare`'s; this maps `matchImage`'s options
|
|
107
|
+
* onto it.
|
|
108
|
+
*/
|
|
109
|
+
const compareImages = async (cfg, comparer) => {
|
|
110
|
+
const diffPath = (0, exports.diffPathFor)(cfg.actualPath);
|
|
111
|
+
const { entry, images } = await comparer.compare({
|
|
112
|
+
name: cfg.name ?? path_1.default.basename(cfg.baselinePath, '.png'),
|
|
113
|
+
// stamped once, so every file derived from it carries the package marker
|
|
114
|
+
actual: (0, image_utils_1.addPNGMetadata)(cfg.imgNew),
|
|
115
|
+
files: {
|
|
116
|
+
baseline: cfg.baselinePath,
|
|
117
|
+
actual: cfg.actualPath,
|
|
118
|
+
diff: diffPath,
|
|
119
|
+
},
|
|
120
|
+
test: cfg.test,
|
|
121
|
+
platform: cfg.platform,
|
|
122
|
+
viewport: cfg.viewport,
|
|
123
|
+
entry: cfg.entry,
|
|
124
|
+
options: {
|
|
125
|
+
limits: { maxDiffRatio: cfg.maxDiffThreshold },
|
|
126
|
+
engineOptions: { ...cfg.diffConfig },
|
|
127
|
+
update: cfg.updateImages === true
|
|
128
|
+
? 'all'
|
|
129
|
+
: cfg.updateImages === 'failures-only'
|
|
130
|
+
? 'failures-only'
|
|
131
|
+
: 'none',
|
|
132
|
+
onMissingBaseline: cfg.createMissingImages ? 'create' : 'fail',
|
|
133
|
+
},
|
|
134
|
+
}, { include: ['baseline', 'actual', 'diff'] });
|
|
135
|
+
const status = entry.status;
|
|
136
|
+
const buffer = (bytes) => bytes ? Buffer.from(bytes) : undefined;
|
|
137
|
+
return {
|
|
138
|
+
status,
|
|
139
|
+
error: status === 'failed' || status === 'missing-baseline',
|
|
140
|
+
message: entry.message ?? '',
|
|
141
|
+
diffRatio: entry.comparison.diffRatio,
|
|
142
|
+
threshold: cfg.maxDiffThreshold,
|
|
143
|
+
baselineWritten: entry.baselineWritten,
|
|
144
|
+
diffPath,
|
|
145
|
+
imgNew: buffer(images.actual),
|
|
146
|
+
imgOld: buffer(images.baseline),
|
|
147
|
+
imgDiff: buffer(images.diff),
|
|
148
|
+
entry,
|
|
149
|
+
};
|
|
150
|
+
};
|
|
151
|
+
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,72 @@
|
|
|
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
|
+
export type VisualRegressionOptions = MatchImageOptions;
|
|
33
|
+
export type MatchImageResult = {
|
|
34
|
+
status: CompareStatus;
|
|
35
|
+
message: string;
|
|
36
|
+
/** Share of differing pixels, or `undefined` when nothing was compared. */
|
|
37
|
+
diffValue: number | undefined;
|
|
38
|
+
/** Baseline path. */
|
|
39
|
+
imgPath: string;
|
|
40
|
+
/** `.actual.png` path (only exists on disk for failures). */
|
|
41
|
+
imgNewPath: string;
|
|
42
|
+
/** `.diff.png` path (only exists on disk for failures). */
|
|
43
|
+
imgDiffPath: string;
|
|
44
|
+
imgNew: Buffer | undefined;
|
|
45
|
+
img: Buffer | undefined;
|
|
46
|
+
imgDiff: Buffer | undefined;
|
|
47
|
+
};
|
|
48
|
+
export type MatchImage = (target?: Page | Locator, options?: MatchImageOptions) => Promise<MatchImageResult>;
|
|
49
|
+
export type VisualRegressionTestFixtures = {
|
|
50
|
+
/** Global `matchImage` defaults, set through `use` in `playwright.config`. */
|
|
51
|
+
visualRegression: VisualRegressionOptions;
|
|
52
|
+
/** Takes a screenshot of the page (or a locator) and compares it with its baseline. */
|
|
53
|
+
matchImage: MatchImage;
|
|
54
|
+
};
|
|
55
|
+
export type VisualRegressionWorkerFixtures = {
|
|
56
|
+
/**
|
|
57
|
+
* Where the run manifest goes (relative paths resolve against `rootDir`);
|
|
58
|
+
* `false` disables it. Every worker process writes its own file, so a
|
|
59
|
+
* configured `reports/run.json` becomes `reports/run.w0.json`,
|
|
60
|
+
* `reports/run.w1.json`, ... (`w<workerIndex>`, unique per process even
|
|
61
|
+
* when Playwright restarts a worker after a failure).
|
|
62
|
+
* @default '<outputDir>/visual-regression-manifest.playwright.w<workerIndex>.json'
|
|
63
|
+
*/
|
|
64
|
+
visualRegressionManifestPath: string | false | undefined;
|
|
65
|
+
/** The worker's manifest writer from `visual-regression-manifest`; `null` when disabled. */
|
|
66
|
+
visualRegressionManifest: ManifestWriter | null;
|
|
67
|
+
/** The worker's `visual-regression-compare` comparer; records into `visualRegressionManifest`. */
|
|
68
|
+
visualRegressionComparer: Comparer;
|
|
69
|
+
};
|
|
70
|
+
export declare const visualRegressionFixtures: Fixtures<VisualRegressionTestFixtures, VisualRegressionWorkerFixtures, PlaywrightTestArgs & PlaywrightTestOptions, PlaywrightWorkerArgs & PlaywrightWorkerOptions>;
|
|
71
|
+
export declare const test: import("@playwright/test").TestType<PlaywrightTestArgs & PlaywrightTestOptions & VisualRegressionTestFixtures, PlaywrightWorkerArgs & PlaywrightWorkerOptions & VisualRegressionWorkerFixtures>;
|
|
72
|
+
export { expect } from '@playwright/test';
|