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: make refs & emitGeneric private for mcp (#35888)
Pavel Feldmanf89d0ae870cc
diff --git a/docs/src/api/class-locator.md b/docs/src/api/class-locator.mdindex 15943f1a42..8fbd60651c 100644--- a/docs/src/api/class-locator.md+++ b/docs/src/api/class-locator.md@@ -206,19 +206,6 @@ 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]>--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/docs/src/release-notes-csharp.md b/docs/src/release-notes-csharp.mdindex d72ab970de..79fcfcde14 100644--- a/docs/src/release-notes-csharp.md+++ b/docs/src/release-notes-csharp.md@@ -30,7 +30,7 @@ toc_max_heading_level: 2### Miscellaneous- New option [`option: APIRequest.newContext.maxRedirects`] in [`method: APIRequest.newContext`] to control the maximum number of redirects.-- New option [`option: Locator.ariaSnapshot.ref`] in [`method: Locator.ariaSnapshot`] to generate reference for each element in the snapshot which can later be used to locate the element.+- New option `ref` in [`method: Locator.ariaSnapshot`] to generate reference for each element in the snapshot which can later be used to locate the element.### Breaking Changesdiff --git a/docs/src/release-notes-java.md b/docs/src/release-notes-java.mdindex 00537f7248..0eda486352 100644--- a/docs/src/release-notes-java.md+++ b/docs/src/release-notes-java.md@@ -30,7 +30,7 @@ toc_max_heading_level: 2### Miscellaneous- New option [`option: APIRequest.newContext.maxRedirects`] in [`method: APIRequest.newContext`] to control the maximum number of redirects.-- New option [`option: Locator.ariaSnapshot.ref`] in [`method: Locator.ariaSnapshot`] to generate reference for each element in the snapshot which can later be used to locate the element.+- New option `ref` in [`method: Locator.ariaSnapshot`] to generate reference for each element in the snapshot which can later be used to locate the element.### Breaking Changesdiff --git a/docs/src/release-notes-js.md b/docs/src/release-notes-js.mdindex b2ec57c24c..b6adcaffdd 100644--- a/docs/src/release-notes-js.md+++ b/docs/src/release-notes-js.md@@ -38,7 +38,7 @@ import LiteYouTube from '@site/src/components/LiteYouTube';### Miscellaneous- New option [`option: APIRequest.newContext.maxRedirects`] in [`method: APIRequest.newContext`] to control the maximum number of redirects.-- New option [`option: Locator.ariaSnapshot.ref`] in [`method: Locator.ariaSnapshot`] to generate reference for each element in the snapshot which can later be used to locate the element.+- New option `ref` in [`method: Locator.ariaSnapshot`] to generate reference for each element in the snapshot which can later be used to locate the element.- HTML reporter now supports *NOT filtering* via `!@my-tag` or `!my-file.spec.ts` or `!p:my-project`.### Breaking Changesdiff --git a/docs/src/release-notes-python.md b/docs/src/release-notes-python.mdindex a2228139d2..24485c74a0 100644--- a/docs/src/release-notes-python.md+++ b/docs/src/release-notes-python.md@@ -30,7 +30,7 @@ toc_max_heading_level: 2### Miscellaneous- New option [`option: APIRequest.newContext.maxRedirects`] in [`method: APIRequest.newContext`] to control the maximum number of redirects.-- New option [`option: Locator.ariaSnapshot.ref`] in [`method: Locator.ariaSnapshot`] to generate reference for each element in the snapshot which can later be used to locate the element.+- New option `ref` in [`method: Locator.ariaSnapshot`] to generate reference for each element in the snapshot which can later be used to locate the element.### Breaking Changesdiff --git a/packages/injected/src/ariaSnapshot.ts b/packages/injected/src/ariaSnapshot.tsindex d3fc5ab031..43a79f824d 100644--- a/packages/injected/src/ariaSnapshot.ts+++ b/packages/injected/src/ariaSnapshot.ts@@ -40,7 +40,7 @@ export type AriaSnapshot = {ids: Map<Element, number>;};-export function generateAriaTree(rootElement: Element, generation: number, options?: { emitGeneric?: boolean }): AriaSnapshot {+export function generateAriaTree(rootElement: Element, generation: number, options?: { forAI?: boolean }): AriaSnapshot {const visited = new Set<Node>();const snapshot: AriaSnapshot = {@@ -147,11 +147,11 @@ export function generateAriaTree(rootElement: Element, generation: number, optioreturn snapshot;}-function toAriaNode(element: Element, options?: { emitGeneric?: boolean }): AriaNode | null {+function toAriaNode(element: Element, options?: { forAI?: boolean }): AriaNode | null {if (element.nodeName === 'IFRAME')return { role: 'iframe', name: '', children: [], props: {}, element, box: box(element), receivesPointerEvents: true };- const defaultRole = options?.emitGeneric ? 'generic' : null;+ const defaultRole = options?.forAI ? 'generic' : null;const role = roleUtils.getAriaRole(element) ?? defaultRole;if (!role || role === 'presentation' || role === 'none')return null;@@ -363,7 +363,7 @@ function matchesNodeDeep(root: AriaNode, template: AriaTemplateNode, collectAll:return results;}-export function renderAriaTree(ariaSnapshot: AriaSnapshot, options?: { mode?: 'raw' | 'regex', ref?: boolean }): string {+export function renderAriaTree(ariaSnapshot: AriaSnapshot, options?: { mode?: 'raw' | 'regex', forAI?: boolean }): string {const lines: string[] = [];const includeText = options?.mode === 'regex' ? textContributesInfo : () => true;const renderString = options?.mode === 'regex' ? convertToBestGuessRegex : (str: string) => str;@@ -402,7 +402,7 @@ export function renderAriaTree(ariaSnapshot: AriaSnapshot, options?: { mode?: 'rkey += ` [pressed]`;if (ariaNode.selected === true)key += ` [selected]`;- if (options?.ref && canRef(ariaNode)) {+ if (options?.forAI && canRef(ariaNode)) {const id = ariaSnapshot.ids.get(ariaNode.element);if (id)key += ` [ref=s${ariaSnapshot.generation}e${id}]`;diff --git a/packages/injected/src/consoleApi.ts b/packages/injected/src/consoleApi.tsindex 592fe329cb..e35c5ef950 100644--- a/packages/injected/src/consoleApi.ts+++ b/packages/injected/src/consoleApi.ts@@ -91,7 +91,7 @@ export 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?: { ref?: boolean }) => {+ ariaSnapshot: (element?: Element, options?: { forAI?: boolean }) => {return this._injectedScript.ariaSnapshot(element || this._injectedScript.document.body, options);},resume: () => this._resume(),diff --git a/packages/injected/src/injectedScript.ts b/packages/injected/src/injectedScript.tsindex 553af7b832..ba7c9fb81f 100644--- a/packages/injected/src/injectedScript.ts+++ b/packages/injected/src/injectedScript.ts@@ -297,7 +297,7 @@ export class InjectedScript {return new Set<Element>(result.map(r => r.element));}- ariaSnapshot(node: Node, options?: { mode?: 'raw' | 'regex', ref?: boolean, emitGeneric?: boolean }): string {+ ariaSnapshot(node: Node, options?: { mode?: 'raw' | 'regex', forAI?: 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;diff --git a/packages/playwright-client/types/types.d.ts b/packages/playwright-client/types/types.d.tsindex a42adb176e..f9a1e6d7fb 100644--- a/packages/playwright-client/types/types.d.ts+++ b/packages/playwright-client/types/types.d.ts@@ -12500,17 +12500,6 @@ 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.- */- 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 b431d7a317..be42ffc60e 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?: { ref?: boolean, emitGeneric?: boolean, _mode?: 'raw' | 'regex' } & TimeoutOptions): Promise<string> {- const result = await this._frame._channel.ariaSnapshot({ ...options, mode: options?._mode, selector: this._selector });+ async ariaSnapshot(options?: { _forAI?: boolean } & TimeoutOptions): Promise<string> {+ const result = await this._frame._channel.ariaSnapshot({ ...options, forAI: options?._forAI, selector: this._selector });return result.snapshot;}diff --git a/packages/playwright-core/src/protocol/validator.ts b/packages/playwright-core/src/protocol/validator.tsindex fd824e12a5..a172ab90da 100644--- a/packages/playwright-core/src/protocol/validator.ts+++ b/packages/playwright-core/src/protocol/validator.ts@@ -1484,9 +1484,7 @@ scheme.FrameAddStyleTagResult = tObject({});scheme.FrameAriaSnapshotParams = tObject({selector: tString,- ref: tOptional(tBoolean),- emitGeneric: tOptional(tBoolean),- mode: tOptional(tEnum(['raw', 'regex'])),+ forAI: tOptional(tBoolean),timeout: tOptional(tNumber),});scheme.FrameAriaSnapshotResult = tObject({diff --git a/packages/playwright-core/src/server/dom.ts b/packages/playwright-core/src/server/dom.tsindex 270ca4de54..a047680092 100644--- a/packages/playwright-core/src/server/dom.ts+++ b/packages/playwright-core/src/server/dom.ts@@ -811,7 +811,7 @@ export class ElementHandle<T extends Node = Node> extends js.JSHandle<T> {return this._page.delegate.getBoundingBox(this);}- async ariaSnapshot(options: { ref?: boolean, emitGeneric?: boolean, mode?: 'raw' | 'regex' }): Promise<string> {+ async ariaSnapshot(options: { forAI?: boolean }): 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 1cef4d7b15..b45bba2fb8 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, emitGeneric?: boolean, mode?: 'raw' | 'regex' } & types.TimeoutOptions = {}): Promise<string> {+ async ariaSnapshot(metadata: CallMetadata, selector: string, options: { forAI?: boolean } & 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 a42adb176e..f9a1e6d7fb 100644--- a/packages/playwright-core/types/types.d.ts+++ b/packages/playwright-core/types/types.d.ts@@ -12500,17 +12500,6 @@ 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.- */- 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/protocol/src/channels.d.ts b/packages/protocol/src/channels.d.tsindex ac8dfbf6e9..464abd5f3c 100644--- a/packages/protocol/src/channels.d.ts+++ b/packages/protocol/src/channels.d.ts@@ -2695,15 +2695,11 @@ export type FrameAddStyleTagResult = {};export type FrameAriaSnapshotParams = {selector: string,- ref?: boolean,- emitGeneric?: boolean,- mode?: 'raw' | 'regex',+ forAI?: boolean,timeout?: number,};export type FrameAriaSnapshotOptions = {- ref?: boolean,- emitGeneric?: boolean,- mode?: 'raw' | 'regex',+ forAI?: boolean,timeout?: number,};export type FrameAriaSnapshotResult = {diff --git a/packages/protocol/src/protocol.yml b/packages/protocol/src/protocol.ymlindex 310020baf9..605e87d252 100644--- a/packages/protocol/src/protocol.yml+++ b/packages/protocol/src/protocol.yml@@ -1976,13 +1976,7 @@ Frame:ariaSnapshot:parameters:selector: string- ref: boolean?- emitGeneric: boolean?- mode:- type: enum?- literals:- - raw- - regex+ forAI: boolean?timeout: number?returns:snapshot: stringdiff --git a/tests/page/page-aria-snapshot.spec.ts b/tests/page/page-aria-snapshot.spec.tsindex ca3c941096..87cc91796d 100644--- a/tests/page/page-aria-snapshot.spec.ts+++ b/tests/page/page-aria-snapshot.spec.ts@@ -41,6 +41,8 @@ const expect = baseExpect.extend({}});+const forAI = { _forAI: true } as any;+function unshift(snapshot: string): string {const lines = snapshot.split('\n');let whitespacePrefixLength = 100;@@ -690,7 +692,7 @@ it('should generate refs', async ({ page }) => {<button>Three</button>`);- const snapshot1 = await page.locator('body').ariaSnapshot({ ref: true });+ const snapshot1 = await page.locator('body').ariaSnapshot(forAI);expect(snapshot1).toContain('- button "One" [ref=s1e3]');expect(snapshot1).toContain('- button "Two" [ref=s1e4]');expect(snapshot1).toContain('- button "Three" [ref=s1e5]');@@ -699,7 +701,7 @@ it('should generate refs', async ({ page }) => {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 });+ const snapshot2 = await page.locator('body').ariaSnapshot(forAI);expect(snapshot2).toContain('- button "One" [ref=s2e3]');await expect(page.locator('aria-ref=s2e3')).toHaveText('One');@@ -713,7 +715,7 @@ it('should list iframes', async ({ page }) => {<iframe name="foo" src="data:text/html,<h1>World</h1>">`);- const snapshot1 = await page.locator('body').ariaSnapshot({ ref: true });+ const snapshot1 = await page.locator('body').ariaSnapshot(forAI);expect(snapshot1).toContain('- iframe');const frameSnapshot = await page.frameLocator(`iframe`).locator('body').ariaSnapshot();@@ -724,7 +726,7 @@ it('ref mode can be used to stitch all frame snapshots', async ({ page, server }await page.goto(server.PREFIX + '/frames/nested-frames.html');async function allFrameSnapshot(frame: Page | FrameLocator): Promise<string> {- const snapshot = await frame.locator('body').ariaSnapshot({ ref: true });+ const snapshot = await frame.locator('body').ariaSnapshot(forAI);const lines = snapshot.split('\n');const result = [];for (const line of lines) {@@ -746,11 +748,11 @@ it('ref mode can be used to stitch all frame snapshots', async ({ page, server }expect(await allFrameSnapshot(page)).toContainYaml(`- iframe [ref=s1e3]:- iframe [ref=s1e3]:- - text: Hi, I'm frame+ - generic [ref=s1e3]: Hi, I'm frame- iframe [ref=s1e4]:- - text: Hi, I'm frame+ - generic [ref=s1e3]: Hi, I'm frame- iframe [ref=s1e4]:- - text: Hi, I'm frame+ - generic [ref=s1e3]: Hi, I'm frame`);});@@ -761,11 +763,12 @@ it('should not generate refs for hidden elements', async ({ page }) => {<button>Three</button>`);- const snapshot = await page.locator('body').ariaSnapshot({ ref: true });+ const snapshot = await page.locator('body').ariaSnapshot(forAI);expect(snapshot).toContainYaml(`- - button "One" [ref=s1e3]- - button "Two"- - button "Three" [ref=s1e5]+ - generic [ref=s1e2]:+ - button "One" [ref=s1e3]+ - button "Two"+ - button "Three" [ref=s1e5]`);});@@ -792,13 +795,16 @@ it('should not generate refs for elements with pointer-events:none', async ({ pa</div>`);- const snapshot = await page.locator('body').ariaSnapshot({ ref: true });+ const snapshot = await page.locator('body').ariaSnapshot(forAI);expect(snapshot).toContainYaml(`- - button "no-ref"- - button "with-ref" [ref=s1e5]- - button "with-ref" [ref=s1e8]- - button "with-ref" [ref=s1e11]- - button "no-ref"+ - generic [ref=s1e2]:+ - button "no-ref"+ - button "with-ref" [ref=s1e5]+ - button "with-ref" [ref=s1e8]+ - button "with-ref" [ref=s1e11]+ - generic [ref=s1e12]:+ - generic:+ - button "no-ref"`);});@@ -833,7 +839,7 @@ it('emit generic roles for nodes w/o roles', async ({ page }) => {</div>`);- const snapshot = await page.locator('body').ariaSnapshot({ ref: true, emitGeneric: true });+ const snapshot = await page.locator('body').ariaSnapshot(forAI);expect(snapshot).toContainYaml(`- generic [ref=s1e5]:@@ -859,7 +865,7 @@ it('should collapse generic nodes', async ({ page }) => {</div>`);- const snapshot = await page.locator('body').ariaSnapshot({ ref: true, emitGeneric: true });+ const snapshot = await page.locator('body').ariaSnapshot(forAI);expect(snapshot).toContainYaml(`- button \"Button\" [ref=s1e6]`);