Skip to content

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.ts
index 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.ts
index 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(() => ({