@lullabot/playwright-testing 0.1.0

package/lib/index.js

@@ -0,0 +1,29 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./focus.js"), exports);
+__exportStar(require("./accessibility-baseline.js"), exports);
+__exportStar(require("./accessibility-baseline-file.js"), exports);
+__exportStar(require("./accessible-screenshot.js"), exports);
+__exportStar(require("./fonts.js"), exports);
+__exportStar(require("./frames.js"), exports);
+__exportStar(require("./hover.js"), exports);
+__exportStar(require("./images.js"), exports);
+__exportStar(require("./interaction-states.js"), exports);
+__exportStar(require("./pseudo-state.js"), exports);
+__exportStar(require("./videos.js"), exports);
+__exportStar(require("./visualdiff.js"), exports);
+__exportStar(require("./mock/index.js"), exports);

package/lib/interaction-states.d.ts

@@ -0,0 +1,22 @@
+import type { Locator } from '@playwright/test';
+/** Real browser interaction states supported consistently by Playwright. */
+export type InteractionState = 'hover' | 'focus';
+/** A locator and the real browser interaction states to apply to it. */
+export interface ScreenshotInteractionState {
+    locator: Locator;
+    states: InteractionState[];
+}
+export interface InteractionStateCleanupOptions {
+    /** Move the pointer away from the hovered locator during cleanup. */
+    clearHover?: () => Promise<void>;
+}
+/** Validate that the requested states are possible with real browser input. */
+export declare function validateInteractionStates(interactionStates: ScreenshotInteractionState[]): void;
+/**
+ * Apply real hover and focus, returning an idempotent cleanup function.
+ *
+ * Hover is applied before focus so focusing cannot disturb the pointer. If an
+ * interaction fails, any state already applied is cleaned before the original
+ * error is rethrown.
+ */
+export declare function applyInteractionStates(interactionStates: ScreenshotInteractionState[], cleanupOptions?: InteractionStateCleanupOptions): Promise<() => Promise<void>>;

package/lib/interaction-states.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateInteractionStates = validateInteractionStates;
+exports.applyInteractionStates = applyInteractionStates;
+/** Validate that the requested states are possible with real browser input. */
+function validateInteractionStates(interactionStates) {
+    const hoverTargets = interactionStates.filter(({ states }) => states.includes('hover'));
+    const focusTargets = interactionStates.filter(({ states }) => states.includes('focus'));
+    if (hoverTargets.length > 1) {
+        throw new Error('interactionStates can hover at most one locator at a time.');
+    }
+    if (focusTargets.length > 1) {
+        throw new Error('interactionStates can focus at most one locator at a time.');
+    }
+    for (const { states } of interactionStates) {
+        if (new Set(states).size !== states.length) {
+            throw new Error('interactionStates cannot repeat a state for the same locator.');
+        }
+    }
+}
+/**
+ * Apply real hover and focus, returning an idempotent cleanup function.
+ *
+ * Hover is applied before focus so focusing cannot disturb the pointer. If an
+ * interaction fails, any state already applied is cleaned before the original
+ * error is rethrown.
+ */
+async function applyInteractionStates(interactionStates, cleanupOptions = {}) {
+    validateInteractionStates(interactionStates);
+    const hoverTarget = interactionStates.find(({ states }) => states.includes('hover'))?.locator;
+    const focusTarget = interactionStates.find(({ states }) => states.includes('focus'))?.locator;
+    let hoverApplied = false;
+    let focusApplied = false;
+    let cleaned = false;
+    const cleanup = async () => {
+        if (cleaned) {
+            return;
+        }
+        cleaned = true;
+        try {
+            if (focusApplied) {
+                await focusTarget?.blur();
+            }
+        }
+        finally {
+            if (hoverApplied) {
+                await cleanupOptions.clearHover?.();
+            }
+        }
+    };
+    try {
+        if (hoverTarget) {
+            // Mark the state first: Playwright can move the pointer and then fail
+            // while waiting for actionability, and that partial effect still needs
+            // cleanup.
+            hoverApplied = true;
+            await hoverTarget.hover();
+        }
+        if (focusTarget) {
+            focusApplied = true;
+            await focusTarget.focus();
+        }
+        return cleanup;
+    }
+    catch (error) {
+        try {
+            await cleanup();
+        }
+        catch {
+            // Preserve the interaction failure. Cleanup is best effort on this path;
+            // callers cannot act on a cleanup error if applying the state failed.
+        }
+        throw error;
+    }
+}

package/lib/mock/index.d.ts

@@ -0,0 +1 @@
+export { YoutubeMock } from './youtube.js';

package/lib/mock/index.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.YoutubeMock = void 0;
+var youtube_js_1 = require("./youtube.js");
+Object.defineProperty(exports, "YoutubeMock", { enumerable: true, get: function () { return youtube_js_1.YoutubeMock; } });

package/lib/mock/youtube.d.ts

@@ -0,0 +1,5 @@
+import type { Page } from '@playwright/test';
+import type { Mockable } from "../visualdiff.js";
+export declare class YoutubeMock implements Mockable {
+    mock(page: Page): Promise<void>;
+}

