@krizaka/page-audit 0.4.0 → 0.5.0

package/README.md

@@ -40,3 +40,26 @@ await auditRoutes({
 
 `a11y` runs axe through `@krizaka/a11y-audit` (an optional peer) and ratchets with the repo's own baseline file; `--a11y-update` and
 `--a11y-init` work as there. The CLI takes `--sitemap`, `--status`, `--empty-main`, `--min-action`, `--a11y app:baseline.json`.
+
+## Visual regression of the journeys (0.4)
+
+`@krizaka/page-audit/visual` (krizaka/.github#375) compares screenshots of an app's main journeys against Linux baselines, with `@playwright/test`
+as the runner. It freezes what moves (clock, motion, caret, View Transition, locale, time zone, fonts) and leaves the app its routes, its persona and its masks.
+
+```js
+import { test, expect } from "@playwright/test";
+import { defineJourneyTests } from "@krizaka/page-audit/visual";
+defineJourneyTests({
+  test, expect,
+  signIn: async (page) => { /* the seeded persona signs in through the form */ },
+  journeys: [
+    { name: "landing", path: "/fr" },
+    { name: "home", path: "/fr/app", session: true, mask: ["[data-live]"] },
+    { name: "home", path: "/fr/app", session: true, firstPaint: true, viewports: ["phone"] },          // the HTML the server sent
+    { name: "home", path: "/fr/app", session: true, firstPaint: { hold: ["**/api/me"] } },             // hydrated, account query pending
+  ],
+});
+```
+
+Baselines are taken in the official Playwright container by the shared workflows of krizaka/.github (`visual-regression.yml` to compare,
+`update-visual-baselines.yml` to commit them on a branch); never on a Mac.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@krizaka/page-audit",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "The page audit of every Krizaka app, in one place: HTTP status, empty main, horizontal overflow, a card out of its panel, sections covering each other, a column cut off, top chrome overlaps, unnamed buttons, empty headings. Runs in a real browser (Playwright) over a route list, viewports and themes, with View Transitions neutralised and a self-test on its own fixtures.",
   "keywords": [
     "krizaka",
@@ -34,7 +34,11 @@
       "import": "./src/settle.mjs"
     },
     "./fixtures": "./src/fixtures.mjs",
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./visual": {
+      "types": "./src/visual.d.ts",
+      "import": "./src/visual.mjs"
+    }
   },
   "files": [
     "src",

package/src/visual.d.ts

@@ -0,0 +1,26 @@
+import type { Browser,Page } from "playwright-core";
+
+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;
+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[];
+  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 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;
+}): void;
+export type { Browser };

package/src/visual.mjs

