Playwright is a framework for Web Testing and Automation. It allows testing Chromium, Firefox and WebKit with a single API.
TypeScript automationchromechromiume2e-testingelectronend-to-end-testingfirefoxjavascriptplaywrighttesttest-automationtestingtesting-toolswebwebkit
chore: allow matching aria children strictly (#35481)
Pavel Feldman26fa959a1010
diff --git a/docs/src/aria-snapshots.md b/docs/src/aria-snapshots.mdindex 1f6c01ab5d..4ace92d764 100644--- a/docs/src/aria-snapshots.md+++ b/docs/src/aria-snapshots.md@@ -263,6 +263,48 @@ Similarly, you can partially match children in lists or groups by omitting speciPartial matches let you create flexible snapshot tests that verify essential page structure without enforcingspecific content or attributes.+### Strict matching++By default, a template containing the subset of children will be matched:++```html+<ul>+ <li>Feature A</li>+ <li>Feature B</li>+ <li>Feature C</li>+</ul>+```++*aria snapshot for partial match*++```yaml+- list+ - listitem: Feature B+```+++The `/children` property can be used to control how child elements are matched:+- `contain` (default): Matches if all specified children are present in any order+- `equal`: Matches if the children exactly match the specified list in order+- `deep-equal`: Matches if the children exactly match the specified list in order, including nested children++```html+<ul>+ <li>Feature A</li>+ <li>Feature B</li>+ <li>Feature C</li>+</ul>+```++*aria snapshot will fail due Feature C not being in the template*++```yaml+- list+ - /children: equal+ - listitem: Feature A+ - listitem: Feature B+```+### Matching with regular expressionsRegular expressions allow flexible matching for elements with dynamic or variable text. Accessible names and text candiff --git a/packages/injected/src/ariaSnapshot.ts b/packages/injected/src/ariaSnapshot.tsindex 892b017d2f..98d482604e 100644--- a/packages/injected/src/ariaSnapshot.ts+++ b/packages/injected/src/ariaSnapshot.ts@@ -236,7 +236,7 @@ export type MatcherReceived = {export function matchesAriaTree(builtins: Builtins, rootElement: Element, template: AriaTemplateNode): { matches: AriaNode[], received: MatcherReceived } {const snapshot = generateAriaTree(builtins, rootElement, 0, false);- const matches = matchesNodeDeep(snapshot.root, template, false);+ const matches = matchesNodeDeep(snapshot.root, template, false, false);return {matches,received: {@@ -248,41 +248,57 @@ export function matchesAriaTree(builtins: Builtins, rootElement: Element, templaexport function getAllByAria(builtins: Builtins, rootElement: Element, template: AriaTemplateNode): Element[] {const root = generateAriaTree(builtins, rootElement, 0, false).root;- const matches = matchesNodeDeep(root, template, true);+ const matches = matchesNodeDeep(root, template, true, false);return matches.map(n => n.element);}-function matchesNode(node: AriaNode | string, template: AriaTemplateNode, depth: number): boolean {+function matchesNode(node: AriaNode | string, template: AriaTemplateNode, isDeepEqual: boolean): boolean {if (typeof node === 'string' && template.kind === 'text')return matchesTextNode(node, template);- if (node !== null && typeof node === 'object' && template.kind === 'role') {- if (template.role !== 'fragment' && template.role !== node.role)- return false;- if (template.checked !== undefined && template.checked !== node.checked)- return false;- if (template.disabled !== undefined && template.disabled !== node.disabled)- return false;- if (template.expanded !== undefined && template.expanded !== node.expanded)- return false;- if (template.level !== undefined && template.level !== node.level)- return false;- if (template.pressed !== undefined && template.pressed !== node.pressed)- return false;- if (template.selected !== undefined && template.selected !== node.selected)- return false;- if (!matchesName(node.name, template))- return false;- if (!matchesText(node.props.url, template.props?.url))- return false;- if (!containsList(node.children || [], template.children || [], depth))+ if (node === null || typeof node !== 'object' || template.kind !== 'role')+ return false;++ if (template.role !== 'fragment' && template.role !== node.role)+ return false;+ if (template.checked !== undefined && template.checked !== node.checked)+ return false;+ if (template.disabled !== undefined && template.disabled !== node.disabled)+ return false;+ if (template.expanded !== undefined && template.expanded !== node.expanded)+ return false;+ if (template.level !== undefined && template.level !== node.level)+ return false;+ if (template.pressed !== undefined && template.pressed !== node.pressed)+ return false;+ if (template.selected !== undefined && template.selected !== node.selected)+ return false;+ if (!matchesName(node.name, template))+ return false;+ if (!matchesText(node.props.url, template.props?.url))+ return false;++ // Proceed based on the container mode.+ if (template.containerMode === 'contain')+ return containsList(node.children || [], template.children || []);+ if (template.containerMode === 'equal')+ return listEqual(node.children || [], template.children || [], false);+ if (template.containerMode === 'deep-equal' || isDeepEqual)+ return listEqual(node.children || [], template.children || [], true);+ return containsList(node.children || [], template.children || []);+}++function listEqual(children: (AriaNode | string)[], template: AriaTemplateNode[], isDeepEqual: boolean): boolean {+ if (template.length !== children.length)+ return false;+ for (let i = 0; i < template.length; ++i) {+ if (!matchesNode(children[i], template[i], isDeepEqual))return false;- return true;}- return false;+ return true;}-function containsList(children: (AriaNode | string)[], template: AriaTemplateNode[], depth: number): boolean {+function containsList(children: (AriaNode | string)[], template: AriaTemplateNode[]): boolean {if (template.length > children.length)return false;const cc = children.slice();@@ -290,7 +306,7 @@ function containsList(children: (AriaNode | string)[], template: AriaTemplateNodfor (const t of tt) {let c = cc.shift();while (c) {- if (matchesNode(c, t, depth + 1))+ if (matchesNode(c, t, false))break;c = cc.shift();}@@ -300,10 +316,10 @@ function containsList(children: (AriaNode | string)[], template: AriaTemplateNodreturn true;}-function matchesNodeDeep(root: AriaNode, template: AriaTemplateNode, collectAll: boolean): AriaNode[] {+function matchesNodeDeep(root: AriaNode, template: AriaTemplateNode, collectAll: boolean, isDeepEqual: boolean): AriaNode[] {const results: AriaNode[] = [];const visit = (node: AriaNode | string, parent: AriaNode | null): boolean => {- if (matchesNode(node, template, 0)) {+ if (matchesNode(node, template, isDeepEqual)) {const result = typeof node === 'string' ? parent : node;if (result)results.push(result);diff --git a/packages/playwright-core/src/utils/isomorphic/ariaSnapshot.ts b/packages/playwright-core/src/utils/isomorphic/ariaSnapshot.tsindex 04e5b7c471..ffbd50ddef 100644--- a/packages/playwright-core/src/utils/isomorphic/ariaSnapshot.ts+++ b/packages/playwright-core/src/utils/isomorphic/ariaSnapshot.ts@@ -47,6 +47,7 @@ export type AriaTemplateRoleNode = AriaProps & {name?: AriaRegex | string;children?: AriaTemplateNode[];props?: Record<string, string | AriaRegex>;+ containerMode?: 'contain' | 'equal' | 'deep-equal';};export type AriaTemplateNode = AriaTemplateRoleNode | AriaTemplateTextNode;@@ -152,6 +153,20 @@ export function parseAriaSnapshot(yaml: YamlLibrary, text: string, options: yamlcontinue;}+ // - /children: equal+ if (key.value === '/children') {+ const valueIsString = value instanceof yaml.Scalar && typeof value.value === 'string';+ if (!valueIsString || (value.value !== 'contain' && value.value !== 'equal' && value.value !== 'deep-equal')) {+ errors.push({+ message: 'Strict value should be "contain", "equal" or "deep-equal"',+ range: convertRange(((entry.value as any).range || map.range)),+ });+ continue;+ }+ container.containerMode = value.value;+ continue;+ }+// - /url: "about:blank"if (key.value.startsWith('/')) {const valueIsString = value instanceof yaml.Scalar && typeof value.value === 'string';diff --git a/tests/page/to-match-aria-snapshot.spec.ts b/tests/page/to-match-aria-snapshot.spec.tsindex f57a01cab4..f929f1b11a 100644--- a/tests/page/to-match-aria-snapshot.spec.ts+++ b/tests/page/to-match-aria-snapshot.spec.ts@@ -693,3 +693,101 @@ test('should match url', async ({ page }) => {- /url: /.*example.com/`);});++test('should detect unexpected children: equal', async ({ page }) => {+ await page.setContent(`+ <ul>+ <li>One</li>+ <li>Two</li>+ <li>Three</li>+ </ul>+ `);++ await expect(page.locator('body')).toMatchAriaSnapshot(`+ - list:+ - listitem: "One"+ - listitem: "Three"+ `);++ const e = await expect(page.locator('body')).toMatchAriaSnapshot(`+ - list:+ - /children: equal+ - listitem: "One"+ - listitem: "Three"+ `, { timeout: 1000 }).catch(e => e);++ expect(e.message).toContain('Timed out 1000ms waiting');+ expect(stripAnsi(e.message)).toContain('+ - listitem: Two');+});++test('should detect unexpected children: deep-equal', async ({ page }) => {+ await page.setContent(`+ <ul>+ <li>+ <ul>+ <li>1.1</li>+ <li>1.2</li>+ </ul>+ </li>+ </ul>+ `);++ await expect(page.locator('body')).toMatchAriaSnapshot(`+ - list:+ - listitem:+ - list:+ - listitem: 1.1+ `);++ await expect(page.locator('body')).toMatchAriaSnapshot(`+ - list:+ - /children: equal+ - listitem:+ - list:+ - listitem: 1.1+ `);++ const e = await expect(page.locator('body')).toMatchAriaSnapshot(`+ - list:+ - /children: deep-equal+ - listitem:+ - list:+ - listitem: 1.1+ `, { timeout: 1000 }).catch(e => e);++ expect(e.message).toContain('Timed out 1000ms waiting');+ expect(stripAnsi(e.message)).toContain('+ - listitem: \"1.2\"');+});++test('should allow restoring contain mode inside deep-equal', async ({ page }) => {+ await page.setContent(`+ <ul>+ <li>+ <ul>+ <li>1.1</li>+ <li>1.2</li>+ </ul>+ </li>+ </ul>+ `);++ const e = await expect(page.locator('body')).toMatchAriaSnapshot(`+ - list:+ - /children: deep-equal+ - listitem:+ - list:+ - listitem: 1.1+ `, { timeout: 1000 }).catch(e => e);++ expect(e.message).toContain('Timed out 1000ms waiting');+ expect(stripAnsi(e.message)).toContain('+ - listitem: \"1.2\"');++ await expect(page.locator('body')).toMatchAriaSnapshot(`+ - list:+ - /children: deep-equal+ - listitem:+ - list:+ - /children: contain+ - listitem: 1.1+ `);+});