@krizaka/page-audit 0.5.1 → 0.7.0

package/src/self-test.mjs

@@ -1,6 +1,29 @@
 // The audit proven on its own fixtures, in a real browser: each broken fixture must be reported, the fine ones must not.
 // A guard that stopped seeing is itself a red build.
-import { BOX_TOO_WIDE, BROKEN_PARTS, CARD_OVER_NEXT, CHROME_BAD, CHROME_FINE, COLUMN_CUT, EMPTY_MAIN, FINE, FOLDED_SECTION, FRAME_FITS, FRAME_FORCES_SCROLL, HIDDEN_CONTENT, MAP_COLLAPSED, MAP_FINE, MAP_HIDDEN, MAP_NO_CANVAS, SECTIONS_OVERLAP, SMALL_ACTION, TOKEN_IN_STRETCHED_ROW, TOKEN_WRAPPED } from "./fixtures.mjs";
+import {
+  BOX_TOO_WIDE,
+  BROKEN_PARTS,
+  CARD_OVER_NEXT,
+  CHROME_BAD,
+  CHROME_FINE,
+  COLUMN_CUT,
+  CONTROLS_FINE,
+  CONTROLS_OVERLAP,
+  EMPTY_MAIN,
+  FINE,
+  FOLDED_SECTION,
+  FRAME_FITS,
+  FRAME_FORCES_SCROLL,
+  HIDDEN_CONTENT,
+  MAP_COLLAPSED,
+  MAP_FINE,
+  MAP_HIDDEN,
+  MAP_NO_CANVAS,
+  SECTIONS_OVERLAP,
+  SMALL_ACTION,
+  TOKEN_IN_STRETCHED_ROW,
+  TOKEN_WRAPPED,
+} from "./fixtures.mjs";
 import { auditPage, problemsOf } from "./page-audit.mjs";
 import { auditContext } from "./settle.mjs";
 
