playwright-utils

Usefull playwright utilities, such as fixtures, custom commands and matchers.

Installation

npm install --save-dev @gemini-testing/playwright-utils

Contents

• Matchers
  • ToMatchScreenshot
    • Usage
    • Migration from toHaveScreenshot:

Matchers

• toMatchScreenshot

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:

// playwright.ts
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 };

// playwright.config.ts
import { defineConfig, type PlaywrightTestOptions } from "@playwright/test";
import type { PlaywrightUtilsOptions } from "@gemini-testing/playwright-utils";

export default defineConfig<PlaywrightTestOptions, PlaywrightUtilsOptions>({
    // ...
    use: {
        // ...
        toMatchScreenshot: {
            // Default project config
            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", {
    // Comparison options, have higher priority than project options
    maxDiffPixels: 3
});

Args:

• snapshotName: string
• opts?: Object
  • tolerance: number
  • antialiasingTolerance: number
  • shouldCluster: boolean - Used by [html-reporter][html-reporter]'s diffBubbles
  • clustersSize: number - Used by [html-reporter][html-reporter]'s diffBubbles
  • maxDiffPixels: number
  • maxDiffPixelRatio: number
  • [stopOnFirstImageDiff]: boolean - Stop test execution immediately after image comparison error
  • [saveImageOnScreenshotMatch]: boolean - Save image on image comparison success (used by reporters)
  • animations: "disabled" | "allow"
  • caret: "hide" | "initial"
  • maskColor: string
  • scale: "css" | "device"
  • fullPage: boolean
  • timeout: number - Screenshot capturing timeout

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.