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: playwright-cli snapshot [element] (#39643)
Dmitry Gozmancba36ec67bf0
diff --git a/docs/src/api/class-locator.md b/docs/src/api/class-locator.mdindex a94cdbe4a0..179bc2f228 100644--- a/docs/src/api/class-locator.md+++ b/docs/src/api/class-locator.md@@ -2485,6 +2485,19 @@ This method expects [Locator] to point to an### option: Locator.setInputFiles.timeout = %%-input-timeout-js-%%* since: v1.14+## async method: Locator.snapshotForAI+* since: v1.59+- returns: <[Object]>+ - `full` <[string]> Accessibility snapshot of the element matching this locator.++Returns an accessibility snapshot of the element's subtree optimized for AI consumption.++### option: Locator.snapshotForAI.timeout = %%-input-timeout-%%+* since: v1.59++### option: Locator.snapshotForAI.timeout = %%-input-timeout-js-%%+* since: v1.59+## async method: Locator.tap* since: v1.14diff --git a/docs/src/api/class-page.md b/docs/src/api/class-page.mdindex f1e38b9a74..42c4714c48 100644--- a/docs/src/api/class-page.md+++ b/docs/src/api/class-page.md@@ -4223,6 +4223,9 @@ Returns an accessibility snapshot of the page optimized for AI consumption.### option: Page.snapshotForAI.timeout = %%-input-timeout-%%* since: v1.59+### option: Page.snapshotForAI.timeout = %%-input-timeout-js-%%+* since: v1.59+### option: Page.snapshotForAI.track* since: v1.59- `track` <[string]>diff --git a/packages/playwright-client/types/types.d.ts b/packages/playwright-client/types/types.d.tsindex 0f3a236cf3..8c1d25aa20 100644--- a/packages/playwright-client/types/types.d.ts+++ b/packages/playwright-client/types/types.d.ts@@ -4538,6 +4538,14 @@ export interface Page {* @param options*/snapshotForAI(options?: {+ /**+ * 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;+/*** When specified, enables incremental snapshots. Subsequent calls with the same track name will return an incremental* snapshot containing only changes since the last call.@@ -14666,6 +14674,25 @@ export interface Locator {timeout?: number;}): Promise<void>;+ /**+ * Returns an accessibility snapshot of the element's subtree optimized for AI consumption.+ * @param options+ */+ snapshotForAI(options?: {+ /**+ * 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<{+ /**+ * Accessibility snapshot of the element matching this locator.+ */+ full: string;+ }>;+/*** Perform a tap gesture on the element matching the locator. For examples of emulating other gestures by manually* dispatching touch events, see the [emulating legacy touch events](https://playwright.dev/docs/touch-events) page.diff --git a/packages/playwright-core/src/client/locator.ts b/packages/playwright-core/src/client/locator.tsindex 88af0b2eea..fdf1cb8e08 100644--- a/packages/playwright-core/src/client/locator.ts+++ b/packages/playwright-core/src/client/locator.ts@@ -378,6 +378,10 @@ 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 _expect(expression: string, options: FrameExpectParams): Promise<{ matches: boolean, received?: any, log?: string[], timedOut?: boolean, errorMessage?: string }> {return this._frame._expect(expression, {...options,diff --git a/packages/playwright-core/src/protocol/validator.ts b/packages/playwright-core/src/protocol/validator.tsindex eff128b98f..65b8d843f4 100644--- a/packages/playwright-core/src/protocol/validator.ts+++ b/packages/playwright-core/src/protocol/validator.ts@@ -1493,6 +1493,7 @@ scheme.PageRequestsResult = tObject({});scheme.PageSnapshotForAIParams = tObject({track: tOptional(tString),+ selector: tOptional(tString),timeout: tFloat,});scheme.PageSnapshotForAIResult = tObject({diff --git a/packages/playwright-core/src/server/page.ts b/packages/playwright-core/src/server/page.tsindex e30e25808a..894f1a49dc 100644--- a/packages/playwright-core/src/server/page.ts+++ b/packages/playwright-core/src/server/page.ts@@ -30,12 +30,13 @@ import { LongStandingScope, assert, renderTitleForCall, trimStringWithEllipsis }import { asLocator } from '../utils';import { getComparator } from './utils/comparators';import { debugLogger } from './utils/debugLogger';-import { isInvalidSelectorError } from '../utils/isomorphic/selectorParser';+import { isInvalidSelectorError, stringifySelector } from '../utils/isomorphic/selectorParser';import { ManualPromise } from '../utils/isomorphic/manualPromise';import { parseEvaluationResultValue } from '../utils/isomorphic/utilityScriptSerializers';import { compressCallLog } from './callLog';import * as rawBindingsControllerSource from '../generated/bindingsControllerSource';import { Screencast } from './screencast';+import { NonRecoverableDOMError } from './dom';import type { Artifact } from './artifact';import type { BrowserContextEventMap } from './browserContext';@@ -48,6 +49,7 @@ import type * as types from './types';import type { ImageComparatorOptions } from './utils/comparators';import type * as channels from '@protocol/channels';import type { BindingPayload } from '@injected/bindingsController';+import type { SelectorInfo } from './frameSelectors';export interface PageDelegate {readonly rawMouse: input.RawMouse;@@ -884,8 +886,23 @@ 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 } = {}): Promise<{ full: string, incremental?: string }> {- const snapshot = await snapshotFrameForAI(progress, this.mainFrame(), options);+ async snapshotForAI(progress: Progress, options: { track?: string, doNotRenderActive?: boolean, selector?: string } = {}): Promise<{ full: string, incremental?: string }> {+ if (options.selector && options.track)+ throw new Error('Cannot specify both selector and track options');++ let frame: frames.Frame;+ let info: SelectorInfo | undefined;+ if (options.selector) {+ const resolved = await this.mainFrame().selectors.resolveInjectedForSelector(options.selector, { strict: true });+ if (!resolved)+ throw new Error(`Selector "${options.selector}" did not resolve to any element`);+ frame = resolved.frame;+ info = resolved.info;+ } else {+ frame = this.mainFrame();+ }++ const snapshot = await snapshotFrameForAI(progress, frame, { ...options, info });return { full: snapshot.full.join('\n'), incremental: snapshot.incremental?.join('\n') };}@@ -1030,20 +1047,33 @@ export class InitScript extends DisposableObject {}}-async function snapshotFrameForAI(progress: Progress, frame: frames.Frame, options: { track?: string, doNotRenderActive?: boolean } = {}): Promise<{ full: string[], incremental?: string[] }> {+async function snapshotFrameForAI(progress: Progress, frame: frames.Frame, options: { track?: string, doNotRenderActive?: boolean, info?: SelectorInfo } = {}): 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 {const context = await progress.race(frame._utilityContext());const injectedScript = await progress.race(context.injectedScript());const snapshotOrRetry = await progress.race(injectedScript.evaluate((injected, options) => {+ if (options.info) {+ const element = injected.querySelector(options.info.parsed, injected.document, options.info.strict);+ if (!element)+ return false;+ return injected.incrementalAriaSnapshot(element, { mode: 'ai', ...options });+ }const node = injected.document.body;if (!node)return true;return injected.incrementalAriaSnapshot(node, { mode: 'ai', ...options });- }, { refPrefix: frame.seq ? 'f' + frame.seq : '', track: options.track, doNotRenderActive: options.doNotRenderActive }));+ }, {+ refPrefix: frame.seq ? 'f' + frame.seq : '',+ track: options.track,+ doNotRenderActive: options.doNotRenderActive,+ info: options.info,+ }));if (snapshotOrRetry === true)return continuePolling;+ if (snapshotOrRetry === false)+ throw new NonRecoverableDOMError(`Selector "${stringifySelector(options.info!.parsed)}" does not match any element`);return snapshotOrRetry;} catch (e) {if (frame.isNonRetriableError(e))@@ -1093,7 +1123,7 @@ async function snapshotFrameRefForAI(progress: Progress, parentFrame: frames.Fraif (!child)return { full: [] };try {- return await snapshotFrameForAI(progress, child.frame, options);+ return await snapshotFrameForAI(progress, child.frame, { ...options, info: undefined });} catch {return { full: [] };}diff --git a/packages/playwright-core/src/tools/backend/response.ts b/packages/playwright-core/src/tools/backend/response.tsindex bcb7c23024..81b959af61 100644--- a/packages/playwright-core/src/tools/backend/response.ts+++ b/packages/playwright-core/src/tools/backend/response.ts@@ -47,6 +47,7 @@ export class Response {private _context: Context;private _includeSnapshot: 'none' | 'full' | 'incremental' = 'none';private _includeSnapshotFileName: string | undefined;+ private _includeSnapshotSelector: string | undefined;private _isClose: boolean = false;readonly toolName: string;@@ -126,9 +127,10 @@ export class Response {this._includeSnapshot = this._context.config.snapshot?.mode || 'incremental';}- setIncludeFullSnapshot(includeSnapshotFileName?: string) {+ setIncludeFullSnapshot(includeSnapshotFileName?: string, selector?: string) {this._includeSnapshot = 'full';this._includeSnapshotFileName = includeSnapshotFileName;+ this._includeSnapshotSelector = selector;}async serialize(): Promise<CallToolResult> {@@ -193,7 +195,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._clientWorkspace) : undefined;+ const tabSnapshot = this._context.currentTab() ? await this._context.currentTabOrDie().captureSnapshot(this._includeSnapshotSelector, 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.tsindex 2988dff0bb..0506017564 100644--- a/packages/playwright-core/src/tools/backend/snapshot.ts+++ b/packages/playwright-core/src/tools/backend/snapshot.ts@@ -27,13 +27,14 @@ 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.'),+ selector: z.string().optional().describe('Element selector of the root element to capture a partial snapshot instead of the whole page'),}),type: 'readOnly',},handle: async (context, params, response) => {await context.ensureTab();- response.setIncludeFullSnapshot(params.filename);+ response.setIncludeFullSnapshot(params.filename, params.selector);},});diff --git a/packages/playwright-core/src/tools/backend/tab.ts b/packages/playwright-core/src/tools/backend/tab.tsindex c6eebd3413..be8b823e98 100644--- a/packages/playwright-core/src/tools/backend/tab.ts+++ b/packages/playwright-core/src/tools/backend/tab.ts@@ -372,11 +372,11 @@ export class Tab extends EventEmitter<TabEventsInterface> {this._requests.length = 0;}- async captureSnapshot(relativeTo: string | undefined): Promise<TabSnapshot> {+ async captureSnapshot(selector: string | undefined, relativeTo: string | undefined): Promise<TabSnapshot> {await this._initializedPromise;let tabSnapshot: TabSnapshot | undefined;const modalStates = await this._raceAgainstModalStates(async () => {- const snapshot = await this.page.snapshotForAI({ track: 'response' });+ const snapshot: { full: string, incremental?: string } = selector ? await this.page.locator(selector).snapshotForAI() : await this.page.snapshotForAI({ track: 'response' });tabSnapshot = {ariaSnapshot: snapshot.full,ariaSnapshotDiff: this._needsFullSnapshot ? undefined : snapshot.incremental,diff --git a/packages/playwright-core/src/tools/cli-daemon/commands.ts b/packages/playwright-core/src/tools/cli-daemon/commands.tsindex 98e691f02f..06b28a0cd1 100644--- a/packages/playwright-core/src/tools/cli-daemon/commands.ts+++ b/packages/playwright-core/src/tools/cli-daemon/commands.ts@@ -328,12 +328,14 @@ const snapshot = declareCommand({name: 'snapshot',description: 'Capture page snapshot to obtain element ref',category: 'core',- args: z.object({}),+ args: z.object({+ element: z.string().optional().describe('Element selector of 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.'),}),toolName: 'browser_snapshot',- toolParams: ({ filename }) => ({ filename }),+ toolParams: ({ filename, element }) => ({ filename, selector: element }),});const evaluate = declareCommand({diff --git a/packages/playwright-core/types/types.d.ts b/packages/playwright-core/types/types.d.tsindex 0f3a236cf3..8c1d25aa20 100644--- a/packages/playwright-core/types/types.d.ts+++ b/packages/playwright-core/types/types.d.ts@@ -4538,6 +4538,14 @@ export interface Page {* @param options*/snapshotForAI(options?: {+ /**+ * 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;+/*** When specified, enables incremental snapshots. Subsequent calls with the same track name will return an incremental* snapshot containing only changes since the last call.@@ -14666,6 +14674,25 @@ export interface Locator {timeout?: number;}): Promise<void>;+ /**+ * Returns an accessibility snapshot of the element's subtree optimized for AI consumption.+ * @param options+ */+ snapshotForAI(options?: {+ /**+ * 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<{+ /**+ * Accessibility snapshot of the element matching this locator.+ */+ full: string;+ }>;+/*** Perform a tap gesture on the element matching the locator. For examples of emulating other gestures by manually* dispatching touch events, see the [emulating legacy touch events](https://playwright.dev/docs/touch-events) page.diff --git a/packages/protocol/src/channels.d.ts b/packages/protocol/src/channels.d.tsindex f384e99aed..c0a9f5c6c2 100644--- a/packages/protocol/src/channels.d.ts+++ b/packages/protocol/src/channels.d.ts@@ -2608,10 +2608,12 @@ export type PageRequestsResult = {};export type PageSnapshotForAIParams = {track?: string,+ selector?: string,timeout: number,};export type PageSnapshotForAIOptions = {track?: string,+ selector?: string,};export type PageSnapshotForAIResult = {full: string,diff --git a/packages/protocol/src/protocol.yml b/packages/protocol/src/protocol.ymlindex 824adafc32..e53c57c5f8 100644--- a/packages/protocol/src/protocol.yml+++ b/packages/protocol/src/protocol.yml@@ -2012,6 +2012,7 @@ Page:parameters:# When track is present, an incremental snapshot is returned when possible.track: string?+ selector: string?timeout: floatreturns:full: stringdiff --git a/tests/mcp/cli-core.spec.ts b/tests/mcp/cli-core.spec.tsindex af56680d82..f5d1674cda 100644--- a/tests/mcp/cli-core.spec.ts+++ b/tests/mcp/cli-core.spec.ts@@ -263,3 +263,19 @@ test('click button with wrong css selector', async ({ cli, server }) => {const { output } = await cli('click', '#target');expect(output).toContain(`Error: Selector #target does not match any elements.`);});++test('partial snapshot', 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 { snapshot: partialSnapshot } = await cli('snapshot', '#two');+ expect(partialSnapshot).toBe(`- button "Cancel" [ref=e3]`);++ const { output: strictError } = await cli('snapshot', 'button');+ expect(strictError).toContain(`strict mode violation`);++ const { output: noMatchError } = await cli('snapshot', '#target');+ expect(noMatchError).toContain(`Selector "#target" does not match any element`);+});