@@ -21,6 +44,12 @@ const EXPECT = [
   ["a map with no canvas", MAP_NO_CANVAS, /has no canvas/, { maps: true }],
   ["no map where one is required", FINE, /no map on the page/, { maps: { required: true } }],
   ["two page footers and no nav", CHROME_BAD, /2 page footers/, { landmarks: "public" }],
+  [
+    "two controls on top of each other",
+    CONTROLS_OVERLAP,
+    /controls overlap, one cannot be clicked/,
+    { controlOverlaps: true },
+  ],
   ["no nav landmark", CHROME_BAD, /no <nav> landmark/, { landmarks: "app" }],
 ];
 const FINES = [
@@ -30,11 +59,23 @@ const FINES = [
   ["a short token in a row a taller neighbour stretches", TOKEN_IN_STRETCHED_ROW],
 ];
 /** Fixtures that must stay clean even with every opt-in check on. */
-const ALL = { emptyMain: true, frame: true, minAction: 36, boxes: true, pictures: true, emptyControls: true, hardColors: true, landmarks: "public", maps: true };
+const ALL = {
+  emptyMain: true,
+  frame: true,
+  minAction: 36,
+  boxes: true,
+  pictures: true,
+  emptyControls: true,
+  hardColors: true,
+  landmarks: "public",
+  maps: true,
+  controlOverlaps: true,
+};
 const FINES_STRICT = [
   ["a frame that fits its screen", FRAME_FITS, { frame: true, emptyMain: false }],
   ["the family chrome", CHROME_FINE, ALL],
   ["maps with a size and something drawn", MAP_FINE, { maps: true }],
+  ["controls side by side, in a label, in a scroller", CONTROLS_FINE, { controlOverlaps: true }],
   ["a map that is not drawn (display none)", MAP_HIDDEN, { maps: true }],
 ];
 
@@ -57,7 +98,8 @@ export async function selfTest({ launch } = {}) {
     const page = await (await auditContext(browser, { viewport: { width: 1280, height: 800 } })).newPage();
     for (const [name, html, pattern, checks] of EXPECT) {
       const problems = await problemsOn(page, html, checks);
-      if (!problems.some((p) => pattern.test(p))) failures.push(`the audit does not see ${String(name)}: ${problems.join(" | ") || "no problem reported"}`);
+      if (!problems.some((p) => pattern.test(p)))
+        failures.push(`the audit does not see ${String(name)}: ${problems.join(" | ") || "no problem reported"}`);
     }
     for (const [name, html] of FINES) failures.push(...(await reported(page, name, html)));
     await page.setViewportSize({ width: 1280, height: 700 });

package/src/settle.mjs

@@ -28,7 +28,11 @@ export async function auditContext(browser, options) {
 
 /** Resolves once no view transition is running (none starts under reduced motion; this makes the wait explicit). */
 export const settled = (page) =>
-  page.waitForFunction(() => !document.activeViewTransition && !document.documentElement.matches(":active-view-transition"), null, { timeout: 10_000 });
+  page.waitForFunction(
+    () => !document.activeViewTransition && !document.documentElement.matches(":active-view-transition"),
+    null,
+    { timeout: 10_000 },
+  );
 
 /**
  * Loads a page, then waits for the faces and for the transitions: what is read afterwards is final. Returns the response.

package/src/visual.d.ts

@@ -1,6 +1,9 @@
-import type { Browser,Page } from "playwright-core";
+import type { Browser, Page } from "playwright-core";
 
-export interface Size { width: number; height: number }
+export interface Size {
+  width: number;
+  height: number;
+}
 export const VIEWPORTS: Readonly<{ desktop: Size; phone: Size }>;
 export const VISUAL_THEMES: readonly ["light", "dark"];
 export const FROZEN_TIME: string;
@@ -8,19 +11,43 @@ export const VISUAL_LOCALE: string;
 export const VISUAL_TIME_ZONE: string;
 export const FREEZE_CSS: string;
 export interface Journey {
-  name: string; path: string | ((page: Page, o: { origin: string }) => Promise<string>); session?: boolean; mask?: string[]; viewports?: string[];
+  name: string;
+  path: string | ((page: Page, o: { origin: string }) => Promise<string>);
+  session?: boolean;
+  mask?: string[];
+  viewports?: string[];
   ready?: string | ((page: Page) => Promise<unknown>);
   firstPaint?: true | { hold: string[] };
 }
-export interface Cell { viewport: string; size: Size; theme: string; snapshot: string }
-export function visualMatrix(journey: Journey, options?: { viewports?: Record<string, Size>; themes?: readonly string[] }): Cell[];
-export function visualContextOptions(o: { size: Size; theme: string; javaScript?: boolean; storageState?: unknown }): Record<string, unknown>;
+export interface Cell {
+  viewport: string;
+  size: Size;
+  theme: string;
+  snapshot: string;
+}
+export function visualMatrix(
+  journey: Journey,
+  options?: { viewports?: Record<string, Size>; themes?: readonly string[] },
+): Cell[];
+export function visualContextOptions(o: {
+  size: Size;
+  theme: string;
+  javaScript?: boolean;
+  storageState?: unknown;
+}): Record<string, unknown>;
 export function initVisualPage(o: { theme: string; themeKey: string }): void;
 export function prepareVisualPage(page: Page, o?: { theme?: string; themeKey?: string; now?: string }): Promise<void>;
 export function settleForShot(page: Page, o?: { javaScript?: boolean }): Promise<void>;
 export function shotOptions(o?: { mask?: string[]; page?: Page }): Record<string, unknown>;
 export function defineJourneyTests(o: {
-  test: unknown; expect: unknown; journeys: Journey[]; signIn: (page: Page, o: { base?: string }) => Promise<void>;
-  base?: string; viewports?: Record<string, Size>; themes?: readonly string[]; themeKey?: string; now?: string;
+  test: unknown;
+  expect: unknown;
+  journeys: Journey[];
+  signIn: (page: Page, o: { base?: string }) => Promise<void>;
+  base?: string;
+  viewports?: Record<string, Size>;
+  themes?: readonly string[];
+  themeKey?: string;
+  now?: string;
 }): void;
 export type { Browser };

package/src/visual.mjs

@@ -31,7 +31,12 @@ export function visualMatrix(journey, { viewports = VIEWPORTS, themes = VISUAL_T
     if (!viewports[viewport]) throw new Error(`unknown viewport « ${viewport} » in journey « ${journey.name} »`);
     for (const theme of themes) {
       const suffix = journey.firstPaint ? "-first-paint" : "";
-      cells.push({ viewport, size: viewports[viewport], theme, snapshot: `${journey.name}${suffix}-${viewport}-${theme}.png` });
+      cells.push({
+        viewport,
+        size: viewports[viewport],
+        theme,
+        snapshot: `${journey.name}${suffix}-${viewport}-${theme}.png`,
+      });
     }
   }
   return cells;
@@ -53,7 +58,8 @@ export function visualContextOptions({ size, theme, javaScript = true, storageSt
 }
 
 /** The style every capture carries: nothing moves, nothing blinks. */
-export const FREEZE_CSS = "*,*::before,*::after{animation:none!important;transition:none!important;caret-color:transparent!important;scroll-behavior:auto!important}";
+export const FREEZE_CSS =
+  "*,*::before,*::after{animation:none!important;transition:none!important;caret-color:transparent!important;scroll-behavior:auto!important}";
 
 /** Runs before the page's own scripts: the theme the app reads, no View Transition. */
 export const initVisualPage = ({ theme, themeKey }) => {
@@ -106,11 +112,23 @@ export function shotOptions({ mask = [], page } = {}) {
  * now: the instant of the browser clock (default FROZEN_TIME); an app whose seed stamps rows with the day of the run passes that moment.
  * signIn(page, { base }): signs the persona in; its cookies are kept and reused by every signed-in capture of the worker.
  */
-export function defineJourneyTests({ test, expect, journeys, signIn, base, viewports = VIEWPORTS, themes = VISUAL_THEMES, themeKey = "kz-theme", now = FROZEN_TIME }) {
+export function defineJourneyTests({
+  test,
+  expect,
+  journeys,
+  signIn,
+  base,
+  viewports = VIEWPORTS,
+  themes = VISUAL_THEMES,
+  themeKey = "kz-theme",
+  now = FROZEN_TIME,
+}) {
   let session;
   const sessionState = (browser) => {
     session ??= (async () => {
-      const context = await browser.newContext(visualContextOptions({ size: viewports.desktop ?? Object.values(viewports)[0], theme: "light" }));
+      const context = await browser.newContext(
+        visualContextOptions({ size: viewports.desktop ?? Object.values(viewports)[0], theme: "light" }),
+      );
       const page = await context.newPage();
       await signIn(page, { base });
       const state = await context.storageState();
@@ -121,17 +139,24 @@ export function defineJourneyTests({ test, expect, journeys, signIn, base, viewp
   };
   for (const journey of journeys) {
     for (const cell of visualMatrix(journey, { viewports, themes })) {
-      test(`${journey.name} · ${cell.viewport} · ${cell.theme}${journey.firstPaint ? " · first paint" : ""}`, async ({ browser, baseURL }) => {
+      test(`${journey.name} · ${cell.viewport} · ${cell.theme}${journey.firstPaint ? " · first paint" : ""}`, async ({
+        browser,
+        baseURL,
+      }) => {
         const origin = base ?? baseURL;
         const javaScript = !(journey.firstPaint === true);
         const storageState = journey.session ? await sessionState(browser) : undefined;
-        const context = await browser.newContext(visualContextOptions({ size: cell.size, theme: cell.theme, javaScript, storageState }));
+        const context = await browser.newContext(
+          visualContextOptions({ size: cell.size, theme: cell.theme, javaScript, storageState }),
+        );
         try {
           const page = await context.newPage();
           await prepareVisualPage(page, { theme: cell.theme, themeKey, now });
           for (const pattern of journey.firstPaint?.hold ?? []) await page.route(pattern, () => undefined);
           const path = typeof journey.path === "function" ? await journey.path(page, { origin }) : journey.path;
-          await page.goto(new URL(path, origin).toString(), { waitUntil: journey.firstPaint ? "domcontentloaded" : "load" });
+          await page.goto(new URL(path, origin).toString(), {
+            waitUntil: journey.firstPaint ? "domcontentloaded" : "load",
+          });
           if (typeof journey.ready === "string") await page.locator(journey.ready).first().waitFor();
           else if (journey.ready) await journey.ready(page);
           await settleForShot(page, { javaScript });