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
feat(mcp): emit structured snapshot in --json responses (#42098)
Pavel Feldmanea4ea1f658cb
diff --git a/docs/src/api/class-locator.md b/docs/src/api/class-locator.mdindex c252b318fd..7a6d5957ce 100644--- a/docs/src/api/class-locator.md+++ b/docs/src/api/class-locator.md@@ -239,6 +239,61 @@ When `true`, appends each element's bounding box as `[box=x,y,width,height]` torelative to the viewport, in CSS pixels, as returned by [`Element.getBoundingClientRect()`](https://developer.mozilla.org/en-US/docs/Web/API/Element/getBoundingClientRect).Defaults to `false`.+## async method: Locator.ariaSnapshotJSON+* since: v1.63+* langs: js+- returns: <[Serializable]>++Captures the aria snapshot of the given element as a free form JSON object.++**Usage**++```js+await page.getByRole('list').ariaSnapshotJSON();+```++**Details**++This method returns the same tree as [`method: Locator.ariaSnapshot`], serialized as a JSON value instead of YAML markup.+The result is a list of nodes, each node being either a plain string with static text, or an object with the following properties:+* `role` <[string]> Aria role of the element.+* `name` <[string]> Accessible name of the element, if any.+* `text` <[string]> Text content of the element, when it is the only child.+* `children` <[Array]> Child nodes and text fragments.+* Boolean and value properties for element state flags: `checked`, `disabled`, `expanded`, `active`, `invalid`, `level`, `pressed` and `selected`.+* Additional element properties, for example `url` for links and `placeholder` for text boxes.+* `ref` <[string]> Element reference for AI-optimized snapshots.+* `cursor` <[string]> Set to `"pointer"` for clickable elements in AI-optimized snapshots.+* `box` <[Object]> Bounding box of the element when [`option: Locator.ariaSnapshotJSON.boxes`] is set.++### option: Locator.ariaSnapshotJSON.mode+* since: v1.63+- `mode` <[AriaSnapshotMode]<"ai"|"default">>++When set to `"ai"`, returns a snapshot optimized for AI consumption. Defaults to `"default"`. See details in [`method: Locator.ariaSnapshot`].++### option: Locator.ariaSnapshotJSON.timeout = %%-input-timeout-%%+* since: v1.63++### option: Locator.ariaSnapshotJSON.timeout = %%-input-timeout-js-%%+* since: v1.63++### option: Locator.ariaSnapshotJSON.signal = %%-input-signal-%%++### option: Locator.ariaSnapshotJSON.depth+* since: v1.63+- `depth` <[int]>++When specified, limits the depth of the snapshot.++### option: Locator.ariaSnapshotJSON.boxes+* since: v1.63+- `boxes` <[boolean]>++When `true`, includes each element's bounding box as a `box` property with `x`, `y`, `width` and `height`. Coordinates are+relative to the viewport, in CSS pixels, as returned by [`Element.getBoundingClientRect()`](https://developer.mozilla.org/en-US/docs/Web/API/Element/getBoundingClientRect).+Defaults to `false`.+## async method: Locator.blur* since: v1.28diff --git a/docs/src/api/class-page.md b/docs/src/api/class-page.mdindex 423fc97eef..9cb83bef41 100644--- a/docs/src/api/class-page.md+++ b/docs/src/api/class-page.md@@ -4427,6 +4427,43 @@ When `true`, appends each element's bounding box as `[box=x,y,width,height]` torelative to the viewport, in CSS pixels, as returned by [`Element.getBoundingClientRect()`](https://developer.mozilla.org/en-US/docs/Web/API/Element/getBoundingClientRect).Defaults to `false`.+## async method: Page.ariaSnapshotJSON+* since: v1.63+* langs: js+- returns: <[Serializable]>++Captures the aria snapshot of the page as a free form JSON object.+Returns the same tree as [`method: Page.ariaSnapshot`], serialized as a JSON value instead of YAML markup.+See [`method: Locator.ariaSnapshotJSON`] for the details of the format.++### option: Page.ariaSnapshotJSON.mode+* since: v1.63+- `mode` <[AriaSnapshotMode]<"ai"|"default">>++When set to `"ai"`, returns a snapshot optimized for AI consumption: including element references like `[ref=e2]` and snapshots of `<iframe>`s. Defaults to `"default"`.++### option: Page.ariaSnapshotJSON.timeout = %%-input-timeout-%%+* since: v1.63++### option: Page.ariaSnapshotJSON.timeout = %%-input-timeout-js-%%+* since: v1.63++### option: Page.ariaSnapshotJSON.signal = %%-input-signal-%%++### option: Page.ariaSnapshotJSON.depth+* since: v1.63+- `depth` <[int]>++When specified, limits the depth of the snapshot.++### option: Page.ariaSnapshotJSON.boxes+* since: v1.63+- `boxes` <[boolean]>++When `true`, includes each element's bounding box as a `box` property with `x`, `y`, `width` and `height`. Coordinates are+relative to the viewport, in CSS pixels, as returned by [`Element.getBoundingClientRect()`](https://developer.mozilla.org/en-US/docs/Web/API/Element/getBoundingClientRect).+Defaults to `false`.+## async method: Page.tap* since: v1.8* discouraged: Use locator-based [`method: Locator.tap`] instead. Read more about [locators](../locators.md).diff --git a/packages/injected/src/ariaSnapshot.ts b/packages/injected/src/ariaSnapshot.tsindex 35384ad2f2..2673206350 100644--- a/packages/injected/src/ariaSnapshot.ts+++ b/packages/injected/src/ariaSnapshot.ts@@ -583,6 +583,74 @@ export function renderAriaTree(ariaSnapshot: AriaSnapshot, publicOptions: AriaTrreturn { text: lines.join('\n'), iframeDepths };}+export function renderAriaTreeAsJSON(ariaSnapshot: AriaSnapshot, publicOptions: AriaTreeOptions): { json: aria.AriaSnapshotJSON, iframeDepths: Record<string, number> } {+ const options = toInternalOptions(publicOptions);+ const iframeDepths: Record<string, number> = {};++ const visit = (ariaNode: aria.AriaNode, depth: number, renderCursorPointer: boolean): aria.AriaNodeJSON => {+ if (ariaNode.role === 'iframe' && ariaNode.ref)+ iframeDepths[ariaNode.ref] = depth;++ const node: aria.AriaNodeJSON = { role: ariaNode.role };+ if (ariaNode.name)+ node.name = ariaNode.name;+ if (ariaNode.checked === 'mixed' || ariaNode.checked === true)+ node.checked = ariaNode.checked;+ if (ariaNode.disabled)+ node.disabled = true;+ if (ariaNode.expanded)+ node.expanded = true;+ if (ariaNode.active && options.renderActive)+ node.active = true;+ if (ariaNode.invalid)+ node.invalid = ariaNode.invalid;+ if (ariaNode.level)+ node.level = ariaNode.level;+ if (ariaNode.pressed === 'mixed' || ariaNode.pressed === true)+ node.pressed = ariaNode.pressed;+ if (ariaNode.selected === true)+ node.selected = true;+ if (ariaNode.ref) {+ node.ref = ariaNode.ref;+ if (renderCursorPointer && aria.hasPointerCursor(ariaNode))+ node.cursor = 'pointer';+ }+ if (options.renderBoxes) {+ const element = ariaNodeElement(ariaNode);+ if (element) {+ const r = element.getBoundingClientRect();+ node.box = { x: Math.round(r.x), y: Math.round(r.y), width: Math.round(r.width), height: Math.round(r.height) };+ }+ }+ for (const [name, value] of Object.entries(ariaNode.props))+ node[name] = value;++ const singleTextChild = ariaNode.children.length === 1 && typeof ariaNode.children[0] === 'string' ? ariaNode.children[0] : undefined;+ const isAtDepthLimit = !!publicOptions.depth && depth === publicOptions.depth;+ if (singleTextChild !== undefined) {+ node.text = singleTextChild;+ } else if (!isAtDepthLimit && ariaNode.children.length) {+ const inCursorPointer = !!ariaNode.ref && renderCursorPointer && aria.hasPointerCursor(ariaNode);+ node.children = ariaNode.children.map(child => {+ if (typeof child === 'string')+ return child;+ return visit(child, depth + 1, renderCursorPointer && !inCursorPointer);+ });+ }+ return node;+ };++ const json: aria.AriaSnapshotJSON = [];+ const nodesToRender = ariaSnapshot.root.role === 'fragment' ? ariaSnapshot.root.children : [ariaSnapshot.root];+ for (const nodeToRender of nodesToRender) {+ if (typeof nodeToRender === 'string')+ json.push(nodeToRender);+ else+ json.push(visit(nodeToRender, 0, !!options.renderCursorPointer));+ }+ return { json, iframeDepths };+}+function convertToBestGuessRegex(text: string): string {const dynamicContent = [// 550e8400-e29b-41d4-a716-446655440000diff --git a/packages/injected/src/injectedScript.ts b/packages/injected/src/injectedScript.tsindex 42094de518..6a36f1b153 100644--- a/packages/injected/src/injectedScript.ts+++ b/packages/injected/src/injectedScript.ts@@ -20,7 +20,7 @@ import { splitTestIdAttributeNames } from '@isomorphic/locatorUtils';import { parseAttributeSelector, parseSelector, stringifySelector, visitAllSelectorParts } from '@isomorphic/selectorParser';import { cacheNormalizedWhitespaces, normalizeWhiteSpace, trimStringWithEllipsis } from '@isomorphic/stringUtils';-import { generateAriaTree, getAllElementsMatchingExpectAriaTemplate, matchesExpectAriaTemplate, renderAriaTree, findNewElement } from './ariaSnapshot';+import { generateAriaTree, getAllElementsMatchingExpectAriaTemplate, matchesExpectAriaTemplate, renderAriaTree, renderAriaTreeAsJSON, findNewElement } from './ariaSnapshot';import { beginDOMCaches, enclosingShadowRootOrDocument, endDOMCaches, isElementVisible, isInsideScope, parentElementOrShadowHost, setGlobalOptions } from './domUtils';import { Highlight } from './highlight';import { kLayoutSelectorNames, layoutSelectorScore } from './layoutSelectorUtils';@@ -33,7 +33,7 @@ import { XPathEngine } from './xpathSelectorEngine';import { ConsoleAPI } from './consoleApi';import { UtilityScript } from './utilityScript';-import type { AriaTemplateNode } from '@isomorphic/ariaSnapshot';+import type { AriaSnapshotJSON, AriaTemplateNode } from '@isomorphic/ariaSnapshot';import type { CSSComplexSelectorList } from '@isomorphic/cssParser';import type { Language } from '@isomorphic/locatorGenerators';import type { AttributeSelectorPart, NestedSelectorBody, ParsedSelector, ParsedSelectorPart } from '@isomorphic/selectorParser';@@ -328,6 +328,16 @@ export class InjectedScript {return { text: rendered.text, iframeRefs: ariaSnapshot.iframeRefs, iframeDepths: rendered.iframeDepths };}+ ariaSnapshotJSON(node: Node, options: AriaTreeOptions & { depth?: number }): { json: AriaSnapshotJSON, iframeRefs: string[], iframeDepths: Record<string, number> } {+ if (node.nodeType !== Node.ELEMENT_NODE)+ throw this.createStacklessError('Can only capture aria snapshot of Element nodes.');+ options = { ...options, refPrefix: this._frameSeq && options.mode === 'ai' ? 'f' + this._frameSeq : '' };+ const ariaSnapshot = generateAriaTree(node as Element, options);+ const rendered = renderAriaTreeAsJSON(ariaSnapshot, options);+ this._lastAriaSnapshotForQuery = ariaSnapshot;+ return { json: rendered.json, iframeRefs: ariaSnapshot.iframeRefs, iframeDepths: rendered.iframeDepths };+ }+ariaSnapshotForRecorder(): { ariaSnapshot: string, refs: Map<Element, string> } {const tree = generateAriaTree(this.document.body, { mode: 'ai' });const { text: ariaSnapshot } = renderAriaTree(tree, { mode: 'ai' });diff --git a/packages/isomorphic/ariaSnapshot.ts b/packages/isomorphic/ariaSnapshot.tsindex e710975467..9275732c30 100644--- a/packages/isomorphic/ariaSnapshot.ts+++ b/packages/isomorphic/ariaSnapshot.ts@@ -55,6 +55,15 @@ export function hasPointerCursor(ariaNode: AriaNode): boolean {return ariaNode.box.cursor === 'pointer';}+// Free form JSON serialization of the aria tree. Nodes are either static text+// fragments or plain objects with the role, name, state flags and children.+export type AriaNodeJSON = {+ [key: string]: string | number | boolean | object | undefined;+ children?: (AriaNodeJSON | string)[];+};++export type AriaSnapshotJSON = (AriaNodeJSON | string)[];+// We pass parsed template between worlds using JSON, make it easy.export type AriaRegex = { pattern: string };diff --git a/packages/isomorphic/protocolMetainfo.ts b/packages/isomorphic/protocolMetainfo.tsindex 423b0a131c..d8afde4be2 100644--- a/packages/isomorphic/protocolMetainfo.ts+++ b/packages/isomorphic/protocolMetainfo.ts@@ -126,6 +126,7 @@ export const methodMetainfo = new Map<string, MethodMetainfo>([['Frame.addScriptTag', { title: 'Add script tag', snapshot: true, pause: true, }],['Frame.addStyleTag', { title: 'Add style tag', snapshot: true, pause: true, }],['Frame.ariaSnapshot', { title: 'Aria snapshot', group: 'getter', }],+ ['Frame.ariaSnapshotJSON', { title: 'Aria snapshot JSON', group: 'getter', }],['Frame.blur', { title: 'Blur', slowMo: true, snapshot: true, pause: true, }],['Frame.check', { title: 'Check', slowMo: true, snapshot: true, pause: true, input: true, isAutoWaiting: true, }],['Frame.click', { title: 'Click', slowMo: true, snapshot: true, pause: true, input: true, isAutoWaiting: true, }],diff --git a/packages/playwright-client/types/types.d.ts b/packages/playwright-client/types/types.d.tsindex 177bf2afe3..bf6569d6cd 100644--- a/packages/playwright-client/types/types.d.ts+++ b/packages/playwright-client/types/types.d.ts@@ -2138,6 +2138,54 @@ export interface Page {timeout?: number;}): Promise<string>;+ /**+ * Captures the aria snapshot of the page as a free form JSON object. Returns the same tree as+ * [page.ariaSnapshot([options])](https://playwright.dev/docs/api/class-page#page-aria-snapshot), serialized as a JSON+ * value instead of YAML markup. See+ * [locator.ariaSnapshotJSON([options])](https://playwright.dev/docs/api/class-locator#locator-aria-snapshot-json) for+ * the details of the format.+ * @param options+ */+ ariaSnapshotJSON(options?: {+ /**+ * When `true`, includes each element's bounding box as a `box` property with `x`, `y`, `width` and `height`.+ * Coordinates are relative to the viewport, in CSS pixels, as returned by+ * [`Element.getBoundingClientRect()`](https://developer.mozilla.org/en-US/docs/Web/API/Element/getBoundingClientRect).+ * Defaults to `false`.+ */+ boxes?: boolean;++ /**+ * When specified, limits the depth of the snapshot.+ */+ depth?: number;++ /**+ * When set to `"ai"`, returns a snapshot optimized for AI consumption: including element references like `[ref=e2]`+ * and snapshots of `<iframe>`s. Defaults to `"default"`.+ */+ mode?: "ai"|"default";++ /**+ * Allows to cancel the operation using an+ * [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the+ * operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,+ * which can be changed using+ * [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); pass+ * `timeout: 0` to disable the timeout entirely.+ */+ signal?: AbortSignal;++ /**+ * 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<Serializable>;+/*** Brings page to front (activates tab).*/@@ -14350,6 +14398,74 @@ export interface Locator {timeout?: number;}): Promise<string>;+ /**+ * Captures the aria snapshot of the given element as a free form JSON object.+ *+ * **Usage**+ *+ * ```js+ * await page.getByRole('list').ariaSnapshotJSON();+ * ```+ *+ * **Details**+ *+ * This method returns the same tree as+ * [locator.ariaSnapshot([options])](https://playwright.dev/docs/api/class-locator#locator-aria-snapshot), serialized+ * as a JSON value instead of YAML markup. The result is a list of nodes, each node being either a plain string with+ * static text, or an object with the following properties:+ * - `role` <[string]> Aria role of the element.+ * - `name` <[string]> Accessible name of the element, if any.+ * - `text` <[string]> Text content of the element, when it is the only child.+ * - `children` <[Array]> Child nodes and text fragments.+ * - Boolean and value properties for element state flags: `checked`, `disabled`, `expanded`, `active`, `invalid`,+ * `level`, `pressed` and `selected`.+ * - Additional element properties, for example `url` for links and `placeholder` for text boxes.+ * - `ref` <[string]> Element reference for AI-optimized snapshots.+ * - `cursor` <[string]> Set to `"pointer"` for clickable elements in AI-optimized snapshots.+ * - `box` <[Object]> Bounding box of the element when+ * [`boxes`](https://playwright.dev/docs/api/class-locator#locator-aria-snapshot-json-option-boxes) is set.+ * @param options+ */+ ariaSnapshotJSON(options?: {+ /**+ * When `true`, includes each element's bounding box as a `box` property with `x`, `y`, `width` and `height`.+ * Coordinates are relative to the viewport, in CSS pixels, as returned by+ * [`Element.getBoundingClientRect()`](https://developer.mozilla.org/en-US/docs/Web/API/Element/getBoundingClientRect).+ * Defaults to `false`.+ */+ boxes?: boolean;++ /**+ * When specified, limits the depth of the snapshot.+ */+ depth?: number;++ /**+ * When set to `"ai"`, returns a snapshot optimized for AI consumption. Defaults to `"default"`. See details in+ * [locator.ariaSnapshot([options])](https://playwright.dev/docs/api/class-locator#locator-aria-snapshot).+ */+ mode?: "ai"|"default";++ /**+ * Allows to cancel the operation using an+ * [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the+ * operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,+ * which can be changed using+ * [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); pass+ * `timeout: 0` to disable the timeout entirely.+ */+ signal?: AbortSignal;++ /**+ * 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<Serializable>;+/*** Calls [blur](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/blur) on the element.* @param optionsdiff --git a/packages/playwright-core/src/client/channels.d.ts b/packages/playwright-core/src/client/channels.d.tsindex 07944f33b1..b6bb08cd17 100644--- a/packages/playwright-core/src/client/channels.d.ts+++ b/packages/playwright-core/src/client/channels.d.ts@@ -2179,6 +2179,7 @@ export interface FrameChannel extends FrameEventTarget, Channel {addScriptTag(params: FrameAddScriptTagParams, options: TimeoutOptions): Promise<FrameAddScriptTagResult>;addStyleTag(params: FrameAddStyleTagParams, options: TimeoutOptions): Promise<FrameAddStyleTagResult>;ariaSnapshot(params: FrameAriaSnapshotParams, options: TimeoutOptions): Promise<FrameAriaSnapshotResult>;+ ariaSnapshotJSON(params: FrameAriaSnapshotJSONParams, options: TimeoutOptions): Promise<FrameAriaSnapshotJSONResult>;blur(params: FrameBlurParams, options: TimeoutOptions): Promise<FrameBlurResult>;check(params: FrameCheckParams, options: TimeoutOptions): Promise<FrameCheckResult>;click(params: FrameClickParams, options: TimeoutOptions): Promise<FrameClickResult>;@@ -2301,6 +2302,21 @@ export type FrameAriaSnapshotOptions = {export type FrameAriaSnapshotResult = {snapshot: string,};+export type FrameAriaSnapshotJSONParams = {+ mode?: 'ai' | 'default',+ selector?: string,+ depth?: number,+ boxes?: boolean,+};+export type FrameAriaSnapshotJSONOptions = {+ mode?: 'ai' | 'default',+ selector?: string,+ depth?: number,+ boxes?: boolean,+};+export type FrameAriaSnapshotJSONResult = {+ snapshot: any,+};export type FrameBlurParams = {selector: string,strict?: boolean,diff --git a/packages/playwright-core/src/client/locator.ts b/packages/playwright-core/src/client/locator.tsindex e1cdf3c615..8be9d2b102 100644--- a/packages/playwright-core/src/client/locator.ts+++ b/packages/playwright-core/src/client/locator.ts@@ -333,6 +333,11 @@ export class Locator implements api.Locator {return result.snapshot;}+ async ariaSnapshotJSON(options: TimeoutOptions & { mode?: 'ai' | 'default', depth?: number, boxes?: boolean } = {}): Promise<any> {+ const result = await this._frame._channel.ariaSnapshotJSON({ mode: options.mode, selector: this._selector, depth: options.depth, boxes: options.boxes }, this._frame._timeout(options));+ return result.snapshot;+ }+async scrollIntoViewIfNeeded(options: channels.ElementHandleScrollIntoViewIfNeededOptions & TimeoutOptions = {}) {return await this._withElement((h, timeout) => h.scrollIntoViewIfNeeded({ ...options, timeout }), { title: 'Scroll into view', timeout: options.timeout, signal: options.signal });}diff --git a/packages/playwright-core/src/client/page.ts b/packages/playwright-core/src/client/page.tsindex e9b088be1d..d7ea623f7d 100644--- a/packages/playwright-core/src/client/page.ts+++ b/packages/playwright-core/src/client/page.ts@@ -924,6 +924,11 @@ export class Page extends ChannelOwner<channels.PageChannel> implements api.Pagereturn result.snapshot;}+ async ariaSnapshotJSON(options: TimeoutOptions & { mode?: 'ai' | 'default', depth?: number, boxes?: boolean } = {}): Promise<any> {+ const result = await this.mainFrame()._channel.ariaSnapshotJSON({ mode: options.mode, depth: options.depth, boxes: options.boxes }, this._timeoutSettings.timeout(options));+ return result.snapshot;+ }+async _setDockTile(image: Buffer) {await this._channel.setDockTile({ image }, kNoTimeout);}diff --git a/packages/playwright-core/src/server/channels.d.ts b/packages/playwright-core/src/server/channels.d.tsindex e8e7962f2b..48da3163a0 100644--- a/packages/playwright-core/src/server/channels.d.ts+++ b/packages/playwright-core/src/server/channels.d.ts@@ -2180,6 +2180,7 @@ export interface FrameChannel extends FrameEventTarget, Channel {addScriptTag(params: FrameAddScriptTagParams, progress: Progress): Promise<FrameAddScriptTagResult>;addStyleTag(params: FrameAddStyleTagParams, progress: Progress): Promise<FrameAddStyleTagResult>;ariaSnapshot(params: FrameAriaSnapshotParams, progress: Progress): Promise<FrameAriaSnapshotResult>;+ ariaSnapshotJSON(params: FrameAriaSnapshotJSONParams, progress: Progress): Promise<FrameAriaSnapshotJSONResult>;blur(params: FrameBlurParams, progress: Progress): Promise<FrameBlurResult>;check(params: FrameCheckParams, progress: Progress): Promise<FrameCheckResult>;click(params: FrameClickParams, progress: Progress): Promise<FrameClickResult>;@@ -2302,6 +2303,21 @@ export type FrameAriaSnapshotOptions = {export type FrameAriaSnapshotResult = {snapshot: string,};+export type FrameAriaSnapshotJSONParams = {+ mode?: 'ai' | 'default',+ selector?: string,+ depth?: number,+ boxes?: boolean,+};+export type FrameAriaSnapshotJSONOptions = {+ mode?: 'ai' | 'default',+ selector?: string,+ depth?: number,+ boxes?: boolean,+};+export type FrameAriaSnapshotJSONResult = {+ snapshot: any,+};export type FrameBlurParams = {selector: string,strict?: boolean,diff --git a/packages/playwright-core/src/server/dispatchers/frameDispatcher.ts b/packages/playwright-core/src/server/dispatchers/frameDispatcher.tsindex 67593bde88..e72af9d0cd 100644--- a/packages/playwright-core/src/server/dispatchers/frameDispatcher.ts+++ b/packages/playwright-core/src/server/dispatchers/frameDispatcher.ts@@ -138,6 +138,10 @@ export class FrameDispatcher extends Dispatcher<Frame, channels.FrameChannel, Brreturn await this._frame.ariaSnapshot(progress, params);}+ async ariaSnapshotJSON(params: channels.FrameAriaSnapshotJSONParams, progress: Progress): Promise<channels.FrameAriaSnapshotJSONResult> {+ return await this._frame.ariaSnapshotJSON(progress, params);+ }+async click(params: channels.FrameClickParams, progress: Progress): Promise<void> {return await this._frame.click(progress, params.selector, params);}diff --git a/packages/playwright-core/src/server/frames.ts b/packages/playwright-core/src/server/frames.tsindex 637d429e4d..e614cdc293 100644--- a/packages/playwright-core/src/server/frames.ts+++ b/packages/playwright-core/src/server/frames.ts@@ -35,7 +35,7 @@ import { helper } from './helper';import { SdkObject } from './instrumentation';import * as js from './javascript';import * as network from './network';-import { Page, ariaSnapshotForFrame } from './page';+import { Page, ariaSnapshotForFrame, ariaSnapshotJSONForFrame } from './page';import { isAbortError, nullProgress, ProgressController, raceUncancellableOperationWithCleanup } from './progress';import * as types from './types';import { isSessionClosedError } from './protocolError';@@ -46,6 +46,7 @@ import type { Progress } from './progress';import type { ScreenshotOptions } from './screenshotter';import type { RegisteredListener } from '@utils/eventsHelper';import type * as channels from './channels';+import type { AriaSnapshotJSON } from '@isomorphic/ariaSnapshot';type ContextData = {contextPromise: ManualPromise<dom.FrameExecutionContext | { destroyedReason: string }>;@@ -1874,6 +1875,17 @@ export class Frame extends SdkObject<FrameEventMap> {return { snapshot: lines.join('\n') };}+ async ariaSnapshotJSON(progress: Progress, options: { mode?: 'ai' | 'default', doNotRenderActive?: boolean, selector?: string, depth?: number, boxes?: boolean } = {}): Promise<{ snapshot: AriaSnapshotJSON }> {+ if (options.selector && options.mode !== 'ai') {+ // Non-ai locator snapshot is auto-waiting and does not include iframes.+ const snapshot = await this._retryWithProgressIfNotConnected(progress, options.selector, { strict: true, performActionPreChecks: true }, async (progress, handle) => {+ return await progress.race(handle.evaluateInUtility(([injected, element, opts]) => injected.ariaSnapshotJSON(element, opts).json, { mode: 'default' as const, depth: options.depth, boxes: options.boxes }));+ });+ return { snapshot };+ }+ return { snapshot: await ariaSnapshotJSONForFrame(progress, this, options.selector, options) };+ }+private _asLocator(selector: string) {return asLocator(this._page.browserContext._browser.sdkLanguage(), selector);}diff --git a/packages/playwright-core/src/server/page.ts b/packages/playwright-core/src/server/page.tsindex a68b5b21b4..7d87d37802 100644--- a/packages/playwright-core/src/server/page.ts+++ b/packages/playwright-core/src/server/page.ts@@ -53,6 +53,7 @@ import type * as types from './types';import type { ImageComparatorOptions } from '@utils/comparators';import type * as channels from './channels';import type { BindingPayload } from '@injected/bindingsController';+import type { AriaNodeJSON, AriaSnapshotJSON } from '@isomorphic/ariaSnapshot';export interface PageDelegate {readonly rawMouse: input.RawMouse;@@ -1171,6 +1172,65 @@ export async function ariaSnapshotForFrame(progress: Progress, frame: frames.Frareturn lines;}+export async function ariaSnapshotJSONForFrame(progress: Progress, frame: frames.Frame, selector: string | undefined, options: { mode?: 'ai' | 'default', doNotRenderActive?: boolean, depth?: number, boxes?: boolean, strict?: boolean, noDefaultPierce?: boolean } = {}): Promise<AriaSnapshotJSON> {+ const snapshot = await frame.retryWithProgressAndTimeouts(progress, [1000, 2000, 4000, 8000], async (progress, continuePolling) => {+ try {+ // Note: the resolved frame might differ from the original |frame|.+ // See https://developer.mozilla.org/en-US/docs/Web/API/Document/body for body/frameset explanation.+ // Non-strict, because pages with nested framesets have multiple "frameset" elements.+ const resolved = await progress.race(frame.selectors.callOnSelector(selector || 'body,frameset', { strict: options.strict ?? !!selector, noDefaultPierce: !selector || options.noDefaultPierce }, ({ injected, elements }, ariaOptions) => {+ return injected.ariaSnapshotJSON(elements[0], ariaOptions);+ }, {+ mode: options.mode ?? 'default',+ doNotRenderActive: options.doNotRenderActive,+ depth: options.depth,+ boxes: options.boxes,+ }));+ if (!resolved) {+ if (selector)+ throw new NonRecoverableDOMError(`Selector "${selector}" does not match any element`);+ // Retry only for the main frame "body" being absent, so that `page.ariaSnapshotJSON()` does not fail.+ return continuePolling;+ }+ return { ...resolved.result, resolvedFrame: resolved.frame };+ } catch (e) {+ if (frame.isNonRetriableError(e))+ throw e;+ return continuePolling;+ }+ });++ // Only fetch child snapshots for iframes that were actually rendered (not filtered by depth).+ const renderedIframeRefs = snapshot.iframeRefs.filter(ref => ref in snapshot.iframeDepths);+ progress.setAllowConcurrentOrNestedRaces(true);+ const childSnapshotPromises = renderedIframeRefs.map(async ref => {+ const childDepth = options.depth ? options.depth - snapshot.iframeDepths[ref] - 1 : undefined;+ // Non-strict, because child frameset documents have multiple "frameset" elements.+ const frameRootSelector = `aria-ref=${ref} >> internal:control=enter-frame >> body,frameset`;+ try {+ return await ariaSnapshotJSONForFrame(progress, snapshot.resolvedFrame, frameRootSelector, { ...options, depth: childDepth, strict: false, noDefaultPierce: true });+ } catch {+ return [];+ }+ });+ const childSnapshots = await Promise.all(childSnapshotPromises);+ progress.setAllowConcurrentOrNestedRaces(false);++ const mergeIframeChildren = (node: AriaNodeJSON | string) => {+ if (typeof node === 'string')+ return;+ if (node.role === 'iframe' && typeof node.ref === 'string') {+ const childSnapshot = childSnapshots[renderedIframeRefs.indexOf(node.ref)];+ if (childSnapshot?.length)+ node.children = childSnapshot;+ return;+ }+ (node.children || []).forEach(mergeIframeChildren);+ };+ snapshot.json.forEach(mergeIframeChildren);+ return snapshot.json;+}+function ensureArrayLimit<T>(array: T[], limit: number): T[] {if (array.length > limit)return array.splice(0, limit / 10);diff --git a/packages/playwright-core/src/tools/backend/response.ts b/packages/playwright-core/src/tools/backend/response.tsindex c29732af5b..e73adf4879 100644--- a/packages/playwright-core/src/tools/backend/response.ts+++ b/packages/playwright-core/src/tools/backend/response.ts@@ -36,11 +36,13 @@ type ResolvedFile = {printableLink: string;};+type SectionContent = string[] | { json: unknown };+type Section = {title: string;- content: string[];+ content: SectionContent;isError?: boolean;- codeframe?: 'yaml' | 'js';+ codeframe?: 'yaml' | 'js' | 'json';};export class Response {@@ -169,9 +171,14 @@ export class Response {if (isError)payload.isError = true;for (const section of sections) {+ const key = section.title.toLowerCase();+ if (!Array.isArray(section.content)) {+ if (section.content.json !== undefined)+ payload[key] = section.content.json;+ continue;+ }if (!section.content.length)continue;- const key = section.title.toLowerCase();if (key === 'snapshot') {const match = section.content[0]?.match(/^- \[Snapshot\]\(([^)]+)\)$/);payload.snapshot = match ? { file: match[1] } : section.content.join('\n');@@ -183,17 +190,18 @@ export class Response {} else {const text: string[] = [];for (const section of sections) {- if (!section.content.length)+ const lines = Array.isArray(section.content) ? section.content : (section.content.json === undefined ? [] : [JSON.stringify(section.content.json, null, 2)]);+ if (!lines.length)continue;if (!this._raw) {text.push(`### ${section.title}`);if (section.codeframe)text.push(`\`\`\`${section.codeframe}`);- text.push(...section.content);+ text.push(...lines);if (section.codeframe)text.push('```');} else {- text.push(...section.content);+ text.push(...lines);}}serializedText = text.join('\n');@@ -254,7 +262,7 @@ export class Response {private async _build(): Promise<Section[]> {const sections: Section[] = [];- const addSection = (title: string, content: string[], codeframe?: 'yaml' | 'js') => {+ const addSection = (title: string, content: SectionContent, codeframe?: 'yaml' | 'js' | 'json') => {const section = { title, content, isError: title === 'Error', codeframe };sections.push(section);return content;@@ -271,7 +279,9 @@ export class Response {addSection('Ran Playwright code', this._code, 'js');// Render tab titles upon changes or when more than one tab.- const tabSnapshot = this._context.currentTab() ? await this._context.currentTabOrDie().captureSnapshot(this._includeSnapshotRoot, this._includeSnapshotDepth, this._includeSnapshotBoxes, this._clientWorkspace, this._includeSnapshot !== 'none') : undefined;+ const snapshotToFile = this._includeSnapshot !== 'explicit' || !!this._includeSnapshotFileName;+ const ariaFormat = this._includeSnapshot === 'none' ? 'none' : (this._json && !snapshotToFile ? 'json' : 'text');+ const tabSnapshot = this._context.currentTab() ? await this._context.currentTabOrDie().captureSnapshot(this._includeSnapshotRoot, this._includeSnapshotDepth, this._includeSnapshotBoxes, this._clientWorkspace, ariaFormat) : undefined;const tabHeaders = await Promise.all(this._context.tabs().map(tab => tab.headerSnapshot()));if (this._includeSnapshot !== 'none' || tabHeaders.some(header => header.changed)) {if (tabHeaders.length !== 1)@@ -285,11 +295,13 @@ export class Response {// Handle tab snapshotif (tabSnapshot && this._includeSnapshot !== 'none') {- if (this._includeSnapshot !== 'explicit' || this._includeSnapshotFileName) {+ if (snapshotToFile) {const suggestedFilename = this._includeSnapshotFileName === '<auto>' ? undefined : this._includeSnapshotFileName;const resolvedFile = await this.resolveClientFile({ prefix: 'page', ext: 'yml', suggestedFilename }, 'Snapshot');await this._writeFile(resolvedFile, tabSnapshot.ariaSnapshot);addSection('Snapshot', [resolvedFile.printableLink]);+ } else if (tabSnapshot.ariaSnapshotJSON !== undefined) {+ addSection('Snapshot', { json: tabSnapshot.ariaSnapshotJSON }, 'json');} else {addSection('Snapshot', [tabSnapshot.ariaSnapshot], 'yaml');}diff --git a/packages/playwright-core/src/tools/backend/tab.ts b/packages/playwright-core/src/tools/backend/tab.tsindex a23a6a1a91..7d17a14e94 100644--- a/packages/playwright-core/src/tools/backend/tab.ts+++ b/packages/playwright-core/src/tools/backend/tab.ts@@ -83,6 +83,7 @@ export type TabHeader = {type TabSnapshot = {ariaSnapshot: string;+ ariaSnapshotJSON?: unknown;modalStates: ModalState[];events: EventEntry[];consoleLink?: string;@@ -411,20 +412,32 @@ export class Tab extends EventEmitter<TabEventsInterface> {this._requests.length = 0;}- async captureSnapshot(root: playwright.Locator | undefined, depth: number | undefined, boxes: boolean | undefined, relativeTo: string | undefined, includeAria: boolean = true): Promise<TabSnapshot> {+ async captureSnapshot(root: playwright.Locator | undefined, depth: number | undefined, boxes: boolean | undefined, relativeTo: string | undefined, ariaFormat: 'none' | 'text' | 'json' = 'text'): Promise<TabSnapshot> {await this._initializedPromise;let tabSnapshot: TabSnapshot | undefined;let modalStates: ModalState[] = [];- if (includeAria) {+ if (ariaFormat !== 'none') {modalStates = await this._raceAgainstModalStates(async () => {- const ariaSnapshot = root- ? await root.ariaSnapshot({ mode: 'ai', depth, boxes })- : await this.page.ariaSnapshot({ mode: 'ai', depth, boxes });- tabSnapshot = {- ariaSnapshot,- modalStates: [],- events: [],- };+ if (ariaFormat === 'json') {+ const ariaSnapshotJSON = root+ ? await root.ariaSnapshotJSON({ mode: 'ai', depth, boxes })+ : await this.page.ariaSnapshotJSON({ mode: 'ai', depth, boxes });+ tabSnapshot = {+ ariaSnapshot: '',+ ariaSnapshotJSON,+ modalStates: [],+ events: [],+ };+ } else {+ const ariaSnapshot = root+ ? await root.ariaSnapshot({ mode: 'ai', depth, boxes })+ : await this.page.ariaSnapshot({ mode: 'ai', depth, boxes });+ tabSnapshot = {+ ariaSnapshot,+ modalStates: [],+ events: [],+ };+ }});} else if (this.modalStates().length) {// Matches the aria path's modal fallback below, without the race: therediff --git a/packages/playwright-core/types/types.d.ts b/packages/playwright-core/types/types.d.tsindex 177bf2afe3..bf6569d6cd 100644--- a/packages/playwright-core/types/types.d.ts+++ b/packages/playwright-core/types/types.d.ts@@ -2138,6 +2138,54 @@ export interface Page {timeout?: number;}): Promise<string>;+ /**+ * Captures the aria snapshot of the page as a free form JSON object. Returns the same tree as+ * [page.ariaSnapshot([options])](https://playwright.dev/docs/api/class-page#page-aria-snapshot), serialized as a JSON+ * value instead of YAML markup. See+ * [locator.ariaSnapshotJSON([options])](https://playwright.dev/docs/api/class-locator#locator-aria-snapshot-json) for+ * the details of the format.+ * @param options+ */+ ariaSnapshotJSON(options?: {+ /**+ * When `true`, includes each element's bounding box as a `box` property with `x`, `y`, `width` and `height`.+ * Coordinates are relative to the viewport, in CSS pixels, as returned by+ * [`Element.getBoundingClientRect()`](https://developer.mozilla.org/en-US/docs/Web/API/Element/getBoundingClientRect).+ * Defaults to `false`.+ */+ boxes?: boolean;++ /**+ * When specified, limits the depth of the snapshot.+ */+ depth?: number;++ /**+ * When set to `"ai"`, returns a snapshot optimized for AI consumption: including element references like `[ref=e2]`+ * and snapshots of `<iframe>`s. Defaults to `"default"`.+ */+ mode?: "ai"|"default";++ /**+ * Allows to cancel the operation using an+ * [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the+ * operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,+ * which can be changed using+ * [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); pass+ * `timeout: 0` to disable the timeout entirely.+ */+ signal?: AbortSignal;++ /**+ * 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<Serializable>;+/*** Brings page to front (activates tab).*/@@ -14350,6 +14398,74 @@ export interface Locator {timeout?: number;}): Promise<string>;+ /**+ * Captures the aria snapshot of the given element as a free form JSON object.+ *+ * **Usage**+ *+ * ```js+ * await page.getByRole('list').ariaSnapshotJSON();+ * ```+ *+ * **Details**+ *+ * This method returns the same tree as+ * [locator.ariaSnapshot([options])](https://playwright.dev/docs/api/class-locator#locator-aria-snapshot), serialized+ * as a JSON value instead of YAML markup. The result is a list of nodes, each node being either a plain string with+ * static text, or an object with the following properties:+ * - `role` <[string]> Aria role of the element.+ * - `name` <[string]> Accessible name of the element, if any.+ * - `text` <[string]> Text content of the element, when it is the only child.+ * - `children` <[Array]> Child nodes and text fragments.+ * - Boolean and value properties for element state flags: `checked`, `disabled`, `expanded`, `active`, `invalid`,+ * `level`, `pressed` and `selected`.+ * - Additional element properties, for example `url` for links and `placeholder` for text boxes.+ * - `ref` <[string]> Element reference for AI-optimized snapshots.+ * - `cursor` <[string]> Set to `"pointer"` for clickable elements in AI-optimized snapshots.+ * - `box` <[Object]> Bounding box of the element when+ * [`boxes`](https://playwright.dev/docs/api/class-locator#locator-aria-snapshot-json-option-boxes) is set.+ * @param options+ */+ ariaSnapshotJSON(options?: {+ /**+ * When `true`, includes each element's bounding box as a `box` property with `x`, `y`, `width` and `height`.+ * Coordinates are relative to the viewport, in CSS pixels, as returned by+ * [`Element.getBoundingClientRect()`](https://developer.mozilla.org/en-US/docs/Web/API/Element/getBoundingClientRect).+ * Defaults to `false`.+ */+ boxes?: boolean;++ /**+ * When specified, limits the depth of the snapshot.+ */+ depth?: number;++ /**+ * When set to `"ai"`, returns a snapshot optimized for AI consumption. Defaults to `"default"`. See details in+ * [locator.ariaSnapshot([options])](https://playwright.dev/docs/api/class-locator#locator-aria-snapshot).+ */+ mode?: "ai"|"default";++ /**+ * Allows to cancel the operation using an+ * [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the+ * operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,+ * which can be changed using+ * [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); pass+ * `timeout: 0` to disable the timeout entirely.+ */+ signal?: AbortSignal;++ /**+ * 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<Serializable>;+/*** Calls [blur](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/blur) on the element.* @param optionsdiff --git a/packages/protocol/spec/frame.yml b/packages/protocol/spec/frame.ymlindex 421530f52a..a8dd00d337 100644--- a/packages/protocol/spec/frame.yml+++ b/packages/protocol/spec/frame.yml@@ -90,6 +90,21 @@ Frame:returns:snapshot: string+ ariaSnapshotJSON:+ title: Aria snapshot JSON+ group: getter+ parameters:+ mode:+ type: enum?+ literals:+ - ai+ - default+ selector: string?+ depth: int?+ boxes: boolean?+ returns:+ snapshot: json+blur:title: Blurparameters:diff --git a/packages/protocol/src/validator.ts b/packages/protocol/src/validator.tsindex 719f94a430..9e5cd7dcde 100644--- a/packages/protocol/src/validator.ts+++ b/packages/protocol/src/validator.ts@@ -1248,6 +1248,15 @@ scheme.FrameAriaSnapshotParams = tObject({scheme.FrameAriaSnapshotResult = tObject({snapshot: tString,});+scheme.FrameAriaSnapshotJSONParams = tObject({+ mode: tOptional(tEnum(['ai', 'default'])),+ selector: tOptional(tString),+ depth: tOptional(tInt),+ boxes: tOptional(tBoolean),+});+scheme.FrameAriaSnapshotJSONResult = tObject({+ snapshot: tAny,+});scheme.FrameBlurParams = tObject({selector: tString,strict: tOptional(tBoolean),diff --git a/tests/mcp/cli-json.spec.ts b/tests/mcp/cli-json.spec.tsindex d702d5ecbf..31060c2cb3 100644--- a/tests/mcp/cli-json.spec.ts+++ b/tests/mcp/cli-json.spec.ts@@ -151,13 +151,41 @@ test('tab-close closes a tab and returns remaining tabs', async ({ cli, server }]);});-test('snapshot returns inline snapshot yaml', async ({ cli, server }) => {+test('snapshot returns structured inline snapshot', async ({ cli, server }) => {server.setContent('/', '<h1>Hi</h1>', 'text/html');await cli('open', server.PREFIX);const { output } = await cli('--json', 'snapshot');const parsed = JSON.parse(output);- expect(typeof parsed.snapshot).toBe('string');- expect(parsed.snapshot).toContain('heading "Hi"');+ expect(parsed.snapshot).toEqual([+ { role: 'heading', name: 'Hi', level: 1, ref: expect.stringMatching(/^e\d+$/) },+ ]);+});++test('snapshot returns structured children and flags', async ({ cli, server }) => {+ server.setContent('/', `+ <a style="cursor: pointer" href="https://example.com/">Link</a>+ <button disabled>Click</button>+ `, 'text/html');+ await cli('open', server.PREFIX);+ const { output } = await cli('--json', 'snapshot');+ const parsed = JSON.parse(output);+ expect(parsed.snapshot).toEqual([+ {+ role: 'generic',+ active: true,+ ref: expect.stringMatching(/^e\d+$/),+ children: [+ {+ role: 'link',+ name: 'Link',+ url: 'https://example.com/',+ ref: expect.stringMatching(/^e\d+$/),+ cursor: 'pointer',+ },+ { role: 'button', name: 'Click', disabled: true, ref: expect.stringMatching(/^e\d+$/) },+ ],+ },+ ]);});test('tool error on bad navigation returns JSON error', async ({ cli, server }) => {diff --git a/tests/page/page-aria-snapshot-json.spec.ts b/tests/page/page-aria-snapshot-json.spec.tsnew file mode 100644index 0000000000..413046ba41--- /dev/null+++ b/tests/page/page-aria-snapshot-json.spec.ts@@ -0,0 +1,173 @@+/**+ * Copyright (c) Microsoft Corporation.+ *+ * Licensed under the Apache License, Version 2.0 (the "License");+ * you may not use this file except in compliance with the License.+ * You may obtain a copy of the License at+ *+ * http://www.apache.org/licenses/LICENSE-2.0+ *+ * Unless required by applicable law or agreed to in writing, software+ * distributed under the License is distributed on an "AS IS" BASIS,+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.+ * See the License for the specific language governing permissions and+ * limitations under the License.+ */++import { test as it, expect } from './pageTest';++type NodeJSON = { role: string, name?: string, ref?: string, children?: (NodeJSON | string)[] } & Record<string, any>;++function findNode(nodes: (NodeJSON | string)[], predicate: (node: NodeJSON) => boolean): NodeJSON | undefined {+ for (const node of nodes) {+ if (typeof node === 'string')+ continue;+ if (predicate(node))+ return node;+ const result = findNode(node.children || [], predicate);+ if (result)+ return result;+ }+ return undefined;+}++it('should snapshot roles, names and text', async ({ page }) => {+ await page.setContent(`+ <h1>title</h1>+ <ul aria-label="my list">+ <li>one</li>+ <li>two</li>+ </ul>+ `);+ expect(await page.ariaSnapshotJSON()).toEqual([+ { role: 'heading', name: 'title', level: 1 },+ {+ role: 'list',+ name: 'my list',+ children: [+ { role: 'listitem', text: 'one' },+ { role: 'listitem', text: 'two' },+ ],+ },+ ]);+});++it('should snapshot flags as properties', async ({ page }) => {+ await page.setContent(`+ <input type="checkbox" title="Check" checked>+ <button disabled>Click</button>+ `);+ expect(await page.ariaSnapshotJSON()).toEqual([+ { role: 'checkbox', name: 'Check', checked: true },+ { role: 'button', name: 'Click', disabled: true },+ ]);+});++it('should snapshot link url and textbox value', async ({ page }) => {+ await page.setContent(`+ <a href="https://example.com/">Link</a>+ <input title="Input" value="hello">+ `);+ expect(await page.ariaSnapshotJSON()).toEqual([+ { role: 'link', name: 'Link', url: 'https://example.com/' },+ { role: 'textbox', name: 'Input', text: 'hello' },+ ]);+});++it('should snapshot text fragments in children', async ({ page }) => {+ await page.setContent(`<p>Hello <a href="/link">world</a> again</p>`);+ expect(await page.ariaSnapshotJSON()).toEqual([+ {+ role: 'paragraph',+ children: [+ 'Hello',+ { role: 'link', name: 'world', url: '/link' },+ 'again',+ ],+ },+ ]);+});++it('should generate refs in ai mode', async ({ page }) => {+ await page.setContent(`+ <button>One</button>+ <button>Two</button>+ `);+ expect(await page.ariaSnapshotJSON({ mode: 'ai' })).toEqual([+ {+ role: 'generic',+ active: true,+ ref: 'e1',+ children: [+ { role: 'button', name: 'One', ref: 'e2' },+ { role: 'button', name: 'Two', ref: 'e3' },+ ],+ },+ ]);+ await expect(page.locator('aria-ref=e2')).toHaveText('One');+});++it('should mark clickable elements with cursor in ai mode', async ({ page }) => {+ await page.setContent(`<button style="cursor: pointer">One</button>`);+ const json = await page.ariaSnapshotJSON({ mode: 'ai' }) as NodeJSON[];+ const button = findNode(json, node => node.role === 'button');+ expect(button?.cursor).toBe('pointer');+});++it('should snapshot iframes in ai mode', async ({ page }) => {+ await page.setContent(`+ <h1>Hello</h1>+ <iframe srcdoc="<button>In frame</button>"></iframe>+ `);+ const json = await page.ariaSnapshotJSON({ mode: 'ai' }) as NodeJSON[];+ const iframe = findNode(json, node => node.role === 'iframe');+ expect(iframe?.ref).toBeTruthy();+ const button = findNode(iframe!.children!, node => node.role === 'button');+ expect(button?.name).toBe('In frame');+ expect(button?.ref).toMatch(/^f\d+e\d+$/);+});++it('should limit depth', async ({ page }) => {+ await page.setContent(`<ul><li><button>One</button></li></ul>`);+ expect(await page.ariaSnapshotJSON({ depth: 1 })).toEqual([+ {+ role: 'list',+ children: [+ { role: 'listitem' },+ ],+ },+ ]);+});++it('should include boxes when requested', async ({ page }) => {+ await page.setContent(`<button>One</button>`);+ const json = await page.ariaSnapshotJSON({ boxes: true }) as NodeJSON[];+ const button = findNode(json, node => node.role === 'button');+ expect(button?.box).toEqual({+ x: expect.any(Number),+ y: expect.any(Number),+ width: expect.any(Number),+ height: expect.any(Number),+ });+ expect(button!.box.width).toBeGreaterThan(0);+ expect(button!.box.height).toBeGreaterThan(0);+});++it('should snapshot a locator', async ({ page }) => {+ await page.setContent(`+ <h1>title</h1>+ <ul>+ <li>one</li>+ <li>two</li>+ </ul>+ `);+ expect(await page.locator('ul').ariaSnapshotJSON()).toEqual([+ {+ role: 'list',+ children: [+ { role: 'listitem', text: 'one' },+ { role: 'listitem', text: 'two' },+ ],+ },+ ]);+});