@augment-vir/test 31.61.0 → 31.63.0

package/dist/test-playwright/compare-images.d.ts

@@ -0,0 +1,71 @@
+import type { Dimensions } from '@augment-vir/common';
+import { PNG } from 'pngjs';
+/**
+ * Options for image comparison thresholds.
+ *
+ * @category Internal
+ */
+export type ImageComparisonOptions = {
+    /**
+     * Per-pixel color threshold for `pixelmatch` (0–1). Smaller values make comparison more
+     * sensitive.
+     */
+    threshold: number;
+    /** Maximum ratio of differing pixels allowed before the comparison is considered a failure. */
+    maxDiffPixelRatio: number;
+};
+/**
+ * Default image comparison options used in {@link compareImages}.
+ *
+ * @category Internal
+ */
+export declare const defaultImageComparisonOptions: Readonly<ImageComparisonOptions>;
+/**
+ * The result of comparing two images via {@link compareImages}.
+ *
+ * @category Internal
+ */
+export type ImageComparisonResult = {
+    /** Whether the images match within the allowed diff ratio. */
+    passed: boolean;
+    /** The number of differing pixels. */
+    diffPixelCount: number;
+    /** Total pixel count of the (padded) comparison canvas. */
+    totalPixels: number;
+    /** The ratio of differing pixels to total pixels. */
+    diffRatio: number;
+    /** The dimensions of the comparison canvas. */
+    dimensions: Readonly<Dimensions>;
+    /** PNG data for the base image (padded to the comparison canvas). */
+    basePng: PNG;
+    /** PNG data for the current image (padded to the comparison canvas). */
+    currentPng: PNG;
+    /** PNG data for the visual diff output. */
+    diffPng: PNG;
+};
+/**
+ * Pads both images to the same canvas size (max width/height of the two) without scaling, then
+ * returns the decoded PNGs and the shared dimensions.
+ *
+ * @category Internal
+ */
+export declare function padToSameCanvas(aBuf: Buffer, bBuf: Buffer): Promise<{
+    aPng: import("pngjs").PNGWithMetadata;
+    bPng: import("pngjs").PNGWithMetadata;
+    dimensions: Readonly<Dimensions>;
+}>;
+/**
+ * Compare two PNG image buffers pixel-by-pixel. The images may have different dimensions — they
+ * will be padded to the same canvas size before comparison.
+ *
+ * This function is fully Playwright-agnostic and can be used in any Node.js context.
+ *
+ * @category Internal
+ */
+export declare function compareImages(baseImageBuffer: Buffer, currentImageBuffer: Buffer, options?: Readonly<ImageComparisonOptions>): Promise<ImageComparisonResult>;
+/**
+ * Encode a {@link PNG} instance to a `Buffer`.
+ *
+ * @category Internal
+ */
+export declare function encodePng(png: PNG): Buffer;

package/dist/test-playwright/compare-images.js

@@ -0,0 +1,87 @@
+import pixelmatch from 'pixelmatch';
+import { PNG } from 'pngjs';
+import sharp from 'sharp';
+/**
+ * Default image comparison options used in {@link compareImages}.
+ *
+ * @category Internal
+ */
+export const defaultImageComparisonOptions = {
+    threshold: 0.1,
+    maxDiffPixelRatio: 0.08,
+};
+async function padImage(image, { height, width }) {
+    return await sharp({
+        create: { width, height, channels: 4, background: { r: 0, g: 0, b: 0, alpha: 0 } },
+    })
+        /** Top-left align. */
+        .composite([{ input: image, left: 0, top: 0 }])
+        .png()
+        .toBuffer();
+}
+/**
+ * Pads both images to the same canvas size (max width/height of the two) without scaling, then
+ * returns the decoded PNGs and the shared dimensions.
+ *
+ * @category Internal
+ */
+export async function padToSameCanvas(aBuf, bBuf) {
+    const [aMeta, bMeta,] = await Promise.all([
+        sharp(aBuf).metadata(),
+        sharp(bBuf).metadata(),
+    ]);
+    if (!aMeta.width || !aMeta.height || !bMeta.width || !bMeta.height) {
+        throw new Error('Unable to read image dimensions.');
+    }
+    const dimensions = {
+        width: Math.max(aMeta.width, bMeta.width),
+        height: Math.max(aMeta.height, bMeta.height),
+    };
+    const [aPadded, bPadded,] = await Promise.all([
+        padImage(aBuf, dimensions),
+        padImage(bBuf, dimensions),
+    ]);
+    const aPng = PNG.sync.read(aPadded);
+    const bPng = PNG.sync.read(bPadded);
+    return {
+        aPng,
+        bPng,
+        dimensions,
+    };
+}
+/**
+ * Compare two PNG image buffers pixel-by-pixel. The images may have different dimensions — they
+ * will be padded to the same canvas size before comparison.
+ *
+ * This function is fully Playwright-agnostic and can be used in any Node.js context.
+ *
+ * @category Internal
+ */
+export async function compareImages(baseImageBuffer, currentImageBuffer, options = defaultImageComparisonOptions) {
+    const { aPng: basePng, bPng: currentPng, dimensions, } = await padToSameCanvas(baseImageBuffer, currentImageBuffer);
+    const diffPng = new PNG(dimensions);
+    const diffPixelCount = pixelmatch(basePng.data, currentPng.data, diffPng.data, dimensions.width, dimensions.height, {
+        threshold: options.threshold,
+    });
+    const totalPixels = dimensions.width * dimensions.height;
+    const diffRatio = diffPixelCount / totalPixels;
+    const passed = diffRatio <= options.maxDiffPixelRatio;
+    return {
+        passed,
+        diffPixelCount,
+        totalPixels,
+        diffRatio,
+        dimensions,
+        basePng,
+        currentPng,
+        diffPng,
+    };
+}
+/**
+ * Encode a {@link PNG} instance to a `Buffer`.
+ *
+ * @category Internal
+ */
+export function encodePng(png) {
+    return PNG.sync.write(png);
+}

