An open source design system that's fully customizable and agent ready
TypeScript
test(a11y-spec): a pointer's reach is counted in rendered frames (#9751)
Christopher Chedeau8a74c58fe807
diff --git a/internal/a11y-spec/src/harness/chromium.chromium.spec.ts b/internal/a11y-spec/src/harness/chromium.chromium.spec.tsindex f7174bae24..379b092a7b 100644--- a/internal/a11y-spec/src/harness/chromium.chromium.spec.ts+++ b/internal/a11y-spec/src/harness/chromium.chromium.spec.ts@@ -4,11 +4,12 @@/*** @file chromium.chromium.spec.ts* @input Uses @playwright/test and the public Chromium harness seam- * @output Focused accessibility-tree mapping, clipping-aware rendered-visibility, and pointer hover/away tests+ * @output Focused accessibility-tree mapping, clipping-aware rendered-visibility, pointer hover/away and pointer reach tests* @position Harness regression coverage; proves browser AX properties are exposed without DOM substitution.*/import {expect, test} from '../playwright';+import type {Page} from '../playwright';import {createChromiumHarness, holdMotionStill} from './chromium';test('computed node exposes selected state for tabs', async ({page}) => {@@ -282,3 +283,325 @@ test('pointerAway refuses when every candidate point is on a watched subject', a'nowhere to move the pointer away to',);});++/**+ * Keeps the page's main thread busy for `ms` from its next task, as on a+ * starved machine: no script, frame or event handler runs meanwhile.+ */+async function busyMainThread(page: Page, ms: number): Promise<void> {+ await page.evaluate(duration => {+ setTimeout(() => {+ const end = performance.now() + duration;+ while (performance.now() < end) {+ // Busy on purpose.+ }+ }, 0);+ }, ms);+}++// Longer than the 2 s that 120 frames take on an idle page.+const BUSY_MS = 3_000;++// At 40 ms of script in every frame, the page renders about 25 frames each+// second.+const BUSY_FRAME_MS = 40;++test('a click reaches a control while the page is busy for longer than 120 idle frames take', async ({+ page,+}) => {+ await page.setContent(+ '<button id="go" onclick="this.dataset.clicks = Number(this.dataset.clicks || 0) + 1">Go</button>',+ );+ const cdp = await page.context().newCDPSession(page);+ const harness = createChromiumHarness({+ page,+ subject: page.locator('#go'),+ cdp,+ });+ const subject = await harness.subject();++ await busyMainThread(page, BUSY_MS);+ await harness.click(subject);++ await expect(page.locator('#go')).toHaveAttribute('data-clicks', '1');+});++test('hover reaches a subject while the page is busy for longer than 120 idle frames take', async ({+ page,+}) => {+ await page.setContent(+ '<button id="go" onmouseenter="this.dataset.entered = \'yes\'">Go</button>',+ );+ const cdp = await page.context().newCDPSession(page);+ const harness = createChromiumHarness({+ page,+ subject: page.locator('#go'),+ cdp,+ });+ const subject = await harness.subject();++ await busyMainThread(page, BUSY_MS);+ await harness.hover(subject);++ await expect(page.locator('#go')).toHaveAttribute('data-entered', 'yes');+});++test('canReceivePointer is true for a control while the page is busy for longer than 120 idle frames take', async ({+ page,+}) => {+ await page.setContent('<button id="go">Go</button>');+ const cdp = await page.context().newCDPSession(page);+ const subject = await createChromiumHarness({+ page,+ subject: page.locator('#go'),+ cdp,+ }).subject();++ await busyMainThread(page, BUSY_MS);++ expect(await subject.canReceivePointer()).toBe(true);+});++test('a control under a covering element cannot receive a pointer, and a click on it says why', async ({+ page,+}) => {+ await page.setContent(`+ <button id="go">Go</button>+ <div id="shield" style="position:fixed;inset:0"></div>+ `);+ const cdp = await page.context().newCDPSession(page);+ const harness = createChromiumHarness({+ page,+ subject: page.locator('#go'),+ cdp,+ });+ const subject = await harness.subject();++ expect(await subject.canReceivePointer()).toBe(false);+ const error = await harness.click(subject).then(+ () => null,+ (thrown: unknown) => thrown,+ );+ expect(error).toBeInstanceOf(Error);+ expect((error as Error).message).toMatch(+ /^a pointer could not reach this control within /,+ );+ // The failure names the element that takes the pointer.+ const cause = (error as Error).cause as Error | undefined;+ expect(`${(error as Error).message} ${cause?.message ?? ''}`).toContain(+ 'shield',+ );+});++test('a control that never holds still cannot receive a pointer', async ({+ page,+}) => {+ await page.setContent(`+ <style>+ @keyframes drift {+ from { transform: translateX(0); }+ to { transform: translateX(80px); }+ }+ #go { animation: drift 0.5s linear infinite; }+ </style>+ <button id="go">Go</button>+ `);+ const cdp = await page.context().newCDPSession(page);+ const subject = await createChromiumHarness({+ page,+ subject: page.locator('#go'),+ cdp,+ }).subject();++ // The button moves from one frame to the next before the check starts.+ const moves = await page.locator('#go').evaluate(+ button =>+ new Promise<boolean>(resolve => {+ requestAnimationFrame(() => {+ const before = button.getBoundingClientRect().x;+ requestAnimationFrame(() => {+ resolve(button.getBoundingClientRect().x !== before);+ });+ });+ }),+ );+ expect(moves).toBe(true);++ expect(await subject.canReceivePointer()).toBe(false);+});++test('a click on the trigger of an open popover closes it', async ({page}) => {+ // The press decides from the state it starts in, as a menu trigger does.+ // Light dismiss closes the popover. The click opens it only when the press+ // started with it closed.+ await page.setContent(`+ <button id="trigger">Menu</button>+ <div id="menu" popover>Choices</div>+ <script>+ let openAtPress = false;+ trigger.addEventListener('pointerdown', () => {+ openAtPress = menu.matches(':popover-open');+ });+ trigger.addEventListener('click', () => {+ if (!openAtPress) menu.showPopover();+ });+ </script>+ `);+ const cdp = await page.context().newCDPSession(page);+ const harness = createChromiumHarness({+ page,+ subject: page.locator('#trigger'),+ cdp,+ });+ const subject = await harness.subject();++ await harness.click(subject);+ await expect(page.locator('#menu')).toBeVisible();+ await harness.click(subject);+ await expect(page.locator('#menu')).toBeHidden();+});++/**+ * Spends `ms` of every frame in script from now on, as on a machine that stays+ * busy: the page keeps rendering, only more slowly.+ */+async function busyEveryFrame(page: Page, ms: number): Promise<void> {+ await page.evaluate(duration => {+ const burn = () => {+ const end = performance.now() + duration;+ while (performance.now() < end) {+ // Busy on purpose.+ }+ requestAnimationFrame(burn);+ };+ requestAnimationFrame(burn);+ }, ms);+}++test('a pointer reaches a control on a page that spends most of every frame in script', async ({+ page,+}) => {+ await page.setContent(+ '<button id="go" onclick="this.dataset.clicks = Number(this.dataset.clicks || 0) + 1">Go</button>',+ );+ const cdp = await page.context().newCDPSession(page);+ const harness = createChromiumHarness({+ page,+ subject: page.locator('#go'),+ cdp,+ });+ const subject = await harness.subject();++ await busyEveryFrame(page, BUSY_FRAME_MS);++ expect(await subject.canReceivePointer()).toBe(true);+ await harness.click(subject);+ await expect(page.locator('#go')).toHaveAttribute('data-clicks', '1');+});++test('a hover onto a subject that hides as the pointer leaves the trigger returns', async ({+ page,+}) => {+ // The tip hides when the pointer leaves the trigger, so moving onto it hides+ // it. The hover still returns, and the page shows what happened.+ await page.setContent(`+ <div style="padding:40px">+ <button id="trigger">Trigger</button>+ <div id="tip" hidden style="margin-top:24px;padding:8px">Tip</div>+ </div>+ <script>+ trigger.addEventListener('mouseenter', () => { tip.hidden = false; });+ trigger.addEventListener('mouseleave', () => { tip.hidden = true; });+ </script>+ `);+ const cdp = await page.context().newCDPSession(page);+ const harness = createChromiumHarness({+ page,+ subject: page.locator('#trigger'),+ cdp,+ related: {tip: page.locator('#tip')},+ });++ await harness.hover(await harness.subject());+ await expect(page.locator('#tip')).toBeVisible();+ await harness.hover(await harness.related('tip'));+ await expect(page.locator('#tip')).toBeHidden();+});++test('a link that wraps onto two lines can receive a pointer', async ({+ page,+}) => {+ await page.setContent(`+ <p style="width:200px;margin:0;font:16px/24px monospace">+ aaaaaaaaaaaaa+ <a id="go" href="#" onclick="event.preventDefault(); this.dataset.clicks = Number(this.dataset.clicks || 0) + 1">bbbbbb cccccccc</a>+ dddd eeee+ </p>+ `);+ const cdp = await page.context().newCDPSession(page);+ const harness = createChromiumHarness({+ page,+ subject: page.locator('#go'),+ cdp,+ });+ const subject = await harness.subject();+ // The link has two boxes, and the centre of its whole box is not the link.+ const layout = await page.locator('#go').evaluate(link => {+ const box = link.getBoundingClientRect();+ const hit = document.elementFromPoint(+ box.left + box.width / 2,+ box.top + box.height / 2,+ );+ return {+ parts: link.getClientRects().length,+ centreIsLink: hit === link || link.contains(hit),+ };+ });+ expect(layout).toEqual({parts: 2, centreIsLink: false});++ expect(await subject.canReceivePointer()).toBe(true);+ await harness.click(subject);+ await expect(page.locator('#go')).toHaveAttribute('data-clicks', '1');+});++test('a control under a sticky header can receive a pointer', async ({+ page,+}) => {+ await page.setContent(`+ <style>+ body { margin: 0; }+ #bar { position: fixed; top: 0; left: 0; right: 0; height: 120px; background: #eee; }+ </style>+ <div id="bar">Header</div>+ <div style="height:1500px"></div>+ <button id="go" onclick="this.dataset.clicks = Number(this.dataset.clicks || 0) + 1">Go</button>+ <div style="height:1500px"></div>+ `);+ await page.evaluate(() => {+ const button = document.getElementById('go');+ if (button != null) {+ window.scrollTo(0, button.offsetTop - 40);+ }+ });+ const cdp = await page.context().newCDPSession(page);+ const harness = createChromiumHarness({+ page,+ subject: page.locator('#go'),+ cdp,+ });+ const subject = await harness.subject();+ // The header covers the button where it starts.+ const covered = await page.locator('#go').evaluate(button => {+ const box = button.getBoundingClientRect();+ const hit = document.elementFromPoint(+ box.left + box.width / 2,+ box.top + box.height / 2,+ );+ return hit?.id ?? null;+ });+ expect(covered).toBe('bar');++ expect(await subject.canReceivePointer()).toBe(true);+ await harness.click(subject);+ await expect(page.locator('#go')).toHaveAttribute('data-clicks', '1');+});diff --git a/internal/a11y-spec/src/harness/chromium.ts b/internal/a11y-spec/src/harness/chromium.tsindex 510ca9c892..c87287cc44 100644--- a/internal/a11y-spec/src/harness/chromium.ts+++ b/internal/a11y-spec/src/harness/chromium.ts@@ -28,7 +28,6 @@* to ../harness/jsdom.ts — both implement Harness in ../harness.ts.*/-import {errors as playwrightErrors} from '@playwright/test';import type {CDPSession, Locator, Page} from '@playwright/test';import {MissingHarnessRelation,@@ -48,33 +47,144 @@ export const CHROMIUM_OBSERVES: readonly EvidenceLayer[] = [];/**- * How long a pointer gets to reach a control before the attempt is a failure.+ * How many frames the page renders while a pointer waits to reach a control,+ * before the attempt is a failure.*- * Generous for a control that is reachable at all — Playwright's actionability- * check normally settles in single-digit milliseconds — and short enough that a- * control a pointer can never reach reports why instead of hanging.+ * The count is in the page's own frames, not in milliseconds. A page that+ * stalls and then resumes, or a page that stays busy and renders slowly, gets+ * the same 120 frames as an idle page. On an idle page, 120 frames take 2 s.*/-const POINTER_REACH_BUDGET_MS = 2_000;+const POINTER_REACH_FRAMES = 120;++/** Whether a pointer can reach an element and, if it cannot, what stops it. */+type PointerReach =+ {readonly reached: true} | {readonly reached: false; readonly why: string};/**- * Playwright's own timeout type, rather than a regex over the message: the- * message is prose that can be reworded in any release, and matching it would- * turn a wording change into a mystery failure.+ * Waits, frame by frame, until a pointer can reach the element. The element+ * must be visible and hold still from one frame to the next. It must be enabled+ * when `enabled` is set. The page must hit-test it at the centre of its first+ * part in view. The check sends no input, so it cannot dismiss a popover or+ * move focus, as a trial click can. It may scroll the element into view, as a+ * click does. It gives up after POINTER_REACH_FRAMES frames.*/-function isTimeout(error: unknown): boolean {- return error instanceof playwrightErrors.TimeoutError;+function waitForPointerReach(+ locator: Locator,+ {enabled}: {readonly enabled: boolean},+): Promise<PointerReach> {+ return locator.evaluate(+ (element, {frames, needsEnabled}) =>+ new Promise<PointerReach>(resolve => {+ const document = element.ownerDocument;+ const view = document.defaultView ?? window;+ const describe = (node: Element | null) =>+ node == null+ ? 'nothing'+ : `<${node.localName}${node.id === '' ? '' : `#${node.id}`}>`;+ const hitAt = (x: number, y: number) => {+ let hit = document.elementFromPoint(x, y);+ while (hit?.shadowRoot != null) {+ const inner = hit.shadowRoot.elementFromPoint(x, y);+ if (inner == null || inner === hit) {+ break;+ }+ hit = inner;+ }+ return hit;+ };+ const isElementOrInside = (hit: Element | null) => {+ for (let node: Node | null = hit; node != null;) {+ if (node === element) {+ return true;+ }+ node =+ node.parentNode instanceof ShadowRoot+ ? node.parentNode.host+ : node.parentNode;+ }+ return false;+ };+ // The centre of the first part of the element in view. A link that+ // wraps onto two lines has a box per line. The space between them is+ // not the link.+ const firstPartInView = () => {+ for (const rect of element.getClientRects()) {+ const left = Math.max(rect.left, 0);+ const top = Math.max(rect.top, 0);+ const right = Math.min(rect.right, view.innerWidth);+ const bottom = Math.min(rect.bottom, view.innerHeight);+ if (right > left && bottom > top) {+ return {x: (left + right) / 2, y: (top + bottom) / 2};+ }+ }+ return null;+ };+ // Like a click, a check that finds the element covered scrolls it to+ // another place in view and looks again, as under a sticky header.+ const alignments: ScrollLogicalPosition[] = ['end', 'center', 'start'];+ let nextAlignment = 0;+ const scrollToNextPlace = () => {+ const alignment = alignments[nextAlignment % alignments.length];+ nextAlignment += 1;+ element.scrollIntoView({block: alignment, inline: alignment});+ };+ let previous: DOMRect | null = null;+ let rendered = 0;+ let why = 'it was never visible';+ const look = () => {+ rendered += 1;+ const box = element.getBoundingClientRect();+ const still =+ previous != null &&+ box.x === previous.x &&+ box.y === previous.y &&+ box.width === previous.width &&+ box.height === previous.height;+ previous = box;+ const point = firstPartInView();+ if (!element.isConnected) {+ why = 'it left the document';+ } else if (+ box.width === 0 ||+ box.height === 0 ||+ !element.checkVisibility({visibilityProperty: true})+ ) {+ why = 'it was never visible';+ } else if (+ needsEnabled &&+ (element.matches(':disabled') ||+ element.closest('[aria-disabled="true"]') != null)+ ) {+ why = 'it stayed disabled';+ } else if (point == null) {+ element.scrollIntoView({block: 'center', inline: 'center'});+ why = 'it never came into view';+ } else if (!still) {+ why = 'it never held still from one frame to the next';+ } else {+ const hit = hitAt(point.x, point.y);+ if (isElementOrInside(hit)) {+ resolve({reached: true});+ return;+ }+ why = `${describe(hit)} takes the pointer at the centre of its first part in view, not the element or anything inside it`;+ scrollToNextPlace();+ }+ if (rendered >= frames) {+ resolve({reached: false, why});+ return;+ }+ requestAnimationFrame(look);+ };+ requestAnimationFrame(look);+ }),+ {frames: POINTER_REACH_FRAMES, needsEnabled: enabled},+ );}async function canReceivePointer(locator: Locator): Promise<boolean> {- try {- await locator.click({trial: true, timeout: POINTER_REACH_BUDGET_MS});- return true;- } catch (error) {- if (isTimeout(error)) {- return false;- }- throw error;- }+ const reach = await waitForPointerReach(locator, {enabled: true});+ return reach.reached;}const KEYS: Record<Key, string> = {@@ -1085,24 +1195,22 @@ export function createChromiumHarness(// `ignoreAvailability` skips that judgement, which is the only way to ask// a control the browser calls unavailable what it does when clicked// anyway.- try {- await target.click({- force: options?.ignoreAvailability === true,- // Bounded, and short. A control a pointer cannot reach — one covered- // by something else, or clipped to nothing — otherwise sits here- // until the whole test times out, and a timeout says nothing about- // WHY. This turns that into a legible failure the report can carry.- timeout: POINTER_REACH_BUDGET_MS,- });- } catch (error) {- if (isTimeout(error)) {- throw new Error(- `a pointer could not reach this control within ${POINTER_REACH_BUDGET_MS}ms: the browser never found it visible, stable, and able to receive a pointer event. Something is covering it, or it is clipped to nothing.`,- {cause: error},- );- }- throw error;+ if (options?.ignoreAvailability === true) {+ await target.click({force: true});+ return;}+ // A control a pointer cannot reach, covered by something else or+ // clipped to nothing, otherwise waits until the whole test times out.+ // That timeout says nothing about why, so the reach is checked first.+ const reach = await waitForPointerReach(target, {enabled: true});+ if (!reach.reached) {+ throw new Error(+ `a pointer could not reach this control within ${POINTER_REACH_FRAMES} rendered frames: ${reach.why}.`,+ );+ }+ // The check above is the judge, so Playwright only performs the click.+ // Without `force` it would judge the control again, with no bound.+ await target.click({force: true});},clickBeside: async targetSubject => {const target = pointerTargets.get(targetSubject);@@ -1212,17 +1320,15 @@ export function createChromiumHarness(}// The same bounded reach as `click`: a subject a pointer can never rest// on reports why instead of sitting out the whole test timeout.- try {- await target.hover({timeout: POINTER_REACH_BUDGET_MS});- } catch (error) {- if (isTimeout(error)) {- throw new Error(- `a pointer could not reach this subject within ${POINTER_REACH_BUDGET_MS}ms: the browser never found it visible, stable, and able to receive a pointer event. Something is covering it, or it is clipped to nothing.`,- {cause: error},- );- }- throw error;+ const reach = await waitForPointerReach(target, {enabled: false});+ if (!reach.reached) {+ throw new Error(+ `a pointer could not reach this subject within ${POINTER_REACH_FRAMES} rendered frames: ${reach.why}.`,+ );}+ // As for `click`: the check above is the judge. A subject that vanishes+ // as the pointer moves onto it then fails the contract's own check.+ await target.hover({force: true});},pointerAway: async () => {const viewport = await page.evaluate(() => ({