add mcp and cli commands

Author: dgozman

docs/src/api/class-locator.md

@@ -2498,6 +2498,12 @@ Returns an accessibility snapshot of the element's subtree optimized for AI cons
 ### option: Locator.snapshotForAI.timeout = %%-input-timeout-js-%%
 * since: v1.59
 
+### option: Locator.snapshotForAI.depth
+* since: v1.59
+- `depth` <[int]>
+
+When specified, limits the depth of the snapshot.
+
 ## async method: Locator.tap
 * since: v1.14
 

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

@@ -14689,6 +14689,11 @@ export interface Locator {
    * @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/locator.ts

@@ -378,8 +378,8 @@ export class Locator implements api.Locator {
     await this._frame._channel.waitForSelector({ selector: this._selector, strict: true, omitReturnValue: true, ...options, timeout: this._frame._timeout(options) });
   }
 
-  async snapshotForAI(options: TimeoutOptions = {}): Promise<{ full: string }> {
-    return await this._frame._page!._channel.snapshotForAI({ timeout: this._frame._timeout(options), selector: this._selector });
+  async snapshotForAI(options: TimeoutOptions & { depth?: number } = {}): Promise<{ full: string }> {
+    return await this._frame._page!._channel.snapshotForAI({ timeout: this._frame._timeout(options), selector: this._selector, depth: options.depth });
   }
 
   async _expect(expression: string, options: FrameExpectParams): Promise<{ matches: boolean, received?: any, log?: string[], timedOut?: boolean, errorMessage?: string }> {

packages/playwright-core/src/tools/backend/response.ts

@@ -48,6 +48,7 @@ export class Response {
   private _includeSnapshot: 'none' | 'full' | 'incremental' = 'none';
   private _includeSnapshotFileName: string | undefined;
   private _includeSnapshotSelector: string | undefined;
+  private _includeSnapshotDepth: number | undefined;
   private _isClose: boolean = false;
 
   readonly toolName: string;
@@ -127,9 +128,10 @@ export class Response {
     this._includeSnapshot = this._context.config.snapshot?.mode || 'incremental';
   }
 
-  setIncludeFullSnapshot(includeSnapshotFileName?: string, selector?: string) {
+  setIncludeFullSnapshot(includeSnapshotFileName?: string, selector?: string, depth?: number) {
     this._includeSnapshot = 'full';
     this._includeSnapshotFileName = includeSnapshotFileName;
+    this._includeSnapshotDepth = depth;
     this._includeSnapshotSelector = selector;
   }
 
@@ -195,7 +197,7 @@ 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._includeSnapshotSelector, this._clientWorkspace) : undefined;
+    const tabSnapshot = this._context.currentTab() ? await this._context.currentTabOrDie().captureSnapshot(this._includeSnapshotSelector, this._includeSnapshotDepth, this._clientWorkspace) : 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)

packages/playwright-core/src/tools/backend/snapshot.ts

@@ -28,13 +28,14 @@ const snapshot = defineTool({
     inputSchema: z.object({
       filename: z.string().optional().describe('Save snapshot to markdown file instead of returning it in the response.'),
       selector: z.string().optional().describe('Element selector of the root element to capture a partial snapshot instead of the whole page'),
+      depth: z.number().optional().describe('Limit the depth of the snapshot tree'),
     }),
     type: 'readOnly',
   },
 
   handle: async (context, params, response) => {
     await context.ensureTab();
-    response.setIncludeFullSnapshot(params.filename, params.selector);
+    response.setIncludeFullSnapshot(params.filename, params.selector, params.depth);
   },
 });
 

packages/playwright-core/src/tools/backend/tab.ts

@@ -372,11 +372,11 @@ export class Tab extends EventEmitter<TabEventsInterface> {
     this._requests.length = 0;
   }
 
-  async captureSnapshot(selector: string | undefined, relativeTo: string | undefined): Promise<TabSnapshot> {
+  async captureSnapshot(selector: string | undefined, depth: number | undefined, relativeTo: string | undefined): Promise<TabSnapshot> {
     await this._initializedPromise;
     let tabSnapshot: TabSnapshot | undefined;
     const modalStates = await this._raceAgainstModalStates(async () => {
-      const snapshot: { full: string, incremental?: string } = selector ? await this.page.locator(selector).snapshotForAI() : await this.page.snapshotForAI({ track: 'response' });
+      const snapshot: { full: string, incremental?: string } = selector ? await this.page.locator(selector).snapshotForAI({ depth }) : await this.page.snapshotForAI({ track: 'response', depth });
       tabSnapshot = {
         ariaSnapshot: snapshot.full,
         ariaSnapshotDiff: this._needsFullSnapshot ? undefined : snapshot.incremental,

packages/playwright-core/src/tools/cli-daemon/commands.ts

@@ -347,9 +347,10 @@ const snapshot = declareCommand({
   }),
   options: z.object({
     filename: z.string().optional().describe('Save snapshot to markdown file instead of returning it in the response.'),
+    depth: numberArg.optional().describe('Limit snapshot depth, unlimited by default.'),
   }),
   toolName: 'browser_snapshot',
-  toolParams: ({ filename, element }) => ({ filename, selector: element }),
+  toolParams: ({ filename, element, depth }) => ({ filename, selector: element, depth }),
 });
 
 const evaluate = declareCommand({

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

@@ -14689,6 +14689,11 @@ export interface Locator {
    * @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

tests/mcp/cli-core.spec.ts

@@ -279,3 +279,20 @@ test('partial snapshot', async ({ cli, server }) => {
   const { output: noMatchError } = await cli('snapshot', '#target');
   expect(noMatchError).toContain(`Selector "#target" does not match any element`);
 });
+
+test('snapshot depth', async ({ cli, server }) => {
+  server.setContent('/', `<ul><li><button id=one>Submit</button></li><li><button id=two>Cancel</button></li></ul>`, 'text/html');
+  await cli('open', server.PREFIX);
+
+  const { snapshot: limitedSnapshot } = await cli('snapshot', '--depth=1');
+  expect(limitedSnapshot).toBe(`- list [ref=e2]:
+  - listitem [ref=e3]
+  - listitem [ref=e5]`);
+
+  const { snapshot: fullSnapshot } = await cli('snapshot', '--depth=100');
+  expect(fullSnapshot).toBe(`- list [ref=e2]:
+  - listitem [ref=e3]:
+    - button "Submit" [ref=e4]
+  - listitem [ref=e5]:
+    - button "Cancel" [ref=e6]`);
+});

tests/mcp/core.spec.ts

@@ -246,3 +246,46 @@ test('visibility: hidden > visible should be shown', { annotation: { type: 'issu
     snapshot: expect.stringContaining(`- button "Button"`),
   });
 });
+
+test('snapshot depth', async ({ client, server }) => {
+  server.setContent('/', `
+    <ul>
+      <li>text</li>
+      <li>
+        <button>Button</button>
+      </li>
+    </ul>
+  `, 'text/html');
+
+  await client.callTool({
+    name: 'browser_navigate',
+    arguments: { url: server.PREFIX },
+  });
+
+  expect(await client.callTool({
+    name: 'browser_snapshot',
+    arguments: {
+      depth: 1,
+    }
+  })).toHaveResponse({
+    snapshot: `\`\`\`yaml
+- list [ref=e2]:
+  - listitem [ref=e3]: text
+  - listitem [ref=e4]
+\`\`\``,
+  });
+
+  expect(await client.callTool({
+    name: 'browser_snapshot',
+    arguments: {
+      depth: 2,
+    }
+  })).toHaveResponse({
+    snapshot: `\`\`\`yaml
+- list [ref=e2]:
+  - listitem [ref=e3]: text
+  - listitem [ref=e4]:
+    - button "Button" [ref=e5]
+\`\`\``,
+  });
+});