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
chore: simplify snapshotForAI to return string with mode option (#39755)
Pavel Feldman21c1cfce6457
diff --git a/docs/src/api/class-locator.md b/docs/src/api/class-locator.mdindex d361b0b1a2..c8f3570acd 100644--- a/docs/src/api/class-locator.md+++ b/docs/src/api/class-locator.md@@ -2487,8 +2487,7 @@ This method expects [Locator] to point to an## async method: Locator.snapshotForAI* since: v1.59-- returns: <[Object]>- - `full` <[string]> Accessibility snapshot of the element matching this locator.+- returns: <[string]>Returns an accessibility snapshot of the element's subtree optimized for AI consumption.diff --git a/docs/src/api/class-page.md b/docs/src/api/class-page.mdindex 730ced1bad..9978466b1b 100644--- a/docs/src/api/class-page.md+++ b/docs/src/api/class-page.md@@ -4213,9 +4213,7 @@ Page height in pixels.## async method: Page.snapshotForAI* since: v1.59-- returns: <[Object]>- - `full` <[string]> Full accessibility snapshot of the page.- - `incremental` ?<[string]> Incremental snapshot containing only changes since the last tracked snapshot, when using the [`option: Page.snapshotForAI.track`] option.+- returns: <[string]>Returns an accessibility snapshot of the page optimized for AI consumption.@@ -4229,8 +4227,16 @@ Returns an accessibility snapshot of the page optimized for AI consumption.* since: v1.59- `track` <[string]>-When specified, enables incremental snapshots. Subsequent calls with the same track name will return-an incremental snapshot containing only changes since the last call.+When specified, enables incremental snapshots. Subsequent calls with the same track name will+track changes between calls.++### option: Page.snapshotForAI.mode+* since: v1.59+- `mode` <[string]>++When set to `"incremental"` and [`option: Page.snapshotForAI.track`] is specified, returns an+incremental snapshot containing only changes since the last call with the same track name.+Defaults to `"full"`.### option: Page.snapshotForAI.depth* since: v1.59diff --git a/packages/playwright-client/types/types.d.ts b/packages/playwright-client/types/types.d.tsindex 98132f06fd..86882d9abc 100644--- a/packages/playwright-client/types/types.d.ts+++ b/packages/playwright-client/types/types.d.ts@@ -4525,6 +4525,13 @@ export interface Page {*/depth?: number;+ /**+ * When set to `"incremental"` and+ * [`track`](https://playwright.dev/docs/api/class-page#page-snapshot-for-ai-option-track) is specified, returns an+ * incremental snapshot containing only changes since the last call with the same track name. Defaults to `"full"`.+ */+ mode?: string;+/*** 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@@ -4534,22 +4541,11 @@ export interface Page {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.+ * When specified, enables incremental snapshots. Subsequent calls with the same track name will track changes between+ * calls.*/track?: string;- }): Promise<{- /**- * Full accessibility snapshot of the page.- */- full: string;-- /**- * Incremental snapshot containing only changes since the last tracked snapshot, when using the- * [`track`](https://playwright.dev/docs/api/class-page#page-snapshot-for-ai-option-track) option.- */- incremental?: string;- }>;+ }): Promise<string>;/*** **NOTE** Use locator-based [locator.tap([options])](https://playwright.dev/docs/api/class-locator#locator-tap) instead. Read@@ -14706,12 +14702,7 @@ export interface Locator {* 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;- }>;+ }): Promise<string>;/*** Perform a tap gesture on the element matching the locator. For examples of emulating other gestures by manuallydiff --git a/packages/playwright-core/src/client/locator.ts b/packages/playwright-core/src/client/locator.tsindex 6e543098ee..d92813f36e 100644--- a/packages/playwright-core/src/client/locator.ts+++ b/packages/playwright-core/src/client/locator.ts@@ -378,8 +378,9 @@ 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 & { depth?: number } = {}): Promise<{ full: string }> {- return await this._frame._page!._channel.snapshotForAI({ timeout: this._frame._timeout(options), selector: this._selector, depth: options.depth });+ async snapshotForAI(options: TimeoutOptions & { depth?: number } = {}): Promise<string> {+ const result = await this._frame._page!._channel.snapshotForAI({ timeout: this._frame._timeout(options), selector: this._selector, depth: options.depth });+ return result.snapshot;}async _expect(expression: string, options: FrameExpectParams): Promise<{ matches: boolean, received?: any, log?: string[], timedOut?: boolean, errorMessage?: string }> {diff --git a/packages/playwright-core/src/client/page.ts b/packages/playwright-core/src/client/page.tsindex 3109aa8c54..0f9027608b 100644--- a/packages/playwright-core/src/client/page.ts+++ b/packages/playwright-core/src/client/page.ts@@ -851,8 +851,9 @@ export class Page extends ChannelOwner<channels.PageChannel> implements api.Pagereturn result.pdf;}- 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 snapshotForAI(options: TimeoutOptions & { track?: string, mode?: 'full' | 'incremental', depth?: number } = {}): Promise<string> {+ const result = await this._channel.snapshotForAI({ timeout: this._timeoutSettings.timeout(options), track: options.track, mode: options.mode, depth: options.depth });+ return result.snapshot;}async _setDockTile(image: Buffer) {diff --git a/packages/playwright-core/src/protocol/validator.ts b/packages/playwright-core/src/protocol/validator.tsindex 86a14ab62b..3870bad4d7 100644--- a/packages/playwright-core/src/protocol/validator.ts+++ b/packages/playwright-core/src/protocol/validator.ts@@ -1496,13 +1496,13 @@ scheme.PageRequestsResult = tObject({});scheme.PageSnapshotForAIParams = tObject({track: tOptional(tString),+ mode: tOptional(tEnum(['full', 'incremental'])),selector: tOptional(tString),depth: tOptional(tInt),timeout: tFloat,});scheme.PageSnapshotForAIResult = tObject({- full: tString,- incremental: tOptional(tString),+ snapshot: tString,});scheme.PageStartJSCoverageParams = tObject({resetOnNavigation: tOptional(tBoolean),diff --git a/packages/playwright-core/src/server/page.ts b/packages/playwright-core/src/server/page.tsindex 567d2633ba..ff45b15766 100644--- a/packages/playwright-core/src/server/page.ts+++ b/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, depth?: number } = {}): Promise<{ full: string, incremental?: string }> {+ async snapshotForAI(progress: Progress, options: { track?: string, mode?: 'full' | 'incremental', doNotRenderActive?: boolean, selector?: string, depth?: number } = {}): Promise<{ snapshot: string }> {if (options.selector && options.track)throw new Error('Cannot specify both selector and track options');@@ -902,8 +902,9 @@ export class Page extends SdkObject<PageEventMap> {frame = this.mainFrame();}- const snapshot = await snapshotFrameForAI(progress, frame, { ...options, info });- return { full: snapshot.full.join('\n'), incremental: snapshot.incremental?.join('\n') };+ const result = await snapshotFrameForAI(progress, frame, { ...options, info });+ const snapshot = options.mode === 'incremental' && result.incremental !== undefined ? result.incremental.join('\n') : result.full.join('\n');+ return { snapshot };}async setDockTile(image: Buffer) {diff --git a/packages/playwright-core/src/tools/backend/response.ts b/packages/playwright-core/src/tools/backend/response.tsindex 0e4941351f..2949a46c6f 100644--- a/packages/playwright-core/src/tools/backend/response.ts+++ b/packages/playwright-core/src/tools/backend/response.ts@@ -197,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._includeSnapshotDepth, this._clientWorkspace) : undefined;+ const tabSnapshot = this._context.currentTab() ? await this._context.currentTabOrDie().captureSnapshot(this._includeSnapshotSelector, this._includeSnapshotDepth, this._clientWorkspace, this._includeSnapshot === 'incremental' ? 'incremental' : 'full') : 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)@@ -213,7 +213,7 @@ export class Response {// Handle tab snapshotif (tabSnapshot && this._includeSnapshot !== 'none') {- const snapshot = this._includeSnapshot === 'full' ? tabSnapshot.ariaSnapshot : tabSnapshot.ariaSnapshotDiff ?? tabSnapshot.ariaSnapshot;+ const snapshot = tabSnapshot.ariaSnapshot;if (this._context.config.outputMode === 'file' || this._includeSnapshotFileName) {const resolvedFile = await this.resolveClientFile({ prefix: 'page', ext: 'yml', suggestedFilename: this._includeSnapshotFileName }, 'Snapshot');await fs.promises.writeFile(resolvedFile.fileName, snapshot, 'utf-8');diff --git a/packages/playwright-core/src/tools/backend/tab.ts b/packages/playwright-core/src/tools/backend/tab.tsindex 4fb129b9ec..c28edd06c8 100644--- a/packages/playwright-core/src/tools/backend/tab.ts+++ b/packages/playwright-core/src/tools/backend/tab.ts@@ -84,7 +84,6 @@ export type TabHeader = {type TabSnapshot = {ariaSnapshot: string;- ariaSnapshotDiff?: string;modalStates: ModalState[];events: EventEntry[];consoleLink?: string;@@ -375,14 +374,15 @@ 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(selector: string | undefined, depth: number | undefined, relativeTo: string | undefined, mode: 'full' | 'incremental'): 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({ depth }) : await this.page.snapshotForAI({ track: 'response', depth });+ const ariaSnapshot = selector+ ? await this.page.locator(selector).snapshotForAI({ depth })+ : await this.page.snapshotForAI({ track: 'response', mode: this._needsFullSnapshot ? 'full' : mode, depth });tabSnapshot = {- ariaSnapshot: snapshot.full,- ariaSnapshotDiff: this._needsFullSnapshot ? undefined : snapshot.incremental,+ ariaSnapshot,modalStates: [],events: [],};@@ -398,7 +398,6 @@ export class Tab extends EventEmitter<TabEventsInterface> {this._needsFullSnapshot = !tabSnapshot;return tabSnapshot ?? {ariaSnapshot: '',- ariaSnapshotDiff: '',modalStates,events: [],};diff --git a/packages/playwright-core/types/types.d.ts b/packages/playwright-core/types/types.d.tsindex 98132f06fd..86882d9abc 100644--- a/packages/playwright-core/types/types.d.ts+++ b/packages/playwright-core/types/types.d.ts@@ -4525,6 +4525,13 @@ export interface Page {*/depth?: number;+ /**+ * When set to `"incremental"` and+ * [`track`](https://playwright.dev/docs/api/class-page#page-snapshot-for-ai-option-track) is specified, returns an+ * incremental snapshot containing only changes since the last call with the same track name. Defaults to `"full"`.+ */+ mode?: string;+/*** 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@@ -4534,22 +4541,11 @@ export interface Page {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.+ * When specified, enables incremental snapshots. Subsequent calls with the same track name will track changes between+ * calls.*/track?: string;- }): Promise<{- /**- * Full accessibility snapshot of the page.- */- full: string;-- /**- * Incremental snapshot containing only changes since the last tracked snapshot, when using the- * [`track`](https://playwright.dev/docs/api/class-page#page-snapshot-for-ai-option-track) option.- */- incremental?: string;- }>;+ }): Promise<string>;/*** **NOTE** Use locator-based [locator.tap([options])](https://playwright.dev/docs/api/class-locator#locator-tap) instead. Read@@ -14706,12 +14702,7 @@ export interface Locator {* 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;- }>;+ }): Promise<string>;/*** Perform a tap gesture on the element matching the locator. For examples of emulating other gestures by manuallydiff --git a/packages/playwright/src/index.ts b/packages/playwright/src/index.tsindex 3aa3db889a..2ce170393a 100644--- a/packages/playwright/src/index.ts+++ b/packages/playwright/src/index.ts@@ -709,7 +709,7 @@ class ArtifactsRecorder {try {// TODO: maybe capture snapshot when the error is created, so it's from the right page and right timeawait page._wrapApiCall(async () => {- this._pageSnapshot = (await page.snapshotForAI({ timeout: 5000 })).full;+ this._pageSnapshot = await page.snapshotForAI({ timeout: 5000 });}, { internal: true });} catch {}}diff --git a/packages/playwright/src/mcp/test/browserBackend.ts b/packages/playwright/src/mcp/test/browserBackend.tsindex 0b3ac3718e..b6438a84a7 100644--- a/packages/playwright/src/mcp/test/browserBackend.ts+++ b/packages/playwright/src/mcp/test/browserBackend.ts@@ -98,7 +98,7 @@ async function generatePausedMessage(testInfo: TestInfoImpl, context: playwrightlines.push(`- Page Snapshot:`,'```yaml',- (await page.snapshotForAI()).full,+ await page.snapshotForAI(),'```',);}diff --git a/packages/protocol/src/channels.d.ts b/packages/protocol/src/channels.d.tsindex d205475ae7..8512dcc0dd 100644--- a/packages/protocol/src/channels.d.ts+++ b/packages/protocol/src/channels.d.ts@@ -2612,18 +2612,19 @@ export type PageRequestsResult = {};export type PageSnapshotForAIParams = {track?: string,+ mode?: 'full' | 'incremental',selector?: string,depth?: number,timeout: number,};export type PageSnapshotForAIOptions = {track?: string,+ mode?: 'full' | 'incremental',selector?: string,depth?: number,};export type PageSnapshotForAIResult = {- full: string,- incremental?: string,+ snapshot: string,};export type PageStartJSCoverageParams = {resetOnNavigation?: boolean,diff --git a/packages/protocol/src/protocol.yml b/packages/protocol/src/protocol.ymlindex c7f20e761a..4c0ab686bc 100644--- a/packages/protocol/src/protocol.yml+++ b/packages/protocol/src/protocol.yml@@ -2013,12 +2013,16 @@ Page:parameters:# When track is present, an incremental snapshot is returned when possible.track: string?+ mode:+ type: enum?+ literals:+ - full+ - incrementalselector: string?depth: int?timeout: floatreturns:- full: string- incremental: string?+ snapshot: stringstartJSCoverage:title: Start JS coveragediff --git a/tests/page/page-aria-snapshot-ai.spec.ts b/tests/page/page-aria-snapshot-ai.spec.tsindex d4cf11f00a..a4a0bc6753 100644--- a/tests/page/page-aria-snapshot-ai.spec.ts+++ b/tests/page/page-aria-snapshot-ai.spec.ts@@ -19,9 +19,8 @@ import { test as it, expect } from './pageTest';import { unshift } from '../config/utils';import type { Page } from 'playwright-core';-async function snapshotForAI(page: Page, options?: Parameters<Page['snapshotForAI']>[0] & { mode?: 'full' | 'incremental' }): Promise<string> {- const snapshot = await page.snapshotForAI(options);- return options?.mode === 'incremental' ? snapshot.incremental : snapshot.full;+async function snapshotForAI(page: Page, options?: Parameters<Page['snapshotForAI']>[0]): Promise<string> {+ return await page.snapshotForAI(options);}it('should generate refs', async ({ page }) => {@@ -717,7 +716,13 @@ it('should not create incremental snapshots without tracks', async ({ page }) =>- button "a button" [ref=e4]- listitem [ref=e5]: a span`);- expect(await snapshotForAI(page, { mode: 'incremental' })).toBe(undefined);+ // Without a track, mode: 'incremental' falls back to full snapshot.+ expect(await snapshotForAI(page, { mode: 'incremental' })).toContainYaml(`+ - list [ref=e2]:+ - listitem [ref=e3]:+ - button "a button" [ref=e4]+ - listitem [ref=e5]: a span+ `);});it('should create incremental snapshot for children swap', async ({ page }) => {@@ -794,7 +799,7 @@ it('should limit depth', async ({ page }) => {- listitem [ref=e10]: item3`);- const { full: snapshot4 } = await page.locator('#target').snapshotForAI({ depth: 1 });+ const snapshot4 = await page.locator('#target').snapshotForAI({ depth: 1 });expect(snapshot4).toContainYaml(`- list [ref=e6]:- listitem [ref=e7]: item2