Skip to content

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

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.md
index 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]` to
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.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.28
diff --git a/docs/src/api/class-page.md b/docs/src/api/class-page.md
index 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]` to
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.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.ts
index 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: AriaTr
return { 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-446655440000
diff --git a/packages/injected/src/injectedScript.ts b/packages/injected/src/injectedScript.ts
index 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.ts
index 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.ts
index 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.ts
index 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 options
diff --git a/packages/playwright-core/src/client/channels.d.ts b/packages/playwright-core/src/client/channels.d.ts
index 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.ts
index 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.ts
index 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.Page
return 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.ts
index 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.ts
index 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, Br
return 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.ts
index 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.ts
index 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.Fra
return 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.ts
index 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 snapshot
if (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.ts
index 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: there
diff --git a/packages/playwright-core/types/types.d.ts b/packages/playwright-core/types/types.d.ts
index 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 options
diff --git a/packages/protocol/spec/frame.yml b/packages/protocol/spec/frame.yml
index 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: Blur
parameters:
diff --git a/packages/protocol/src/validator.ts b/packages/protocol/src/validator.ts
index 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.ts
index 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.ts
new file mode 100644
index 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' },
+ ],
+ },
+ ]);
+});