Skip to content

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

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.md
index 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.49
diff --git a/docs/src/release-notes-csharp.md b/docs/src/release-notes-csharp.md
index 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 Changes
diff --git a/docs/src/release-notes-java.md b/docs/src/release-notes-java.md
index 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 Changes
diff --git a/docs/src/release-notes-js.md b/docs/src/release-notes-js.md
index 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 Changes
diff --git a/docs/src/release-notes-python.md b/docs/src/release-notes-python.md
index 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 Changes
diff --git a/packages/injected/src/ariaSnapshot.ts b/packages/injected/src/ariaSnapshot.ts
index 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, 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
index 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.ts
index 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.ts
index 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 the
diff --git a/packages/playwright-core/src/client/locator.ts b/packages/playwright-core/src/client/locator.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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 the
diff --git a/packages/protocol/src/channels.d.ts b/packages/protocol/src/channels.d.ts
index 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.yml
index 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: string
diff --git a/tests/page/page-aria-snapshot.spec.ts b/tests/page/page-aria-snapshot.spec.ts
index 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]
`);