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: merge snapshotForAI() into ariaSnapshot() (#39759)
Dmitry Gozmanc45b0d5ef6a8
diff --git a/docs/src/api/class-locator.md b/docs/src/api/class-locator.mdindex 8adf3be214..da7139618d 100644--- a/docs/src/api/class-locator.md+++ b/docs/src/api/class-locator.md@@ -206,12 +206,25 @@ Below is the HTML markup and the respective ARIA snapshot:- link "About"```+### option: Locator.ariaSnapshot.format+* since: v1.59+- `format` <[AriaSnapshotFormat]<"ai"|"default">>++When set to `"ai"`, returns a snapshot optimized for AI consumption with element references.+Defaults to `"default"`.+### option: Locator.ariaSnapshot.timeout = %%-input-timeout-%%* since: v1.49### option: Locator.ariaSnapshot.timeout = %%-input-timeout-js-%%* since: v1.49+### option: Locator.ariaSnapshot.depth+* since: v1.59+- `depth` <[int]>++When specified, limits the depth of the snapshot.+## async method: Locator.blur* since: v1.28@@ -2492,23 +2505,6 @@ This method expects [Locator] to point to an### option: Locator.setInputFiles.timeout = %%-input-timeout-js-%%* since: v1.14-## async method: Locator.snapshotForAI-* since: v1.59-- returns: <[string]>--Returns an accessibility snapshot of the element's subtree optimized for AI consumption.--### option: Locator.snapshotForAI.timeout = %%-input-timeout-%%-* since: v1.59--### option: Locator.snapshotForAI.timeout = %%-input-timeout-js-%%-* since: v1.59--### option: Locator.snapshotForAI.depth-* since: v1.59-- `depth` <[int]>--When specified, limits the depth of the snapshot.## async method: Locator.tap* since: v1.14diff --git a/docs/src/api/class-page.md b/docs/src/api/class-page.mdindex 9978466b1b..d5194a48f9 100644--- a/docs/src/api/class-page.md+++ b/docs/src/api/class-page.md@@ -4211,34 +4211,40 @@ Page width in pixels.Page height in pixels.-## async method: Page.snapshotForAI+## async method: Page.ariaSnapshot* since: v1.59- returns: <[string]>-Returns an accessibility snapshot of the page optimized for AI consumption.+Captures the aria snapshot of the page. Read more about [aria snapshots](../aria-snapshots.md).-### option: Page.snapshotForAI.timeout = %%-input-timeout-%%+### option: Page.ariaSnapshot.format* since: v1.59+- `format` <[AriaSnapshotFormat]<"ai"|"default">>-### option: Page.snapshotForAI.timeout = %%-input-timeout-js-%%+When set to `"ai"`, returns a snapshot optimized for AI consumption with element references. Defaults to `"default"`.++### option: Page.ariaSnapshot.timeout = %%-input-timeout-%%+* since: v1.59++### option: Page.ariaSnapshot.timeout = %%-input-timeout-js-%%* since: v1.59-### option: Page.snapshotForAI.track+### option: Page.ariaSnapshot.track* since: v1.59- `track` <[string]>When specified, enables incremental snapshots. Subsequent calls with the same track name willtrack changes between calls.-### option: Page.snapshotForAI.mode+### option: Page.ariaSnapshot.mode* since: v1.59-- `mode` <[string]>+- `mode` <[AriaSnapshotContent]<"incremental"|"full">>-When set to `"incremental"` and [`option: Page.snapshotForAI.track`] is specified, returns an+When set to `"incremental"` and [`option: Page.ariaSnapshot.track`] is specified, returns anincremental snapshot containing only changes since the last call with the same track name.Defaults to `"full"`.-### option: Page.snapshotForAI.depth+### option: Page.ariaSnapshot.depth* since: v1.59- `depth` <[int]>diff --git a/packages/injected/src/ariaSnapshot.ts b/packages/injected/src/ariaSnapshot.tsindex b661c7fdc6..4bb00a1705 100644--- a/packages/injected/src/ariaSnapshot.ts+++ b/packages/injected/src/ariaSnapshot.ts@@ -37,7 +37,7 @@ type AriaRef = {let lastRef = 0;export type AriaTreeOptions = {- mode: 'ai' | 'expect' | 'codegen' | 'autoexpect';+ format: 'ai' | 'default' | 'codegen' | 'autoexpect';refPrefix?: string;doNotRenderActive?: boolean;depth?: number;@@ -54,7 +54,7 @@ type InternalOptions = {};function toInternalOptions(options: AriaTreeOptions): InternalOptions {- if (options.mode === 'ai') {+ if (options.format === 'ai') {// For AI consumption.return {visibility: 'ariaOrVisible',@@ -65,11 +65,11 @@ function toInternalOptions(options: AriaTreeOptions): InternalOptions {renderCursorPointer: true,};}- if (options.mode === 'autoexpect') {+ if (options.format === 'autoexpect') {// To auto-generate assertions on visible elements.return { visibility: 'ariaAndVisible', refs: 'none' };}- if (options.mode === 'codegen') {+ if (options.format === 'codegen') {// To generate aria assertion with regex heurisitcs.return { visibility: 'aria', refs: 'none', renderStringsAsRegex: true };}@@ -387,19 +387,19 @@ export type MatcherReceived = {};export function matchesExpectAriaTemplate(rootElement: Element, template: aria.AriaTemplateNode): { matches: aria.AriaNode[], received: MatcherReceived } {- const snapshot = generateAriaTree(rootElement, { mode: 'expect' });+ const snapshot = generateAriaTree(rootElement, { format: 'default' });const matches = matchesNodeDeep(snapshot.root, template, false, false);return {matches,received: {- raw: renderAriaTree(snapshot, { mode: 'expect' }),- regex: renderAriaTree(snapshot, { mode: 'codegen' }),+ raw: renderAriaTree(snapshot, { format: 'default' }),+ regex: renderAriaTree(snapshot, { format: 'codegen' }),}};}export function getAllElementsMatchingExpectAriaTemplate(rootElement: Element, template: aria.AriaTemplateNode): Element[] {- const root = generateAriaTree(rootElement, { mode: 'expect' }).root;+ const root = generateAriaTree(rootElement, { format: 'default' }).root;const matches = matchesNodeDeep(root, template, true, false);return matches.map(n => ariaNodeElement(n));}diff --git a/packages/injected/src/consoleApi.ts b/packages/injected/src/consoleApi.tsindex 2406c2e894..38967e3bda 100644--- a/packages/injected/src/consoleApi.ts+++ b/packages/injected/src/consoleApi.ts@@ -93,7 +93,7 @@ export class ConsoleAPI {selector: (element: Element) => this._selector(element),generateLocator: (element: Element, language?: Language) => this._generateLocator(element, language),ariaSnapshot: (element?: Element, options?: AriaTreeOptions) => {- return this._injectedScript.ariaSnapshot(element || this._injectedScript.document.body, options || { mode: 'expect' });+ return this._injectedScript.ariaSnapshot(element || this._injectedScript.document.body, options || { format: 'default' });},resume: () => this._resume(),...new Locator(this._injectedScript, ''),diff --git a/packages/injected/src/injectedScript.ts b/packages/injected/src/injectedScript.tsindex 416ef12ea6..89dbad7bdc 100644--- a/packages/injected/src/injectedScript.ts+++ b/packages/injected/src/injectedScript.ts@@ -323,8 +323,8 @@ export class InjectedScript {}ariaSnapshotForRecorder(): { ariaSnapshot: string, refs: Map<Element, string> } {- const tree = generateAriaTree(this.document.body, { mode: 'ai' });- const ariaSnapshot = renderAriaTree(tree, { mode: 'ai' });+ const tree = generateAriaTree(this.document.body, { format: 'ai' });+ const ariaSnapshot = renderAriaTree(tree, { format: 'ai' });return { ariaSnapshot, refs: tree.refs };}diff --git a/packages/injected/src/recorder/recorder.ts b/packages/injected/src/recorder/recorder.tsindex 40dbf7df80..724cb2511e 100644--- a/packages/injected/src/recorder/recorder.ts+++ b/packages/injected/src/recorder/recorder.ts@@ -1064,7 +1064,7 @@ class TextAssertionTool implements RecorderTool {name: 'assertSnapshot',selector: this._hoverHighlight.selector,signals: [],- ariaSnapshot: this._recorder.injectedScript.ariaSnapshot(target, { mode: 'codegen' }),+ ariaSnapshot: this._recorder.injectedScript.ariaSnapshot(target, { format: 'codegen' }),};} else {const generated = this._recorder.injectedScript.generateSelector(target, { testIdAttributeName: this._recorder.state.testIdAttributeName, forTextExpect: true });@@ -1698,7 +1698,7 @@ export class Recorder {private _captureAutoExpectSnapshot() {const documentElement = this.injectedScript.document.documentElement;- return documentElement ? this.injectedScript.utils.generateAriaTree(documentElement, { mode: 'autoexpect' }) : undefined;+ return documentElement ? this.injectedScript.utils.generateAriaTree(documentElement, { format: 'autoexpect' }) : undefined;}async performAction(action: actions.PerformOnRecordAction) {@@ -1723,7 +1723,7 @@ export class Recorder {}elementPicked(selector: string, model: HighlightModel) {- const ariaSnapshot = this.injectedScript.ariaSnapshot(model.elements[0], { mode: 'expect' });+ const ariaSnapshot = this.injectedScript.ariaSnapshot(model.elements[0], { format: 'default' });void this._delegate.elementPicked?.({ selector, ariaSnapshot });}}diff --git a/packages/playwright-client/types/types.d.ts b/packages/playwright-client/types/types.d.tsindex 2c06394479..6d792fc9a2 100644--- a/packages/playwright-client/types/types.d.ts+++ b/packages/playwright-client/types/types.d.ts@@ -2099,6 +2099,44 @@ export interface Page {url?: string;}): Promise<ElementHandle>;+ /**+ * Captures the aria snapshot of the page. Read more about [aria snapshots](https://playwright.dev/docs/aria-snapshots).+ * @param options+ */+ ariaSnapshot(options?: {+ /**+ * When specified, limits the depth of the snapshot.+ */+ depth?: number;++ /**+ * When set to `"ai"`, returns a snapshot optimized for AI consumption with element references. Defaults to+ * `"default"`.+ */+ format?: "ai"|"default";++ /**+ * When set to `"incremental"` and+ * [`track`](https://playwright.dev/docs/api/class-page#page-aria-snapshot-option-track) is specified, returns an+ * incremental snapshot containing only changes since the last call with the same track name. Defaults to `"full"`.+ */+ mode?: "incremental"|"full";++ /**+ * 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+ * [browserContext.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-browsercontext#browser-context-set-default-timeout)+ * or [page.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-page#page-set-default-timeout) methods.+ */+ timeout?: number;++ /**+ * When specified, enables incremental snapshots. Subsequent calls with the same track name will track changes between+ * calls.+ */+ track?: string;+ }): Promise<string>;+/*** Brings page to front (activates tab).*/@@ -4515,38 +4553,6 @@ export interface Page {height: number;}): Promise<void>;- /**- * Returns an accessibility snapshot of the page optimized for AI consumption.- * @param options- */- snapshotForAI(options?: {- /**- * When specified, limits the depth of the snapshot.- */- depth?: number;-- /**- * When set to `"incremental"` and- * [`track`](https://playwright.dev/docs/api/class-page#page-snapshot-for-ai-option-track) is specified, returns an- * incremental snapshot containing only changes since the last call with the same track name. Defaults to `"full"`.- */- mode?: string;-- /**- * 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- * [browserContext.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-browsercontext#browser-context-set-default-timeout)- * or [page.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-page#page-set-default-timeout) methods.- */- timeout?: number;-- /**- * When specified, enables incremental snapshots. Subsequent calls with the same track name will track changes between- * calls.- */- track?: string;- }): Promise<string>;-/*** **NOTE** Use locator-based [locator.tap([options])](https://playwright.dev/docs/api/class-locator#locator-tap) instead. Read* more about [locators](https://playwright.dev/docs/locators).@@ -12772,6 +12778,17 @@ export interface Locator {* @param options*/ariaSnapshot(options?: {+ /**+ * When specified, limits the depth of the snapshot.+ */+ depth?: number;++ /**+ * When set to `"ai"`, returns a snapshot optimized for AI consumption with element references. Defaults to+ * `"default"`.+ */+ format?: "ai"|"default";+/*** 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@@ -14680,25 +14697,6 @@ export interface Locator {timeout?: number;}): Promise<void>;- /**- * Returns an accessibility snapshot of the element's subtree optimized for AI consumption.- * @param options- */- snapshotForAI(options?: {- /**- * When specified, limits the depth of the snapshot.- */- depth?: number;-- /**- * 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- * [browserContext.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-browsercontext#browser-context-set-default-timeout)- * or [page.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-page#page-set-default-timeout) methods.- */- timeout?: number;- }): Promise<string>;-/*** Perform a tap gesture on the element matching the locator. For examples of emulating other gestures by manually* dispatching touch events, see the [emulating legacy touch events](https://playwright.dev/docs/touch-events) page.diff --git a/packages/playwright-core/src/client/locator.ts b/packages/playwright-core/src/client/locator.tsindex 4d29ce7dcf..29f2f66e09 100644--- a/packages/playwright-core/src/client/locator.ts+++ b/packages/playwright-core/src/client/locator.ts@@ -312,8 +312,8 @@ export class Locator implements api.Locator {return await this._withElement((h, timeout) => h.screenshot({ ...options, mask, timeout }), { title: 'Screenshot', timeout: options.timeout });}- async ariaSnapshot(options?: TimeoutOptions): Promise<string> {- const result = await this._frame._channel.ariaSnapshot({ ...options, selector: this._selector, timeout: this._frame._timeout(options) });+ async ariaSnapshot(options: TimeoutOptions & { format?: 'ai' | 'default', depth?: number } = {}): Promise<string> {+ const result = await this._frame._page!._channel.ariaSnapshot({ timeout: this._frame._timeout(options), format: options.format, selector: this._selector, depth: options.depth });return result.snapshot;}@@ -378,10 +378,6 @@ export class Locator implements api.Locator {await this._frame._channel.waitForSelector({ selector: this._selector, strict: true, omitReturnValue: true, ...options, timeout: this._frame._timeout(options) });}- async snapshotForAI(options: TimeoutOptions & { depth?: number } = {}): Promise<string> {- const result = await this._frame._page!._channel.snapshotForAI({ timeout: this._frame._timeout(options), selector: this._selector, depth: options.depth });- return result.snapshot;- }async _expect(expression: string, options: FrameExpectParams): Promise<{ matches: boolean, received?: any, log?: string[], timedOut?: boolean, errorMessage?: string }> {return this._frame._expect(expression, {diff --git a/packages/playwright-core/src/client/page.ts b/packages/playwright-core/src/client/page.tsindex 05f951ac49..ca36eb25ec 100644--- a/packages/playwright-core/src/client/page.ts+++ b/packages/playwright-core/src/client/page.ts@@ -851,8 +851,8 @@ export class Page extends ChannelOwner<channels.PageChannel> implements api.Pagereturn result.pdf;}- async snapshotForAI(options: TimeoutOptions & { track?: string, mode?: 'full' | 'incremental', depth?: number } = {}): Promise<string> {- const result = await this._channel.snapshotForAI({ timeout: this._timeoutSettings.timeout(options), track: options.track, mode: options.mode, depth: options.depth });+ async ariaSnapshot(options: TimeoutOptions & { format?: 'ai' | 'default', track?: string, mode?: 'full' | 'incremental', depth?: number } = {}): Promise<string> {+ const result = await this._channel.ariaSnapshot({ timeout: this._timeoutSettings.timeout(options), format: options.format, track: options.track, mode: options.mode, depth: options.depth });return result.snapshot;}diff --git a/packages/playwright-core/src/protocol/validator.ts b/packages/playwright-core/src/protocol/validator.tsindex b94e90e840..479b1b2fd4 100644--- a/packages/playwright-core/src/protocol/validator.ts+++ b/packages/playwright-core/src/protocol/validator.ts@@ -1494,14 +1494,15 @@ scheme.PageRequestsParams = tOptional(tObject({}));scheme.PageRequestsResult = tObject({requests: tArray(tChannel(['Request'])),});-scheme.PageSnapshotForAIParams = tObject({+scheme.PageAriaSnapshotParams = tObject({+ format: tOptional(tEnum(['ai', 'default'])),track: tOptional(tString),mode: tOptional(tEnum(['full', 'incremental'])),selector: tOptional(tString),depth: tOptional(tInt),timeout: tFloat,});-scheme.PageSnapshotForAIResult = tObject({+scheme.PageAriaSnapshotResult = tObject({snapshot: tString,});scheme.PageStartJSCoverageParams = tObject({@@ -1630,13 +1631,6 @@ scheme.FrameAddStyleTagParams = tObject({scheme.FrameAddStyleTagResult = tObject({element: tChannel(['ElementHandle']),});-scheme.FrameAriaSnapshotParams = tObject({- selector: tString,- timeout: tFloat,-});-scheme.FrameAriaSnapshotResult = tObject({- snapshot: tString,-});scheme.FrameBlurParams = tObject({selector: tString,strict: tOptional(tBoolean),diff --git a/packages/playwright-core/src/server/dispatchers/frameDispatcher.ts b/packages/playwright-core/src/server/dispatchers/frameDispatcher.tsindex dc64740578..d0b93af295 100644--- a/packages/playwright-core/src/server/dispatchers/frameDispatcher.ts+++ b/packages/playwright-core/src/server/dispatchers/frameDispatcher.ts@@ -271,8 +271,4 @@ export class FrameDispatcher extends Dispatcher<Frame, channels.FrameChannel, Brresult.received = serializeResult(result.received);return result;}-- async ariaSnapshot(params: channels.FrameAriaSnapshotParams, progress: Progress): Promise<channels.FrameAriaSnapshotResult> {- return { snapshot: await this._frame.ariaSnapshot(progress, params.selector) };- }}diff --git a/packages/playwright-core/src/server/dispatchers/pageDispatcher.ts b/packages/playwright-core/src/server/dispatchers/pageDispatcher.tsindex 1db511c353..a0e8651366 100644--- a/packages/playwright-core/src/server/dispatchers/pageDispatcher.ts+++ b/packages/playwright-core/src/server/dispatchers/pageDispatcher.ts@@ -344,8 +344,8 @@ export class PageDispatcher extends Dispatcher<Page, channels.PageChannel, Browsreturn { requests: this._page.networkRequests().map(request => RequestDispatcher.from(this.parentScope(), request)) };}- async snapshotForAI(params: channels.PageSnapshotForAIParams, progress: Progress): Promise<channels.PageSnapshotForAIResult> {- return await this._page.snapshotForAI(progress, params);+ async ariaSnapshot(params: channels.PageAriaSnapshotParams, progress: Progress): Promise<channels.PageAriaSnapshotResult> {+ return await this._page.ariaSnapshot(progress, params);}async bringToFront(params: channels.PageBringToFrontParams, progress: Progress): Promise<void> {diff --git a/packages/playwright-core/src/server/dom.ts b/packages/playwright-core/src/server/dom.tsindex de84b41652..e82f381d56 100644--- a/packages/playwright-core/src/server/dom.ts+++ b/packages/playwright-core/src/server/dom.ts@@ -763,10 +763,6 @@ export class ElementHandle<T extends Node = Node> extends js.JSHandle<T> {return this._page.delegate.getBoundingBox(this);}- async ariaSnapshot(): Promise<string> {- return await this.evaluateInUtility(([injected, element]) => injected.ariaSnapshot(element, { mode: 'expect' }), {});- }-async screenshot(progress: Progress, options: ScreenshotOptions): Promise<Buffer> {return await this._page.screenshotter.screenshotElement(progress, this, options);}diff --git a/packages/playwright-core/src/server/frames.ts b/packages/playwright-core/src/server/frames.tsindex 3f7f2cc5fd..ddf782b282 100644--- a/packages/playwright-core/src/server/frames.ts+++ b/packages/playwright-core/src/server/frames.ts@@ -1376,10 +1376,6 @@ export class Frame extends SdkObject<FrameEventMap> {return progress.wait(timeout);}- async ariaSnapshot(progress: Progress, selector: string): Promise<string> {- return await this._retryWithProgressIfNotConnected(progress, selector, { strict: true, performActionPreChecks: true }, handle => progress.race(handle.ariaSnapshot()));- }-async expect(progress: Progress, selector: string | undefined, options: FrameExpectParams): Promise<ExpectResult> {progress.log(`${renderTitleForCall(progress.metadata)}${options.timeoutForLogs ? ` with timeout ${options.timeoutForLogs}ms` : ''}`);const lastIntermediateResult: { received?: any, isSet: boolean, errorMessage?: string } = { isSet: false };diff --git a/packages/playwright-core/src/server/page.ts b/packages/playwright-core/src/server/page.tsindex ff45b15766..0bcbb3e9b8 100644--- a/packages/playwright-core/src/server/page.ts+++ b/packages/playwright-core/src/server/page.ts@@ -886,7 +886,7 @@ export class Page extends SdkObject<PageEventMap> {await Promise.all(this.frames().map(frame => frame.hideHighlight().catch(() => {})));}- async snapshotForAI(progress: Progress, options: { track?: string, mode?: 'full' | 'incremental', doNotRenderActive?: boolean, selector?: string, depth?: number } = {}): Promise<{ snapshot: string }> {+ async ariaSnapshot(progress: Progress, options: { format?: 'ai' | 'default', track?: string, mode?: 'full' | 'incremental', doNotRenderActive?: boolean, selector?: string, depth?: number } = {}): Promise<{ snapshot: string }> {if (options.selector && options.track)throw new Error('Cannot specify both selector and track options');@@ -902,7 +902,7 @@ export class Page extends SdkObject<PageEventMap> {frame = this.mainFrame();}- const result = await snapshotFrameForAI(progress, frame, { ...options, info });+ const result = await ariaSnapshotForFrame(progress, frame, { ...options, info });const snapshot = options.mode === 'incremental' && result.incremental !== undefined ? result.incremental.join('\n') : result.full.join('\n');return { snapshot };}@@ -1048,7 +1048,7 @@ export class InitScript extends DisposableObject {}}-async function snapshotFrameForAI(progress: Progress, frame: frames.Frame, options: { track?: string, doNotRenderActive?: boolean, info?: SelectorInfo, depth?: number } = {}): Promise<{ full: string[], incremental?: string[] }> {+async function ariaSnapshotForFrame(progress: Progress, frame: frames.Frame, options: { format?: 'ai' | 'default', track?: string, doNotRenderActive?: boolean, info?: SelectorInfo, depth?: number } = {}): Promise<{ full: string[], incremental?: string[] }> {// Only await the topmost navigations, inner frames will be empty when racing.const snapshot = await frame.retryWithProgressAndTimeouts(progress, [1000, 2000, 4000, 8000], async continuePolling => {try {@@ -1059,13 +1059,14 @@ async function snapshotFrameForAI(progress: Progress, frame: frames.Frame, optioconst element = injected.querySelector(options.info.parsed, injected.document, options.info.strict);if (!element)return false;- return injected.incrementalAriaSnapshot(element, { mode: 'ai', ...options });+ return injected.incrementalAriaSnapshot(element, options);}const node = injected.document.body;if (!node)return true;- return injected.incrementalAriaSnapshot(node, { mode: 'ai', ...options });+ return injected.incrementalAriaSnapshot(node, options);}, {+ format: options.format ?? 'default',refPrefix: frame.seq ? 'f' + frame.seq : '',track: options.track,doNotRenderActive: options.doNotRenderActive,@@ -1084,7 +1085,7 @@ async function snapshotFrameForAI(progress: Progress, frame: frames.Frame, optio}});- const childSnapshotPromises = snapshot.iframeRefs.map(ref => snapshotFrameRefForAI(progress, frame, ref, options));+ const childSnapshotPromises = snapshot.iframeRefs.map(ref => ariaSnapshotFrameRef(progress, frame, ref, options));const childSnapshots = await Promise.all(childSnapshotPromises);const full = [];@@ -1118,14 +1119,14 @@ async function snapshotFrameForAI(progress: Progress, frame: frames.Frame, optioreturn { full, incremental };}-async function snapshotFrameRefForAI(progress: Progress, parentFrame: frames.Frame, frameRef: string, options: { track?: string, mode?: 'full' | 'incremental' }): Promise<{ full: string[], incremental?: string[] }> {+async function ariaSnapshotFrameRef(progress: Progress, parentFrame: frames.Frame, frameRef: string, options: { format?: 'ai' | 'default', track?: string, doNotRenderActive?: boolean, mode?: 'full' | 'incremental' }): Promise<{ full: string[], incremental?: string[] }> {const frameSelector = `aria-ref=${frameRef} >> internal:control=enter-frame`;const frameBodySelector = `${frameSelector} >> body`;const child = await progress.race(parentFrame.selectors.resolveFrameForSelector(frameBodySelector, { strict: true }));if (!child)return { full: [] };try {- return await snapshotFrameForAI(progress, child.frame, { ...options, info: undefined });+ return await ariaSnapshotForFrame(progress, child.frame, { ...options, info: undefined });} catch {return { full: [] };}diff --git a/packages/playwright-core/src/tools/backend/tab.ts b/packages/playwright-core/src/tools/backend/tab.tsindex 53d10cc633..8a37f89e1e 100644--- a/packages/playwright-core/src/tools/backend/tab.ts+++ b/packages/playwright-core/src/tools/backend/tab.ts@@ -379,8 +379,8 @@ export class Tab extends EventEmitter<TabEventsInterface> {let tabSnapshot: TabSnapshot | undefined;const modalStates = await this._raceAgainstModalStates(async () => {const ariaSnapshot = selector- ? await this.page.locator(selector).snapshotForAI({ depth })- : await this.page.snapshotForAI({ track: 'response', mode: this._needsFullSnapshot ? 'full' : mode, depth });+ ? await this.page.locator(selector).ariaSnapshot({ format: 'ai', depth })+ : await this.page.ariaSnapshot({ format: 'ai', track: 'response', mode: this._needsFullSnapshot ? 'full' : mode, depth });tabSnapshot = {ariaSnapshot,modalStates: [],diff --git a/packages/playwright-core/src/utils/isomorphic/protocolMetainfo.ts b/packages/playwright-core/src/utils/isomorphic/protocolMetainfo.tsindex 951b109102..a09db6bd60 100644--- a/packages/playwright-core/src/utils/isomorphic/protocolMetainfo.ts+++ b/packages/playwright-core/src/utils/isomorphic/protocolMetainfo.ts@@ -139,7 +139,7 @@ export const methodMetainfo = new Map<string, { internal?: boolean, title?: stri['Page.pageErrors', { title: 'Get page errors', group: 'getter', }],['Page.pdf', { title: 'PDF', }],['Page.requests', { title: 'Get network requests', group: 'getter', }],- ['Page.snapshotForAI', { internal: true, }],+ ['Page.ariaSnapshot', { title: 'Aria snapshot', group: 'getter', }],['Page.startJSCoverage', { title: 'Start JS coverage', group: 'configuration', }],['Page.stopJSCoverage', { title: 'Stop JS coverage', group: 'configuration', }],['Page.startCSSCoverage', { title: 'Start CSS coverage', group: 'configuration', }],@@ -157,7 +157,6 @@ export const methodMetainfo = new Map<string, { internal?: boolean, title?: stri['Frame.evalOnSelectorAll', { title: 'Evaluate', snapshot: true, pausesBeforeAction: true, }],['Frame.addScriptTag', { title: 'Add script tag', snapshot: true, pausesBeforeAction: true, }],['Frame.addStyleTag', { title: 'Add style tag', snapshot: true, pausesBeforeAction: true, }],- ['Frame.ariaSnapshot', { title: 'Aria snapshot', snapshot: true, pausesBeforeAction: true, }],['Frame.blur', { title: 'Blur', slowMo: true, snapshot: true, pausesBeforeAction: true, }],['Frame.check', { title: 'Check', slowMo: true, snapshot: true, pausesBeforeInput: true, }],['Frame.click', { title: 'Click', slowMo: true, snapshot: true, pausesBeforeInput: true, }],diff --git a/packages/playwright-core/types/types.d.ts b/packages/playwright-core/types/types.d.tsindex 2c06394479..6d792fc9a2 100644--- a/packages/playwright-core/types/types.d.ts+++ b/packages/playwright-core/types/types.d.ts@@ -2099,6 +2099,44 @@ export interface Page {url?: string;}): Promise<ElementHandle>;+ /**+ * Captures the aria snapshot of the page. Read more about [aria snapshots](https://playwright.dev/docs/aria-snapshots).+ * @param options+ */+ ariaSnapshot(options?: {+ /**+ * When specified, limits the depth of the snapshot.+ */+ depth?: number;++ /**+ * When set to `"ai"`, returns a snapshot optimized for AI consumption with element references. Defaults to+ * `"default"`.+ */+ format?: "ai"|"default";++ /**+ * When set to `"incremental"` and+ * [`track`](https://playwright.dev/docs/api/class-page#page-aria-snapshot-option-track) is specified, returns an+ * incremental snapshot containing only changes since the last call with the same track name. Defaults to `"full"`.+ */+ mode?: "incremental"|"full";++ /**+ * 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+ * [browserContext.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-browsercontext#browser-context-set-default-timeout)+ * or [page.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-page#page-set-default-timeout) methods.+ */+ timeout?: number;++ /**+ * When specified, enables incremental snapshots. Subsequent calls with the same track name will track changes between+ * calls.+ */+ track?: string;+ }): Promise<string>;+/*** Brings page to front (activates tab).*/@@ -4515,38 +4553,6 @@ export interface Page {height: number;}): Promise<void>;- /**- * Returns an accessibility snapshot of the page optimized for AI consumption.- * @param options- */- snapshotForAI(options?: {- /**- * When specified, limits the depth of the snapshot.- */- depth?: number;-- /**- * When set to `"incremental"` and- * [`track`](https://playwright.dev/docs/api/class-page#page-snapshot-for-ai-option-track) is specified, returns an- * incremental snapshot containing only changes since the last call with the same track name. Defaults to `"full"`.- */- mode?: string;-- /**- * 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- * [browserContext.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-browsercontext#browser-context-set-default-timeout)- * or [page.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-page#page-set-default-timeout) methods.- */- timeout?: number;-- /**- * When specified, enables incremental snapshots. Subsequent calls with the same track name will track changes between- * calls.- */- track?: string;- }): Promise<string>;-/*** **NOTE** Use locator-based [locator.tap([options])](https://playwright.dev/docs/api/class-locator#locator-tap) instead. Read* more about [locators](https://playwright.dev/docs/locators).@@ -12772,6 +12778,17 @@ export interface Locator {* @param options*/ariaSnapshot(options?: {+ /**+ * When specified, limits the depth of the snapshot.+ */+ depth?: number;++ /**+ * When set to `"ai"`, returns a snapshot optimized for AI consumption with element references. Defaults to+ * `"default"`.+ */+ format?: "ai"|"default";+/*** 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@@ -14680,25 +14697,6 @@ export interface Locator {timeout?: number;}): Promise<void>;- /**- * Returns an accessibility snapshot of the element's subtree optimized for AI consumption.- * @param options- */- snapshotForAI(options?: {- /**- * When specified, limits the depth of the snapshot.- */- depth?: number;-- /**- * 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- * [browserContext.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-browsercontext#browser-context-set-default-timeout)- * or [page.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-page#page-set-default-timeout) methods.- */- timeout?: number;- }): Promise<string>;-/*** Perform a tap gesture on the element matching the locator. For examples of emulating other gestures by manually* dispatching touch events, see the [emulating legacy touch events](https://playwright.dev/docs/touch-events) page.diff --git a/packages/playwright/src/index.ts b/packages/playwright/src/index.tsindex 2ce170393a..62b815dce7 100644--- a/packages/playwright/src/index.ts+++ b/packages/playwright/src/index.ts@@ -709,7 +709,7 @@ class ArtifactsRecorder {try {// TODO: maybe capture snapshot when the error is created, so it's from the right page and right timeawait page._wrapApiCall(async () => {- this._pageSnapshot = await page.snapshotForAI({ timeout: 5000 });+ this._pageSnapshot = await page.ariaSnapshot({ format: 'ai', timeout: 5000 });}, { internal: true });} catch {}}diff --git a/packages/playwright/src/mcp/test/browserBackend.ts b/packages/playwright/src/mcp/test/browserBackend.tsindex 504891b103..3c30678dcb 100644--- a/packages/playwright/src/mcp/test/browserBackend.ts+++ b/packages/playwright/src/mcp/test/browserBackend.ts@@ -98,7 +98,7 @@ async function generatePausedMessage(testInfo: TestInfoImpl, context: playwrightlines.push(`- Page Snapshot:`,'```yaml',- await page.snapshotForAI(),+ await page.ariaSnapshot({ format: 'ai' }),'```',);}diff --git a/packages/protocol/src/channels.d.ts b/packages/protocol/src/channels.d.tsindex 235003ac0f..0dc226d605 100644--- a/packages/protocol/src/channels.d.ts+++ b/packages/protocol/src/channels.d.ts@@ -2140,7 +2140,7 @@ export interface PageChannel extends PageEventTarget, EventTargetChannel {pageErrors(params: PagePageErrorsParams, progress?: Progress): Promise<PagePageErrorsResult>;pdf(params: PagePdfParams, progress?: Progress): Promise<PagePdfResult>;requests(params?: PageRequestsParams, progress?: Progress): Promise<PageRequestsResult>;- snapshotForAI(params: PageSnapshotForAIParams, progress?: Progress): Promise<PageSnapshotForAIResult>;+ ariaSnapshot(params: PageAriaSnapshotParams, progress?: Progress): Promise<PageAriaSnapshotResult>;startJSCoverage(params: PageStartJSCoverageParams, progress?: Progress): Promise<PageStartJSCoverageResult>;stopJSCoverage(params?: PageStopJSCoverageParams, progress?: Progress): Promise<PageStopJSCoverageResult>;startCSSCoverage(params: PageStartCSSCoverageParams, progress?: Progress): Promise<PageStartCSSCoverageResult>;@@ -2610,20 +2610,22 @@ export type PageRequestsOptions = {};export type PageRequestsResult = {requests: RequestChannel[],};-export type PageSnapshotForAIParams = {+export type PageAriaSnapshotParams = {+ format?: 'ai' | 'default',track?: string,mode?: 'full' | 'incremental',selector?: string,depth?: number,timeout: number,};-export type PageSnapshotForAIOptions = {+export type PageAriaSnapshotOptions = {+ format?: 'ai' | 'default',track?: string,mode?: 'full' | 'incremental',selector?: string,depth?: number,};-export type PageSnapshotForAIResult = {+export type PageAriaSnapshotResult = {snapshot: string,};export type PageStartJSCoverageParams = {@@ -2767,7 +2769,6 @@ export interface FrameChannel extends FrameEventTarget, Channel {evalOnSelectorAll(params: FrameEvalOnSelectorAllParams, progress?: Progress): Promise<FrameEvalOnSelectorAllResult>;addScriptTag(params: FrameAddScriptTagParams, progress?: Progress): Promise<FrameAddScriptTagResult>;addStyleTag(params: FrameAddStyleTagParams, progress?: Progress): Promise<FrameAddStyleTagResult>;- ariaSnapshot(params: FrameAriaSnapshotParams, progress?: Progress): Promise<FrameAriaSnapshotResult>;blur(params: FrameBlurParams, progress?: Progress): Promise<FrameBlurResult>;check(params: FrameCheckParams, progress?: Progress): Promise<FrameCheckResult>;click(params: FrameClickParams, progress?: Progress): Promise<FrameClickResult>;@@ -2873,16 +2874,6 @@ export type FrameAddStyleTagOptions = {export type FrameAddStyleTagResult = {element: ElementHandleChannel,};-export type FrameAriaSnapshotParams = {- selector: string,- timeout: number,-};-export type FrameAriaSnapshotOptions = {--};-export type FrameAriaSnapshotResult = {- snapshot: string,-};export type FrameBlurParams = {selector: string,strict?: boolean,diff --git a/packages/protocol/src/protocol.yml b/packages/protocol/src/protocol.ymlindex 8a7792f49e..90ca47e39e 100644--- a/packages/protocol/src/protocol.yml+++ b/packages/protocol/src/protocol.yml@@ -2008,9 +2008,15 @@ Page:type: arrayitems: Request- snapshotForAI:- internal: true+ ariaSnapshot:+ title: Aria snapshot+ group: getterparameters:+ format:+ type: enum?+ literals:+ - ai+ - default# When track is present, an incremental snapshot is returned when possible.track: string?mode:@@ -2273,17 +2279,6 @@ Frame:snapshot: truepausesBeforeAction: true- ariaSnapshot:- title: Aria snapshot- parameters:- selector: string- timeout: float- returns:- snapshot: string- flags:- snapshot: true- pausesBeforeAction: true-blur:title: Blurparameters:diff --git a/tests/page/page-aria-snapshot-ai.spec.ts b/tests/page/page-aria-snapshot-ai.spec.tsindex 55dc17bf31..093b32e675 100644--- a/tests/page/page-aria-snapshot-ai.spec.ts+++ b/tests/page/page-aria-snapshot-ai.spec.ts@@ -19,8 +19,8 @@ import { test as it, expect } from './pageTest';import { unshift } from '../config/utils';import type { Page } from 'playwright-core';-async function snapshotForAI(page: Page, options?: Parameters<Page['snapshotForAI']>[0]): Promise<string> {- return await page.snapshotForAI(options);+async function snapshotForAI(page: Page, options?: Omit<Parameters<Page['ariaSnapshot']>[0], 'format'>): Promise<string> {+ return await page.ariaSnapshot({ ...options, format: 'ai' });}it('should generate refs', async ({ page }) => {@@ -799,7 +799,7 @@ it('should limit depth', async ({ page }) => {- listitem [ref=e10]: item3`);- const snapshot4 = await page.locator('#target').snapshotForAI({ depth: 1 });+ const snapshot4 = await page.locator('#target').ariaSnapshot({ format: 'ai', depth: 1 });expect(snapshot4).toContainYaml(`- list [ref=e6]:- listitem [ref=e7]: item2