Skip to content

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

chore: allow generating aria references (#35132)

Pavel Feldman807d9066d635
diff --git a/docs/src/api/class-locator.md b/docs/src/api/class-locator.md
index 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.49
diff --git a/packages/playwright-client/types/types.d.ts b/packages/playwright-client/types/types.d.ts
index 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 the
diff --git a/packages/playwright-core/src/client/locator.ts b/packages/playwright-core/src/client/locator.ts
index 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.ts
index 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.ts
index 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.ts
index 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' | 'r
key += ` [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.ts
index 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.ts
index 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-globals
readonly 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.ts
index 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.ts
index 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 the
diff --git a/packages/playwright-mcp/src/tools/snapshot.ts b/packages/playwright-mcp/src/tools/snapshot.ts
index 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.ts
index 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.yml
index 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.ts
index 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');
+});