package/lib/mock/youtube.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.YoutubeMock = void 0;
+class YoutubeMock {
+    async mock(page) {
+        await page.route(/www\.youtube\.com/i, async (route) => {
+            await route.fulfill({
+                contentType: 'text/html',
+                body: `
+<html>
+<head>
+    <title>Youtube Video Mock</title>
+    <style>
+        body {
+          color: white;
+          background-color: darkred;
+        }
+        div {
+          position: absolute;
+          top: 50%;
+          left: 50%;
+          margin: 0;
+          transform: translate(-50%, -50%);
+          font-size: xxx-large;
+          text-align: center;
+        }
+    </style>
+</head>
+<body>
+    <div>Youtube Video Mock</div>
+</body>
+</html>
+`,
+            });
+        });
+    }
+}
+exports.YoutubeMock = YoutubeMock;

package/lib/pseudo-state.d.ts

@@ -0,0 +1,17 @@
+import { Page } from '@playwright/test';
+/** Pseudo-classes supported by Chromium's CSS.forcePseudoState command. */
+export type ForcedPseudoClass = 'active' | 'focus' | 'focus-visible' | 'focus-within' | 'hover' | 'target';
+/** A CSS selector and the pseudo-classes to force on its first match. */
+export interface ForcedPseudoState {
+    selector: string;
+    pseudoClasses: ForcedPseudoClass[];
+}
+/**
+ * Force CSS pseudo-classes on the first element matching a selector.
+ *
+ * This uses Chromium's DevTools Protocol and therefore only works in Chromium
+ * projects. The state is synthetic: moving the pointer or blurring the active
+ * element does not clear it. Call the returned idempotent cleanup function when
+ * the screenshot and accessibility scan are complete.
+ */
+export declare function forcePseudoState(page: Page, selector: string, pseudoClasses: ForcedPseudoClass[]): Promise<() => Promise<void>>;

package/lib/pseudo-state.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.forcePseudoState = forcePseudoState;
+/**
+ * Force CSS pseudo-classes on the first element matching a selector.
+ *
+ * This uses Chromium's DevTools Protocol and therefore only works in Chromium
+ * projects. The state is synthetic: moving the pointer or blurring the active
+ * element does not clear it. Call the returned idempotent cleanup function when
+ * the screenshot and accessibility scan are complete.
+ */
+async function forcePseudoState(page, selector, pseudoClasses) {
+    let session;
+    try {
+        session = await page.context().newCDPSession(page);
+    }
+    catch (error) {
+        throw new Error('forcePseudoState() requires a Chromium browser project.', { cause: error });
+    }
+    try {
+        await session.send('DOM.enable');
+        await session.send('CSS.enable');
+        const { root } = await session.send('DOM.getDocument');
+        const { nodeId } = await session.send('DOM.querySelector', {
+            nodeId: root.nodeId,
+            selector,
+        });
+        if (!nodeId) {
+            throw new Error(`forcePseudoState() could not find an element matching "${selector}".`);
+        }
+        await session.send('CSS.forcePseudoState', { nodeId, forcedPseudoClasses: pseudoClasses });
+        let cleared = false;
+        return async () => {
+            if (cleared) {
+                return;
+            }
+            cleared = true;
+            try {
+                await session.send('CSS.forcePseudoState', { nodeId, forcedPseudoClasses: [] });
+            }
+            finally {
+                await session.detach();
+            }
+        };
+    }
+    catch (error) {
+        await session.detach();
+        throw error;
+    }
+}

package/lib/videos.d.ts

