chore: make refs & emitGeneric private for mcp

pavelfeldman · pavelfeldman · commit 05cfaf47902d · 2025-05-07T18:03:25.000-07:00
diff --git 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.49
 
diff --git 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 Changes
 
diff --git 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 Changes
 
diff --git 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 Changes
diff --git 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 Changes
 
diff --git 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, optio
   return 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?: 'r
       key += ` [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.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.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.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 the
diff --git 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.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.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.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.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 the
diff --git 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.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: string
diff --git 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]
   `);

Original file line number	Diff line number	Diff line change
`@@ -297,7 +297,7 @@ export class InjectedScript {`
`297`	`297`	`return new Set<Element>(result.map(r => r.element));`
`298`	`298`	`}`
`299`	`299`
`300`		`- ariaSnapshot(node: Node, options?: { mode?: 'raw' \| 'regex', ref?: boolean, emitGeneric?: boolean }): string {`
	`300`	`+ ariaSnapshot(node: Node, options?: { mode?: 'raw' \| 'regex', forAI?: boolean }): string {`
`301`	`301`	`if (node.nodeType !== Node.ELEMENT_NODE)`
`302`	`302`	`throw this.createStacklessError('Can only capture aria snapshot of Element nodes.');`
`303`	`303`	`const generation = (this._lastAriaSnapshot?.generation \|\| 0) + 1;`
Original file line number	Diff line number	Diff line change
`@@ -303,8 +303,8 @@ export class Locator implements api.Locator {`
`303`	`303`	`return await this._withElement((h, timeout) => h.screenshot({ ...options, mask, timeout }), options.timeout);`
`304`	`304`	`}`
`305`	`305`
`306`		`- async ariaSnapshot(options?: { ref?: boolean, emitGeneric?: boolean, _mode?: 'raw' \| 'regex' } & TimeoutOptions): Promise<string> {`
`307`		`- const result = await this._frame._channel.ariaSnapshot({ ...options, mode: options?._mode, selector: this._selector });`
	`306`	`+ async ariaSnapshot(options?: { _forAI?: boolean } & TimeoutOptions): Promise<string> {`
	`307`	`+ const result = await this._frame._channel.ariaSnapshot({ ...options, forAI: options?._forAI, selector: this._selector });`
`308`	`308`	`return result.snapshot;`
`309`	`309`	`}`
`310`	`310`