@augment-vir/test 31.64.0 → 31.65.0

package/dist/augments/test-playwright.d.ts

@@ -1,7 +1,7 @@
 import { RuntimeEnvError } from '@augment-vir/core';
 export { type MenuOptionOptions } from '../test-playwright/get-option.js';
 export { type NavOptions } from '../test-playwright/nav.js';
-export { type LocatorScreenshotOptions, type SaveScreenshotOptions, type TakeScreenshotOptions, } from '../test-playwright/screenshot.js';
+export { type LocatorScreenshotOptions, type SaveScreenshotOptions, type TakeScreenshotOptions, } from '../test-playwright/playwright-screenshot.js';
 declare function importPlaywrightTestApi(this: void): Promise<RuntimeEnvError | {
     navigation: {
         /** Navigate to a URL in Playwright via given paths. */
@@ -31,17 +31,19 @@ declare function importPlaywrightTestApi(this: void): Promise<RuntimeEnvError |
         /**
          * Similar to Playwright's `expect().toHaveScreenshot` but allows images to have
          * different sizes and has default comparison threshold options that are wide enough to
-         * allow testing between different operating systems without failure (usually).
+         * allow testing between different operating systems without failure.
+         *
+         * Update screenshots with `--update`.
          */
-        expectScreenshot: typeof import("../test-playwright/screenshot.js").expectScreenshot;
+        expectScreenshot: typeof import("../test-playwright/playwright-screenshot.js").expectPlaywrightScreenshot;
         /** Get the path to save the given screenshot file name to. */
-        getScreenshotPath: typeof import("../test-playwright/screenshot.js").getScreenshotPath;
+        getScreenshotPath: typeof import("../test-playwright/playwright-screenshot.js").getScreenshotPath;
         /**
          * Take and immediately save a screenshot.
          *
          * @returns The path that the screenshot was saved to.
          */
-        takeScreenshot: typeof import("../test-playwright/screenshot.js").takeScreenshot;
+        takeScreenshot: typeof import("../test-playwright/playwright-screenshot.js").takeScreenshot;
     };
 }>;
 /**

package/dist/augments/test-playwright.js

@@ -7,7 +7,7 @@ async function importPlaywrightTestApi() {
     const { enterTextByLabel } = await import('../test-playwright/enter-text.js');
     const { expectAllVisible } = await import('../test-playwright/all-visible.js');
     const { getMenuOption } = await import('../test-playwright/get-option.js');
-    const { getScreenshotPath, takeScreenshot, expectScreenshot } = await import('../test-playwright/screenshot.js');
+    const { getScreenshotPath, takeScreenshot, expectPlaywrightScreenshot } = await import('../test-playwright/playwright-screenshot.js');
     const { handleNewPageOrDownload } = await import('../test-playwright/new-page-or-download.js');
     const { navigateTo, extractNavUrl } = await import('../test-playwright/nav.js');
     const { readLocalStorage } = await import('../test-playwright/local-storage.js');
@@ -40,9 +40,11 @@ async function importPlaywrightTestApi() {
             /**
              * Similar to Playwright's `expect().toHaveScreenshot` but allows images to have
              * different sizes and has default comparison threshold options that are wide enough to
-             * allow testing between different operating systems without failure (usually).
+             * allow testing between different operating systems without failure.
+             *
+             * Update screenshots with `--update`.
              */
-            expectScreenshot,
+            expectScreenshot: expectPlaywrightScreenshot,
             /** Get the path to save the given screenshot file name to. */
             getScreenshotPath,
             /**

package/dist/augments/test-web.d.ts

@@ -17,10 +17,9 @@ declare function importWebTestApi(this: void): Promise<RuntimeEnvError | {
     /**
      * Test a screenshot against an already established screenshot.
      *
-     * To update screenshots, run the test command with `--update` or
-     * `--update-visual-baseline`.
+     * To update screenshots, run the test command with `--update`.
      */
-    testScreenshot: typeof import("../test-web/test-screenshot.js").testScreenshot;
+    assertScreenshot: typeof import("../test-web/web-screenshot.js").assertWebScreenshot;
     /**
      * Renders a string or TemplateResult and puts it in the DOM via a fixtureWrapper.
      *

package/dist/augments/test-web.js

@@ -9,7 +9,7 @@ async function importWebTestApi() {
     const { fixtureCleanup, fixture } = await import('@open-wc/testing-helpers');
     const { renderElement } = await import('../test-web/render-element.js');
     const { elementCases } = await import('../test-web/element-cases.js');
-    const { testScreenshot } = await import('../test-web/test-screenshot.js');
+    const { assertWebScreenshot } = await import('../test-web/web-screenshot.js');
     return {
         /**
          * Cleans up all rendered test HTML by removing the actual wrapper nodes. Common use case is
@@ -27,10 +27,9 @@ async function importWebTestApi() {
         /**
          * Test a screenshot against an already established screenshot.
          *
-         * To update screenshots, run the test command with `--update` or
-         * `--update-visual-baseline`.
+         * To update screenshots, run the test command with `--update`.
          */
