@augment-vir/test 31.49.0 → 31.50.0

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

@@ -0,0 +1,42 @@
+import { RuntimeEnvError } from '@augment-vir/core';
+export { type MenuOptionOptions } from '../test-playwright/get-option.js';
+export { playwrightTeatNameUrlParam, type NavPath } from '../test-playwright/nav.js';
+export { type LocatorScreenshotOptions } from '../test-playwright/screenshot.js';
+declare function importPlaywrightTestApi(this: void): Promise<RuntimeEnvError | {
+    /** Navigate to a URL in Playwright via given paths. */
+    nav: typeof import("../test-playwright/nav.js").nav;
+    /**
+     * Expects that all matches for the given locator are either visible or hidden (controlled
+     * by `isVisible`).
+     */
+    expectAllVisible: typeof import("../test-playwright/all-visible.js").expectAllVisible;
+    /**
+     * 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).
+     */
+    expectScreenshot: typeof import("../test-playwright/screenshot.js").expectScreenshot;
+    /** Clicks a label to select its input and then types the given text. */
+    enterTextByLabel: typeof import("../test-playwright/enter-text").enterTextByLabel;
+    /** Find the matching (or first) element with the "option" role. */
+    getMenuOption: typeof import("../test-playwright/get-option.js").getMenuOption;
+    /** Checks if a locator contains the given class. */
+    checkHasClass: typeof import("../test-playwright/has-class").checkHasClass;
+    /**
+     * Run the trigger and catch a new page _or_ a new download (sometimes Playwright
+     * inconsistently chooses on or the other).
+     */
+    handleNewPageOrDownload: typeof import("../test-playwright/new-page-or-download").handleNewPageOrDownload;
+    /** Read from a page's local storage (using `page.evaluate`). */
+    readLocalStorage: typeof import("../test-playwright/local-storage.js").readLocalStorage;
+}>;
+/**
+ * A suite of Playwright test helpers. This is only accessible within a Playwright test runtime. If
+ * accessed outside of a Playwright runtime, it'll be an Error instead of a collection of test
+ * helpers.
+ *
+ * @category Test
+ * @category Package : @augment-vir/test
+ * @package [`@augment-vir/test`](https://www.npmjs.com/package/@augment-vir/test)
+ */
+export declare const testPlaywright: Exclude<Awaited<ReturnType<typeof importPlaywrightTestApi>>, Error>;

package/dist/augments/test-playwright.js

@@ -0,0 +1,53 @@
+import { isInsidePlaywrightTest, RuntimeEnvError } from '@augment-vir/core';
+export { playwrightTeatNameUrlParam } from '../test-playwright/nav.js';
+async function importPlaywrightTestApi() {
+    if (!isInsidePlaywrightTest()) {
+        return new RuntimeEnvError("The 'testPlaywright' api cannot be used outside of a Playwright test context.");
+    }
+    const { checkHasClass } = await import('../test-playwright/has-class');
+    const { enterTextByLabel } = await import('../test-playwright/enter-text');
+    const { expectAllVisible } = await import('../test-playwright/all-visible.js');
+    const { expectScreenshot } = await import('../test-playwright/screenshot.js');
+    const { getMenuOption } = await import('../test-playwright/get-option');
+    const { handleNewPageOrDownload } = await import('../test-playwright/new-page-or-download');
+    const { nav } = await import('../test-playwright/nav.js');
+    const { readLocalStorage } = await import('../test-playwright/local-storage.js');
+    return {
+        /** Navigate to a URL in Playwright via given paths. */
+        nav,
+        /**
+         * Expects that all matches for the given locator are either visible or hidden (controlled
+         * by `isVisible`).
+         */
+        expectAllVisible,
+        /**
+         * 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).
+         */
+        expectScreenshot,
+        /** Clicks a label to select its input and then types the given text. */
+        enterTextByLabel,
+        /** Find the matching (or first) element with the "option" role. */
+        getMenuOption,
+        /** Checks if a locator contains the given class. */
+        checkHasClass,
+        /**
+         * Run the trigger and catch a new page _or_ a new download (sometimes Playwright
+         * inconsistently chooses on or the other).
+         */
+        handleNewPageOrDownload,
+        /** Read from a page's local storage (using `page.evaluate`). */
+        readLocalStorage,
+    };
+}
+/**
+ * A suite of Playwright test helpers. This is only accessible within a Playwright test runtime. If
+ * accessed outside of a Playwright runtime, it'll be an Error instead of a collection of test
+ * helpers.
+ *
+ * @category Test
+ * @category Package : @augment-vir/test
+ * @package [`@augment-vir/test`](https://www.npmjs.com/package/@augment-vir/test)
+ */
+export const testPlaywright = (await importPlaywrightTestApi());

package/dist/augments/universal-testing-suite/universal-describe.js