@@ -0,0 +1,143 @@
+// Visual regression of the main journeys, one source for every app (krizaka/.github#375).
+//
+// What it fixes so that two runs of the same build give the same pixels: a frozen clock, reduced motion, no caret, no
+// View Transition, the fonts loaded, a fixed locale and time zone, the app's theme key set before the page runs, and the
+// live values masked. What it leaves to the app: its routes, how its persona signs in, what is live on its pages.
+// The baselines are Linux ones, taken in the official Playwright container (the `visual-regression` workflow of
+// krizaka/.github); the helper never compares against a baseline taken on a Mac.
+//
+//   import { test, expect } from "@playwright/test";
+//   import { defineJourneyTests } from "@krizaka/page-audit/visual";
+//   defineJourneyTests({ test, expect, journeys: [{ name: "landing", path: "/fr" }, …], signIn });
+
+import { settled, withoutViewTransitions } from "./settle.mjs";
+
+/** The two sizes of every journey: a laptop and a phone. */
+export const VIEWPORTS = Object.freeze({
+  desktop: { width: 1280, height: 800 },
+  phone: { width: 390, height: 844 },
+});
+export const VISUAL_THEMES = Object.freeze(["light", "dark"]);
+/** The clock of every capture (a Thursday, in winter: no daylight-saving edge). */
+export const FROZEN_TIME = "2026-01-15T15:00:00.000Z";
+export const VISUAL_LOCALE = "fr-CA";
+export const VISUAL_TIME_ZONE = "America/Toronto";
+
+/** The viewport × theme cells of a journey, with the snapshot name of each (`<journey>-<viewport>-<theme>.png`). */
+export function visualMatrix(journey, { viewports = VIEWPORTS, themes = VISUAL_THEMES } = {}) {
+  const only = journey.viewports ?? Object.keys(viewports);
+  const cells = [];
+  for (const viewport of only) {
+    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` });
+    }
+  }
+  return cells;
+}
+
+/** The options of a browser context for a capture. `javaScript: false` shows the page as the server sent it. */
+export function visualContextOptions({ size, theme, javaScript = true, storageState }) {
+  return {
+    viewport: size,
+    colorScheme: theme,
+    reducedMotion: "reduce",
+    locale: VISUAL_LOCALE,
+    timezoneId: VISUAL_TIME_ZONE,
+    deviceScaleFactor: 1,
+    javaScriptEnabled: javaScript,
+    serviceWorkers: "block",
+    ...(storageState ? { storageState } : {}),
+  };
+}
+
+/** 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}";
+
+/** Runs before the page's own scripts: the theme the app reads, no View Transition. */
+export const initVisualPage = ({ theme, themeKey }) => {
+  try {
+    localStorage.setItem(themeKey, theme);
+  } catch {
+    /* storage can be blocked: the colour scheme of the context still applies */
+  }
+};
+
+/** Prepares a page: fixed time, the theme key, no View Transition. Call before the first `goto`. */
+export async function prepareVisualPage(page, { theme, themeKey = "kz-theme", now = FROZEN_TIME } = {}) {
+  // Date is fixed, timers still run: the app finishes loading.
+  await page.context().clock.setFixedTime(new Date(now));
+  await page.addInitScript(initVisualPage, { theme, themeKey });
+  await page.addInitScript(withoutViewTransitions);
+}
+
+/** Waits until what is on screen is final: the faces, the images, the transitions. */
+export async function settleForShot(page, { javaScript = true } = {}) {
+  await page.addStyleTag({ content: FREEZE_CSS });
+  if (!javaScript) return;
+  await page.evaluate(() => document.fonts.ready);
+  await settled(page);
+  await page.evaluate(() =>
+    Promise.all([...document.images].filter((img) => !img.complete).map((img) => img.decode().catch(() => undefined))),
+  );
+}
+
+/** The options of `toHaveScreenshot`: a small tolerance for anti-aliasing, never for a missing element. */
+export function shotOptions({ mask = [], page } = {}) {
+  return {
+    animations: "disabled",
+    caret: "hide",
+    scale: "css",
+    maxDiffPixelRatio: 0.002,
+    ...(page && mask.length ? { mask: mask.map((selector) => page.locator(selector)) } : {}),
+  };
+}
+
+/**
+ * Registers one test per journey × viewport × theme.
+ *
+ * journey: { name, path (a string, or `(page, { origin }) => Promise<string>` that finds it, e.g. the first document), session?: boolean, mask?: string[] (selectors of live values), ready?: selector | (page) => Promise,
+ *            viewports?: string[], firstPaint?: true | { hold: string[] } }
+ *   firstPaint: the page before it is alive. `true` turns JavaScript off (the HTML the server sent); `{ hold }` keeps JavaScript
+ *   but never answers the listed URL patterns (the account query, say), so the account mark is captured while its query is pending.
+ * 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 }) {
+  let session;
+  const sessionState = (browser) => {
+    session ??= (async () => {
+      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();
+      await context.close();
+      return state;
+    })();
+    return session;
+  };
+  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 }) => {
+        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 }));
+        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" });
+          if (typeof journey.ready === "string") await page.locator(journey.ready).first().waitFor();
+          else if (journey.ready) await journey.ready(page);
+          await settleForShot(page, { javaScript });
+          await expect(page).toHaveScreenshot(cell.snapshot, shotOptions({ mask: journey.mask, page }));
+        } finally {
+          await context.close();
+        }
+      });
+    }
+  }
+}