@@ -0,0 +1,134 @@
+import { Page } from "@playwright/test";
+/**
+ * Settle every <video> on the page so a screenshot of it is reproducible.
+ *
+ * A `<video>` is the one replaced element nothing else in the screenshot path
+ * covers. waitForImages() only looks at `img`, and Playwright's
+ * `animations: 'disabled'` only fast-forwards CSS transitions and Web
+ * Animations -- it does not touch media playback. That leaves two separate ways
+ * for a video to break a visual comparison:
+ *
+ * 1. **The frame is captured before it exists.** A full-page screenshot rasters
+ *    the whole document, including regions that were never in the viewport, so
+ *    it will happily capture a video that is still loading. The region paints as
+ *    an empty box on one capture and as the video on the next, which Playwright
+ *    reports as "Failed to take two consecutive stable screenshots" -- the run
+ *    burns its whole stability window and fails even though the image it ended
+ *    up with was correct. When the video is slower still, the captures agree on
+ *    the empty box, which is worse: it passes stability and bakes a blank
+ *    rectangle into the baseline if snapshots are being regenerated.
+ * 2. **The frame is captured while the video is playing.** An `autoplay muted
+ *    loop` video renders whatever moment the shutter caught. Chromium only
+ *    autoplays a muted video while it is on screen, so whether such a baseline
+ *    is reproducible at all currently rests on nothing more principled than
+ *    whether an earlier scroll happened to bring the video into the viewport.
+ *
+ * Both are fixed together: pin playback first, bring the video on screen so it
+ * both loads and composites, wait for a decodable frame, and rewind.
+ *
+ * Note this is deliberately *not* built on `requestVideoFrameCallback()`, which
+ * looks like the right signal and is not: it only fires when a frame is
+ * presented, and a paused off-screen video never presents one. Measured against
+ * a real page it never fired at all -- every call sat there until its timeout,
+ * adding the full timeout to each capture and reporting nothing.
+ */
+/**
+ * Settle every visible video, in the browser.
+ *
+ * This runs in the browser via `page.evaluate()`, which serializes the function
+ * source, so it must stay self-contained and reference nothing else in this
+ * module. It is exported separately from waitForVideos() so it can be tested
+ * directly.
+ *
+ * The order of operations matters and is not the obvious one:
+ *
+ * - Playback is pinned -- `autoplay` cleared and the element paused -- *before*
+ *   the video is scrolled into view, because bringing a muted `autoplay` video
+ *   on screen is exactly what starts it: measured on a real page, scrolling to
+ *   it first and pausing after left `currentTime` at 0.6s and climbing, while
+ *   pinning first held it at 0 through the same scroll. Pinning first turns the
+ *   scroll into a pure repaint.
+ * - The video is scrolled into view *before* its readiness is polled, because
+ *   for a lazily loaded video the scroll is what starts the load. Polling first
+ *   would sit there watching a `preload="none"` element that has been told not
+ *   to fetch anything, burn the whole timeout, and only then scroll it on
+ *   screen -- leaving the capture racing a load that had just begun.
+ *
+ * Videos are handled in serial: each one is scrolled into view in turn, and
+ * doing that concurrently would just mean the last one wins. Every scroll is
+ * undone -- the window offset and any scrollable ancestor `scrollIntoView()`
+ * moved -- so this composes with callers that care where the page is left;
+ * waitForImages(), in particular, does its own careful scroll back to the top.
+ *
+ * Playback state is not restored here, because the whole point is to leave the
+ * videos pinned at their first frame for the capture. It is recorded on each
+ * element so restorePlayback() can put it back afterwards.
+ *
+ * A video that never produces a frame is not an error. A page that legitimately
+ * references a missing or undecodable video should still be screenshotted and
+ * still have its accessibility checked, and the comparison is what fails. The
+ * wait is not silent either: the sources that never became ready are returned
+ * so the caller can report them.
+ *
+ * @param options.timeoutMs How long to wait for each video to become ready.
+ * @param options.pollMs How long to sleep between readiness checks.
+ * @param options.paintTimeoutMs How long to wait on a frame or a seek that may
+ *   never arrive.
+ * @returns The sources of the videos that never became ready, and whether the
+ *   page was scrolled at all.
+ */
+export declare function settleVideos(options: {
+    timeoutMs: number;
+    pollMs?: number;
+    paintTimeoutMs?: number;
+}): Promise<{
+    notReady: string[];
+    scrolled: boolean;
+}>;
+/**
+ * Put back the playback state settleVideos() recorded, in the browser.
+ *
+ * Like settleVideos() this is serialized into the page by `page.evaluate()`, so
+ * it must stay self-contained, and it is exported separately from
+ * restoreVideoPlayback() so it can be tested directly.
+ *
+ * Videos that were not settled are left alone, and the recorded state is
+ * cleared as it is applied so a second call is a no-op rather than a rewind of
+ * whatever the test did in between.
+ */
+export declare function restorePlayback(): void;
+/**
+ * Wait for every visible video to be ready, composited, and paused at its
+ * first frame.
+ *
+ * See settleVideos() for what "ready" means, why playback is pinned before the
+ * video is scrolled into view, why the readiness poll comes after that scroll,
+ * and why this is not built on `requestVideoFrameCallback()`.
+ *
+ * This runs in every frame, not just the main one: media embeds commonly render
+ * inside iframes, and a
+ * `<video>` in one of those is no less able to break a comparison.
+ *
+ * @param page
+ * @param options A timeout or settling options.
+ * @returns The sources of the videos that never became ready. Empty when they
+ *   all did.
+ */
+export interface WaitForVideosOptions {
+    /** How long to wait for each video to produce a frame. */
+    timeoutMs?: number;
+    /** Optional adapter hook run after video scrolling has been restored. */
+    afterScroll?: (page: Page) => Promise<void>;
+}
+export declare function waitForVideos(page: Page, options?: number | WaitForVideosOptions): Promise<string[]>;
+/**
+ * Restore the playback state waitForVideos() pinned.
+ *
+ * Settling a video means pausing it, clearing `autoplay` and rewinding it, and
+ * a test that takes a screenshot has not asked for any of that to outlive the
+ * capture -- it may well go on to assert that the video is playing. Call this
+ * once the screenshot is taken to hand the page back as it was found.
+ *
+ * @param page
+ */
+export declare function restoreVideoPlayback(page: Page): Promise<void>;