-        testScreenshot,
+        assertScreenshot: assertWebScreenshot,
         /**
          * Renders a string or TemplateResult and puts it in the DOM via a fixtureWrapper.
          *

package/dist/test-playwright/{screenshot.d.ts → playwright-screenshot.d.ts}

@@ -83,5 +83,5 @@ export declare function takeScreenshot(testContext: Readonly<UniversalTestContex
  *
  * @category Internal
  */
-export declare function expectScreenshot(testContext: Readonly<UniversalTestContext>, options: Readonly<SaveScreenshotOptions>): Promise<void>;
+export declare function expectPlaywrightScreenshot(testContext: Readonly<UniversalTestContext>, options: Readonly<SaveScreenshotOptions>): Promise<void>;
 export {};

package/dist/test-playwright/{screenshot.js → playwright-screenshot.js}

@@ -2,11 +2,11 @@ import { assert } from '@augment-vir/assert';
 import { addSuffix, log } from '@augment-vir/common';
 import { writeFileAndDir } from '@augment-vir/node';
 import { expect } from '@playwright/test';
+import { compareImages, defaultImageComparisonOptions, encodePng, } from '@virmator/test/dist/web-screenshot-plugin/compare-images.js';
 import { existsSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
 import { relative } from 'node:path';
 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() {
@@ -76,7 +76,7 @@ export async function takeScreenshot(testContext, options) {
  *
  * @category Internal
  */
-export async function expectScreenshot(testContext, options) {
+export async function expectPlaywrightScreenshot(testContext, options) {
     assertTestContext(testContext, TestEnv.Playwright);
     const currentScreenshotBuffer = await takeScreenshotBuffer(testContext, options);
     const screenshotFilePath = getScreenshotPath(testContext, options.screenshotBaseName);

package/dist/test-web/web-screenshot.d.ts

@@ -0,0 +1,7 @@
+import { type PartialWithUndefined, type SelectFrom } from '@augment-vir/common';
+import { type CompareScreenshotCommandPayload } from '@virmator/test/dist/web-screenshot-plugin/screenshot-payload.js';
+import { type UniversalTestContext } from '../augments/universal-testing-suite/universal-test-context.js';
+export declare function assertWebScreenshot(element: Element, screenshotNameOrTestContext: string | UniversalTestContext, options?: Readonly<PartialWithUndefined<SelectFrom<CompareScreenshotCommandPayload, {
+    maxDiffPixelRatio: true;
+    threshold: true;
+}>>>): Promise<void>;

package/dist/test-web/web-screenshot.js

@@ -0,0 +1,34 @@
+import { getOrSet, randomString, } from '@augment-vir/common';
+import { globalElementStoreKey, ScreenshotCommand, } from '@virmator/test/dist/web-screenshot-plugin/screenshot-payload.js';
+import { executeServerCommand } from '@web/test-runner-commands';
+import { extractTestNameAsDir, } from '../augments/universal-testing-suite/universal-test-context.js';
+export async function assertWebScreenshot(element, screenshotNameOrTestContext, options) {
+    if (!element.isConnected) {
+        throw new Error('Element must be connected to the DOM.');
+    }
+    else if (element.ownerDocument !== document) {
+        throw new Error('Element must belong to the same document the tests are run in.');
+    }
+    const elementKey = randomString();
+    getOrSet(globalThis, globalElementStoreKey, () => {
+        return {};
+    })[elementKey] = element;
+    const screenshotName = typeof screenshotNameOrTestContext === 'string'
+        ? screenshotNameOrTestContext
+        : extractTestNameAsDir(screenshotNameOrTestContext);
+    const payload = {
+        ...options,
+        elementKey,
+        screenshotFileName: screenshotName,
+    };
+    const result = await executeServerCommand(ScreenshotCommand.CompareScreenshot, payload);
+    if (result.updated) {
+        /** Ignore updates. */
+        return;
+    }
+    else if (!result.passed) {
+        throw new Error(typeof screenshotNameOrTestContext === 'string'
+            ? `Screenshot comparison failed for '${screenshotNameOrTestContext}'`
+            : 'Screenshot comparison failed.');
+    }
+}

package/package.json

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

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

@@ -1,71 +0,0 @@
-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

@@ -1,87 +0,0 @@
-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-web/test-screenshot.d.ts

@@ -1 +0,0 @@
-export declare function testScreenshot(element: Node, screenshotName: string): Promise<void>;

package/dist/test-web/test-screenshot.js

@@ -1,5 +0,0 @@
-// @ts-expect-error: this package's export types are messed up
-import { visualDiff } from '@web/test-runner-visual-regression';
-export async function testScreenshot(element, screenshotName) {
-    return await visualDiff(element, screenshotName);
-}