feat: support depth option in aria snapshot

Author: dgozman

docs/src/api/class-page.md

@@ -4233,6 +4233,12 @@ Returns an accessibility snapshot of the page optimized for AI consumption.
 When specified, enables incremental snapshots. Subsequent calls with the same track name will return
 an incremental snapshot containing only changes since the last call.
 
+### option: Page.snapshotForAI.depth
+* since: v1.59
+- `depth` <[int]>
+
+When specified, limits the depth of the snapshot.
+
 ## async method: Page.tap
 * since: v1.8
 * discouraged: Use locator-based [`method: Locator.tap`] instead. Read more about [locators](../locators.md).

packages/injected/src/ariaSnapshot.ts

@@ -40,6 +40,7 @@ export type AriaTreeOptions = {
   mode: 'ai' | 'expect' | 'codegen' | 'autoexpect';
   refPrefix?: string;
   doNotRenderActive?: boolean;
+  depth?: number;
 };
 
 type InternalOptions = {
@@ -563,6 +564,10 @@ function filterSnapshotDiff(nodes: (aria.AriaNode | string)[], statusMap: Map<ar
   return result;
 }
 
+function indent(depth: number): string {
+  return '  '.repeat(depth);
+}
+
 export function renderAriaTree(ariaSnapshot: AriaSnapshot, publicOptions: AriaTreeOptions, previousSnapshot?: AriaSnapshot): string {
   const options = toInternalOptions(publicOptions);
   const lines: string[] = [];
@@ -576,10 +581,12 @@ export function renderAriaTree(ariaSnapshot: AriaSnapshot, publicOptions: AriaTr
   if (previousSnapshot)
     nodesToRender = filterSnapshotDiff(nodesToRender, statusMap);
 
-  const visitText = (text: string, indent: string) => {
+  const visitText = (text: string, depth: number) => {
+    if (publicOptions.depth && depth > publicOptions.depth)
+      return;
     const escaped = yamlEscapeValueIfNeeded(renderString(text));
     if (escaped)
-      lines.push(indent + '- text: ' + escaped);
+      lines.push(indent(depth) + '- text: ' + escaped);
   };
 
   const createKey = (ariaNode: aria.AriaNode, renderCursorPointer: boolean): string => {
@@ -623,19 +630,24 @@ export function renderAriaTree(ariaSnapshot: AriaSnapshot, publicOptions: AriaTr
     return ariaNode?.children.length === 1 && typeof ariaNode.children[0] === 'string' && !Object.keys(ariaNode.props).length ? ariaNode.children[0] : undefined;
   };
 
-  const visit = (ariaNode: aria.AriaNode, indent: string, renderCursorPointer: boolean) => {
+  const visit = (ariaNode: aria.AriaNode, depth: number, renderCursorPointer: boolean) => {
+    if (publicOptions.depth && depth > publicOptions.depth)
+      return;
+
     // Replace the whole subtree with a single reference when possible.
     if (statusMap.get(ariaNode) === 'same' && ariaNode.ref) {
-      lines.push(indent + `- ref=${ariaNode.ref} [unchanged]`);
+      lines.push(indent(depth) + `- ref=${ariaNode.ref} [unchanged]`);
       return;
     }
 
     // When producing a diff, add <changed> marker to all diff roots.
-    const isDiffRoot = !!previousSnapshot && !indent;
-    const escapedKey = indent + '- ' + (isDiffRoot ? '<changed> ' : '') + yamlEscapeKeyIfNeeded(createKey(ariaNode, renderCursorPointer));
+    const isDiffRoot = !!previousSnapshot && !depth;
+    const escapedKey = indent(depth) + '- ' + (isDiffRoot ? '<changed> ' : '') + yamlEscapeKeyIfNeeded(createKey(ariaNode, renderCursorPointer));
     const singleInlinedTextChild = getSingleInlinedTextChild(ariaNode);
+    const isAtDepthLimit = !!publicOptions.depth && depth === publicOptions.depth;
+    const hasNoChildren = !singleInlinedTextChild && (!ariaNode.children.length || isAtDepthLimit);
 
-    if (!ariaNode.children.length && !Object.keys(ariaNode.props).length) {
+    if (hasNoChildren && !Object.keys(ariaNode.props).length) {
       // Leaf node without children.
       lines.push(escapedKey);
     } else if (singleInlinedTextChild !== undefined) {
@@ -649,24 +661,23 @@ export function renderAriaTree(ariaSnapshot: AriaSnapshot, publicOptions: AriaTr
       // Node with (optional) props and some children.
       lines.push(escapedKey + ':');
       for (const [name, value] of Object.entries(ariaNode.props))
-        lines.push(indent + '  - /' + name + ': ' + yamlEscapeValueIfNeeded(value));
+        lines.push(indent(depth + 1) + '- /' + name + ': ' + yamlEscapeValueIfNeeded(value));
 
-      const childIndent = indent + '  ';
       const inCursorPointer = !!ariaNode.ref && renderCursorPointer && aria.hasPointerCursor(ariaNode);
       for (const child of ariaNode.children) {
         if (typeof child === 'string')
-          visitText(includeText(ariaNode, child) ? child : '', childIndent);
+          visitText(includeText(ariaNode, child) ? child : '', depth + 1);
         else
-          visit(child, childIndent, renderCursorPointer && !inCursorPointer);
+          visit(child, depth + 1, renderCursorPointer && !inCursorPointer);
       }
     }
   };
 
   for (const nodeToRender of nodesToRender) {
     if (typeof nodeToRender === 'string')
-      visitText(nodeToRender, '');
+      visitText(nodeToRender, 0);
     else
-      visit(nodeToRender, '', !!options.renderCursorPointer);
+      visit(nodeToRender, 0, !!options.renderCursorPointer);
   }
   return lines.join('\n');
 }

packages/injected/src/injectedScript.ts

@@ -306,7 +306,7 @@ export class InjectedScript {
     return this.incrementalAriaSnapshot(node, options).full;
   }
 
-  incrementalAriaSnapshot(node: Node, options: AriaTreeOptions & { track?: string }): { full: string, incremental?: string, iframeRefs: string[] } {
+  incrementalAriaSnapshot(node: Node, options: AriaTreeOptions & { track?: string, depth?: number }): { full: string, incremental?: string, iframeRefs: string[] } {
     if (node.nodeType !== Node.ELEMENT_NODE)
       throw this.createStacklessError('Can only capture aria snapshot of Element nodes.');
     const ariaSnapshot = generateAriaTree(node as Element, options);

packages/playwright-client/types/types.d.ts

@@ -4538,6 +4538,11 @@ export interface Page {
    * @param options
    */
   snapshotForAI(options?: {
+    /**
+     * When specified, limits the depth of the snapshot.
+     */
+    depth?: number;
+
     /**
      * Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `actionTimeout`
      * option in the config, or by using the

packages/playwright-core/src/client/page.ts

@@ -855,8 +855,8 @@ export class Page extends ChannelOwner<channels.PageChannel> implements api.Page
     return result.pdf;
   }
 
-  async snapshotForAI(options: TimeoutOptions & { track?: string } = {}): Promise<{ full: string, incremental?: string }> {
-    return await this._channel.snapshotForAI({ timeout: this._timeoutSettings.timeout(options), track: options.track });
+  async snapshotForAI(options: TimeoutOptions & { track?: string, depth?: number } = {}): Promise<{ full: string, incremental?: string }> {
+    return await this._channel.snapshotForAI({ timeout: this._timeoutSettings.timeout(options), track: options.track, depth: options.depth });
   }
 
   async _setDockTile(image: Buffer) {

packages/playwright-core/src/protocol/validator.ts

@@ -1497,6 +1497,7 @@ scheme.PageRequestsResult = tObject({
 scheme.PageSnapshotForAIParams = tObject({
   track: tOptional(tString),
   selector: tOptional(tString),
+  depth: tOptional(tInt),
   timeout: tFloat,
 });
 scheme.PageSnapshotForAIResult = tObject({

packages/playwright-core/src/server/page.ts

@@ -886,7 +886,7 @@ export class Page extends SdkObject<PageEventMap> {
     await Promise.all(this.frames().map(frame => frame.hideHighlight().catch(() => {})));
   }
 
-  async snapshotForAI(progress: Progress, options: { track?: string, doNotRenderActive?: boolean, selector?: string } = {}): Promise<{ full: string, incremental?: string }> {
+  async snapshotForAI(progress: Progress, options: { track?: string, doNotRenderActive?: boolean, selector?: string, depth?: number } = {}): Promise<{ full: string, incremental?: string }> {
     if (options.selector && options.track)
       throw new Error('Cannot specify both selector and track options');
 
@@ -1047,7 +1047,7 @@ export class InitScript extends DisposableObject {
   }
 }
 
-async function snapshotFrameForAI(progress: Progress, frame: frames.Frame, options: { track?: string, doNotRenderActive?: boolean, info?: SelectorInfo } = {}): Promise<{ full: string[], incremental?: string[] }> {
+async function snapshotFrameForAI(progress: Progress, frame: frames.Frame, options: { track?: string, doNotRenderActive?: boolean, info?: SelectorInfo, depth?: number } = {}): Promise<{ full: string[], incremental?: string[] }> {
   // Only await the topmost navigations, inner frames will be empty when racing.
   const snapshot = await frame.retryWithProgressAndTimeouts(progress, [1000, 2000, 4000, 8000], async continuePolling => {
     try {
@@ -1069,6 +1069,7 @@ async function snapshotFrameForAI(progress: Progress, frame: frames.Frame, optio
         track: options.track,
         doNotRenderActive: options.doNotRenderActive,
         info: options.info,
+        depth: options.depth,
       }));
       if (snapshotOrRetry === true)
         return continuePolling;

packages/playwright-core/types/types.d.ts

@@ -4538,6 +4538,11 @@ export interface Page {
    * @param options
    */
   snapshotForAI(options?: {
+    /**
+     * When specified, limits the depth of the snapshot.
+     */
+    depth?: number;
+
     /**
      * Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `actionTimeout`
      * option in the config, or by using the

packages/protocol/src/channels.d.ts

@@ -2613,11 +2613,13 @@ export type PageRequestsResult = {
 export type PageSnapshotForAIParams = {
   track?: string,
   selector?: string,
+  depth?: number,
   timeout: number,
 };
 export type PageSnapshotForAIOptions = {
   track?: string,
   selector?: string,
+  depth?: number,
 };
 export type PageSnapshotForAIResult = {
   full: string,

packages/protocol/src/protocol.yml

@@ -2014,6 +2014,7 @@ Page:
         # When track is present, an incremental snapshot is returned when possible.
         track: string?
         selector: string?
+        depth: int?
         timeout: float
       returns:
         full: string