@lullabot/playwright-testing 0.1.0 → 1.0.1

package/src/images.ts

@@ -1,4 +1,4 @@
-import {Page} from "@playwright/test";
+import { Page } from "@playwright/test";
 
 export interface WaitForImagesOptions {
   /** How long to wait for visible images to decode. */
@@ -36,13 +36,15 @@ export async function waitForImages(
     for (const l of await locators.all()) {
       // Ensure images are connected to the DOM before trying to scroll to them.
       // https://github.com/microsoft/playwright/issues/23758
-      if (await l.evaluate(image => image.isConnected)) {
+      if (await l.evaluate((image) => image.isConnected)) {
         await l.scrollIntoViewIfNeeded();
       }
     }
 
     // Make sure all images have loaded.
-    const promises = (await locators.all()).map(locator => locator.evaluate(settleImage));
+    const promises = (await locators.all()).map((locator) =>
+      locator.evaluate(settleImage),
+    );
     await Promise.all(promises);
 
     // The wait above treats an errored image as "loaded". Decode each visible
@@ -59,16 +61,16 @@ export async function waitForImages(
       window.scroll({
         top: 0,
         left: 0,
-        behavior: 'instant',
-      })
+        behavior: "instant",
+      }),
     );
 
     // window.scroll is async and doesn't return a promise, so wait until the
     // browser confirms we are at the top again.
-    const scrollState = {forced: false};
-    await page.waitForFunction(state => {
+    const scrollState = { forced: false };
+    await page.waitForFunction((state) => {
       if (window.scrollY !== 0 && !state.forced) {
-        window.scroll({top: 0, left: 0, behavior: 'instant'});
+        window.scroll({ top: 0, left: 0, behavior: "instant" });
         state.forced = true;
       }
       return window.scrollY === 0;
@@ -111,7 +113,7 @@ export function settleImage(image: HTMLImageElement): void | Promise<void> {
   if ((image.width <= 1 && image.height <= 1) || image.complete) {
     return;
   }
-  return new Promise<void>(resolve => {
+  return new Promise<void>((resolve) => {
     const settled = () => {
       image.removeEventListener("load", settled);
       image.removeEventListener("error", settled);
@@ -131,7 +133,7 @@ export async function waitForAllImages(
   page: Page,
   options: WaitForImagesOptions = {},
 ): Promise<void> {
-  await waitForImages(page, 'img:visible', options);
+  await waitForImages(page, "img:visible", options);
 }
 
 /**
@@ -167,14 +169,12 @@ export async function waitForAllImages(
  *   rewritten and re-requested. Defaults to false.
  * @returns The URLs of the images that never decoded. Empty when they all did.
  */
-export async function decodeVisibleImages(
-  options: {
-    timeoutMs: number,
-    pollMs?: number,
-    reloadIntervalMs?: number,
-    recoverErroredImages?: boolean,
-  }
-): Promise<string[]> {
+export async function decodeVisibleImages(options: {
+  timeoutMs: number;
+  pollMs?: number;
+  reloadIntervalMs?: number;
+  recoverErroredImages?: boolean;
+}): Promise<string[]> {
   const timeoutMs = options.timeoutMs;
   const pollMs = options.pollMs ?? 250;
   const reloadIntervalMs = options.reloadIntervalMs ?? 2000;
@@ -204,7 +204,7 @@ export async function decodeVisibleImages(
       // one fetched, instead of re-running srcset selection.
       const picture = img.closest("picture");
       if (picture) {
-        picture.querySelectorAll("source").forEach(source => source.remove());
+        picture.querySelectorAll("source").forEach((source) => source.remove());
       }
       img.removeAttribute("srcset");
       img.src = url.href;
@@ -220,31 +220,37 @@ export async function decodeVisibleImages(
     const candidates = Array.from(document.images).filter(isCandidate);
     // Collect the verdicts positionally rather than pushing as each check
     // settles, so anything reported below stays in document order.
-    const verdicts = await Promise.all(candidates.map(async img => {
-      if (img.complete && img.naturalWidth > 0) {
-        return "loaded"; // Loaded with intrinsic dimensions.
-      }
-      if (!img.complete) {
-        return "loading";
-      }
-      // Complete with a zero naturalWidth is ambiguous: a genuine load error
-      // (404/503) rejects decode(), while a valid but dimensionless image
-      // (such as an SVG with no intrinsic size) resolves it. Only the former
-      // should be re-requested; the latter is already settled.
-      try {
-        await img.decode();
-        return "loaded";
-      } catch {
-        return "errored";
-      }
-    }));
-    const pending = candidates.filter((img, index) => verdicts[index] !== "loaded");
-    const errored = candidates.filter((img, index) => verdicts[index] === "errored");
+    const verdicts = await Promise.all(
+      candidates.map(async (img) => {
+        if (img.complete && img.naturalWidth > 0) {
+          return "loaded"; // Loaded with intrinsic dimensions.
+        }
+        if (!img.complete) {
+          return "loading";
+        }
+        // Complete with a zero naturalWidth is ambiguous: a genuine load error
+        // (404/503) rejects decode(), while a valid but dimensionless image
+        // (such as an SVG with no intrinsic size) resolves it. Only the former
+        // should be re-requested; the latter is already settled.
+        try {
+          await img.decode();
+          return "loaded";
+        } catch {
+          return "errored";
+        }
+      }),
+    );
+    const pending = candidates.filter(
+      (img, index) => verdicts[index] !== "loaded",
+    );
+    const errored = candidates.filter(
+      (img, index) => verdicts[index] === "errored",
+    );
     if (pending.length === 0) {
       return [];
     }
     if (Date.now() >= deadline) {
-      return pending.map(img => {
+      return pending.map((img) => {
         const src = img.currentSrc || img.src;
         try {
           // Report the URL as the page authored it, without the cache-busting
@@ -262,7 +268,7 @@ export async function decodeVisibleImages(
       lastReload = Date.now();
       errored.forEach(reload);
     }
-    await new Promise(resolve => setTimeout(resolve, pollMs));
+    await new Promise((resolve) => setTimeout(resolve, pollMs));
   }
 }
 
@@ -289,10 +295,13 @@ export async function waitForImagesToDecode(
   timeoutMs = 15000,
   recoverErroredImages = false,
 ): Promise<string[]> {
-  const undecoded = await page.evaluate(decodeVisibleImages, {timeoutMs, recoverErroredImages});
+  const undecoded = await page.evaluate(decodeVisibleImages, {
+    timeoutMs,
+    recoverErroredImages,
+  });
   if (undecoded.length > 0) {
     console.warn(
-      `waitForImagesToDecode: ${undecoded.length} image(s) did not finish loading within ${timeoutMs}ms and may be captured as broken: ${undecoded.join(', ')}`
+      `waitForImagesToDecode: ${undecoded.length} image(s) did not finish loading within ${timeoutMs}ms and may be captured as broken: ${undecoded.join(", ")}`,
     );
   }
   return undecoded;

package/src/index.ts

@@ -1,13 +1,13 @@
-export * from './focus.js'
-export * from './accessibility-baseline.js'
-export * from './accessibility-baseline-file.js'
-export * from './accessible-screenshot.js'
-export * from './fonts.js'
-export * from './frames.js'
-export * from './hover.js'
-export * from './images.js'
-export * from './interaction-states.js'
-export * from './pseudo-state.js'
-export * from './videos.js'
-export * from './visualdiff.js'
-export * from './mock/index.js'
+export * from "./focus.js";
+export * from "./accessibility-baseline.js";
+export * from "./accessibility-baseline-file.js";
+export * from "./accessible-screenshot.js";
+export * from "./fonts.js";
+export * from "./frames.js";
+export * from "./hover.js";
+export * from "./images.js";
+export * from "./interaction-states.js";
+export * from "./pseudo-state.js";
+export * from "./videos.js";
+export * from "./visualdiff.js";
+export * from "./mock/index.js";

package/src/interaction-states.test.ts

@@ -1,48 +1,78 @@
-import {describe, expect, it, vi} from 'vitest'
-import {applyInteractionStates, validateInteractionStates} from './interaction-states'
+import { describe, expect, it, vi } from "vitest";
+import {
+  applyInteractionStates,
+  validateInteractionStates,
+} from "./interaction-states";
 
-describe('validateInteractionStates', () => {
-  it('rejects states that real input cannot hold simultaneously', () => {
-    const locator = {} as never
-    expect(() => validateInteractionStates([
-      {locator, states: ['hover']},
-      {locator, states: ['hover']},
-    ])).toThrow('at most one')
-    expect(() => validateInteractionStates([
-      {locator, states: ['focus', 'focus']},
-    ])).toThrow('cannot repeat')
-  })
-})
+describe("validateInteractionStates", () => {
+  it("rejects states that real input cannot hold simultaneously", () => {
+    const locator = {} as never;
+    expect(() =>
+      validateInteractionStates([
+        { locator, states: ["hover"] },
+        { locator, states: ["hover"] },
+      ]),
+    ).toThrow("at most one");
+    expect(() =>
+      validateInteractionStates([{ locator, states: ["focus", "focus"] }]),
+    ).toThrow("cannot repeat");
+  });
+});
 
-describe('applyInteractionStates', () => {
-  it('applies hover before focus and cleans both states up', async () => {
-    const hover = vi.fn().mockResolvedValue(undefined)
-    const focus = vi.fn().mockResolvedValue(undefined)
-    const blur = vi.fn().mockResolvedValue(undefined)
-    const clearHover = vi.fn().mockResolvedValue(undefined)
+describe("applyInteractionStates", () => {
+  it("applies hover before focus and cleans both states up", async () => {
+    const hover = vi.fn().mockResolvedValue(undefined);
+    const focus = vi.fn().mockResolvedValue(undefined);
+    const blur = vi.fn().mockResolvedValue(undefined);
+    const clearHover = vi.fn().mockResolvedValue(undefined);
 
-    const cleanup = await applyInteractionStates([
-      {locator: {hover, focus: vi.fn(), blur: vi.fn()} as never, states: ['hover']},
-      {locator: {hover: vi.fn(), focus, blur} as never, states: ['focus']},
-    ], {clearHover})
+    const cleanup = await applyInteractionStates(
+      [
+        {
+          locator: { hover, focus: vi.fn(), blur: vi.fn() } as never,
+          states: ["hover"],
+        },
+        {
+          locator: { hover: vi.fn(), focus, blur } as never,
+          states: ["focus"],
+        },
+      ],
+      { clearHover },
+    );
 
-    expect(hover.mock.invocationCallOrder[0]).toBeLessThan(focus.mock.invocationCallOrder[0])
-    await cleanup()
-    await cleanup()
-    expect(blur).toHaveBeenCalledOnce()
-    expect(clearHover).toHaveBeenCalledOnce()
-  })
+    expect(hover.mock.invocationCallOrder[0]).toBeLessThan(
+      focus.mock.invocationCallOrder[0],
+    );
+    await cleanup();
+    await cleanup();
+    expect(blur).toHaveBeenCalledOnce();
+    expect(clearHover).toHaveBeenCalledOnce();
+  });
 
-  it('cleans already-applied state when a later interaction fails', async () => {
-    const clearHover = vi.fn().mockResolvedValue(undefined)
-    const blur = vi.fn().mockResolvedValue(undefined)
-    const failure = new Error('focus failed')
+  it("cleans already-applied state when a later interaction fails", async () => {
+    const clearHover = vi.fn().mockResolvedValue(undefined);
+    const blur = vi.fn().mockResolvedValue(undefined);
+    const failure = new Error("focus failed");
 
-    await expect(applyInteractionStates([
-      {locator: {hover: vi.fn().mockResolvedValue(undefined)} as never, states: ['hover']},
-      {locator: {focus: vi.fn().mockRejectedValue(failure), blur} as never, states: ['focus']},
-    ], {clearHover})).rejects.toBe(failure)
-    expect(blur).toHaveBeenCalledOnce()
-    expect(clearHover).toHaveBeenCalledOnce()
-  })
-})
+    await expect(
+      applyInteractionStates(
+        [
+          {
+            locator: { hover: vi.fn().mockResolvedValue(undefined) } as never,
+            states: ["hover"],
+          },
+          {
+            locator: {
+              focus: vi.fn().mockRejectedValue(failure),
+              blur,
+            } as never,
+            states: ["focus"],
+          },
+        ],
+        { clearHover },
+      ),
+    ).rejects.toBe(failure);
+    expect(blur).toHaveBeenCalledOnce();
+    expect(clearHover).toHaveBeenCalledOnce();
+  });
+});

package/src/interaction-states.ts

@@ -1,35 +1,45 @@
-import type {Locator} from '@playwright/test'
+import type { Locator } from "@playwright/test";
 
 /** Real browser interaction states supported consistently by Playwright. */
-export type InteractionState = 'hover' | 'focus'
+export type InteractionState = "hover" | "focus";
 
 /** A locator and the real browser interaction states to apply to it. */
 export interface ScreenshotInteractionState {
-  locator: Locator
-  states: InteractionState[]
+  locator: Locator;
+  states: InteractionState[];
 }
 
 export interface InteractionStateCleanupOptions {
   /** Move the pointer away from the hovered locator during cleanup. */
-  clearHover?: () => Promise<void>
+  clearHover?: () => Promise<void>;
 }
 
 /** Validate that the requested states are possible with real browser input. */
 export function validateInteractionStates(
   interactionStates: ScreenshotInteractionState[],
 ): void {
-  const hoverTargets = interactionStates.filter(({states}) => states.includes('hover'))
-  const focusTargets = interactionStates.filter(({states}) => states.includes('focus'))
+  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.')
+    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.')
+    throw new Error(
+      "interactionStates can focus at most one locator at a time.",
+    );
   }
-  for (const {states} of interactionStates) {
+  for (const { states } of interactionStates) {
     if (new Set(states).size !== states.length) {
-      throw new Error('interactionStates cannot repeat a state for the same locator.')
+      throw new Error(
+        "interactionStates cannot repeat a state for the same locator.",
+      );
     }
   }
 }
@@ -45,50 +55,54 @@ export async function applyInteractionStates(
   interactionStates: ScreenshotInteractionState[],
   cleanupOptions: InteractionStateCleanupOptions = {},
 ): Promise<() => Promise<void>> {
-  validateInteractionStates(interactionStates)
+  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 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
+      return;
     }
-    cleaned = true
+    cleaned = true;
     try {
       if (focusApplied) {
-        await focusTarget?.blur()
+        await focusTarget?.blur();
       }
     } finally {
       if (hoverApplied) {
-        await cleanupOptions.clearHover?.()
+        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()
+      hoverApplied = true;
+      await hoverTarget.hover();
     }
     if (focusTarget) {
-      focusApplied = true
-      await focusTarget.focus()
+      focusApplied = true;
+      await focusTarget.focus();
     }
-    return cleanup
+    return cleanup;
   } catch (error) {
     try {
-      await cleanup()
+      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
+    throw error;
   }
 }

package/src/mock/index.ts

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

package/src/mock/youtube.test.ts

@@ -1,38 +1,38 @@
-import { describe, it, expect, vi } from 'vitest'
-import { YoutubeMock } from './youtube'
+import { describe, it, expect, vi } from "vitest";
+import { YoutubeMock } from "./youtube";
 
-describe('YoutubeMock', () => {
-  it('registers a route handler for youtube.com', async () => {
+describe("YoutubeMock", () => {
+  it("registers a route handler for youtube.com", async () => {
     const mockPage = {
       route: vi.fn(),
-    }
+    };
 
-    const mock = new YoutubeMock()
-    await mock.mock(mockPage as any)
+    const mock = new YoutubeMock();
+    await mock.mock(mockPage as any);
 
-    expect(mockPage.route).toHaveBeenCalledOnce()
-    const [pattern] = mockPage.route.mock.calls[0]
-    expect(pattern).toBeInstanceOf(RegExp)
-    expect(pattern.test('https://www.youtube.com/embed/abc123')).toBe(true)
-    expect(pattern.test('https://www.notyoutube.com')).toBe(false)
-  })
+    expect(mockPage.route).toHaveBeenCalledOnce();
+    const [pattern] = mockPage.route.mock.calls[0];
+    expect(pattern).toBeInstanceOf(RegExp);
+    expect(pattern.test("https://www.youtube.com/embed/abc123")).toBe(true);
+    expect(pattern.test("https://www.notyoutube.com")).toBe(false);
+  });
 
-  it('fulfills with HTML mock content', async () => {
-    const mockFulfill = vi.fn()
+  it("fulfills with HTML mock content", async () => {
+    const mockFulfill = vi.fn();
     const mockPage = {
       route: vi.fn(),
-    }
+    };
 
-    const mock = new YoutubeMock()
-    await mock.mock(mockPage as any)
+    const mock = new YoutubeMock();
+    await mock.mock(mockPage as any);
 
     // Call the route handler
-    const handler = mockPage.route.mock.calls[0][1]
-    await handler({ fulfill: mockFulfill })
+    const handler = mockPage.route.mock.calls[0][1];
+    await handler({ fulfill: mockFulfill });
 
-    expect(mockFulfill).toHaveBeenCalledOnce()
-    const fulfillArg = mockFulfill.mock.calls[0][0]
-    expect(fulfillArg.contentType).toBe('text/html')
-    expect(fulfillArg.body).toContain('Youtube Video Mock')
-  })
-})
+    expect(mockFulfill).toHaveBeenCalledOnce();
+    const fulfillArg = mockFulfill.mock.calls[0][0];
+    expect(fulfillArg.contentType).toBe("text/html");
+    expect(fulfillArg.body).toContain("Youtube Video Mock");
+  });
+});

package/src/mock/youtube.ts

@@ -1,12 +1,11 @@
-import type {Page} from '@playwright/test';
-import type {Mockable} from "../visualdiff.js";
+import type { Page } from "@playwright/test";
+import type { Mockable } from "../visualdiff.js";
 
 export class YoutubeMock implements Mockable {
-
   public async mock(page: Page): Promise<void> {
-    await page.route(/www\.youtube\.com/i, async route => {
+    await page.route(/www\.youtube\.com/i, async (route) => {
       await route.fulfill({
-        contentType: 'text/html',
+        contentType: "text/html",
         body: `
 <html>
 <head>
@@ -35,5 +34,4 @@ export class YoutubeMock implements Mockable {
       });
     });
   }
-
 }