Skip to content

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

fix(cli): resolve refs for snapshot command (#40114)

Yury Semikhatskyfb75e2528d86
diff --git a/packages/playwright-core/src/tools/backend/response.ts b/packages/playwright-core/src/tools/backend/response.ts
index 5a0b030669..6a92c68132 100644
--- a/packages/playwright-core/src/tools/backend/response.ts
+++ b/packages/playwright-core/src/tools/backend/response.ts
@@ -21,6 +21,7 @@ import debug from 'debug';
import { renderModalStates } from './tab';
import { scaleImageToFitMessage } from './screenshot';
+import type * as playwright from '../../..';
import type { TabHeader } from './tab';
import type { CallToolResult, ImageContent, TextContent } from '@modelcontextprotocol/sdk/types.js';
import type { Context, FilenameTemplate } from './context';
@@ -47,7 +48,7 @@ export class Response {
private _context: Context;
private _includeSnapshot: 'none' | 'full' | 'explicit' = 'none';
private _includeSnapshotFileName: string | undefined;
- private _includeSnapshotSelector: string | undefined;
+ private _includeSnapshotRoot: playwright.Locator | undefined;
private _includeSnapshotDepth: number | undefined;
private _isClose: boolean = false;
@@ -134,11 +135,11 @@ export class Response {
this._includeSnapshot = this._context.config.snapshot?.mode ?? 'full';
}
- setIncludeFullSnapshot(includeSnapshotFileName?: string, selector?: string, depth?: number) {
+ setIncludeFullSnapshot(includeSnapshotFileName?: string, root?: playwright.Locator, depth?: number) {
this._includeSnapshot = 'explicit';
this._includeSnapshotFileName = includeSnapshotFileName;
this._includeSnapshotDepth = depth;
- this._includeSnapshotSelector = selector;
+ this._includeSnapshotRoot = root;
}
private _redactSecrets(text: string): string {
@@ -213,7 +214,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._includeSnapshotDepth, this._clientWorkspace) : undefined;
+ const tabSnapshot = this._context.currentTab() ? await this._context.currentTabOrDie().captureSnapshot(this._includeSnapshotRoot, 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)
diff --git a/packages/playwright-core/src/tools/backend/snapshot.ts b/packages/playwright-core/src/tools/backend/snapshot.ts
index 62f27a0a76..bfa437ec1f 100644
--- a/packages/playwright-core/src/tools/backend/snapshot.ts
+++ b/packages/playwright-core/src/tools/backend/snapshot.ts
@@ -17,9 +17,9 @@
import * as z from 'zod';
import { formatObject, formatObjectOrVoid } from '@isomorphic/stringUtils';
-import { defineTabTool, defineTool } from './tool';
+import { defineTabTool } from './tool';
-const snapshot = defineTool({
+const snapshot = defineTabTool({
capability: 'core',
schema: {
name: 'browser_snapshot',
@@ -27,15 +27,18 @@ const snapshot = defineTool({
description: 'Capture accessibility snapshot of the current page, this is better than screenshot',
inputSchema: z.object({
filename: z.string().optional().describe('Save snapshot to markdown file instead of returning it in the response.'),
+ ref: z.string().optional().describe('Element reference from the previous page snapshot to capture a partial snapshot instead of the whole page'),
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, params.depth);
+ handle: async (tab, params, response) => {
+ const root = (params.ref || params.selector)
+ ? (await tab.refLocator({ ref: params.ref ?? '', selector: params.selector })).locator
+ : undefined;
+ response.setIncludeFullSnapshot(params.filename, root, params.depth);
},
});
diff --git a/packages/playwright-core/src/tools/backend/tab.ts b/packages/playwright-core/src/tools/backend/tab.ts
index 2cbe7f26f6..f5a1f1077d 100644
--- a/packages/playwright-core/src/tools/backend/tab.ts
+++ b/packages/playwright-core/src/tools/backend/tab.ts
@@ -383,12 +383,12 @@ export class Tab extends EventEmitter<TabEventsInterface> {
this._requests.length = 0;
}
- async captureSnapshot(selector: string | undefined, depth: number | undefined, relativeTo: string | undefined): Promise<TabSnapshot> {
+ async captureSnapshot(root: playwright.Locator | undefined, depth: number | undefined, relativeTo: string | undefined): Promise<TabSnapshot> {
await this._initializedPromise;
let tabSnapshot: TabSnapshot | undefined;
const modalStates = await this._raceAgainstModalStates(async () => {
- const ariaSnapshot = selector
- ? await this.page.locator(selector).ariaSnapshot({ mode: 'ai', depth })
+ const ariaSnapshot = root
+ ? await root.ariaSnapshot({ mode: 'ai', depth })
: await this.page.ariaSnapshot({ mode: 'ai', depth });
tabSnapshot = {
ariaSnapshot,
diff --git a/packages/playwright-core/src/tools/cli-daemon/commands.ts b/packages/playwright-core/src/tools/cli-daemon/commands.ts
index 59d2484d1a..62583a4cfb 100644
--- a/packages/playwright-core/src/tools/cli-daemon/commands.ts
+++ b/packages/playwright-core/src/tools/cli-daemon/commands.ts
@@ -345,14 +345,14 @@ const snapshot = declareCommand({
description: 'Capture page snapshot to obtain element ref',
category: 'core',
args: z.object({
- element: z.string().optional().describe('Element selector of the root element to capture a partial snapshot instead of the whole page'),
+ element: z.string().optional().describe('Element reference from the previous page snapshot, or a unique element selector for the root element to capture a partial snapshot instead of the whole page'),
}),
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, depth }) => ({ filename, selector: element, depth }),
+ toolParams: ({ filename, element, depth }) => ({ filename, ...asRef(element), depth }),
});
const evaluate = declareCommand({
diff --git a/tests/mcp/cli-core.spec.ts b/tests/mcp/cli-core.spec.ts
index f7bcbdb999..89c472b887 100644
--- a/tests/mcp/cli-core.spec.ts
+++ b/tests/mcp/cli-core.spec.ts
@@ -280,6 +280,19 @@ test('partial snapshot', async ({ cli, server }) => {
expect(noMatchError).toContain(`"#target" does not match any element`);
});
+test('partial snapshot by ref', { annotation: { type: 'issue', description: 'https://github.com/microsoft/playwright-cli/issues/347' } }, async ({ cli, server }) => {
+ server.setContent('/', `<button id=one>Submit</button><button id=two>Cancel</button>`, 'text/html');
+ const { snapshot } = await cli('open', server.PREFIX);
+ expect(snapshot).toContain('- button "Submit" [ref=e2]');
+ expect(snapshot).toContain('- button "Cancel" [ref=e3]');
+
+ const { inlineSnapshot: partialSnapshot } = await cli('snapshot', 'e3');
+ expect(partialSnapshot).toBe(`- button "Cancel" [ref=e3]`);
+
+ const { output: missingRefError } = await cli('snapshot', 'e999');
+ expect(missingRefError).toContain(`Ref e999 not found in the current page snapshot.`);
+});
+
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);
diff --git a/tests/mcp/core.spec.ts b/tests/mcp/core.spec.ts
index a0936e80ac..9a6e3fa409 100644
--- a/tests/mcp/core.spec.ts
+++ b/tests/mcp/core.spec.ts
@@ -275,3 +275,41 @@ test('snapshot depth', async ({ client, server }) => {
- button "Button" [ref=e5]`,
});
});
+
+test('snapshot by ref', { annotation: { type: 'issue', description: 'https://github.com/microsoft/playwright-cli/issues/347' } }, 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: {
+ ref: 'e2',
+ }
+ })).toHaveResponse({
+ inlineSnapshot: `- list [ref=e2]:
+ - listitem [ref=e3]: text
+ - listitem [ref=e4]:
+ - button "Button" [ref=e5]`,
+ });
+
+ expect(await client.callTool({
+ name: 'browser_snapshot',
+ arguments: {
+ ref: 'e999',
+ }
+ })).toHaveResponse({
+ error: expect.stringContaining(`Ref e999 not found in the current page snapshot. Try capturing new snapshot.`),
+ isError: true,
+ });
+});