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 generating aria references (#35132)
Pavel Feldman807d9066d635
diff --git a/docs/src/api/class-locator.md b/docs/src/api/class-locator.mdindex 42c09c79f1..2a2d81f6eb 100644--- a/docs/src/api/class-locator.md+++ b/docs/src/api/class-locator.md@@ -206,6 +206,13 @@ Below is the HTML markup and the respective ARIA snapshot:- link "About"```+### option: Locator.ariaSnapshot.ref+* since: v1.52+- `ref` <[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.+### option: Locator.ariaSnapshot.timeout = %%-input-timeout-%%* since: v1.49diff --git a/packages/playwright-client/types/types.d.ts b/packages/playwright-client/types/types.d.tsindex 49a2ca9ce3..2eb9af4926 100644--- a/packages/playwright-client/types/types.d.ts+++ b/packages/playwright-client/types/types.d.ts@@ -12481,6 +12481,12 @@ export interface Locator {* @param options*/ariaSnapshot(options?: {+ /**+ * Generate symbolic reference for each element. One can use `aria-ref=<ref>` locator immediately after capturing the+ * snapshot to perform actions on the element.+ */+ ref?: boolean;+/*** Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `actionTimeout`* option in the config, or by using thediff --git a/packages/playwright-core/src/client/locator.ts b/packages/playwright-core/src/client/locator.tsindex a915c0a8ef..46825a99a9 100644--- a/packages/playwright-core/src/client/locator.ts+++ b/packages/playwright-core/src/client/locator.ts@@ -303,8 +303,8 @@ export class Locator implements api.Locator {return await this._withElement((h, timeout) => h.screenshot({ ...options, mask, timeout }), options.timeout);}- async ariaSnapshot(options?: { _id?: boolean, _mode?: 'raw' | 'regex' } & TimeoutOptions): Promise<string> {- const result = await this._frame._channel.ariaSnapshot({ ...options, id: options?._id, mode: options?._mode, selector: this._selector });+ async ariaSnapshot(options?: { ref?: 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 eda99fbc6c..109990bc88 100644--- a/packages/playwright-core/src/protocol/validator.ts+++ b/packages/playwright-core/src/protocol/validator.ts@@ -1467,7 +1467,7 @@ scheme.FrameAddStyleTagResult = tObject({});scheme.FrameAriaSnapshotParams = tObject({selector: tString,- id: tOptional(tBoolean),+ ref: tOptional(tBoolean),mode: tOptional(tEnum(['raw', 'regex'])),timeout: tOptional(tNumber),});diff --git a/packages/playwright-core/src/server/frames.ts b/packages/playwright-core/src/server/frames.tsindex 69ef1ecba5..873ba2875b 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: { id?: boolean, mode?: 'raw' | 'regex' } & types.TimeoutOptions = {}): Promise<string> {+ async ariaSnapshot(metadata: CallMetadata, selector: string, options: { ref?: 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/src/server/injected/ariaSnapshot.ts b/packages/playwright-core/src/server/injected/ariaSnapshot.tsindex 3813960fe4..9acf2a8159 100644--- a/packages/playwright-core/src/server/injected/ariaSnapshot.ts+++ b/packages/playwright-core/src/server/injected/ariaSnapshot.ts@@ -32,15 +32,17 @@ export type AriaNode = AriaProps & {export type AriaSnapshot = {root: AriaNode;elements: Map<number, Element>;+ generation: number;ids: Map<Element, number>;};-export function generateAriaTree(rootElement: Element): AriaSnapshot {+export function generateAriaTree(rootElement: Element, generation: number): AriaSnapshot {const visited = new Set<Node>();const snapshot: AriaSnapshot = {root: { role: 'fragment', name: '', children: [], element: rootElement },elements: new Map<number, Element>(),+ generation,ids: new Map<Element, number>(),};@@ -223,19 +225,19 @@ export type MatcherReceived = {};export function matchesAriaTree(rootElement: Element, template: AriaTemplateNode): { matches: AriaNode[], received: MatcherReceived } {- const root = generateAriaTree(rootElement).root;- const matches = matchesNodeDeep(root, template, false);+ const snapshot = generateAriaTree(rootElement, 0);+ const matches = matchesNodeDeep(snapshot.root, template, false);return {matches,received: {- raw: renderAriaTree(root, { mode: 'raw' }),- regex: renderAriaTree(root, { mode: 'regex' }),+ raw: renderAriaTree(snapshot, { mode: 'raw' }),+ regex: renderAriaTree(snapshot, { mode: 'regex' }),}};}export function getAllByAria(rootElement: Element, template: AriaTemplateNode): Element[] {- const root = generateAriaTree(rootElement).root;+ const root = generateAriaTree(rootElement, 0).root;const matches = matchesNodeDeep(root, template, true);return matches.map(n => n.element);}@@ -307,7 +309,7 @@ function matchesNodeDeep(root: AriaNode, template: AriaTemplateNode, collectAll:return results;}-export function renderAriaTree(ariaNode: AriaNode, options?: { mode?: 'raw' | 'regex', ids?: Map<Element, number> }): string {+export function renderAriaTree(ariaSnapshot: AriaSnapshot, options?: { mode?: 'raw' | 'regex', ref?: boolean }): string {const lines: string[] = [];const includeText = options?.mode === 'regex' ? textContributesInfo : () => true;const renderString = options?.mode === 'regex' ? convertToBestGuessRegex : (str: string) => str;@@ -346,10 +348,10 @@ export function renderAriaTree(ariaNode: AriaNode, options?: { mode?: 'raw' | 'rkey += ` [pressed]`;if (ariaNode.selected === true)key += ` [selected]`;- if (options?.ids) {- const id = options?.ids.get(ariaNode.element);+ if (options?.ref) {+ const id = ariaSnapshot.ids.get(ariaNode.element);if (id)- key += ` [id=${id}]`;+ key += ` [ref=s${ariaSnapshot.generation}e${id}]`;}const escapedKey = indent + '- ' + yamlEscapeKeyIfNeeded(key);@@ -368,6 +370,7 @@ export function renderAriaTree(ariaNode: AriaNode, options?: { mode?: 'raw' | 'r}};+ const ariaNode = ariaSnapshot.root;if (ariaNode.role === 'fragment') {// Render fragment.for (const child of ariaNode.children || [])diff --git a/packages/playwright-core/src/server/injected/consoleApi.ts b/packages/playwright-core/src/server/injected/consoleApi.tsindex 5bcd94a5bf..159686d90c 100644--- a/packages/playwright-core/src/server/injected/consoleApi.ts+++ b/packages/playwright-core/src/server/injected/consoleApi.ts@@ -88,7 +88,7 @@ class ConsoleAPI {inspect: (selector: string) => this._inspect(selector),selector: (element: Element) => this._selector(element),generateLocator: (element: Element, language?: Language) => this._generateLocator(element, language),- ariaSnapshot: (element?: Element, options?: { id?: boolean }) => {+ ariaSnapshot: (element?: Element, options?: { ref?: boolean }) => {return this._injectedScript.ariaSnapshot(element || this._injectedScript.document.body, options);},resume: () => this._resume(),diff --git a/packages/playwright-core/src/server/injected/injectedScript.ts b/packages/playwright-core/src/server/injected/injectedScript.tsindex 70374852f7..82b5b0c81d 100644--- a/packages/playwright-core/src/server/injected/injectedScript.ts+++ b/packages/playwright-core/src/server/injected/injectedScript.ts@@ -33,7 +33,7 @@ import { parseAttributeSelector } from '../../utils/isomorphic/selectorParser';import { parseSelector, stringifySelector, visitAllSelectorParts } from '../../utils/isomorphic/selectorParser';import { cacheNormalizedWhitespaces, normalizeWhiteSpace, trimStringWithEllipsis } from '../../utils/isomorphic/stringUtils';-import type { AriaNode, AriaSnapshot } from './ariaSnapshot';+import type { AriaSnapshot } from './ariaSnapshot';import type { LayoutSelectorName } from './layoutSelectorUtils';import type { SelectorEngine, SelectorRoot } from './selectorEngine';import type { GenerateSelectorOptions } from './selectorGenerator';@@ -78,7 +78,7 @@ export class InjectedScript {// eslint-disable-next-line no-restricted-globalsreadonly window: Window & typeof globalThis;readonly document: Document;- private _ariaElementById: Map<number, Element> | undefined;+ private _lastAriaSnapshot: AriaSnapshot | undefined;// Recorder must use any external dependencies through InjectedScript.// Otherwise it will end up with a copy of all modules it uses, and any@@ -137,7 +137,7 @@ export class InjectedScript {this._engines.set('internal:attr', this._createNamedAttributeEngine());this._engines.set('internal:testid', this._createNamedAttributeEngine());this._engines.set('internal:role', createRoleEngine(true));- this._engines.set('internal:aria-id', this._createAriaIdEngine());+ this._engines.set('aria-ref', this._createAriaIdEngine());for (const { name, engine } of customEngines)this._engines.set(name, engine);@@ -225,30 +225,18 @@ export class InjectedScript {return new Set<Element>(result.map(r => r.element));}- ariaSnapshot(node: Node, options?: { mode?: 'raw' | 'regex', id?: boolean }): string {+ ariaSnapshot(node: Node, options?: { mode?: 'raw' | 'regex', ref?: boolean }): string {if (node.nodeType !== Node.ELEMENT_NODE)throw this.createStacklessError('Can only capture aria snapshot of Element nodes.');- const ariaSnapshot = generateAriaTree(node as Element);- this._ariaElementById = ariaSnapshot.elements;- return renderAriaTree(ariaSnapshot.root, { ...options, ids: options?.id ? ariaSnapshot.ids : undefined });- }-- ariaSnapshotAsObject(node: Node): AriaSnapshot {- return generateAriaTree(node as Element);+ const generation = (this._lastAriaSnapshot?.generation || 0) + 1;+ this._lastAriaSnapshot = generateAriaTree(node as Element, generation);+ return renderAriaTree(this._lastAriaSnapshot, options);}ariaSnapshotElement(snapshot: AriaSnapshot, elementId: number): Element | null {return snapshot.elements.get(elementId) || null;}- renderAriaTree(ariaNode: AriaNode, options?: { mode?: 'raw' | 'regex', id?: boolean}): string {- return renderAriaTree(ariaNode, options);- }-- renderAriaSnapshotWithIds(ariaSnapshot: AriaSnapshot): string {- return renderAriaTree(ariaSnapshot.root, { ids: ariaSnapshot.ids });- }-getAllByAria(document: Document, template: AriaTemplateNode): Element[] {return getAllByAria(document.documentElement, template);}@@ -620,8 +608,13 @@ export class InjectedScript {_createAriaIdEngine() {const queryAll = (root: SelectorRoot, selector: string): Element[] => {- const ariaId = parseInt(selector, 10);- const result = this._ariaElementById?.get(ariaId);+ const match = selector.match(/^s(\d+)e(\d+)$/);+ if (!match)+ throw this.createStacklessError('Invalid aria-ref selector, should be of form s<number>e<number>');+ const [, generation, elementId] = match;+ if (this._lastAriaSnapshot?.generation !== +generation)+ throw this.createStacklessError(`Stale aria-ref, expected s${this._lastAriaSnapshot?.generation}e{number}, got ${selector}`);+ const result = this._lastAriaSnapshot?.elements?.get(+elementId);return result && result.isConnected ? [result] : [];};return { queryAll };diff --git a/packages/playwright-core/src/server/selectors.ts b/packages/playwright-core/src/server/selectors.tsindex 886108b972..ff377ee3d3 100644--- a/packages/playwright-core/src/server/selectors.ts+++ b/packages/playwright-core/src/server/selectors.ts@@ -41,7 +41,7 @@ export class Selectors {'internal:has', 'internal:has-not','internal:has-text', 'internal:has-not-text','internal:and', 'internal:or', 'internal:chain',- 'role', 'internal:attr', 'internal:label', 'internal:text', 'internal:role', 'internal:testid', 'internal:aria-id'+ 'role', 'internal:attr', 'internal:label', 'internal:text', 'internal:role', 'internal:testid', 'aria-ref']);this._builtinEnginesInMainWorld = new Set(['_react', '_vue',diff --git a/packages/playwright-core/types/types.d.ts b/packages/playwright-core/types/types.d.tsindex 49a2ca9ce3..2eb9af4926 100644--- a/packages/playwright-core/types/types.d.ts+++ b/packages/playwright-core/types/types.d.ts@@ -12481,6 +12481,12 @@ export interface Locator {* @param options*/ariaSnapshot(options?: {+ /**+ * Generate symbolic reference for each element. One can use `aria-ref=<ref>` locator immediately after capturing the+ * snapshot to perform actions on the element.+ */+ ref?: boolean;+/*** Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `actionTimeout`* option in the config, or by using thediff --git a/packages/playwright-mcp/src/tools/snapshot.ts b/packages/playwright-mcp/src/tools/snapshot.tsindex 22cf2eea53..1495a6376e 100644--- a/packages/playwright-mcp/src/tools/snapshot.ts+++ b/packages/playwright-mcp/src/tools/snapshot.ts@@ -19,10 +19,10 @@ import { waitForCompletion } from '../utils';import type * as playwright from 'playwright';import type { Tool, ToolContext, ToolResult } from './common';-const elementIdProperty = {- elementId: {- type: 'number',- description: 'Target element',+const elementRefProperty = {+ elementRef: {+ type: 'string',+ description: 'Target element reference',}};@@ -68,14 +68,14 @@ export const click: Tool = {inputSchema: {type: 'object',properties: {- ...elementIdProperty,+ ...elementRefProperty,},- required: ['elementId'],+ required: ['elementRef'],}},handle: async (context, params) => {- const locator = elementIdLocator(context.page, params!);+ const locator = elementRefLocator(context.page, params!);return runAndCaptureSnapshot(context, () => locator.click());}};@@ -87,14 +87,14 @@ export const hover: Tool = {inputSchema: {type: 'object',properties: {- ...elementIdProperty,+ ...elementRefProperty,},- required: ['elementId'],+ required: ['elementRef'],}},handle: async (context, params) => {- const locator = elementIdLocator(context.page, params!);+ const locator = elementRefLocator(context.page, params!);return runAndCaptureSnapshot(context, () => locator.hover());}};@@ -106,7 +106,7 @@ export const type: Tool = {inputSchema: {type: 'object',properties: {- ...elementIdProperty,+ ...elementRefProperty,text: {type: 'string',description: 'Text to enter',@@ -116,12 +116,12 @@ export const type: Tool = {description: 'Whether to submit entered text (press Enter after)'}},- required: ['elementId', 'text'],+ required: ['elementRef', 'text'],}},handle: async (context, params) => {- const locator = elementIdLocator(context.page, params!);+ const locator = elementRefLocator(context.page, params!);return await runAndCaptureSnapshot(context, async () => {locator.fill(params!.text as string);if (params!.submit)@@ -130,8 +130,8 @@ export const type: Tool = {}};-function elementIdLocator(page: playwright.Page, params: Record<string, string>): playwright.Locator {- return page.locator(`internal:aria-id=${params.elementId}`);+function elementRefLocator(page: playwright.Page, params: Record<string, string>): playwright.Locator {+ return page.locator(`internal:aria-ref=${params.elementRef}`);}async function runAndCaptureSnapshot(context: ToolContext, callback: () => Promise<any>): Promise<ToolResult> {diff --git a/packages/protocol/src/channels.d.ts b/packages/protocol/src/channels.d.tsindex 137bc6238f..582c61e721 100644--- a/packages/protocol/src/channels.d.ts+++ b/packages/protocol/src/channels.d.ts@@ -2668,12 +2668,12 @@ export type FrameAddStyleTagResult = {};export type FrameAriaSnapshotParams = {selector: string,- id?: boolean,+ ref?: boolean,mode?: 'raw' | 'regex',timeout?: number,};export type FrameAriaSnapshotOptions = {- id?: boolean,+ ref?: boolean,mode?: 'raw' | 'regex',timeout?: number,};diff --git a/packages/protocol/src/protocol.yml b/packages/protocol/src/protocol.ymlindex e45b01ddeb..f385b3eb7a 100644--- a/packages/protocol/src/protocol.yml+++ b/packages/protocol/src/protocol.yml@@ -1946,7 +1946,7 @@ Frame:ariaSnapshot:parameters:selector: string- id: boolean?+ ref: boolean?mode:type: enum?literals:diff --git a/tests/page/page-aria-snapshot.spec.ts b/tests/page/page-aria-snapshot.spec.tsindex e5ba5a6c4b..e568fc6227 100644--- a/tests/page/page-aria-snapshot.spec.ts+++ b/tests/page/page-aria-snapshot.spec.ts@@ -621,3 +621,27 @@ it('should not report textarea textContent', async ({ page }) => {- textbox: After`);});++it('should generate refs', async ({ page }) => {+ await page.setContent(`+ <button>One</button>+ <button>Two</button>+ <button>Three</button>+ `);++ const snapshot1 = await page.locator('body').ariaSnapshot({ ref: true });+ expect(snapshot1).toContain('- button "One" [ref=s1e3]');+ expect(snapshot1).toContain('- button "Two" [ref=s1e4]');+ expect(snapshot1).toContain('- button "Three" [ref=s1e5]');++ await expect(page.locator('aria-ref=s1e3')).toHaveText('One');+ await expect(page.locator('aria-ref=s1e4')).toHaveText('Two');+ await expect(page.locator('aria-ref=s1e5')).toHaveText('Three');++ const snapshot2 = await page.locator('body').ariaSnapshot({ ref: true });+ expect(snapshot2).toContain('- button "One" [ref=s2e3]');+ await expect(page.locator('aria-ref=s2e3')).toHaveText('One');++ const e = await expect(page.locator('aria-ref=s1e3')).toHaveText('One').catch(e => e);+ expect(e.message).toContain('Error: Stale aria-ref, expected s2e{number}, got s1e3');+});