test/helpers.ts

Functions

Imports

It imports no other module of this repo. No module of this repo imports it.

Source

1import AxeBuilder from "@axe-core/playwright";
2import { expect, test, type Page } from "@playwright/test";
3
4// Shared by every component's spec. A spec calls `eachTheme` and, inside it, names its
5// tests with one of the prefixes below; the site's test panel groups results by prefix.
6//   "keyboard: ..."       a key does what the doc page's keyboard table says
7//   "accessibility: ..."  the axe scan, the ARIA snapshot, painted contrast
8//   "behaviour: ..."      anything else the component promises
9
10export const THEMES = ["light", "dark"] as const;
11export type Theme = (typeof THEMES)[number];
12
13// Runs `body` once per theme, with the browser's colour scheme and the page's data-theme
14// both set, so a component is checked as each theme actually paints it. In the dark theme
15// only the accessibility tests run (playwright.config.ts, grepInvert).
16export function eachTheme(body: (theme: Theme) => void): void {
17  for (const theme of THEMES) {
18    test.describe(`${theme} theme`, () => {
19      test.use({ colorScheme: theme });
20      body(theme);
21    });
22  }
23}
24
25declare global {
26  interface Window {
27    capRatio(a: string, b: string): number;
28  }
29}
30
31// The contrast ratio of two CSS colours as the browser paints them (a canvas pixel, so any
32// colour syntax works). visitStates installs it, for checks that run inside the page.
33function installRatio(): void {
34  const lum = (c: string) => {
35    const x = document.createElement("canvas").getContext("2d")!;
36    x.fillStyle = c;
37    x.fillRect(0, 0, 1, 1);
38    const [r, g, b] = [...x.getImageData(0, 0, 1, 1).data].map((v) => v / 255).map((v) => (v <= 0.04045 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4));
39    return 0.2126 * r! + 0.7152 * g! + 0.0722 * b!;
40  };
41  window.capRatio = (a, b) => {
42    const [x, y] = [lum(a), lum(b)];
43    return (Math.max(x, y) + 0.05) / (Math.min(x, y) + 0.05);
44  };
45}
46
47// Opens a component's states page in the given theme and waits for its fonts.
48// With `only`, opens one page-level specimen (a <template data-specimen>) as the whole page.
49export async function visitStates(page: Page, name: string, theme: Theme, only?: string): Promise<void> {
50  const q = new URLSearchParams({ theme });
51  if (only) q.set("only", only);
52  await page.goto(`components/${name}/states.html?${q}`);
53  await page.evaluate(() => document.fonts.ready.then(() => undefined));
54  await page.evaluate(installRatio);
55  if (!only) await expect(page.locator("h1").first()).toBeVisible();
56}
57
58// The automated scan, against WCAG 2.2 A and AA. Any violation fails, with its rule, its
59// impact and the first offending node in the message, so a failure says where to look.
60// Base UI's focus guards are visually hidden sentinels it places around an open popup on
61// purpose: aria-hidden and focusable so focus can wrap. axe's aria-hidden-focus rule flags
62// them; `baseUi: true` leaves exactly those elements out of the scan and nothing else.
63// `exclude` leaves one element out, for a state the scan misreads; say why where it is used.
64export async function expectNoAxeViolations(page: Page, include?: string, options: { baseUi?: boolean; exclude?: string } = {}): Promise<void> {
65  let builder = new AxeBuilder({ page }).withTags(["wcag2a", "wcag2aa", "wcag21a", "wcag21aa", "wcag22aa"]);
66  if (include) builder = builder.include(include);
67  // A states page that shows open popups in <iframe> frames is scanned frame by frame, by the
68  // tests that visit each frame on its own, so those frames are left out of the page scan.
69  if (options.baseUi) builder = builder.exclude("[data-base-ui-focus-guard]").exclude("iframe");
70  if (options.exclude) builder = builder.exclude(options.exclude);
71  // axe reads colours as painted. A dialog fading in, or a control mid-transition, is read
72  // blended with what is behind it, so wait for every finite animation and transition to end
73  // first (the first CI run caught a danger button at 4.18:1 for this reason).
74  await page.evaluate(() =>
75    Promise.all(
76      document
77        .getAnimations()
78        .filter((a) => Number.isFinite(a.effect?.getComputedTiming().endTime ?? Infinity))
79        .map((a) => a.finished.catch(() => undefined)),
80    ).then(() => undefined),
81  );
82  const { violations } = await builder.analyze();
83  const found = violations.map((v) => `${v.id} (${v.impact}): ${v.help}. First at ${v.nodes[0]?.target.join(" ")} (${v.nodes.length} nodes). ${(v.nodes[0]?.failureSummary ?? "").replace(/\s+/g, " ").trim()}`);
84  expect(found, "axe violations").toEqual([]);
85}
86
87export interface Reading {
88  fg: string;
89  bg: string;
90  ratio: number;
91}
92
93// Contrast as the browser paints it: the colour of the element (its text, or its border)
94// against the first opaque background behind it, compositing translucent layers. From the
95// Capsid Portal's contrast spec, where it caught a selected row at 1.06:1. A selector ending in
96// ::before or ::after reads that pseudo-element (a sliding highlight's edge), on its element.
97export function paintedContrast(page: Page, selector: string, part: "color" | "border" | "outline" = "color"): Promise<Reading | null> {
98  return page.evaluate(
99    ([full, which]) => {
100      const [sel = full, pseudo] = full.split(/(?=::)/);
101      const el = document.querySelector<HTMLElement>(sel);
102      if (!el) return null;
103      const parse = (s: string): [number, number, number, number] => {
104        // A color-mix() computes to color(srgb r g b / a), its channels from 0 to 1.
105        const srgb = s.match(/color\(srgb ([^)]+)\)/)?.[1];
106        if (srgb) {
107          const q = srgb.split(/[\s/]+/).filter(Boolean).map(Number);
108          return [Math.round((q[0] ?? 0) * 255), Math.round((q[1] ?? 0) * 255), Math.round((q[2] ?? 0) * 255), q.length > 3 ? (q[3] ?? 1) : 1];
109        }
110        const m = s.match(/rgba?\(([^)]+)\)/);
111        const inner = m?.[1];
112        if (!inner) return [0, 0, 0, 0];
113        const p = inner.split(/[\s,/]+/).filter(Boolean).map(Number);
114        return [p[0] ?? 0, p[1] ?? 0, p[2] ?? 0, p.length > 3 ? (p[3] ?? 1) : 1];
115      };
116      const over = (top: [number, number, number, number], under: [number, number, number]): [number, number, number] => {
117        const a = top[3];
118        return [Math.round(top[0] * a + under[0] * (1 - a)), Math.round(top[1] * a + under[1] * (1 - a)), Math.round(top[2] * a + under[2] * (1 - a))];
119      };
120      let bg: [number, number, number] = [255, 255, 255];
121      const layers: [number, number, number, number][] = [];
122      for (let n: HTMLElement | null = which === "color" || pseudo ? el : el.parentElement; n; n = n.parentElement) {
123        const c = parse(getComputedStyle(n).backgroundColor);
124        if (c[3] > 0) layers.unshift(c);
125        if (c[3] >= 1) break;
126      }
127      if (layers.length === 0 || (layers[0]?.[3] ?? 0) < 1) layers.unshift(parse(getComputedStyle(document.body).backgroundColor));
128      // SVG text is painted with fill, on the shape drawn before it in its group (a tile's
129      // polygon, a box's rect), not on a CSS background.
130      const svgText = which === "color" && (el as Element) instanceof SVGTextElement;
131      if (svgText) {
132        const shape = el.parentElement?.querySelector("polygon, rect, circle");
133        const fill = shape ? parse(getComputedStyle(shape).fill) : [0, 0, 0, 0];
134        if ((fill[3] ?? 0) > 0) layers.push(fill as [number, number, number, number]);
135      }
136      for (const l of layers) bg = over(l, bg);
137      const cs = getComputedStyle(el, pseudo ?? null);
138      const fgRaw = parse(svgText ? cs.fill : which === "color" ? cs.color : which === "border" ? cs.borderTopColor : cs.outlineColor);
139      const fg = over(fgRaw, bg);
140      const lum = (c: [number, number, number]) => {
141        const f = (v: number) => {
142          const s = v / 255;
143          return s <= 0.04045 ? s / 12.92 : Math.pow((s + 0.055) / 1.055, 2.4);
144        };
145        return 0.2126 * f(c[0]) + 0.7152 * f(c[1]) + 0.0722 * f(c[2]);
146      };
147      const a = lum(fg);
148      const b = lum(bg);
149      const hex = (c: [number, number, number]) => "#" + c.map((v) => v.toString(16).padStart(2, "0")).join("");
150      return { fg: hex(fg), bg: hex(bg), ratio: (Math.max(a, b) + 0.05) / (Math.min(a, b) + 0.05) };
151    },
152    [selector, part] as const,
153  );
154}
155
156// Every selector must match and reach its bar. A missing element fails rather than
157// passing vacuously.
158export async function expectContrast(page: Page, checks: Array<{ sel: string; what: string; part?: "color" | "border" | "outline"; min?: number }>): Promise<void> {
159  const low: string[] = [];
160  for (const c of checks) {
161    const r = await paintedContrast(page, c.sel, c.part ?? "color");
162    expect(r, `${c.what} (${c.sel}) is on the page`).not.toBeNull();
163    const min = c.min ?? (c.part && c.part !== "color" ? 3 : 4.5);
164    if (r && r.ratio < min) low.push(`${c.what}: ${r.fg} on ${r.bg} is ${r.ratio.toFixed(2)}:1, needs ${min}:1`);
165  }
166  expect(low).toEqual([]);
167}
168
169// The element that has focus, described for an assertion message.
170export function focused(page: Page): Promise<string> {
171  return page.evaluate(() => {
172    const el = document.activeElement;
173    if (!el || el === document.body) return "body";
174    const name = el.getAttribute("aria-label") ?? el.textContent?.trim().slice(0, 40) ?? "";
175    return `${el.tagName.toLowerCase()}${el.id ? `#${el.id}` : ""} "${name}"`;
176  });
177}
178
179// Catches the next submit of a form under `root` (a selector), stops it, and resolves with what the
180// browser would have posted: the method, the encoding and every field, a file as "file:<name>". For
181// a spec that checks a component's forms work with no script.
182export function nextPost(page: Page, root: string): Promise<{ method: string; enctype: string; fields: Record<string, string[]> }> {
183  return page.evaluate(
184    (sel) =>
185      new Promise<{ method: string; enctype: string; fields: Record<string, string[]> }>((done) => {
186        document.querySelector(sel)!.addEventListener(
187          "submit",
188          (e) => {
189            e.preventDefault();
190            const form = e.target as HTMLFormElement;
191            const data = new FormData(form, (e as SubmitEvent).submitter);
192            const fields: Record<string, string[]> = {};
193            for (const k of new Set(data.keys())) fields[k] = data.getAll(k).map((v) => (typeof v === "string" ? v : `file:${v.name}`));
194            done({ method: form.method, enctype: form.enctype, fields });
195          },
196          { capture: true, once: true },
197        );
198      }),
199    root,
200  );
201}
202
203// A focused row's ring is an inset outline over the row's own --sel tint, so its contrast is the
204// outline colour against the row's background (paintedContrast measures an outline against the
205// parent's background, which is not what the eye sees there).
206export function ringContrast(page: Page, sel: string): Promise<{ ring: string; bg: string; ratio: number; width: string } | null> {
207  return page.evaluate((s) => {
208    const el = document.querySelector<HTMLElement>(s);
209    if (!el) return null;
210    const cs = getComputedStyle(el);
211    const rgb = (v: string) => (v.match(/[\d.]+/g) ?? []).slice(0, 3).map(Number);
212    const lum = (c: number[]) => {
213      const f = (x: number) => {
214        const t = x / 255;
215        return t <= 0.04045 ? t / 12.92 : Math.pow((t + 0.055) / 1.055, 2.4);
216      };
217      return 0.2126 * f(c[0] ?? 0) + 0.7152 * f(c[1] ?? 0) + 0.0722 * f(c[2] ?? 0);
218    };
219    const a = lum(rgb(cs.outlineColor));
220    const b = lum(rgb(cs.backgroundColor));
221    return { ring: cs.outlineColor, bg: cs.backgroundColor, width: cs.outlineWidth, ratio: (Math.max(a, b) + 0.05) / (Math.min(a, b) + 0.05) };
222  }, sel);
223}
224
225// What sticks out of a list row, or leaves its title under 100px to be read: an empty list is a fit.
226export function rowOverflow(page: Page): Promise<string[]> {
227  return page.evaluate(() => {
228    const out: string[] = [];
229    for (const row of document.querySelectorAll<HTMLElement>("li.cap-row")) {
230      const r = row.getBoundingClientRect();
231      if (r.width === 0) continue;
232      for (const el of row.querySelectorAll<HTMLElement>("*")) {
233        const b = el.getBoundingClientRect();
234        if (b.width === 0 || b.height === 0 || el.closest("[hidden], .cap-sr-only")) continue;
235        if (b.right > r.right + 1 || b.left < r.left - 1) out.push(`${row.id} ${el.className || el.tagName} sticks out of its row`);
236      }
237      const t = row.querySelector<HTMLElement>(".cap-row-title");
238      if (t && t.getBoundingClientRect().width < 100) out.push(`${row.id} title is ${Math.round(t.getBoundingClientRect().width)}px wide`);
239    }
240    return out;
241  });
242}