package/dist/test-playwright/screenshot.js

@@ -5,10 +5,8 @@ import { expect } from '@playwright/test';
 import { existsSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
 import { relative } from 'node:path';
-import pixelmatch from 'pixelmatch';
-import { PNG } from 'pngjs';
-import sharp from 'sharp';
 import { assertTestContext, assertWrapTestContext, TestEnv, } from '../augments/universal-testing-suite/universal-test-context.js';
+import { compareImages, defaultImageComparisonOptions, encodePng } from './compare-images.js';
 /** This is used for type extraction because Playwright does not export the types we need. */
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
 function extractScreenshotMethod() {
@@ -29,40 +27,6 @@ export const defaultScreenshotOptions = {
     threshold: 0.1,
     maxDiffPixelRatio: 0.08,
 };
-async function padImage(image, { height, width }) {
-    return await sharp({
-        create: { width, height, channels: 4, background: { r: 0, g: 0, b: 0, alpha: 0 } },
-    })
-        /** Top-left align. */
-        .composite([{ input: image, left: 0, top: 0 }])
-        .png()
-        .toBuffer();
-}
-/** Pads both images to the same canvas (max width/height) without scaling. */
-async function padToSameCanvas(aBuf, bBuf) {
-    const [aMeta, bMeta,] = await Promise.all([
-        sharp(aBuf).metadata(),
-        sharp(bBuf).metadata(),
-    ]);
-    if (!aMeta.width || !aMeta.height || !bMeta.width || !bMeta.height) {
-        throw new Error('Unable to read image dimensions.');
-    }
-    const dimensions = {
-        width: Math.max(aMeta.width, bMeta.width),
-        height: Math.max(aMeta.height, bMeta.height),
-    };
-    const [aPadded, bPadded,] = await Promise.all([
-        padImage(aBuf, dimensions),
-        padImage(bBuf, dimensions),
-    ]);
-    const aPng = PNG.sync.read(aPadded);
-    const bPng = PNG.sync.read(bPadded);
-    return {
-        aPng,
-        bPng,
-        dimensions,
-    };
-}
 async function takeScreenshotBuffer(testContext, options = {}) {
     if (options.locator) {
         /** The locator expectation has different options than the page expectation. */
@@ -137,23 +101,19 @@ export async function expectScreenshot(testContext, options) {
         throw new Error(`Baseline screenshot not found: ${screenshotFilePath}. Re-run with --update-snapshots to create it.`);
     }
     const baseScreenshotBuffer = await readFile(screenshotFilePath);
-    const { aPng: baseScreenshotPng, bPng: currentScreenshotPng, dimensions, } = await padToSameCanvas(baseScreenshotBuffer, currentScreenshotBuffer);
-    const diffPng = new PNG(dimensions);
-    const diffPixelCount = pixelmatch(baseScreenshotPng.data, currentScreenshotPng.data, diffPng.data, dimensions.width, dimensions.height, {
+    const result = await compareImages(baseScreenshotBuffer, currentScreenshotBuffer, {
         threshold: defaultScreenshotOptions.threshold,
+        maxDiffPixelRatio: defaultScreenshotOptions.maxDiffPixelRatio,
     });
-    const totalPixels = dimensions.width * dimensions.height;
-    const diffRatio = diffPixelCount / totalPixels;
-    const ratioOk = diffRatio <= defaultScreenshotOptions.maxDiffPixelRatio;
-    if (!ratioOk) {
+    if (!result.passed) {
         if (process.env.CI) {
             await writeNewScreenshot();
         }
         else {
-            await writeExpectationScreenshot(PNG.sync.write(baseScreenshotPng), 'expected');
-            await writeExpectationScreenshot(PNG.sync.write(currentScreenshotPng), 'actual');
-            await writeExpectationScreenshot(PNG.sync.write(diffPng), 'diff');
-            throw new Error(`Screenshot mismatch: ${screenshotFilePath}\n diff=${diffPixelCount}px (${(diffRatio * 100).toFixed(3)}%) (limit: ${(defaultScreenshotOptions.maxDiffPixelRatio * 100).toFixed(3)}%). Run with --update-snapshots to update screenshot.`);
+            await writeExpectationScreenshot(encodePng(result.basePng), 'expected');
+            await writeExpectationScreenshot(encodePng(result.currentPng), 'actual');
+            await writeExpectationScreenshot(encodePng(result.diffPng), 'diff');
+            throw new Error(`Screenshot mismatch: ${screenshotFilePath}\n diff=${result.diffPixelCount}px (${(result.diffRatio * 100).toFixed(3)}%) (limit: ${(defaultImageComparisonOptions.maxDiffPixelRatio * 100).toFixed(3)}%). Run with --update-snapshots to update screenshot.`);
         }
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@augment-vir/test",
-    "version": "31.61.0",
+    "version": "31.63.0",
     "description": "A universal testing suite that works with Mocha style test runners _and_ Node.js's built-in test runner.",
     "keywords": [
         "test",
@@ -44,8 +44,8 @@
         "test:web": "virmator test --no-deps web 'src/test-web/**/*.test.ts' 'src/augments/universal-testing-suite/**/*.test.ts'"
     },
     "dependencies": {
-        "@augment-vir/assert": "^31.61.0",
-        "@augment-vir/common": "^31.61.0",
+        "@augment-vir/assert": "^31.63.0",
+        "@augment-vir/common": "^31.63.0",
         "@date-vir/duration": "^8.1.0",
         "@virmator/test": "^14.5.1",
         "type-fest": "^5.4.4"