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
feat(aria): emit generic nodes (#35686)
Pavel Feldman7ec70c61d7ae
diff --git a/docs/src/api/class-locator.md b/docs/src/api/class-locator.mdindex 4397d144db..15943f1a42 100644--- a/docs/src/api/class-locator.md+++ b/docs/src/api/class-locator.md@@ -206,6 +206,12 @@ Below is the HTML markup and the respective ARIA snapshot:- link "About"```+### option: Locator.ariaSnapshot.emitGeneric+* since: v1.53+- `emitGeneric` <[boolean]>++Generate `generic` aria nodes for elements w/o roles (similar to Chrome DevTools).+### option: Locator.ariaSnapshot.ref* since: v1.52- `ref` <[boolean]>diff --git a/packages/injected/src/ariaSnapshot.ts b/packages/injected/src/ariaSnapshot.tsindex 7f7b72c356..17de28ecbf 100644--- a/packages/injected/src/ariaSnapshot.ts+++ b/packages/injected/src/ariaSnapshot.ts@@ -38,7 +38,7 @@ export type AriaSnapshot = {ids: Map<Element, number>;};-export function generateAriaTree(rootElement: Element, generation: number): AriaSnapshot {+export function generateAriaTree(rootElement: Element, generation: number, options?: { emitGeneric?: boolean }): AriaSnapshot {const visited = new Set<Node>();const snapshot: AriaSnapshot = {@@ -91,7 +91,7 @@ export function generateAriaTree(rootElement: Element, generation: number): Ariareturn;addElement(element);- const childAriaNode = toAriaNode(element);+ const childAriaNode = toAriaNode(element, options);if (childAriaNode)ariaNode.children.push(childAriaNode);processElement(childAriaNode || ariaNode, element, ariaChildren);@@ -145,14 +145,16 @@ export function generateAriaTree(rootElement: Element, generation: number): Aria}normalizeStringChildren(snapshot.root);+ normalizeGenericRoles(snapshot.root);return snapshot;}-function toAriaNode(element: Element): AriaNode | null {+function toAriaNode(element: Element, options?: { emitGeneric?: boolean }): AriaNode | null {if (element.nodeName === 'IFRAME')return { role: 'iframe', name: '', children: [], props: {}, element };- const role = roleUtils.getAriaRole(element);+ const defaultRole = options?.emitGeneric ? 'generic' : null;+ const role = roleUtils.getAriaRole(element) ?? defaultRole;if (!role || role === 'presentation' || role === 'none')return null;@@ -185,6 +187,33 @@ function toAriaNode(element: Element): AriaNode | null {return result;}+function normalizeGenericRoles(rootA11yNode: AriaNode) {+ const visit = (ariaNode: AriaNode) => {+ const newChildren: (AriaNode | string)[] = [];+ for (const child of ariaNode.children) {+ if (typeof child === 'string') {+ newChildren.push(child);+ continue;+ }+ const isEmptyGeneric = child.role === 'generic' && child.children.length === 0;+ const isSingleGenericChild = child.role === 'generic' && child.children.length === 1;+ if (isSingleGenericChild) {+ // Inline single child chains.+ const newChild = child.children[0];+ newChildren.push(newChild);+ if (typeof newChild !== 'string')+ visit(newChild);+ } else if (!isEmptyGeneric) {+ // Empty div+ newChildren.push(child);+ visit(child);+ }+ }+ ariaNode.children = newChildren;+ };+ visit(rootA11yNode);+}+function normalizeStringChildren(rootA11yNode: AriaNode) {const flushChildren = (buffer: string[], normalizedChildren: (AriaNode | string)[]) => {if (!buffer.length)diff --git a/packages/injected/src/injectedScript.ts b/packages/injected/src/injectedScript.tsindex 5a1ba8bc89..d333e1460d 100644--- a/packages/injected/src/injectedScript.ts+++ b/packages/injected/src/injectedScript.ts@@ -281,11 +281,11 @@ export class InjectedScript {return new Set<Element>(result.map(r => r.element));}- ariaSnapshot(node: Node, options?: { mode?: 'raw' | 'regex', ref?: boolean }): string {+ ariaSnapshot(node: Node, options?: { mode?: 'raw' | 'regex', ref?: boolean, emitGeneric?: boolean }): string {if (node.nodeType !== Node.ELEMENT_NODE)throw this.createStacklessError('Can only capture aria snapshot of Element nodes.');const generation = (this._lastAriaSnapshot?.generation || 0) + 1;- this._lastAriaSnapshot = generateAriaTree(node as Element, generation);+ this._lastAriaSnapshot = generateAriaTree(node as Element, generation, options);return renderAriaTree(this._lastAriaSnapshot, options);}diff --git a/packages/playwright-client/types/types.d.ts b/packages/playwright-client/types/types.d.tsindex de16729658..c018ad0623 100644--- a/packages/playwright-client/types/types.d.ts+++ b/packages/playwright-client/types/types.d.ts@@ -12500,6 +12500,11 @@ export interface Locator {* @param options*/ariaSnapshot(options?: {+ /**+ * Generate `generic` aria nodes for elements w/o roles (similar to Chrome DevTools).+ */+ emitGeneric?: boolean;+/*** Generate symbolic reference for each element. One can use `aria-ref=<ref>` locator immediately after capturing the* snapshot to perform actions on the element.diff --git a/packages/playwright-core/src/client/locator.ts b/packages/playwright-core/src/client/locator.tsindex 46825a99a9..b431d7a317 100644--- a/packages/playwright-core/src/client/locator.ts+++ b/packages/playwright-core/src/client/locator.ts@@ -303,7 +303,7 @@ export class Locator implements api.Locator {return await this._withElement((h, timeout) => h.screenshot({ ...options, mask, timeout }), options.timeout);}- async ariaSnapshot(options?: { ref?: boolean, _mode?: 'raw' | 'regex' } & TimeoutOptions): Promise<string> {+ async ariaSnapshot(options?: { ref?: boolean, emitGeneric?: boolean, _mode?: 'raw' | 'regex' } & TimeoutOptions): Promise<string> {const result = await this._frame._channel.ariaSnapshot({ ...options, mode: options?._mode, selector: this._selector });return result.snapshot;}diff --git a/packages/playwright-core/src/protocol/validator.ts b/packages/playwright-core/src/protocol/validator.tsindex 0484fd1c11..8ef6aa850f 100644--- a/packages/playwright-core/src/protocol/validator.ts+++ b/packages/playwright-core/src/protocol/validator.ts@@ -1481,6 +1481,7 @@ scheme.FrameAddStyleTagResult = tObject({scheme.FrameAriaSnapshotParams = tObject({selector: tString,ref: tOptional(tBoolean),+ emitGeneric: tOptional(tBoolean),mode: tOptional(tEnum(['raw', 'regex'])),timeout: tOptional(tNumber),});diff --git a/packages/playwright-core/src/server/dom.ts b/packages/playwright-core/src/server/dom.tsindex fc4bd34255..0886ad9195 100644--- a/packages/playwright-core/src/server/dom.ts+++ b/packages/playwright-core/src/server/dom.ts@@ -813,7 +813,7 @@ export class ElementHandle<T extends Node = Node> extends js.JSHandle<T> {return this._page._delegate.getBoundingBox(this);}- async ariaSnapshot(options: { id?: boolean, mode?: 'raw' | 'regex' }): Promise<string> {+ async ariaSnapshot(options: { ref?: boolean, emitGeneric?: boolean, mode?: 'raw' | 'regex' }): Promise<string> {return await this.evaluateInUtility(([injected, element, options]) => injected.ariaSnapshot(element, options), options);}diff --git a/packages/playwright-core/src/server/frames.ts b/packages/playwright-core/src/server/frames.tsindex 179a046ed4..bf5be6e09d 100644--- a/packages/playwright-core/src/server/frames.ts+++ b/packages/playwright-core/src/server/frames.ts@@ -1411,7 +1411,7 @@ export class Frame extends SdkObject {});}- async ariaSnapshot(metadata: CallMetadata, selector: string, options: { ref?: boolean, mode?: 'raw' | 'regex' } & types.TimeoutOptions = {}): Promise<string> {+ async ariaSnapshot(metadata: CallMetadata, selector: string, options: { ref?: boolean, emitGeneric?: boolean, mode?: 'raw' | 'regex' } & types.TimeoutOptions = {}): Promise<string> {const controller = new ProgressController(metadata, this);return controller.run(async progress => {return await this._retryWithProgressIfNotConnected(progress, selector, true /* strict */, true /* performActionPreChecks */, handle => handle.ariaSnapshot(options));diff --git a/packages/playwright-core/types/types.d.ts b/packages/playwright-core/types/types.d.tsindex de16729658..c018ad0623 100644--- a/packages/playwright-core/types/types.d.ts+++ b/packages/playwright-core/types/types.d.ts@@ -12500,6 +12500,11 @@ export interface Locator {* @param options*/ariaSnapshot(options?: {+ /**+ * Generate `generic` aria nodes for elements w/o roles (similar to Chrome DevTools).+ */+ emitGeneric?: boolean;+/*** Generate symbolic reference for each element. One can use `aria-ref=<ref>` locator immediately after capturing the* snapshot to perform actions on the element.diff --git a/packages/protocol/src/channels.d.ts b/packages/protocol/src/channels.d.tsindex 2e1c447b88..170e76410f 100644--- a/packages/protocol/src/channels.d.ts+++ b/packages/protocol/src/channels.d.ts@@ -2688,11 +2688,13 @@ export type FrameAddStyleTagResult = {export type FrameAriaSnapshotParams = {selector: string,ref?: boolean,+ emitGeneric?: boolean,mode?: 'raw' | 'regex',timeout?: number,};export type FrameAriaSnapshotOptions = {ref?: boolean,+ emitGeneric?: boolean,mode?: 'raw' | 'regex',timeout?: number,};diff --git a/packages/protocol/src/protocol.yml b/packages/protocol/src/protocol.ymlindex c146e995da..481570f6e3 100644--- a/packages/protocol/src/protocol.yml+++ b/packages/protocol/src/protocol.yml@@ -1975,6 +1975,7 @@ Frame:parameters:selector: stringref: boolean?+ emitGeneric: boolean?mode:type: enum?literals:diff --git a/tests/page/page-aria-snapshot.spec.ts b/tests/page/page-aria-snapshot.spec.tsindex 5e3f0cf93a..c52dd68df1 100644--- a/tests/page/page-aria-snapshot.spec.ts+++ b/tests/page/page-aria-snapshot.spec.ts@@ -742,3 +742,42 @@ it('should not include hidden input elements', async ({ page }) => {expect(snapshot).toContain(`- button \"One\"- button \"Three\"`);});++it('emit generic roles for nodes w/o roles', async ({ page }) => {+ await page.setContent(`+ <style>+ input {+ width: 0;+ height: 0;+ opacity: 0;+ }+ </style>+ <div>+ <label>+ <span>+ <input type="radio" value="Apple" checked="">+ </span>+ <span>Apple</span>+ </label>+ <label>+ <span>+ <input type="radio" value="Pear">+ </span>+ <span>Pear</span>+ </label>+ <label>+ <span>+ <input type="radio" value="Orange">+ </span>+ <span>Orange</span>+ </label>+ </div>+ `);++ const snapshot = await page.locator('body').ariaSnapshot({ emitGeneric: true });++ expect(snapshot).toContain(`- generic:+ - generic: Apple+ - generic: Pear+ - generic: Orange`);+});