@@ -1,8 +1,22 @@
-import { isRuntimeEnv, RuntimeEnv } from '@augment-vir/core';
+import { isInsidePlaywrightTest, isRuntimeEnv, RuntimeEnv } from '@augment-vir/core';
 const describes = isRuntimeEnv(RuntimeEnv.Node)
-    ? {
-        node: (await import('node:test')).describe,
-    }
+    ? isInsidePlaywrightTest()
+        ? {
+            playwright: await (async () => {
+                const playwrightImport = await import('@playwright/test');
+                /** `as any` cast to prevent type guarding {@link playwrightImport}. */
+                if ('default' in playwrightImport) {
+                    return playwrightImport.default.describe;
+                }
+                else {
+                    return playwrightImport
+                        .describe;
+                }
+            })(),
+        }
+        : {
+            node: (await import('node:test')).describe,
+        }
     : {
         mocha: globalThis.describe,
     };
@@ -33,4 +47,4 @@ const describes = isRuntimeEnv(RuntimeEnv.Node)
  *
  * @package [`@augment-vir/test`](https://www.npmjs.com/package/@augment-vir/test)
  */
-export const describe = describes.mocha || describes.node;
+export const describe = describes.mocha || describes.playwright || describes.node;

package/dist/augments/universal-testing-suite/universal-it.js

@@ -1,4 +1,5 @@
-import { isRuntimeEnv, RuntimeEnv } from '@augment-vir/core';
+import { randomString } from '@augment-vir/common';
+import { isInsidePlaywrightTest, isRuntimeEnv, RuntimeEnv } from '@augment-vir/core';
 function createWebIt() {
     const webIt = Object.assign((doesThis, callback) => {
         return globalThis.it(doesThis, async function () {
@@ -21,6 +22,101 @@ function createWebIt() {
     });
     return webIt;
 }
+async function createPlaywrightIt() {
+    const rawPlaywrightImport = await import('@playwright/test');
+    const originalPlaywrightIt = 'default' in rawPlaywrightImport
+        ? rawPlaywrightImport.default
+        : rawPlaywrightImport;
+    const playwrightIt = Object.assign((doesThis, callback) => {
+        return originalPlaywrightIt(doesThis, async ({ page, baseURL, browser, context, extraHTTPHeaders, viewport, video, userAgent, timezoneId, serviceWorkers, screenshot, isMobile, headless, hasTouch, }, testInfo) => {
+            const playwrightTestContext = {
+                page,
+                baseURL,
+                browser,
+                context,
+                extraHTTPHeaders,
+                viewport,
+                video,
+                userAgent,
+                timezoneId,
+                serviceWorkers,
+                screenshot,
+                isMobile,
+                headless,
+                hasTouch,
+                testInfo,
+                testName: {
+                    clean: testInfo.titlePath.join(' > '),
+                    unique: [
+                        ...testInfo.titlePath,
+                        randomString(),
+                    ].join(' > '),
+                },
+            };
+            await callback(playwrightTestContext);
+        });
+    }, {
+        skip: (doesThis, callback) => {
+            return originalPlaywrightIt.skip(doesThis, async ({ page, baseURL, browser, context, extraHTTPHeaders, viewport, video, userAgent, timezoneId, serviceWorkers, screenshot, isMobile, headless, hasTouch, }, testInfo) => {
+                const playwrightTestContext = {
+                    page,
+                    baseURL,
+                    browser,
+                    context,
+                    extraHTTPHeaders,
+                    viewport,
+                    video,
+                    userAgent,
+                    timezoneId,
+                    serviceWorkers,
+                    screenshot,
+                    isMobile,
+                    headless,
+                    hasTouch,
+                    testInfo,
+                    testName: {
+                        clean: testInfo.titlePath.join(' > '),
+                        unique: [
+                            ...testInfo.titlePath,
+                            randomString(),
+                        ].join(' > '),
+                    },
+                };
+                await callback(playwrightTestContext);
+            });
+        },
+        only: (doesThis, callback) => {
+            return originalPlaywrightIt.only(doesThis, async ({ page, baseURL, browser, context, extraHTTPHeaders, viewport, video, userAgent, timezoneId, serviceWorkers, screenshot, isMobile, headless, hasTouch, }, testInfo) => {
+                const playwrightTestContext = {
+                    page,
+                    baseURL,
+                    browser,
+                    context,
+                    extraHTTPHeaders,
+                    viewport,
+                    video,
+                    userAgent,
+                    timezoneId,
+                    serviceWorkers,
+                    screenshot,
+                    isMobile,
+                    headless,
+                    hasTouch,
+                    testInfo,
+                    testName: {
+                        clean: testInfo.titlePath.join(' > '),
+                        unique: [
+                            ...testInfo.titlePath,
+                            randomString(),
+                        ].join(' > '),
+                    },
+                };
+                await callback(playwrightTestContext);
+            });
+        },
+    });
+    return playwrightIt;
+}
 /**
  * A single test declaration. This can be used in both web tests _and_ node tests, so you only have
  * import from a single place and learn a single interface.
@@ -50,5 +146,7 @@ function createWebIt() {
  * @package [`@augment-vir/test`](https://www.npmjs.com/package/@augment-vir/test)
  */
 export const it = isRuntimeEnv(RuntimeEnv.Node)
-    ? (await import('node:test')).it
+    ? isInsidePlaywrightTest()
+        ? await createPlaywrightIt()
+        : (await import('node:test')).it
     : createWebIt();

package/dist/augments/universal-testing-suite/universal-snapshot.js

@@ -1,6 +1,6 @@
 import { check } from '@augment-vir/assert';
-import { extractErrorMessage, getOrSet, RuntimeEnv } from '@augment-vir/common';
-import { extractTestName, isTestContext, } from './universal-test-context.js';
+import { extractErrorMessage, getOrSet } from '@augment-vir/common';
+import { determineTestContextEnv, extractTestName, isTestContext, TestEnv, } from './universal-test-context.js';
 /**
  * An error that is thrown from {@link assertSnapshot} when the snapshot comparison fails due to the
  * snapshot expectation file simply not existing.
@@ -27,9 +27,9 @@ export class SnapshotFileMissingError extends Error {
  * @package [`@augment-vir/test`](https://www.npmjs.com/package/@augment-vir/test)
  */
 export async function assertSnapshot(testContext, data) {
-    const { snapshotName, testName } = getTestName(testContext);
     const serializedData = check.isString(data) ? data : JSON.stringify(data);
-    if (isTestContext(testContext, RuntimeEnv.Node)) {
+    if (isTestContext(testContext, TestEnv.Node)) {
+        const { testName } = getTestName(testContext);
         try {
             testContext.assert.snapshot(serializedData);
         }
@@ -42,7 +42,8 @@ export async function assertSnapshot(testContext, data) {
             }
         }
     }
-    else {
+    else if (isTestContext(testContext, TestEnv.Web)) {
+        const { snapshotName, testName } = getTestName(testContext);
         const { SnapshotCommand } = await import('@virmator/test/dist/web-snapshot-plugin/snapshot-payload.js');
         const { executeServerCommand } = await import('@web/test-runner-commands');
         const result = await executeServerCommand(SnapshotCommand.CompareSnapshot, {
@@ -58,6 +59,10 @@ export async function assertSnapshot(testContext, data) {
             }
         }
     }
+    else {
+        const testEnv = determineTestContextEnv(testContext);
+        throw new Error(`assertSnapshot not supported for test env '${testEnv}'.`);
+    }
 }
 function getTestName(testContext) {
     const testName = extractTestName(testContext);

package/dist/augments/universal-testing-suite/universal-test-context.d.ts

@@ -1,7 +1,7 @@
-import { RuntimeEnv } from '@augment-vir/core';
+import { type SelectFrom } from '@augment-vir/common';
+import { type PlaywrightTestArgs, type PlaywrightTestOptions, type PlaywrightWorkerArgs, type PlaywrightWorkerOptions, type TestInfo } from '@playwright/test';
 import { type TestContext as NodeTestContextImport } from 'node:test';
 import { type MochaTestContext } from './mocha-types.js';
-export { RuntimeEnv } from '@augment-vir/core';
 /**
  * The test context for [Node.js's test runner](https://nodejs.org/api/test.html).
  *
@@ -15,30 +15,65 @@ export type NodeTestContext = Readonly<NodeTestContextImport> & {
         [TestName in string]: number;
     };
 };
+/**
+ * The test context for Playwright tests.
+ *
+ * @category Test : Util
+ * @category Package : @augment-vir/test
+ * @package [`@augment-vir/test`](https://www.npmjs.com/package/@augment-vir/test)
+ */
+export type PlaywrightTestContext = SelectFrom<PlaywrightTestArgs & PlaywrightTestOptions & PlaywrightWorkerArgs & PlaywrightWorkerOptions, {
+    page: true;
+    baseURL: true;
+    browser: true;
+    context: true;
+    extraHTTPHeaders: true;
+    viewport: true;
+    video: true;
+    userAgent: true;
+    timezoneId: true;
+    serviceWorkers: true;
+    screenshot: true;
+    isMobile: true;
+    headless: true;
+    hasTouch: true;
+}> & {
+    testInfo: TestInfo;
+    testName: {
+        /** Clean, easily readable for humans. */
+        clean: string;
+        /** Unique with a random slug appended. */
+        unique: string;
+    };
+};
 /**
  * Test context provided by `it`'s callback.
  *
- * Compatible with both [Node.js's test runner](https://nodejs.org/api/test.html) and
+ * Compatible with both [Node.js's test runner](https://nodejs.org/api/test.html),
  * [web-test-runner](https://modern-web.dev/docs/test-runner/overview/) or other Mocha-style test
- * runners.
+ * runners, and Playwright's test runner.
  *
  * @category Test : Util
  * @category Package : @augment-vir/test
  * @package [`@augment-vir/test`](https://www.npmjs.com/package/@augment-vir/test)
  */
-export type UniversalTestContext = NodeTestContext | MochaTestContext;
+export type UniversalTestContext = NodeTestContext | MochaTestContext | PlaywrightTestContext;
+export declare enum TestEnv {
+    Node = "node",
+    Web = "web",
+    Playwright = "playwright"
+}
 /**
- * Test context by runtime env when [Node.js's test runner](https://nodejs.org/api/test.html) is
- * used for Node tests and [web-test-runner](https://modern-web.dev/docs/test-runner/overview/) is
- * used for web tests.
+ * Test context by the env they run in.
  *
  * @category Test : Util
  * @category Package : @augment-vir/test
  * @package [`@augment-vir/test`](https://www.npmjs.com/package/@augment-vir/test)
  */
-export type ContextByEnv = {
-    [RuntimeEnv.Node]: NodeTestContext;
-    [RuntimeEnv.Web]: MochaTestContext;
+export type TestContextByEnv = {
+    [TestEnv.Node]: NodeTestContext;
+    [TestEnv.Web]: MochaTestContext;
+    [TestEnv.Playwright]: PlaywrightTestContext;
 };
 /**
  * Extracts the full test name (including parent describes) of a given test context. Whether the
@@ -58,6 +93,14 @@ export declare function extractTestName(testContext: UniversalTestContext): stri
  * @package [`@augment-vir/test`](https://www.npmjs.com/package/@augment-vir/test)
  */
 export declare function extractTestNameAsDir(testContext: UniversalTestContext): string;
+/**
+ * Same as {@link extractTestNameAsDir} but sanitizes any input in the same way.
+ *
+ * @category Test : Util
+ * @category Package : @augment-vir/test
+ * @package [`@augment-vir/test`](https://www.npmjs.com/package/@augment-vir/test)
+ */
+export declare function cleanTestNameAsDir(testName: string): string;
 /**
  * Asserts that the given context is for the given env and returns that context.
  *
@@ -66,7 +109,7 @@ export declare function extractTestNameAsDir(testContext: UniversalTestContext):
  * @throws `TypeError` if the context does not match the env.
  * @package [`@augment-vir/test`](https://www.npmjs.com/package/@augment-vir/test)
  */
-export declare function assertWrapTestContext<const SpecificEnv extends RuntimeEnv>(this: void, context: UniversalTestContext, env: SpecificEnv): ContextByEnv[SpecificEnv];
+export declare function assertWrapTestContext<const SpecificEnv extends TestEnv>(this: void, context: UniversalTestContext, env: SpecificEnv): TestContextByEnv[SpecificEnv];
 /**
  * Asserts that the given context is for the given env, otherwise throws an Error.
  *
@@ -74,7 +117,7 @@ export declare function assertWrapTestContext<const SpecificEnv extends RuntimeE
  * @category Package : @augment-vir/test
  * @package [`@augment-vir/test`](https://www.npmjs.com/package/@augment-vir/test)
  */
-export declare function assertTestContext<const SpecificEnv extends RuntimeEnv>(this: void, context: UniversalTestContext, env: SpecificEnv): asserts context is ContextByEnv[SpecificEnv];
+export declare function assertTestContext<const SpecificEnv extends TestEnv>(this: void, context: UniversalTestContext, env: SpecificEnv): asserts context is TestContextByEnv[SpecificEnv];
 /**
  * Checks that the given context is for the given env.
  *
@@ -82,7 +125,7 @@ export declare function assertTestContext<const SpecificEnv extends RuntimeEnv>(
  * @category Package : @augment-vir/test
  * @package [`@augment-vir/test`](https://www.npmjs.com/package/@augment-vir/test)
  */
-export declare function isTestContext<const SpecificEnv extends RuntimeEnv>(this: void, context: UniversalTestContext, env: SpecificEnv): context is ContextByEnv[SpecificEnv];
+export declare function isTestContext<const SpecificEnv extends TestEnv>(this: void, context: UniversalTestContext, env: SpecificEnv): context is TestContextByEnv[SpecificEnv];
 /**
  * Determine the env for the given test context.
  *
@@ -90,4 +133,4 @@ export declare function isTestContext<const SpecificEnv extends RuntimeEnv>(this
  * @category Package : @augment-vir/test
  * @package [`@augment-vir/test`](https://www.npmjs.com/package/@augment-vir/test)
  */
-export declare function determineTestContextEnv(this: void, context: UniversalTestContext): RuntimeEnv;
+export declare function determineTestContextEnv(this: void, context: UniversalTestContext): TestEnv;

package/dist/augments/universal-testing-suite/universal-test-context.js

@@ -1,6 +1,11 @@
-import { camelCaseToKebabCase } from '@augment-vir/common';
-import { RuntimeEnv } from '@augment-vir/core';
-export { RuntimeEnv } from '@augment-vir/core';
+import { assertWrap } from '@augment-vir/assert';
+import { camelCaseToKebabCase, sanitizeFilePath } from '@augment-vir/common';
+export var TestEnv;
+(function (TestEnv) {
+    TestEnv["Node"] = "node";
+    TestEnv["Web"] = "web";
+    TestEnv["Playwright"] = "playwright";
+})(TestEnv || (TestEnv = {}));
 /**
  * Extracts the full test name (including parent describes) of a given test context. Whether the
  * test be run in web or node tests, the name will be the same.
@@ -10,9 +15,12 @@ export { RuntimeEnv } from '@augment-vir/core';
  * @package [`@augment-vir/test`](https://www.npmjs.com/package/@augment-vir/test)
  */
 export function extractTestName(testContext) {
-    if (isTestContext(testContext, RuntimeEnv.Node)) {
+    if (isTestContext(testContext, TestEnv.Node)) {
         return testContext.fullName;
     }
+    else if (isTestContext(testContext, TestEnv.Playwright)) {
+        return testContext.testName.clean;
+    }
     else {
         return flattenMochaParentTitles(testContext.test).join(' > ');
     }
@@ -26,7 +34,17 @@ export function extractTestName(testContext) {
  * @package [`@augment-vir/test`](https://www.npmjs.com/package/@augment-vir/test)
  */
 export function extractTestNameAsDir(testContext) {
-    return camelCaseToKebabCase(extractTestName(testContext)).replaceAll(/[<>:"/\-\\|?*_\s]+/g, '_');
+    return assertWrap.isTruthy(cleanTestNameAsDir(extractTestName(testContext)));
+}
+/**
+ * Same as {@link extractTestNameAsDir} but sanitizes any input in the same way.
+ *
+ * @category Test : Util
+ * @category Package : @augment-vir/test
+ * @package [`@augment-vir/test`](https://www.npmjs.com/package/@augment-vir/test)
+ */
+export function cleanTestNameAsDir(testName) {
+    return assertWrap.isTruthy(sanitizeFilePath(camelCaseToKebabCase(testName).replaceAll(/[<>:"/\-\\|?*_\s]+/g, '_')));
 }
 function flattenMochaParentTitles(node) {
     if (node.root) {
@@ -81,6 +99,7 @@ export function isTestContext(context, env) {
     }
 }
 const nodeOnlyCheckKey = 'diagnostic';
+const playwrightOnlyCheckKey = 'browser';
 /**
  * Determine the env for the given test context.
  *
@@ -89,5 +108,13 @@ const nodeOnlyCheckKey = 'diagnostic';
  * @package [`@augment-vir/test`](https://www.npmjs.com/package/@augment-vir/test)
  */
 export function determineTestContextEnv(context) {
-    return nodeOnlyCheckKey in context ? RuntimeEnv.Node : RuntimeEnv.Web;
+    if (playwrightOnlyCheckKey in context) {
+        return TestEnv.Playwright;
+    }
+    else if (nodeOnlyCheckKey in context) {
+        return TestEnv.Node;
+    }
+    else {
+        return TestEnv.Web;
+    }
 }

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+export * from './augments/test-playwright.js';
 export * from './augments/test-web.js';
 export * from './augments/universal-testing-suite/it-cases-with-context.js';
 export * from './augments/universal-testing-suite/it-cases.js';

package/dist/index.js

@@ -1,3 +1,4 @@
+export * from './augments/test-playwright.js';
 export * from './augments/test-web.js';
 export * from './augments/universal-testing-suite/it-cases-with-context.js';
 export * from './augments/universal-testing-suite/it-cases.js';

package/dist/test-playwright/all-visible.d.ts

@@ -0,0 +1,8 @@
+import { type Locator } from '@playwright/test';
+/**
+ * Expects that all matches for the given locator are either visible or hidden (controlled by
+ * `isVisible`).
+ *
+ * @category Internal
+ */
+export declare function expectAllVisible(locator: Readonly<Locator>, isVisible: boolean): Promise<void>;

package/dist/test-playwright/all-visible.js

@@ -0,0 +1,18 @@
+import { expect } from '@playwright/test';
+/**
+ * Expects that all matches for the given locator are either visible or hidden (controlled by
+ * `isVisible`).
+ *
+ * @category Internal
+ */
+export async function expectAllVisible(locator, isVisible) {
+    const count = await locator.count();
+    for (let i = 0; i < count; i++) {
+        if (isVisible) {
+            await expect(locator.nth(i)).toBeVisible();
+        }
+        else {
+            await expect(locator.nth(i)).toBeHidden();
+        }
+    }
+}

package/dist/test-playwright/enter-text.d.ts

@@ -0,0 +1,10 @@
+import { type Page } from '@playwright/test';
+/**
+ * Clicks a label to select its input and then types the given text.
+ *
+ * @category Internal
+ */
+export declare function enterTextByLabel(page: Readonly<Page>, { label, text }: {
+    label: string;
+    text: string;
+}): Promise<void>;

package/dist/test-playwright/enter-text.js

@@ -0,0 +1,9 @@
+/**
+ * Clicks a label to select its input and then types the given text.
+ *
+ * @category Internal
+ */
+export async function enterTextByLabel(page, { label, text }) {
+    await page.getByLabel(label).first().click();
+    await page.keyboard.type(text);
+}

package/dist/test-playwright/get-option.d.ts

@@ -0,0 +1,15 @@
+import { type Page } from '@playwright/test';
+/**
+ * Options for `testPlaywright.getMenuOption`.
+ *
+ * @category Internal
+ */
+export type MenuOptionOptions = Parameters<Page['getByRole']>[1] & Partial<{
+    nth: number;
+}>;
+/**
+ * Find the matching (or first) "option" element.
+ *
+ * @category Internal
+ */
+export declare function getMenuOption(page: Readonly<Page>, options?: MenuOptionOptions | undefined): import("playwright-core").Locator;

package/dist/test-playwright/get-option.js

@@ -0,0 +1,14 @@
+/**
+ * Find the matching (or first) "option" element.
+ *
+ * @category Internal
+ */
+export function getMenuOption(page, options) {
+    const baseLocator = page.getByRole('option', options);
+    if (options && 'nth' in options) {
+        return baseLocator.nth(options.nth);
+    }
+    else {
+        return baseLocator.first();
+    }
+}

package/dist/test-playwright/has-class.d.ts

@@ -0,0 +1,7 @@
+import { type Locator } from '@playwright/test';
+/**
+ * Checks if a locator contains the given class.
+ *
+ * @category Internal
+ */
+export declare function checkHasClass(locator: Readonly<Locator>, className: string): Promise<boolean>;

package/dist/test-playwright/has-class.js

@@ -0,0 +1,12 @@
+/**
+ * Checks if a locator contains the given class.
+ *
+ * @category Internal
+ */
+export async function checkHasClass(locator, className) {
+    if (!className) {
+        return false;
+    }
+    const currentClassValue = (await locator.getAttribute('class')) || '';
+    return currentClassValue.includes(className);
+}

package/dist/test-playwright/local-storage.d.ts

@@ -0,0 +1,7 @@
+import { type Page } from '@playwright/test';
+/**
+ * Read from a page's local storage.
+ *
+ * @category Internal
+ */
+export declare function readLocalStorage(page: Readonly<Page>, storageKey: string): Promise<string | undefined>;

package/dist/test-playwright/local-storage.js

@@ -0,0 +1,10 @@
+/**
+ * Read from a page's local storage.
+ *
+ * @category Internal
+ */
+export async function readLocalStorage(page, storageKey) {
+    return ((await page.evaluate((keyToRead) => {
+        return localStorage.getItem(keyToRead);
+    }, storageKey)) || undefined);
+}

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

@@ -0,0 +1,28 @@
+import { type GenericTreePaths } from 'spa-router-vir';
+import { type UniversalTestContext } from '../augments/universal-testing-suite/universal-test-context.js';
+/**
+ * Used for the `path` argument of `testPlaywright.nav`.
+ *
+ * @category Internal
+ */
+export type NavPath = /** A full URL to load, will not be appended to the auto detected frontend url. */ string
+/** Path array to append to the auto detected frontend url. */
+ | string[]
+/** Prefer using tree paths with `frontendPathTree` */
+ | GenericTreePaths;
+/**
+ * The test name appended to the frontend when `testPlaywright.nav` is used.
+ *
+ * @category Internal
+ */
+export declare const playwrightTeatNameUrlParam = "test-name";
+/**
+ * Navigate to a URL in Playwright via given paths.
+ *
+ * @category Internal
+ */
+export declare function nav(testContext: UniversalTestContext, { path, baseFrontendUrl, }: {
+    path: NavPath;
+    /** If not provided, the page's current URL will be used. */
+    baseFrontendUrl?: string | undefined;
+}): Promise<void>;

package/dist/test-playwright/nav.js

@@ -0,0 +1,43 @@
+import { check } from '@augment-vir/assert';
+import { buildUrl } from 'url-vir';
+import { assertTestContext, extractTestNameAsDir, TestEnv, } from '../augments/universal-testing-suite/universal-test-context.js';
+function extractNavUrl(frontendUrl, path) {
+    return check.isString(path)
+        ? path
+        : check.isArray(path)
+            ? buildUrl(frontendUrl, {
+                paths: path,
+            }).href
+            : buildUrl(frontendUrl, {
+                paths: path.fullPaths,
+            }).href;
+}
+/**
+ * The test name appended to the frontend when `testPlaywright.nav` is used.
+ *
+ * @category Internal
+ */
+export const playwrightTeatNameUrlParam = 'test-name';
+/**
+ * Navigate to a URL in Playwright via given paths.
+ *
+ * @category Internal
+ */
+export async function nav(testContext, { path, baseFrontendUrl, }) {
+    assertTestContext(testContext, TestEnv.Playwright);
+    const page = testContext.page;
+    const testName = extractTestNameAsDir(testContext);
+    const finalPath = buildUrl(extractNavUrl(baseFrontendUrl || page.url(), path), {
+        search: {
+            [playwrightTeatNameUrlParam]: [testName],
+        },
+    }).href;
+    if (page.url() === finalPath) {
+        return;
+    }
+    else {
+        await page.goto(finalPath, {
+            waitUntil: 'domcontentloaded',
+        });
+    }
+}

package/dist/test-playwright/new-page-or-download.d.ts

@@ -0,0 +1,13 @@
+import { type MaybePromise } from '@augment-vir/common';
+import { type Download, type Page } from '@playwright/test';
+import { type RequireExactlyOne } from 'type-fest';
+/**
+ * Run the trigger and catch a new page _or_ a new download (sometimes Playwright inconsistently
+ * chooses on or the other).
+ *
+ * @category Internal
+ */
+export declare function handleNewPageOrDownload(page: Readonly<Page>, trigger: () => MaybePromise<void>): Promise<RequireExactlyOne<{
+    newPage: Page;
+    download: Download;
+}>>;

package/dist/test-playwright/new-page-or-download.js

@@ -0,0 +1,23 @@
+/**
+ * Run the trigger and catch a new page _or_ a new download (sometimes Playwright inconsistently
+ * chooses on or the other).
+ *
+ * @category Internal
+ */
+export async function handleNewPageOrDownload(page, trigger) {
+    const openOrDownload = Promise.race([
+        page
+            .context()
+            .waitForEvent('page', async (newPage) => {
+            return (await newPage.opener()) === page;
+        })
+            .then((result) => {
+            return { page: result };
+        }),
+        page.waitForEvent('download').then((result) => {
+            return { download: result };
+        }),
+    ]);
+    await trigger();
+    return (await openOrDownload);
+}

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

@@ -0,0 +1,66 @@
+import { type Locator, type Page, type TestInfo } from '@playwright/test';
+/** This is used for type extraction because Playwright does not export the types we need. */
+declare function extractScreenshotMethod(): {
+    (name: string | ReadonlyArray<string>, options?: {
+        animations?: "disabled" | "allow";
+        caret?: "hide" | "initial";
+        mask?: Array<Locator>;
+        maskColor?: string;
+        maxDiffPixelRatio?: number;
+        maxDiffPixels?: number;
+        omitBackground?: boolean;
+        scale?: "css" | "device";
+        stylePath?: string | Array<string>;
+        threshold?: number;
+        timeout?: number;
+    }): Promise<void>;
+    (options?: {
+        animations?: "disabled" | "allow";
+        caret?: "hide" | "initial";
+        mask?: Array<Locator>;
+        maskColor?: string;
+        maxDiffPixelRatio?: number;
+        maxDiffPixels?: number;
+        omitBackground?: boolean;
+        scale?: "css" | "device";
+        stylePath?: string | Array<string>;
+        threshold?: number;
+        timeout?: number;
+    }): Promise<void>;
+};
+/**
+ * Correct options for `locator.screenshot`. (Playwright's `LocatorScreenshotOptions` export is
+ * wrong.)
+ *
+ * @category Internal
+ * @default defaultScreenshotOptions
+ */
+export type LocatorScreenshotOptions = NonNullable<Parameters<ReturnType<typeof extractScreenshotMethod>>[0]>;
+/**
+ * Default internal options for {@link LocatorScreenshotOptions}, used in {@link expectScreenshot}
+ *
+ * @category Internal
+ */
+export declare const defaultScreenshotOptions: {
+    animations: "disabled";
+    caret: "hide";
+    timeout: number;
+    scale: "css";
+    threshold: number;
+    maxDiffPixelRatio: number;
+};
+/**
+ * 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).
+ *
+ * @category Internal
+ */
+export declare function expectScreenshot(page: Readonly<Page>, { locator, screenshotName, testInfo, options, }: {
+    testInfo: Readonly<TestInfo>;
+    /** If no locator is provided, a screenshot of the whole page will be taken. */
+    locator: Readonly<Locator> | undefined;
+    screenshotName: string;
+    options?: Partial<LocatorScreenshotOptions> | undefined;
+}): Promise<void>;
+export {};

package/dist/test-playwright/screenshot.js

@@ -0,0 +1,128 @@
+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 { 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';
+/** 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() {
+    assert.never('this function should not be executed, it is only used for types');
+    // eslint-disable-next-line @typescript-eslint/unbound-method
+    return expect({}).toHaveScreenshot;
+}
+/**
+ * Default internal options for {@link LocatorScreenshotOptions}, used in {@link expectScreenshot}
+ *
+ * @category Internal
+ */
+export const defaultScreenshotOptions = {
+    animations: 'disabled',
+    caret: 'hide',
+    timeout: 10_000,
+    scale: 'css',
+    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 takeScreenshot({ locator, page, options, }) {
+    if (locator) {
+        /** The locator expectation has different options than the page expectation. */
+        return await locator.screenshot({ ...defaultScreenshotOptions, ...options });
+    }
+    else {
+        return await page.screenshot({
+            ...defaultScreenshotOptions,
+            ...options,
+        });
+    }
+}
+/**
+ * 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).
+ *
+ * @category Internal
+ */
+export async function expectScreenshot(page, { locator, screenshotName, testInfo, options = {}, }) {
+    const screenshotFileName = addSuffix({ value: screenshotName, suffix: '.png' });
+    const currentScreenshotBuffer = await takeScreenshot({ page, locator, options });
+    const screenshotFilePath = testInfo.snapshotPath(screenshotFileName);
+    async function writeNewScreenshot() {
+        log.mutate(`Updated screenshot: ${relative(process.cwd(), screenshotFilePath)}`);
+        await writeFileAndDir(screenshotFilePath, currentScreenshotBuffer);
+    }
+    async function writeExpectationScreenshot(contents, fileName) {
+        const filePath = testInfo.outputPath(addSuffix({ value: fileName, suffix: '.png' }));
+        await writeFileAndDir(filePath, contents);
+    }
+    if (existsSync(screenshotFilePath)) {
+        if (testInfo.config.updateSnapshots === 'changed') {
+            await writeNewScreenshot();
+        }
+    }
+    else {
+        if (testInfo.config.updateSnapshots !== 'none') {
+            await writeNewScreenshot();
+        }
+        await writeExpectationScreenshot(currentScreenshotBuffer, 'actual');
+        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, {
+        threshold: defaultScreenshotOptions.threshold,
+    });
+    const totalPixels = dimensions.width * dimensions.height;
+    const diffRatio = diffPixelCount / totalPixels;
+    const ratioOk = diffRatio <= defaultScreenshotOptions.maxDiffPixelRatio;
+    if (!ratioOk) {
+        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.`);
+        }
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@augment-vir/test",
-    "version": "31.49.0",
+    "version": "31.50.0",
     "description": "A universal testing suite that works with Mocha style test runners _and_ Node.js's built-in test runner.",
     "keywords": [
         "test",
@@ -36,20 +36,22 @@
     "scripts": {
         "compile": "virmator compile",
         "start": "tsx src/index.ts",
-        "test": "runstorm --names node,web \"npm run test:node\" \"npm run test:web\"",
+        "test": "runstorm --names node,web,playwright \"npm run test:node\" \"npm run test:web\" \"npm run test:playwright\"",
         "test:coverage": "npm run test",
         "test:node": "virmator test --no-deps node 'src/augments/universal-testing-suite/**/*.test.ts'",
+        "test:playwright": "playwright test --config configs/playwright.config.ts",
         "test:update": "npm test",
         "test:web": "virmator test --no-deps web 'src/test-web/**/*.test.ts' 'src/augments/universal-testing-suite/**/*.test.ts'"
     },
     "dependencies": {
-        "@augment-vir/assert": "^31.49.0",
-        "@augment-vir/common": "^31.49.0",
+        "@augment-vir/assert": "^31.50.0",
+        "@augment-vir/common": "^31.50.0",
         "@open-wc/testing-helpers": "^3.0.1",
-        "@virmator/test": "^14.2.1",
+        "@virmator/test": "^14.2.2",
         "type-fest": "^5.2.0"
     },
     "devDependencies": {
+        "@playwright/test": "^1.56.1",
         "@types/node": "^24.10.0",
         "@web/dev-server-esbuild": "^1.0.4",
         "@web/test-runner": "^0.20.2",
@@ -57,11 +59,22 @@
         "@web/test-runner-playwright": "^0.11.1",
         "element-vir": "^26.11.1",
         "istanbul-smart-text-reporter": "^1.1.5",
+        "pixelmatch": "^5.3.0",
+        "pngjs": "^7.0.0",
         "runstorm": "^0.6.2",
-        "typescript": "^5.9.3"
+        "sharp": "^0.34.5",
+        "spa-router-vir": "^6.3.1",
+        "typescript": "^5.9.3",
+        "url-vir": "^2.1.6"
     },
     "peerDependencies": {
-        "element-vir": "*"
+        "@playwright/test": "*",
+        "element-vir": "*",
+        "pixelmatch": ">=5",
+        "pngjs": ">=7",
+        "sharp": ">=0.34",
+        "spa-router-vir": ">=6",
+        "url-vir": ">=2"
     },
     "engines": {
         "node": ">=22"