playwright-utils
Usefull playwright utilities, such as fixtures, custom commands and matchers.
Installation
npm install --save-dev @gemini-testing/playwright-utils
Contents
Matchers
ToMatchScreenshot
looks-same based visual comparison. It uses CIEDE2000 based tolerance instead of pixelmatch (which is used under the hood of toHaveScreenshot
) YIQ NTSC transmission color space threshold, which has severe problems calculating the color difference in shades of blue.
Usage
Setup:
import { test as base, expect } from "@playwright/test";
import { createMatchersFixture, type PlaywrightUtilsOptions } from "@gemini-testing/playwright-utils";
const test = base.extend<PlaywrightTestOptions & PlaywrightUtilsOptions>({
...createMatchersFixture(expect)
});
export { test, expect };
import { defineConfig, type PlaywrightTestOptions } from "@playwright/test";
import type { PlaywrightUtilsOptions } from "@gemini-testing/playwright-utils";
export default defineConfig<PlaywrightTestOptions, PlaywrightUtilsOptions>({
use: {
toMatchScreenshot: {
tolerance: 2.3,
antialiasingTolerance: 4,
maxDiffPixels: 0,
maxDiffPixelRatio: 0,
stopOnFirstImageDiff: false,
saveImageOnScreenshotMatch: true,
animations: "disabled",
caret: "hide",
maskColor: "#FF00FF",
scale: "css",
timeout: 30000,
fullPage: false,
}
}
});
Usage:
await expect(page.locator("body")).toMatchScreenshot("plain", {
maxDiffPixels: 3
});
Args:
- snapshotName:
string
- opts?:
Object
Migration from toHaveScreenshot
:
- If you have
toHaveScreenshot
calls without specified name
, it is required to name them. - Move contents of your
toHaveScreenshot
options from expect
section of playwright config to toMatchScreenshot
at use
section of playwright config, then remove threshold
property (toMatchScreenshot
uses tolerance
instead. Preferred value is 2.3).
Note: Screenshot comparison errors, caused by toMatchScreenshot
, won't stop test execution by default. You can configure it with stopOnFirstImageDiff
option.