Skip to content

Playwright is a framework for Web Testing and Automation. It allows testing Chromium, Firefox and WebKit with a single API.

feat(aria): distill ai snapshots to make them less verbose (#41604)

Pavel Feldman26385ab8f858
diff --git a/packages/injected/src/ariaSnapshot.ts b/packages/injected/src/ariaSnapshot.ts
index bddb959f66..610d8b0ea2 100644
--- a/packages/injected/src/ariaSnapshot.ts
+++ b/packages/injected/src/ariaSnapshot.ts
@@ -18,12 +18,13 @@ import * as aria from '@isomorphic/ariaSnapshot';
import { escapeRegExp, longestCommonSubstring, normalizeWhiteSpace, truncateDataUrl } from '@isomorphic/stringUtils';
import { yamlEscapeKeyIfNeeded, yamlEscapeValueIfNeeded } from '@isomorphic/yaml';
+import { distillAriaSnapshot } from './ariaSnapshotDistiller';
import { computeBox, getElementComputedStyle, isElementVisible } from './domUtils';
import * as roleUtils from './roleUtils';
export type AriaSnapshot = {
root: aria.AriaNode;
- elements: Map<string, Element>;
+ info: Map<string, { element: Element, nameFromContentRefs: string[] }>;
refs: Map<Element, string>;
iframeRefs: string[];
};
@@ -84,10 +85,12 @@ function toInternalOptions(options: AriaTreeOptions): InternalOptions {
export function generateAriaTree(rootElement: Element, publicOptions: AriaTreeOptions): AriaSnapshot {
const options = toInternalOptions(publicOptions);
const visited = new Set<Node>();
+ // For each node, the elements that contributed to its accessible name.
+ const nameSourceElements = new Map<aria.AriaNode, Set<Element> | undefined>();
const snapshot: AriaSnapshot = {
root: { role: 'fragment', name: '', children: [], props: {}, box: computeBox(rootElement), receivesPointerEvents: true },
- elements: new Map<string, Element>(),
+ info: new Map<string, { element: Element, nameFromContentRefs: string[] }>(),
refs: new Map<Element, string>(),
iframeRefs: [],
};
@@ -135,10 +138,12 @@ export function generateAriaTree(rootElement: Element, publicOptions: AriaTreeOp
}
}
- const childAriaNode = visible ? toAriaNode(element, options) : null;
+ const childAriaNode = visible ? toAriaNode(element, options, nameSourceElements) : null;
+ let elementInfo: { element: Element, nameFromContentRefs: string[] } | undefined;
if (childAriaNode) {
if (childAriaNode.ref) {
- snapshot.elements.set(childAriaNode.ref, element);
+ elementInfo = { element, nameFromContentRefs: [] };
+ snapshot.info.set(childAriaNode.ref, elementInfo);
snapshot.refs.set(element, childAriaNode.ref);
if (childAriaNode.role === 'iframe')
snapshot.iframeRefs.push(childAriaNode.ref);
@@ -146,6 +151,16 @@ export function generateAriaTree(rootElement: Element, publicOptions: AriaTreeOp
ariaNode.children.push(childAriaNode);
}
processElement(childAriaNode || ariaNode, element, ariaChildren, visible);
+
+ // Now that the subtree is processed, every descendant that contributed to this node's
+ // accessible name has its ref assigned, so we can resolve those refs as the name's origins.
+ if (elementInfo) {
+ for (const contributor of nameSourceElements.get(childAriaNode!) || []) {
+ const ref = snapshot.refs.get(contributor);
+ if (ref && ref !== childAriaNode!.ref)
+ elementInfo.nameFromContentRefs.push(ref);
+ }
+ }
};
function processElement(ariaNode: aria.AriaNode, element: Element, ariaChildren: Element[], parentElementVisible: boolean) {
@@ -200,8 +215,7 @@ export function generateAriaTree(rootElement: Element, publicOptions: AriaTreeOp
roleUtils.endAriaCaches();
}
- normalizeStringChildren(snapshot.root);
- normalizeGenericRoles(snapshot.root);
+ distillAriaSnapshot(snapshot, publicOptions);
return snapshot;
}
@@ -220,8 +234,8 @@ function computeAriaRef(ariaNode: aria.AriaNode, options: InternalOptions) {
ariaNode.ref = ariaRef.ref;
}
-function toAriaNode(element: Element, options: InternalOptions): aria.AriaNode | null {
- const active = element.ownerDocument.activeElement === element;
+function toAriaNode(element: Element, options: InternalOptions, nameSourceElements: Map<aria.AriaNode, Set<Element> | undefined>): aria.AriaNode | null {
+ const active = element.ownerDocument.activeElement === element && element.ownerDocument.hasFocus();
if (element.nodeName === 'IFRAME') {
const ariaNode: aria.AriaNode = {
role: 'iframe',
@@ -242,7 +256,7 @@ function toAriaNode(element: Element, options: InternalOptions): aria.AriaNode |
if (!role || role === 'presentation' || role === 'none')
return null;
- const name = normalizeWhiteSpace(roleUtils.getElementAccessibleName(element, false) || '');
+ const name = roleUtils.getElementAccessibleName(element, false);
const receivesPointerEvents = roleUtils.receivesPointerEvents(element);
const box = computeBox(element);
@@ -251,7 +265,7 @@ function toAriaNode(element: Element, options: InternalOptions): aria.AriaNode |
const result: aria.AriaNode = {
role,
- name,
+ name: normalizeWhiteSpace(name.text),
children: [],
props: {},
box,
@@ -259,6 +273,7 @@ function toAriaNode(element: Element, options: InternalOptions): aria.AriaNode |
active
};
setAriaNodeElement(result, element);
+ nameSourceElements.set(result, name.elements);
computeAriaRef(result, options);
if (roleUtils.kAriaCheckedRoles.includes(role))
@@ -292,59 +307,6 @@ function toAriaNode(element: Element, options: InternalOptions): aria.AriaNode |
return result;
}
-function normalizeGenericRoles(node: aria.AriaNode) {
- const normalizeChildren = (node: aria.AriaNode) => {
- const result: (aria.AriaNode | string)[] = [];
- for (const child of node.children || []) {
- if (typeof child === 'string') {
- result.push(child);
- continue;
- }
- const normalized = normalizeChildren(child);
- result.push(...normalized);
- }
-
- // Only remove generic that encloses one element, logical grouping still makes sense, even if it is not ref-able.
- const removeSelf = node.role === 'generic' && !node.name && result.length <= 1 && result.every(c => typeof c !== 'string' && !!c.ref);
- if (removeSelf)
- return result;
- node.children = result;
- return [node];
- };
-
- normalizeChildren(node);
-}
-
-function normalizeStringChildren(rootA11yNode: aria.AriaNode) {
- const flushChildren = (buffer: string[], normalizedChildren: (aria.AriaNode | string)[]) => {
- if (!buffer.length)
- return;
- const text = normalizeWhiteSpace(buffer.join(''));
- if (text)
- normalizedChildren.push(text);
- buffer.length = 0;
- };
-
- const visit = (ariaNode: aria.AriaNode) => {
- const normalizedChildren: (aria.AriaNode | string)[] = [];
- const buffer: string[] = [];
- for (const child of ariaNode.children || []) {
- if (typeof child === 'string') {
- buffer.push(child);
- } else {
- flushChildren(buffer, normalizedChildren);
- visit(child);
- normalizedChildren.push(child);
- }
- }
- flushChildren(buffer, normalizedChildren);
- ariaNode.children = normalizedChildren.length ? normalizedChildren : [];
- if (ariaNode.children.length === 1 && ariaNode.children[0] === ariaNode.name)
- ariaNode.children = [];
- };
- visit(rootA11yNode);
-}
-
function matchesStringOrRegex(text: string, template: aria.AriaRegex | string | undefined): boolean {
if (!template)
return true;
@@ -570,8 +532,8 @@ export function renderAriaTree(ariaSnapshot: AriaSnapshot, publicOptions: AriaTr
return key;
};
- const getSingleInlinedTextChild = (ariaNode: aria.AriaNode | undefined): string | undefined => {
- return ariaNode?.children.length === 1 && typeof ariaNode.children[0] === 'string' && !Object.keys(ariaNode.props).length ? ariaNode.children[0] : undefined;
+ const getSingleTextChild = (ariaNode: aria.AriaNode): string | undefined => {
+ return ariaNode.children.length === 1 && typeof ariaNode.children[0] === 'string' && !Object.keys(ariaNode.props).length ? ariaNode.children[0] : undefined;
};
const visit = (ariaNode: aria.AriaNode, depth: number, renderCursorPointer: boolean) => {
@@ -582,18 +544,18 @@ export function renderAriaTree(ariaSnapshot: AriaSnapshot, publicOptions: AriaTr
iframeDepths[ariaNode.ref] = depth;
const escapedKey = indent(depth) + '- ' + yamlEscapeKeyIfNeeded(createKey(ariaNode, renderCursorPointer));
- const singleInlinedTextChild = getSingleInlinedTextChild(ariaNode);
+ const singleTextChild = getSingleTextChild(ariaNode);
const isAtDepthLimit = !!publicOptions.depth && depth === publicOptions.depth;
- const hasNoChildren = !singleInlinedTextChild && (!ariaNode.children.length || isAtDepthLimit);
+ const hasNoChildren = !singleTextChild && (!ariaNode.children.length || isAtDepthLimit);
if (hasNoChildren && !Object.keys(ariaNode.props).length) {
// Leaf node without children.
lines.push(escapedKey);
- } else if (singleInlinedTextChild !== undefined) {
+ } else if (singleTextChild !== undefined) {
// Leaf node with just some text inside.
- const shouldInclude = includeText(ariaNode, singleInlinedTextChild);
+ const shouldInclude = includeText(ariaNode, singleTextChild);
if (shouldInclude)
- lines.push(escapedKey + ': ' + yamlEscapeValueIfNeeded(renderString(singleInlinedTextChild)));
+ lines.push(escapedKey + ': ' + yamlEscapeValueIfNeeded(renderString(singleTextChild)));
else
lines.push(escapedKey);
} else {
diff --git a/packages/injected/src/ariaSnapshotDistiller.ts b/packages/injected/src/ariaSnapshotDistiller.ts
new file mode 100644
index 0000000000..3481b06b92
--- /dev/null
+++ b/packages/injected/src/ariaSnapshotDistiller.ts
@@ -0,0 +1,248 @@
+/**
+ * Copyright (c) Microsoft Corporation.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { normalizeWhiteSpace } from '@isomorphic/stringUtils';
+
+import type * as aria from '@isomorphic/ariaSnapshot';
+import type { AriaSnapshot, AriaTreeOptions } from './ariaSnapshot';
+
+// Distillation makes the snapshot less verbose without losing information: after the full tree is
+// built, a single traversal applies the chained plugins below, babel-style. Each plugin is a
+// visitor: `enter` runs pre-order, `exit` runs post-order after the children were traversed - and
+// possibly removed, unwrapped or inlined. Either hook can detach the node by returning 'remove'
+// (from `enter`, the subtree is then not traversed and no further hooks run for it), or replace
+// the node with its children by returning 'unwrap' (from `enter`, the hoisted children are
+// re-visited in the node's place; from `exit`, they were already traversed and are spliced in as
+// is). Plugins mutate the tree in place; `snapshot.info` and `snapshot.refs` are left intact, so
+// refs of removed nodes still resolve through the aria-ref selector engine.
+type DistillerContext = {
+ snapshot: AriaSnapshot;
+ // Depth of the current node; children of the root fragment are at depth 0.
+ depth: number;
+ // Render depth limit, plugins should not rely on anything below it being rendered.
+ maxDepth: number | undefined;
+ // The chain of ancestors of the current node, root first. Maintained by the traversal.
+ ancestors: aria.AriaNode[];
+ // Content refs of the entered nodes' accessible names that are not yet represented in the
+ // output - see `removeRedundantNames`.
+ pendingContentRefs: Set<string>;
+};
+
+type DistillerPlugin = {
+ name: string;
+ enter?(node: aria.AriaNode, ctx: DistillerContext): 'remove' | 'unwrap' | void;
+ exit?(node: aria.AriaNode, ctx: DistillerContext): 'remove' | 'unwrap' | void;
+};
+
+export function distillAriaSnapshot(snapshot: AriaSnapshot, options: Pick<AriaTreeOptions, 'mode' | 'depth'>) {
+ runPlugins(snapshot, options.mode === 'ai' ? aiPlugins : normalizePlugins, options);
+}
+
+function runPlugins(snapshot: AriaSnapshot, plugins: DistillerPlugin[], options: Pick<AriaTreeOptions, 'depth'>) {
+ const ctx: DistillerContext = { snapshot, depth: -1, maxDepth: options.depth, ancestors: [], pendingContentRefs: new Set() };
+ const traverse = (node: aria.AriaNode, depth: number) => {
+ const children: (aria.AriaNode | string)[] = [];
+ const visitChild = (child: aria.AriaNode | string) => {
+ if (typeof child === 'string') {
+ children.push(child);
+ return;
+ }
+ ctx.depth = depth + 1;
+ for (const plugin of plugins) {
+ const result = plugin.enter?.(child, ctx);
+ if (result === 'remove')
+ return;
+ if (result === 'unwrap') {
+ child.children.forEach(visitChild);
+ return;
+ }
+ }
+ traverse(child, depth + 1);
+ ctx.depth = depth + 1;
+ for (const plugin of plugins) {
+ const result = plugin.exit?.(child, ctx);
+ if (result === 'remove')
+ return;
+ if (result === 'unwrap') {
+ children.push(...child.children);
+ return;
+ }
+ }
+ children.push(child);
+ };
+ ctx.ancestors.push(node);
+ node.children.forEach(visitChild);
+ ctx.ancestors.pop();
+ node.children = children;
+ };
+ // Hooks run on the root as well, but the root cannot be removed or unwrapped.
+ for (const plugin of plugins)
+ plugin.enter?.(snapshot.root, ctx);
+ traverse(snapshot.root, -1);
+ ctx.depth = -1;
+ for (const plugin of plugins)
+ plugin.exit?.(snapshot.root, ctx);
+}
+
+// A generic node whose only content is text - it carries no structure of its own.
+function isLeafGeneric(node: aria.AriaNode): boolean {
+ return node.role === 'generic' && node.children.every(child => typeof child === 'string');
+}
+
+// The tree builder emits raw text tokens - text nodes, CSS content, block spacing markers - as
+// string children. Coalesce the adjacent ones, normalize whitespace and drop the empties, then
+// drop a lone text child that merely repeats the node's accessible name. Runs on `exit`, so the
+// merge sees the children in their final shape.
+const mergeStringChildren: DistillerPlugin = {
+ name: 'mergeStringChildren',
+ exit(node: aria.AriaNode) {
+ const children: (aria.AriaNode | string)[] = [];
+ const buffer: string[] = [];
+ const flush = () => {
+ if (!buffer.length)
+ return;
+ const text = normalizeWhiteSpace(buffer.join(''));
+ if (text)
+ children.push(text);
+ buffer.length = 0;
+ };
+ for (const child of node.children) {
+ if (typeof child === 'string') {
+ buffer.push(child);
+ } else {
+ flush();
+ children.push(child);
+ }
+ }
+ flush();
+ node.children = children;
+ if (node.children.length === 1 && node.children[0] === node.name)
+ node.children = [];
+ },
+};
+
+// Only unwrap a generic that encloses at most one element, logical grouping still makes sense,
+// even if it is not ref-able. The decision is made on `exit` - whether the node encloses a single
+// ref-bearing child is only known after its own descendants were unwrapped - so nested wrappers
+// collapse bottom-up.
+const unwrapSingleChildGenerics: DistillerPlugin = {
+ name: 'unwrapSingleChildGenerics',
+ exit(node: aria.AriaNode): 'unwrap' | void {
+ if (node.role === 'generic' && !node.name && node.children.length <= 1 && node.children.every(child => typeof child !== 'string' && !!child.ref))
+ return 'unwrap';
+ },
+};
+
+// A decorative image - role `img` with no accessible name and no content - carries no
+// information. The decision is made on `exit` - whether the node has content is only known after
+// `mergeStringChildren` dropped the empty text tokens.
+const removeNamelessImages: DistillerPlugin = {
+ name: 'removeNamelessImages',
+ exit(node: aria.AriaNode): 'remove' | void {
+ if (node.role === 'img' && !node.name && !node.children.length)
+ return 'remove';
+ },
+};
+
+// The node's accessible name is derived from content; when every node that contributed to it is
+// represented in the output anyway, the name would just repeat that content and is dropped.
+// Single-pass bookkeeping over the shared `pendingContentRefs` set: entering a node clears its
+// own ref - it is now represented - except for leaf generics, which only exist to supply text
+// and are dropped by `removeNameRepeatingChild` once a kept name shows it. On exit, either every
+// contributor was cleared and the name goes, or the kept name now represents its contributors,
+// so they are cleared for the benefit of the ancestors. A node removed on enter never clears its
+// ref, and an unwrapped one does - matching what remains in the tree.
+const removeRedundantNames: DistillerPlugin = {
+ name: 'removeRedundantNames',
+ enter(node: aria.AriaNode, ctx: DistillerContext) {
+ if (!node.ref)
+ return;
+ for (const ref of ctx.snapshot.info.get(node.ref)?.nameFromContentRefs || [])
+ ctx.pendingContentRefs.add(ref);
+ const beyondDepth = !!ctx.maxDepth && ctx.depth > ctx.maxDepth;
+ if (!beyondDepth && !isLeafGeneric(node))
+ ctx.pendingContentRefs.delete(node.ref);
+ },
+ exit(node: aria.AriaNode, ctx: DistillerContext) {
+ if (!node.ref)
+ return;
+ const nameFromContentRefs = ctx.snapshot.info.get(node.ref)?.nameFromContentRefs;
+ if (!nameFromContentRefs?.length)
+ return;
+ if (nameFromContentRefs.every(ref => !ctx.pendingContentRefs.has(ref))) {
+ node.name = '';
+ } else {
+ for (const ref of nameFromContentRefs)
+ ctx.pendingContentRefs.delete(ref);
+ }
+ },
+};
+
+// A generic whose whole content is a piece of text - a single text child, or just an accessible
+// name - that repeats the parent's accessible name adds no information, so it removes itself.
+// `inlineTextIntoGeneric` runs first, bubbling text up through nameless wrappers, so by the time
+// a wrapper exits its text faces the real parent - no need to look further up the ancestor chain.
+// Whenever the node is the source of that name, `removeRedundantNames` keeps the name - the node
+// is a leaf generic - so the text is never lost.
+const removeNameRepeatingChild: DistillerPlugin = {
+ name: 'removeNameRepeatingChild',
+ exit(node: aria.AriaNode, ctx: DistillerContext): 'remove' | void {
+ const parent = ctx.ancestors[ctx.ancestors.length - 1];
+ if (!parent?.name || node.role !== 'generic' || node.active || Object.keys(node.props).length)
+ return;
+ const singleTextChild = node.children.length === 1 && typeof node.children[0] === 'string' ? node.children[0] : undefined;
+ const text = node.name ? (node.children.length ? undefined : node.name) : singleTextChild;
+ if (text && text === parent.name)
+ return 'remove';
+ },
+};
+
+// A generic whose only child is a nameless leaf generic inlines that child's text:
+// `generic: - generic: "text"` becomes `generic: "text"`. Runs post-order, so chains collapse
+// bottom-up, and after the other plugins already removed or unwrapped the children.
+const inlineTextIntoGeneric: DistillerPlugin = {
+ name: 'inlineTextIntoGeneric',
+ exit(node: aria.AriaNode) {
+ if (node.role !== 'generic' || Object.keys(node.props).length || node.children.length !== 1)
+ return;
+ const child = node.children[0];
+ if (typeof child === 'string')
+ return;
+ if (child.role !== 'generic' || child.name || child.active || Object.keys(child.props).length)
+ return;
+ if (child.children.length === 1 && typeof child.children[0] === 'string')
+ node.children = [child.children[0]];
+ },
+};
+
+// Structural normalization applies to all modes - it defines the canonical tree shape.
+const normalizePlugins: DistillerPlugin[] = [
+ mergeStringChildren,
+ unwrapSingleChildGenerics,
+];
+
+// The ai preset compresses the snapshot on top of normalization. It runs as one traversal:
+// `removeRedundantNames` bookkeeping must observe every node the tree retains, including the
+// wrappers that `unwrapSingleChildGenerics` is about to unwrap. On exit, text is first inlined
+// into the node, so that `removeNameRepeatingChild` faces the real parent when it compares.
+const aiPlugins: DistillerPlugin[] = [
+ mergeStringChildren,
+ removeNamelessImages,
+ removeRedundantNames,
+ inlineTextIntoGeneric,
+ removeNameRepeatingChild,
+ unwrapSingleChildGenerics,
+];
diff --git a/packages/injected/src/injectedScript.ts b/packages/injected/src/injectedScript.ts
index 2c816c12a1..cddf13cfeb 100644
--- a/packages/injected/src/injectedScript.ts
+++ b/packages/injected/src/injectedScript.ts
@@ -25,7 +25,7 @@ import { beginDOMCaches, enclosingShadowRootOrDocument, endDOMCaches, isElementV
import { Highlight } from './highlight';
import { kLayoutSelectorNames, layoutSelectorScore } from './layoutSelectorUtils';
import { createRoleEngine } from './roleSelectorEngine';
-import { beginAriaCaches, endAriaCaches, getAriaDisabled, getAriaRole, getCheckedAllowMixed, getCheckedWithoutMixed, getElementAccessibleDescription, getElementAccessibleErrorMessage, getElementAccessibleName, getReadonly } from './roleUtils';
+import { beginAriaCaches, endAriaCaches, getAriaDisabled, getAriaRole, getCheckedAllowMixed, getCheckedWithoutMixed, getElementAccessibleDescription, getElementAccessibleErrorMessage, getElementAccessibleNameText, getReadonly } from './roleUtils';
import { SelectorEvaluatorImpl, sortInDOMOrder } from './selectorEvaluator';
import { generateSelector } from './selectorGenerator';
import { elementMatchesText, elementText, getElementLabels } from './selectorUtils';
@@ -113,8 +113,8 @@ export class InjectedScript {
cacheNormalizedWhitespaces,
elementText,
getAriaRole,
+ getElementAccessibleNameText,
getElementAccessibleDescription,
- getElementAccessibleName,
isElementVisible,
isInsideScope,
normalizeWhiteSpace,
@@ -720,8 +720,8 @@ export class InjectedScript {
_createAriaRefEngine() {
const queryAll = (root: SelectorRoot, selector: string): Element[] => {
- const result = this._lastAriaSnapshotForQuery?.elements?.get(selector);
- return result && result.isConnected ? [result] : [];
+ const result = this._lastAriaSnapshotForQuery?.info?.get(selector);
+ return result && result.element.isConnected ? [result.element] : [];
};
return { queryAll };
}
@@ -1657,7 +1657,7 @@ export class InjectedScript {
} else if (expression === 'to.have.text') {
received = options.useInnerText ? (element as HTMLElement).innerText : elementText(new Map(), element).full;
} else if (expression === 'to.have.accessible.name') {
- received = getElementAccessibleName(element, false /* includeHidden */);
+ received = getElementAccessibleNameText(element, false /* includeHidden */);
} else if (expression === 'to.have.accessible.description') {
received = getElementAccessibleDescription(element, false /* includeHidden */);
} else if (expression === 'to.have.accessible.error.message') {
diff --git a/packages/injected/src/roleSelectorEngine.ts b/packages/injected/src/roleSelectorEngine.ts
index 2691ff32bb..7d18a013d7 100644
--- a/packages/injected/src/roleSelectorEngine.ts
+++ b/packages/injected/src/roleSelectorEngine.ts
@@ -17,7 +17,7 @@
import { parseAttributeSelector } from '@isomorphic/selectorParser';
import { normalizeWhiteSpace } from '@isomorphic/stringUtils';
-import { beginAriaCaches, endAriaCaches, getAriaBusy, getAriaChecked, getAriaDisabled, getAriaExpanded, getAriaLevel, getAriaPressed, getAriaRole, getAriaSelected, getElementAccessibleDescription, getElementAccessibleName, isElementHiddenForAria, kAriaCheckedRoles, kAriaExpandedRoles, kAriaLevelRoles, kAriaPressedRoles, kAriaSelectedRoles } from './roleUtils';
+import { beginAriaCaches, endAriaCaches, getAriaBusy, getAriaChecked, getAriaDisabled, getAriaExpanded, getAriaLevel, getAriaPressed, getAriaRole, getAriaSelected, getElementAccessibleDescription, getElementAccessibleNameText, isElementHiddenForAria, kAriaCheckedRoles, kAriaExpandedRoles, kAriaLevelRoles, kAriaPressedRoles, kAriaSelectedRoles } from './roleUtils';
import { matchesAttributePart } from './selectorUtils';
import type { AttributeSelectorOperator, AttributeSelectorPart } from '@isomorphic/selectorParser';
@@ -173,7 +173,7 @@ function queryRole(scope: SelectorRoot, options: RoleEngineOptions, internal: bo
}
if (options.name !== undefined) {
// Always normalize whitespace in the accessible name.
- const accessibleName = normalizeWhiteSpace(getElementAccessibleName(element, !!options.includeHidden));
+ const accessibleName = normalizeWhiteSpace(getElementAccessibleNameText(element, !!options.includeHidden));
if (typeof options.name === 'string')
options.name = normalizeWhiteSpace(options.name);
// internal:role assumes that [name="foo"i] also means substring.
diff --git a/packages/injected/src/roleUtils.ts b/packages/injected/src/roleUtils.ts
index f18665902a..b167f354a6 100644
--- a/packages/injected/src/roleUtils.ts
+++ b/packages/injected/src/roleUtils.ts
@@ -501,32 +501,49 @@ function allowsNameFromContent(role: string, targetDescendant: boolean) {
return alwaysAllowsNameFromContent || descendantAllowsNameFromContent;
}
-export function getElementAccessibleName(element: Element, includeHidden: boolean): string {
+function computeAccessibleNameComposite(element: Element, includeHidden: boolean, collectElements: boolean): CompositeString {
+ // https://w3c.github.io/accname/#computation-steps
+
+ // step 1.
+ // https://w3c.github.io/aria/#namefromprohibited
+ const elementProhibitsNaming = ['caption', 'code', 'definition', 'deletion', 'emphasis', 'generic', 'insertion', 'mark', 'paragraph', 'presentation', 'strong', 'subscript', 'suggestion', 'superscript', 'term', 'time'].includes(getAriaRole(element) || '');
+ if (elementProhibitsNaming)
+ return emptyCompositeString();
+
+ // step 2.
+ const result = getTextAlternativeInternal(element, {
+ includeHidden,
+ collectElements,
+ visitedElements: new Set(),
+ embeddedInTargetElement: 'self',
+ });
+ return { text: asFlatString(result.text), elements: result.elements };
+}
+
+export function getElementAccessibleName(element: Element, includeHidden: boolean): CompositeString {
const cache = (includeHidden ? cacheAccessibleNameHidden : cacheAccessibleName);
let accessibleName = cache?.get(element);
-
if (accessibleName === undefined) {
- // https://w3c.github.io/accname/#computation-steps
- accessibleName = '';
-
- // step 1.
- // https://w3c.github.io/aria/#namefromprohibited
- const elementProhibitsNaming = ['caption', 'code', 'definition', 'deletion', 'emphasis', 'generic', 'insertion', 'mark', 'paragraph', 'presentation', 'strong', 'subscript', 'suggestion', 'superscript', 'term', 'time'].includes(getAriaRole(element) || '');
-
- if (!elementProhibitsNaming) {
- // step 2.
- accessibleName = asFlatString(getTextAlternativeInternal(element, {
- includeHidden,
- visitedElements: new Set(),
- embeddedInTargetElement: 'self',
- }));
- }
-
+ accessibleName = computeAccessibleNameComposite(element, includeHidden, true /* collectElements */);
cache?.set(element, accessibleName);
}
return accessibleName;
}
+export function getElementAccessibleNameText(element: Element, includeHidden: boolean): string {
+ // Reuse the element-collecting composite if it happens to be cached, otherwise compute text only.
+ const composite = (includeHidden ? cacheAccessibleNameHidden : cacheAccessibleName)?.get(element);
+ if (composite !== undefined)
+ return composite.text;
+ const cache = (includeHidden ? cacheAccessibleNameTextHidden : cacheAccessibleNameText);
+ let text = cache?.get(element);
+ if (text === undefined) {
+ text = computeAccessibleNameComposite(element, includeHidden, false /* collectElements */).text;
+ cache?.set(element, text);
+ }
+ return text;
+}
+
export function getElementAccessibleDescription(element: Element, includeHidden: boolean): string {
const cache = (includeHidden ? cacheAccessibleDescriptionHidden : cacheAccessibleDescription);
let accessibleDescription = cache?.get(element);
@@ -543,7 +560,7 @@ export function getElementAccessibleDescription(element: Element, includeHidden:
includeHidden,
visitedElements: new Set(),
embeddedInDescribedBy: { element: ref, hidden: isElementHiddenForAria(ref) },
- })).join(' '));
+ }).text).join(' '));
} else if (element.hasAttribute('aria-description')) {
// precedence 2
accessibleDescription = asFlatString(element.getAttribute('aria-description') || '');
@@ -619,7 +636,7 @@ export function getElementAccessibleErrorMessage(element: Element): string {
getTextAlternativeInternal(errorMessage, {
visitedElements: new Set(),
embeddedInDescribedBy: { element: errorMessage, hidden: isElementHiddenForAria(errorMessage) },
- })
+ }).text
));
accessibleErrorMessage = parts.join(' ').trim();
}
@@ -630,6 +647,7 @@ export function getElementAccessibleErrorMessage(element: Element): string {
type AccessibleNameOptions = {
visitedElements: Set<Element>,
+ collectElements?: boolean,
includeHidden?: boolean,
embeddedInDescribedBy?: { element: Element, hidden: boolean },
embeddedInLabelledBy?: { element: Element, hidden: boolean },
@@ -638,9 +656,9 @@ type AccessibleNameOptions = {
embeddedInTargetElement?: 'self' | 'descendant',
};
-function getTextAlternativeInternal(element: Element, options: AccessibleNameOptions): string {
+function getTextAlternativeInternal(element: Element, options: AccessibleNameOptions): CompositeString {
if (options.visitedElements.has(element))
- return '';
+ return emptyCompositeString();
const childOptions: AccessibleNameOptions = {
...options,
@@ -659,7 +677,7 @@ function getTextAlternativeInternal(element: Element, options: AccessibleNameOpt
if (isElementIgnoredForAria(element) ||
(!isEmbeddedInHiddenReferenceTraversal && isElementHiddenForAria(element))) {
options.visitedElements.add(element);
- return '';
+ return emptyCompositeString();
}
}
@@ -670,15 +688,15 @@ function getTextAlternativeInternal(element: Element, options: AccessibleNameOpt
// at least one valid IDREF, and the current node is not already part of an ongoing
// aria-labelledby or aria-describedby traversal, process its IDREFs in the order they occur...
if (!options.embeddedInLabelledBy) {
- const accessibleName = (labelledBy || []).map(ref => getTextAlternativeInternal(ref, {
+ const accessibleName = joinCompositeString((labelledBy || []).map(ref => getTextAlternativeInternal(ref, {
...options,
embeddedInLabelledBy: { element: ref, hidden: isElementHiddenForAria(ref) },
embeddedInDescribedBy: undefined,
embeddedInTargetElement: undefined,
embeddedInLabel: undefined,
embeddedInNativeTextAlternative: undefined,
- })).join(' ');
- if (accessibleName)
+ })), ' ', options.collectElements);
+ if (accessibleName.text)
return accessibleName;
}
@@ -700,8 +718,8 @@ function getTextAlternativeInternal(element: Element, options: AccessibleNameOpt
if (role === 'textbox') {
options.visitedElements.add(element);
if (tagName === 'INPUT' || tagName === 'TEXTAREA')
- return (element as HTMLInputElement | HTMLTextAreaElement).value;
- return element.textContent || '';
+ return compositeString((element as HTMLInputElement | HTMLTextAreaElement).value, element, options.collectElements);
+ return compositeString(element.textContent, element, options.collectElements);
}
if (['combobox', 'listbox'].includes(role)) {
options.visitedElements.add(element);
@@ -718,22 +736,22 @@ function getTextAlternativeInternal(element: Element, options: AccessibleNameOpt
// SPEC DIFFERENCE:
// This fallback is not explicitly mentioned in the spec, but all browsers and
// wpt test name_heading-combobox-focusable-alternative-manual.html do this.
- return (element as HTMLInputElement).value;
+ return compositeString((element as HTMLInputElement).value, element, options.collectElements);
}
- return selectedOptions.map(option => getTextAlternativeInternal(option, childOptions)).join(' ');
+ return joinCompositeString(selectedOptions.map(option => getTextAlternativeInternal(option, childOptions)), ' ', options.collectElements);
}
if (['progressbar', 'scrollbar', 'slider', 'spinbutton', 'meter'].includes(role)) {
options.visitedElements.add(element);
if (element.hasAttribute('aria-valuetext'))
- return element.getAttribute('aria-valuetext') || '';
+ return compositeString(element.getAttribute('aria-valuetext'), element, options.collectElements);
if (element.hasAttribute('aria-valuenow'))
- return element.getAttribute('aria-valuenow') || '';
- return element.getAttribute('value') || '';
+ return compositeString(element.getAttribute('aria-valuenow'), element, options.collectElements);
+ return compositeString(element.getAttribute('value'), element, options.collectElements);
}
if (['menu'].includes(role)) {
// https://github.com/w3c/accname/issues/67#issuecomment-553196887
options.visitedElements.add(element);
- return '';
+ return emptyCompositeString();
}
}
}
@@ -742,7 +760,7 @@ function getTextAlternativeInternal(element: Element, options: AccessibleNameOpt
const ariaLabel = element.getAttribute('aria-label') || '';
if (trimFlatString(ariaLabel)) {
options.visitedElements.add(element);
- return ariaLabel;
+ return compositeString(ariaLabel, element, options.collectElements);
}
// step 2e.
@@ -757,13 +775,13 @@ function getTextAlternativeInternal(element: Element, options: AccessibleNameOpt
options.visitedElements.add(element);
const value = (element as HTMLInputElement).value || '';
if (trimFlatString(value))
- return value;
+ return compositeString(value, element, options.collectElements);
if ((element as HTMLInputElement).type === 'submit')
- return 'Submit';
+ return compositeString('Submit', element, options.collectElements);
if ((element as HTMLInputElement).type === 'reset')
- return 'Reset';
+ return compositeString('Reset', element, options.collectElements);
const title = element.getAttribute('title') || '';
- return title;
+ return compositeString(title, element, options.collectElements);
}
// SPEC DIFFERENCE.
@@ -775,7 +793,7 @@ function getTextAlternativeInternal(element: Element, options: AccessibleNameOpt
const labels = (element as HTMLInputElement).labels || [];
if (labels.length && !options.embeddedInLabelledBy)
return getAccessibleNameFromAssociatedLabels(labels, options);
- return 'Choose File';
+ return compositeString('Choose File', element, options.collectElements);
}
// https://w3c.github.io/html-aam/#input-type-image-accessible-name-computation
@@ -789,13 +807,13 @@ function getTextAlternativeInternal(element: Element, options: AccessibleNameOpt
return getAccessibleNameFromAssociatedLabels(labels, options);
const alt = element.getAttribute('alt') || '';
if (trimFlatString(alt))
- return alt;
+ return compositeString(alt, element, options.collectElements);
const title = element.getAttribute('title') || '';
if (trimFlatString(title))
- return title;
+ return compositeString(title, element, options.collectElements);
// SPEC DIFFERENCE.
// Spec says return localized "Submit Query", but browsers and axe-core insist on "Submit".
- return 'Submit';
+ return compositeString('Submit', element, options.collectElements);
}
// https://w3c.github.io/html-aam/#button-element-accessible-name-computation
@@ -813,7 +831,7 @@ function getTextAlternativeInternal(element: Element, options: AccessibleNameOpt
const labels = (element as HTMLOutputElement).labels || [];
if (labels.length)
return getAccessibleNameFromAssociatedLabels(labels, options);
- return element.getAttribute('title') || '';
+ return compositeString(element.getAttribute('title') || '', element, options.collectElements);
}
// https://w3c.github.io/html-aam/#input-type-text-input-type-password-input-type-number-input-type-search-input-type-tel-input-type-email-input-type-url-and-textarea-element-accessible-name-computation
@@ -831,8 +849,8 @@ function getTextAlternativeInternal(element: Element, options: AccessibleNameOpt
const placeholder = element.getAttribute('placeholder') || '';
const title = element.getAttribute('title') || '';
if (!usePlaceholder || title)
- return title;
- return placeholder;
+ return compositeString(title, element, options.collectElements);
+ return compositeString(placeholder, element, options.collectElements);
}
// https://w3c.github.io/html-aam/#fieldset-and-legend-elements
@@ -847,7 +865,7 @@ function getTextAlternativeInternal(element: Element, options: AccessibleNameOpt
}
}
const title = element.getAttribute('title') || '';
- return title;
+ return compositeString(title, element, options.collectElements);
}
// https://w3c.github.io/html-aam/#figure-and-figcaption-elements
@@ -862,7 +880,7 @@ function getTextAlternativeInternal(element: Element, options: AccessibleNameOpt
}
}
const title = element.getAttribute('title') || '';
- return title;
+ return compositeString(title, element, options.collectElements);
}
// https://w3c.github.io/html-aam/#img-element
@@ -873,9 +891,9 @@ function getTextAlternativeInternal(element: Element, options: AccessibleNameOpt
options.visitedElements.add(element);
const alt = element.getAttribute('alt') || '';
if (trimFlatString(alt))
- return alt;
+ return compositeString(alt, element, options.collectElements);
const title = element.getAttribute('title') || '';
- return title;
+ return compositeString(title, element, options.collectElements);
}
// https://w3c.github.io/html-aam/#table-element
@@ -893,7 +911,7 @@ function getTextAlternativeInternal(element: Element, options: AccessibleNameOpt
// Spec does not say a word about <table summary="...">, but all browsers actually support it.
const summary = element.getAttribute('summary') || '';
if (summary)
- return summary;
+ return compositeString(summary, element, options.collectElements);
// SPEC DIFFERENCE.
// Spec says "if the table element has a title attribute, then use that attribute".
// We ignore title to pass "name_from_content-manual.html".
@@ -904,9 +922,9 @@ function getTextAlternativeInternal(element: Element, options: AccessibleNameOpt
options.visitedElements.add(element);
const alt = element.getAttribute('alt') || '';
if (trimFlatString(alt))
- return alt;
+ return compositeString(alt, element, options.collectElements);
const title = element.getAttribute('title') || '';
- return title;
+ return compositeString(title, element, options.collectElements);
}
// https://www.w3.org/TR/svg-aam-1.0/#mapping_additional_nd
@@ -925,7 +943,7 @@ function getTextAlternativeInternal(element: Element, options: AccessibleNameOpt
const title = element.getAttribute('xlink:title') || '';
if (trimFlatString(title)) {
options.visitedElements.add(element);
- return title;
+ return compositeString(title, element, options.collectElements);
}
}
}
@@ -943,9 +961,12 @@ function getTextAlternativeInternal(element: Element, options: AccessibleNameOpt
// Spec says "Return the accumulated text if it is not the empty string". However, that is not really
// compatible with the real browser behavior and wpt tests, where an element with empty contents will fallback to the title.
// So we follow the spec everywhere except for the target element itself. This can probably be improved.
- const maybeTrimmedAccessibleName = options.embeddedInTargetElement === 'self' ? trimFlatString(accessibleName) : accessibleName;
- if (maybeTrimmedAccessibleName)
+ const maybeTrimmedAccessibleName = options.embeddedInTargetElement === 'self' ? trimFlatString(accessibleName.text) : accessibleName.text;
+ if (maybeTrimmedAccessibleName) {
+ // This element owns the accumulated content - record it alongside the descendants it was computed from.
+ accessibleName.elements?.add(element);
return accessibleName;
+ }
}
// step 2i.
@@ -953,21 +974,25 @@ function getTextAlternativeInternal(element: Element, options: AccessibleNameOpt
options.visitedElements.add(element);
const title = element.getAttribute('title') || '';
if (trimFlatString(title))
- return title;
+ return compositeString(title, element, options.collectElements);
}
options.visitedElements.add(element);
- return '';
+ return emptyCompositeString();
}
-function innerAccumulatedElementText(element: Element, options: AccessibleNameOptions): string {
+function innerAccumulatedElementText(element: Element, options: AccessibleNameOptions): CompositeString {
const tokens: string[] = [];
+ const elements = options.collectElements ? new Set<Element>() : undefined;
const visit = (node: Node, skipSlotted: boolean) => {
if (skipSlotted && (node as Element | Text).assignedSlot)
return;
if (node.nodeType === 1 /* Node.ELEMENT_NODE */) {
const display = getElementComputedStyle(node as Element)?.display || 'inline';
- let token = getTextAlternativeInternal(node as Element, options);
+ const childComposite = getTextAlternativeInternal(node as Element, options);
+ let token = childComposite.text;
+ for (const contributor of childComposite.elements || [])
+ elements?.add(contributor);
// SPEC DIFFERENCE.
// Spec says "append the result to the accumulated text", assuming "with space".
// However, multiple tests insist that inline elements do not add a space.
@@ -1005,7 +1030,7 @@ function innerAccumulatedElementText(element: Element, options: AccessibleNameOp
}
}
tokens.push(getCSSContent(element, '::after') || '');
- return tokens.join('');
+ return { text: tokens.join(''), elements };
}
export const kAriaSelectedRoles = ['gridcell', 'option', 'row', 'tab', 'rowheader', 'columnheader', 'treeitem'];
@@ -1160,15 +1185,15 @@ export function getAriaBusy(element: Element): boolean {
return getAriaBoolean(element.getAttribute('aria-busy')) === true;
}
-function getAccessibleNameFromAssociatedLabels(labels: Iterable<HTMLLabelElement>, options: AccessibleNameOptions) {
- return [...labels].map(label => getTextAlternativeInternal(label, {
+function getAccessibleNameFromAssociatedLabels(labels: Iterable<HTMLLabelElement>, options: AccessibleNameOptions): CompositeString {
+ return joinCompositeString([...labels].map(label => getTextAlternativeInternal(label, {
...options,
embeddedInLabel: { element: label, hidden: isElementHiddenForAria(label) },
embeddedInNativeTextAlternative: undefined,
embeddedInLabelledBy: undefined,
embeddedInDescribedBy: undefined,
embeddedInTargetElement: undefined,
- })).filter(accessibleName => !!accessibleName).join(' ');
+ })).filter(accessibleName => !!accessibleName.text), ' ', options.collectElements);
}
export function receivesPointerEvents(element: Element): boolean {
@@ -1205,8 +1230,10 @@ export function receivesPointerEvents(element: Element): boolean {
return result;
}
-let cacheAccessibleName: Map<Element, string> | undefined;
-let cacheAccessibleNameHidden: Map<Element, string> | undefined;
+let cacheAccessibleName: Map<Element, CompositeString> | undefined;
+let cacheAccessibleNameHidden: Map<Element, CompositeString> | undefined;
+let cacheAccessibleNameText: Map<Element, string> | undefined;
+let cacheAccessibleNameTextHidden: Map<Element, string> | undefined;
let cacheAccessibleDescription: Map<Element, string> | undefined;
let cacheAccessibleDescriptionHidden: Map<Element, string> | undefined;
let cacheAccessibleErrorMessage: Map<Element, string> | undefined;
@@ -1222,6 +1249,8 @@ export function beginAriaCaches() {
++cachesCounter;
cacheAccessibleName ??= new Map();
cacheAccessibleNameHidden ??= new Map();
+ cacheAccessibleNameText ??= new Map();
+ cacheAccessibleNameTextHidden ??= new Map();
cacheAccessibleDescription ??= new Map();
cacheAccessibleDescriptionHidden ??= new Map();
cacheAccessibleErrorMessage ??= new Map();
@@ -1236,6 +1265,8 @@ export function endAriaCaches() {
if (!--cachesCounter) {
cacheAccessibleName = undefined;
cacheAccessibleNameHidden = undefined;
+ cacheAccessibleNameText = undefined;
+ cacheAccessibleNameTextHidden = undefined;
cacheAccessibleDescription = undefined;
cacheAccessibleDescriptionHidden = undefined;
cacheAccessibleErrorMessage = undefined;
@@ -1258,3 +1289,29 @@ const inputTypeToRole: Record<string, AriaRole> = {
'reset': 'button',
'submit': 'button',
};
+
+type CompositeString = {
+ text: string,
+ elements?: Set<Element>,
+};
+
+function emptyCompositeString(): CompositeString {
+ return { text: '' };
+}
+
+function compositeString(text: string | null, element: Element, collectElements: boolean | undefined): CompositeString {
+ const elements = text && collectElements ? new Set([element]) : undefined;
+ return { text: text || '', elements };
+}
+
+function joinCompositeString(parts: CompositeString[], separator: string, collectElements: boolean | undefined): CompositeString {
+ let elements: Set<Element> | undefined;
+ if (collectElements) {
+ elements = new Set();
+ for (const part of parts) {
+ for (const element of part.elements || [])
+ elements.add(element);
+ }
+ }
+ return { text: parts.map(part => part.text).join(separator), elements };
+}
diff --git a/packages/injected/src/selectorGenerator.ts b/packages/injected/src/selectorGenerator.ts
index 25de3c184d..3a77c277f4 100644
--- a/packages/injected/src/selectorGenerator.ts
+++ b/packages/injected/src/selectorGenerator.ts
@@ -18,7 +18,7 @@ import { splitTestIdAttributeNames } from '@isomorphic/locatorUtils';
import { escapeForAttributeSelector, escapeForTextSelector, escapeRegExp, quoteCSSAttributeValue } from '@isomorphic/stringUtils';
import { beginDOMCaches, closestCrossShadow, endDOMCaches, isElementVisible, isInsideScope, parentElementOrShadowHost } from './domUtils';
-import { beginAriaCaches, endAriaCaches, getAriaRole, getElementAccessibleDescription, getElementAccessibleName } from './roleUtils';
+import { beginAriaCaches, endAriaCaches, getAriaRole, getElementAccessibleDescription, getElementAccessibleNameText } from './roleUtils';
import { elementText, getElementLabels } from './selectorUtils';
import type { InjectedScript } from './injectedScript';
@@ -348,7 +348,7 @@ function buildTextCandidates(injectedScript: InjectedScript, element: Element, i
const ariaRole = getAriaRole(element);
if (ariaRole && !['none', 'presentation'].includes(ariaRole)) {
- const ariaName = getElementAccessibleName(element, false);
+ const ariaName = getElementAccessibleNameText(element, false);
// \p{Co} means "Private Use" characters - these are often used for icon fonts and make for bad locators.
if (ariaName && !ariaName.match(/^\p{Co}+$/u)) {
const roleToken = { engine: 'internal:role', selector: `${ariaRole}[name=${escapeForAttributeSelector(ariaName, true)}]`, score: kRoleWithNameScoreExact };
diff --git a/tests/library/role-utils.spec.ts b/tests/library/role-utils.spec.ts
index 7006f4d372..39def083f2 100644
--- a/tests/library/role-utils.spec.ts
+++ b/tests/library/role-utils.spec.ts
@@ -22,7 +22,7 @@ test.skip(({ mode }) => mode !== 'default');
async function getNameAndRole(page: Page, selector: string) {
return await page.$eval(selector, e => {
- const name = (window as any).__injectedScript.utils.getElementAccessibleName(e);
+ const name = (window as any).__injectedScript.utils.getElementAccessibleNameText(e);
const role = (window as any).__injectedScript.utils.getAriaRole(e);
return { name, role };
});
@@ -85,7 +85,7 @@ for (let range = 0; range <= ranges.length; range++) {
if (!element)
throw new Error(`Unable to resolve "${step.selector}"`);
const injected = (window as any).__injectedScript;
- const received = step.property === 'name' ? injected.utils.getElementAccessibleName(element) : injected.utils.getElementAccessibleDescription(element);
+ const received = step.property === 'name' ? injected.utils.getElementAccessibleNameText(element) : injected.utils.getElementAccessibleDescription(element);
result.push({ selector: step.selector, expected: step.value, received });
}
return result;
@@ -140,7 +140,7 @@ test('wpt accname non-manual', async ({ page, asset, server, browserName }) => {
const injected = (window as any).__injectedScript;
const title = element.getAttribute('data-testname');
const expected = element.getAttribute('data-expectedlabel');
- const received = injected.utils.getElementAccessibleName(element);
+ const received = injected.utils.getElementAccessibleNameText(element);
result.push({ title, expected, received });
}
return result;
@@ -201,7 +201,7 @@ test('axe-core accessible-text', async ({ page, asset, server }) => {
const element = injected.querySelector(injected.parseSelector('css=' + selector), document, false);
if (!element)
throw new Error(`Unable to resolve "${selector}"`);
- return injected.utils.getElementAccessibleName(element);
+ return injected.utils.getElementAccessibleNameText(element);
});
}, targets);
expect.soft(received, `checking ${JSON.stringify(testCase)}`).toEqual(expected);
diff --git a/tests/mcp/core.spec.ts b/tests/mcp/core.spec.ts
index 8ef418f3eb..b15209da69 100644
--- a/tests/mcp/core.spec.ts
+++ b/tests/mcp/core.spec.ts
@@ -109,7 +109,7 @@ test('browser_navigate can navigate to file:// URLs allowUnrestrictedFileAccess
arguments: { url },
})).toHaveResponse({
page: expect.stringContaining(`- Page URL: ${url}`),
- snapshot: `- generic [ref=e2]: Test file content`,
+ snapshot: `- generic [active] [ref=e1]: Test file content`,
});
});
diff --git a/tests/mcp/iframes.spec.ts b/tests/mcp/iframes.spec.ts
index bd2bbe46cc..7b2c81869b 100644
--- a/tests/mcp/iframes.spec.ts
+++ b/tests/mcp/iframes.spec.ts
@@ -26,7 +26,7 @@ test('stitched aria frames', async ({ client }) => {
snapshot: expect.stringContaining(`- generic [active] [ref=e1]:
- heading "Hello" [level=1] [ref=e2]
- iframe [ref=e3]:
- - generic [active] [ref=f1e1]:
+ - generic [ref=f1e1]:
- button "World" [ref=f1e2]
- main [ref=f1e3]:
- iframe [ref=f1e4]:
diff --git a/tests/page/page-aria-snapshot-ai.spec.ts b/tests/page/page-aria-snapshot-ai.spec.ts
index c0c562ee46..99abe6743a 100644
--- a/tests/page/page-aria-snapshot-ai.spec.ts
+++ b/tests/page/page-aria-snapshot-ai.spec.ts
@@ -105,13 +105,13 @@ it('should stitch all frame snapshots', async ({ page, server }) => {
expect(snapshot).toContainYaml(`
- generic [active] [ref=e1]:
- iframe [ref=e2]:
- - generic [active] [ref=f1e1]:
+ - generic [ref=f1e1]:
- iframe [ref=f1e2]:
- - generic [ref=f3e2]: Hi, I'm frame
+ - generic [ref=f3e1]: Hi, I'm frame
- iframe [ref=f1e3]:
- - generic [ref=f4e2]: Hi, I'm frame
+ - generic [ref=f4e1]: Hi, I'm frame
- iframe [ref=e3]:
- - generic [ref=f2e2]: Hi, I'm frame
+ - generic [ref=f2e1]: Hi, I'm frame
`);
const href = await page.locator('aria-ref=e1').evaluate(e => e.ownerDocument.defaultView.location.href);
@@ -340,14 +340,161 @@ it('should not nest cursor pointer hints', async ({ page }) => {
`);
const snapshot = await snapshotForAI(page);
+ // The link's name is redundant - "Link with a button" prints as text and "Button" as the button -
+ // so it is dropped even though the node is clickable.
expect(snapshot).toContainYaml(`
- - link \"Link with a button Button\" [ref=e2] [cursor=pointer]:
+ - link [ref=e2] [cursor=pointer]:
- /url: about:blank
- text: Link with a button
- button "Button" [ref=e3]
`);
});
+it('should omit names that just repeat printed descendant nodes', async ({ page }) => {
+ await page.setContent(`
+ <h3><a style="cursor: pointer" href="/issues/1">Clipboard API</a></h3>
+ `);
+
+ const snapshot = await snapshotForAI(page);
+ expect(snapshot).toContainYaml(`
+ - heading [level=3] [ref=e2]:
+ - link "Clipboard API" [ref=e3] [cursor=pointer]:
+ - /url: /issues/1
+ `);
+});
+
+it('should omit redundant name when a contributing wrapper is collapsed', async ({ page }) => {
+ // The flex span contributes to the heading's name, but is then removed from the tree as a
+ // single-child generic wrapper. Its contribution is fully represented by the link, so the
+ // heading's name is still redundant.
+ await page.setContent(`
+ <h3><span style="display: flex"><a style="cursor: pointer" href="/issues/1">Clipboard API</a></span></h3>
+ `);
+
+ const snapshot = await snapshotForAI(page);
+ expect(snapshot).toContainYaml(`
+ - heading [level=3] [ref=e2]:
+ - link "Clipboard API" [ref=e4] [cursor=pointer]:
+ - /url: /issues/1
+ `);
+});
+
+it('should omit redundant name when a contributor is a skipped leaf generic', async ({ page }) => {
+ // The outer span is not collapsed (its child is an element, not text), so it becomes a leaf
+ // generic node that contributes to both names. The link's rendered name covers it, which in turn
+ // makes the heading's name redundant.
+ await page.setContent(`
+ <h3><a style="cursor: pointer" href="/issues/1"><span><span>Clipboard API</span></span></a></h3>
+ `);
+
+ const snapshot = await snapshotForAI(page);
+ expect(snapshot).toContainYaml(`
+ - heading [level=3] [ref=e2]:
+ - link "Clipboard API" [ref=e3] [cursor=pointer]:
+ - /url: /issues/1
+ `);
+});
+
+it('should keep names not derived from printed nodes', async ({ page }) => {
+ await page.setContent(`
+ <h3 aria-label="Clipboard API issue"><a style="cursor: pointer" href="/issues/1">Clipboard API</a></h3>
+ `);
+
+ const snapshot = await snapshotForAI(page);
+ expect(snapshot).toContainYaml(`
+ - heading "Clipboard API issue" [level=3] [ref=e2]:
+ - link "Clipboard API" [ref=e3] [cursor=pointer]:
+ - /url: /issues/1
+ `);
+});
+
+it('should omit images without an accessible name', async ({ page }) => {
+ await page.setContent(`
+ <img src="data:image/gif;base64,R0lGODlhAQABAAAAACwAAAAAAQABAAA=">
+ <img alt="A cat" src="data:image/gif;base64,R0lGODlhAQABAAAAACwAAAAAAQABAAA=">
+ <img style="cursor: pointer" src="data:image/gif;base64,R0lGODlhAQABAAAAACwAAAAAAQABAAA=">
+ `);
+
+ const snapshot = await snapshotForAI(page);
+ // A nameless image carries no information and is omitted, whether or not it is clickable. Only
+ // the named image is kept - and the body wrapper, left with a single child, is unwrapped.
+ expect(snapshot).toContainYaml(`
+ - img "A cat" [ref=e3]
+ `);
+ expect(snapshot).not.toContain('[ref=e2]');
+ expect(snapshot).not.toContain('[ref=e4]');
+});
+
+it('should omit a nameless image nested inside a link', async ({ page }) => {
+ // The decorative image has no name, so it is dropped even though it sits inside a clickable link.
+ await page.setContent(`
+ <a style="cursor: pointer" href="/issue/1">Open issue <img src="data:image/gif;base64,R0lGODlhAQABAAAAACwAAAAAAQABAAA="></a>
+ `);
+
+ const snapshot = await snapshotForAI(page);
+ expect(snapshot).toContainYaml(`
+ - link "Open issue" [ref=e2] [cursor=pointer]:
+ - /url: /issue/1
+ `);
+ expect(snapshot).not.toContain('img');
+});
+
+it('should omit leaf generic whose text is already in an ancestor name', async ({ page }) => {
+ // The inner element is block so it survives as its own generic node (an inline single-text span
+ // would be collapsed into the link instead). It inherits the link's pointer cursor.
+ await page.setContent(`
+ <a style="cursor: pointer" href="/issues/15860"><div>[Feature] a dedicated clipboard API</div></a>
+ `);
+
+ const snapshot = await snapshotForAI(page);
+ // The link keeps its name, and the inner leaf generic that the name was computed from is dropped
+ // because its text is already shown by the name.
+ expect(snapshot).toContainYaml(`
+ - link "[Feature] a dedicated clipboard API" [ref=e2] [cursor=pointer]:
+ - /url: /issues/15860
+ `);
+ expect(snapshot).not.toContain('[ref=e3]');
+});
+
+it('should omit name-repeating generic behind a wrapper', async ({ page }) => {
+ // The leaf generic that repeats the link's name sits inside a nameless wrapper. Its text is
+ // first inlined into the wrapper, which then faces the link and removes itself.
+ await page.setContent(`
+ <a style="cursor: pointer" href="/labels"><span style="display: inline-block"><span style="display: inline-block"><span>P3-collecting-feedback</span></span></span></a>
+ `);
+
+ const snapshot = await snapshotForAI(page);
+ expect(snapshot).toContainYaml(`
+ - link "P3-collecting-feedback" [ref=e2] [cursor=pointer]:
+ - /url: /labels
+ `);
+ expect(snapshot.split('P3-collecting-feedback')).toHaveLength(2);
+});
+
+it('should resolve refs of distilled-away nodes', async ({ page }) => {
+ await page.setContent(`
+ <a style="cursor: pointer" href="/issues/15860"><div>[Feature] a dedicated clipboard API</div></a>
+ `);
+
+ const snapshot = await snapshotForAI(page);
+ // The inner leaf generic is distilled away, but its ref still resolves to the element.
+ expect(snapshot).not.toContain('[ref=e3]');
+ await expect(page.locator('aria-ref=e3')).toHaveText('[Feature] a dedicated clipboard API');
+});
+
+it('should not distill snapshots outside of ai mode', async ({ page }) => {
+ await page.setContent(`
+ <h3><a href="/issues/1">Clipboard API</a></h3>
+ `);
+
+ // The heading name would be dropped as redundant in ai mode; matching mode keeps it.
+ await expect(page.locator('body')).toMatchAriaSnapshot(`
+ - heading "Clipboard API" [level=3]:
+ - link "Clipboard API":
+ - /url: /issues/1
+ `);
+});
+
it('should truncate data url in link', async ({ page }) => {
const base64 = Buffer.from('<p>hello</p>').toString('base64');
await page.setContent(`<a href="data:text/html;base64,${base64}">a link</a>`);
@@ -376,7 +523,7 @@ it('should auto-wait for navigation', async ({ page, server }) => {
snapshotForAI(page)
]);
// The snapshot races the reload, which may re-number the main frame, so accept any ref.
- expect(snapshot).toMatch(/- generic \[ref=(?:f\d+)?e\d+\]: Hi, I'm frame/);
+ expect(snapshot).toMatch(/- generic \[active\] \[ref=(?:f\d+)?e\d+\]: Hi, I'm frame/);
});
it('should auto-wait for blocking CSS', async ({ page, server }) => {
@@ -551,6 +698,37 @@ it('should collapse inline generic nodes', async ({ page }) => {
`);
});
+it('should inline single leaf generic child into parent generic', async ({ page }) => {
+ // The nameless images are distilled away, so each wrapper is left with a single leaf generic
+ // child, whose text is inlined into the wrapper - recursively for the second one.
+ await page.setContent(`
+ <div><img src="data:image/gif;base64,R0lGODlhAQABAAAAACwAAAAAAQABAAA="><div>Status: Open.</div></div>
+ <div><img src="data:image/gif;base64,R0lGODlhAQABAAAAACwAAAAAAQABAAA="><div><img src="data:image/gif;base64,R0lGODlhAQABAAAAACwAAAAAAQABAAA="><div>Nested twice.</div></div></div>
+ `);
+
+ const snapshot = await snapshotForAI(page);
+ expect(snapshot).toContainYaml(`
+ - generic [active] [ref=e1]:
+ - generic [ref=e2]: "Status: Open."
+ - generic [ref=e5]: Nested twice.
+ `);
+});
+
+it('should inline a deeply nested generic', async ({ page }) => {
+ // Every wrapper contains a nameless image (distilled away) plus a single generic child, so the
+ // text bubbles up the whole chain - all the way into the body.
+ const img = `<img src="data:image/gif;base64,R0lGODlhAQABAAAAACwAAAAAAQABAAA=">`;
+ await page.setContent(`
+ <div>${img}<div>${img}<div>${img}<div>${img}<div>Deeply nested.</div></div></div></div></div>
+ `);
+
+ const snapshot = await snapshotForAI(page);
+ expect(snapshot).toContainYaml(`
+ - generic [active] [ref=e1]: Deeply nested.
+ `);
+ expect(snapshot).not.toContain('img');
+});
+
it('should not remove generic nodes with title', async ({ page }) => {
await page.setContent(`<div title="Element title">Element content</div>`);