Skip to content

Chrome DevTools for coding agents

chore: in-page tool output: stash DOM elements and preprocess for serialization (#1877)

Wolfgang Beyere046c23563fe
diff --git a/src/McpContext.ts b/src/McpContext.ts
index 24163697..f10a68de 100644
--- a/src/McpContext.ts
+++ b/src/McpContext.ts
@@ -26,7 +26,6 @@ import type {
HTTPRequest,
Page,
ScreenRecorder,
- SerializedAXNode,
Viewport,
Target,
Extension,
@@ -36,17 +35,11 @@ import {Locator} from './third_party/index.js';
import {PredefinedNetworkConditions} from './third_party/index.js';
import {listPages} from './tools/pages.js';
import {CLOSE_PAGE_ERROR} from './tools/ToolDefinition.js';
-import type {
- Context,
- DevToolsData,
- SupportedExtensions,
-} from './tools/ToolDefinition.js';
+import type {Context, SupportedExtensions} from './tools/ToolDefinition.js';
import type {TraceResult} from './trace-processing/parse.js';
import type {
EmulationSettings,
GeolocationOptions,
- TextSnapshot,
- TextSnapshotNode,
ExtensionServiceWorker,
} from './types.js';
import {ensureExtension, saveTemporaryFile} from './utils/files.js';
@@ -92,7 +85,6 @@ export class McpContext implements Context {
#extensionServiceWorkerMap = new WeakMap<Target, string>();
#nextExtensionServiceWorkerId = 1;
- #nextSnapshotId = 1;
#traceResults: TraceResult[] = [];
#locatorClass: typeof Locator;
@@ -647,127 +639,6 @@ export class McpContext implements Context {
return this.#mcpPages.get(page)?.isolatedContextName;
}
- getDevToolsPage(page: Page): Page | undefined {
- return this.#mcpPages.get(page)?.devToolsPage;
- }
-
- async getDevToolsData(page: McpPage): Promise<DevToolsData> {
- try {
- this.logger('Getting DevTools UI data');
- const devtoolsPage = this.getDevToolsPage(page.pptrPage);
- if (!devtoolsPage) {
- this.logger('No DevTools page detected');
- return {};
- }
- const {cdpRequestId, cdpBackendNodeId} = await devtoolsPage.evaluate(
- async () => {
- // @ts-expect-error no types
- const UI = await import('/bundled/ui/legacy/legacy.js');
- // @ts-expect-error no types
- const SDK = await import('/bundled/core/sdk/sdk.js');
- const request = UI.Context.Context.instance().flavor(
- SDK.NetworkRequest.NetworkRequest,
- );
- const node = UI.Context.Context.instance().flavor(
- SDK.DOMModel.DOMNode,
- );
- return {
- cdpRequestId: request?.requestId(),
- cdpBackendNodeId: node?.backendNodeId(),
- };
- },
- );
- return {cdpBackendNodeId, cdpRequestId};
- } catch (err) {
- this.logger('error getting devtools data', err);
- }
- return {};
- }
-
- /**
- * Creates a text snapshot of a page.
- */
- async createTextSnapshot(
- page: McpPage,
- verbose = false,
- devtoolsData: DevToolsData | undefined = undefined,
- ): Promise<void> {
- const rootNode = await page.pptrPage.accessibility.snapshot({
- includeIframes: true,
- interestingOnly: !verbose,
- });
- if (!rootNode) {
- return;
- }
-
- const {uniqueBackendNodeIdToMcpId} = page;
-
- const snapshotId = this.#nextSnapshotId++;
- // Iterate through the whole accessibility node tree and assign node ids that
- // will be used for the tree serialization and mapping ids back to nodes.
- let idCounter = 0;
- const idToNode = new Map<string, TextSnapshotNode>();
- const seenUniqueIds = new Set<string>();
- const assignIds = (node: SerializedAXNode): TextSnapshotNode => {
- let id = '';
- // @ts-expect-error untyped loaderId & backendNodeId.
- const uniqueBackendId = `${node.loaderId}_${node.backendNodeId}`;
- if (uniqueBackendNodeIdToMcpId.has(uniqueBackendId)) {
- // Re-use MCP exposed ID if the uniqueId is the same.
- id = uniqueBackendNodeIdToMcpId.get(uniqueBackendId)!;
- } else {
- // Only generate a new ID if we have not seen the node before.
- id = `${snapshotId}_${idCounter++}`;
- uniqueBackendNodeIdToMcpId.set(uniqueBackendId, id);
- }
- seenUniqueIds.add(uniqueBackendId);
-
- const nodeWithId: TextSnapshotNode = {
- ...node,
- id,
- children: node.children
- ? node.children.map(child => assignIds(child))
- : [],
- };
-
- // The AXNode for an option doesn't contain its `value`.
- // Therefore, set text content of the option as value.
- if (node.role === 'option') {
- const optionText = node.name;
- if (optionText) {
- nodeWithId.value = optionText.toString();
- }
- }
-
- idToNode.set(nodeWithId.id, nodeWithId);
- return nodeWithId;
- };
-
- const rootNodeWithId = assignIds(rootNode);
- const snapshot: TextSnapshot = {
- root: rootNodeWithId,
- snapshotId: String(snapshotId),
- idToNode,
- hasSelectedElement: false,
- verbose,
- };
- page.textSnapshot = snapshot;
- const data = devtoolsData ?? (await this.getDevToolsData(page));
- if (data?.cdpBackendNodeId) {
- snapshot.hasSelectedElement = true;
- snapshot.selectedElementUid = page.resolveCdpElementId(
- data?.cdpBackendNodeId,
- );
- }
-
- // Clean up unique IDs that we did not see anymore.
- for (const key of uniqueBackendNodeIdToMcpId.keys()) {
- if (!seenUniqueIds.has(key)) {
- uniqueBackendNodeIdToMcpId.delete(key);
- }
- }
- }
-
async saveTemporaryFile(
data: Uint8Array<ArrayBufferLike>,
filename: string,
diff --git a/src/McpPage.ts b/src/McpPage.ts
index 35898d32..485e4300 100644
--- a/src/McpPage.ts
+++ b/src/McpPage.ts
@@ -5,6 +5,7 @@
*/
import {logger} from './logger.js';
+import {TextSnapshot} from './TextSnapshot.js';
import type {
Dialog,
ElementHandle,
@@ -14,11 +15,14 @@ import type {
} from './third_party/index.js';
import type {ToolGroup, ToolDefinition} from './tools/inPage.js';
import {takeSnapshot} from './tools/snapshot.js';
-import type {ContextPage} from './tools/ToolDefinition.js';
+import type {
+ ContextPage,
+ DevToolsData,
+ Response,
+} from './tools/ToolDefinition.js';
import type {
EmulationSettings,
GeolocationOptions,
- TextSnapshot,
TextSnapshotNode,
} from './types.js';
import {
@@ -41,6 +45,7 @@ export class McpPage implements ContextPage {
// Snapshot
textSnapshot: TextSnapshot | null = null;
uniqueBackendNodeIdToMcpId = new Map<string, string>();
+ extraHandles: ElementHandle[] = [];
// Emulation
emulationSettings: EmulationSettings = {};
@@ -131,6 +136,195 @@ export class McpPage implements ContextPage {
this.pptrPage.off('dialog', this.#dialogHandler);
}
+ async executeInPageTool(
+ toolName: string,
+ params: Record<string, unknown>,
+ response: Response,
+ ): Promise<void> {
+ // Creates array of ElementHandles from the UIDs in the params.
+ // We do not replace the uids with the ElementsHandles yet, because
+ // the `evaluate` function only turns them into DOM elements if they
+ // are passed as non-nested arguments.
+ const handles: ElementHandle[] = [];
+ for (const value of Object.values(params)) {
+ if (
+ value instanceof Object &&
+ 'uid' in value &&
+ typeof value.uid === 'string' &&
+ Object.keys(value).length === 1
+ ) {
+ handles.push(await this.getElementByUid(value.uid));
+ }
+ }
+
+ const result = await this.pptrPage.evaluate(
+ async (name, args, ...elements) => {
+ // Replace the UIDs with DOM elements.
+ for (const [key, value] of Object.entries(args)) {
+ if (
+ value instanceof Object &&
+ 'uid' in value &&
+ typeof value.uid === 'string' &&
+ Object.keys(value).length === 1
+ ) {
+ args[key] = elements.shift();
+ }
+ }
+
+ if (!window.__dtmcp?.executeTool) {
+ throw new Error('No tools found on the page');
+ }
+ const toolResult = await window.__dtmcp.executeTool(name, args);
+
+ const stashDOMElement = (el: Element) => {
+ if (!window.__dtmcp) {
+ window.__dtmcp = {};
+ }
+ if (window.__dtmcp.stashedElements === undefined) {
+ window.__dtmcp.stashedElements = [];
+ }
+ window.__dtmcp.stashedElements.push(el);
+ return {
+ stashedId: `stashed-${window.__dtmcp.stashedElements.length - 1}`,
+ };
+ };
+
+ const ancestors: unknown[] = [];
+ // Recursively walks the tool result:
+ // - Replaces DOM elements with an ID and stashes the DOM element on the window object
+ // - Replaces non-plain objects with a string representation of the object
+ // - Replaces circular references with the string '<Circular reference>'
+ // - Replaces functions with the string '<Function object>'
+ const processToolResult = (
+ data: unknown,
+ parentEl?: unknown,
+ ): unknown => {
+ // 1. Handle DOM Elements
+ if (data instanceof Element) {
+ return stashDOMElement(data);
+ }
+
+ // 2. Handle Arrays
+ if (Array.isArray(data)) {
+ return data.map((item: unknown) =>
+ processToolResult(item, parentEl),
+ );
+ }
+
+ // 3. Handle Objects
+ if (data !== null && typeof data === 'object') {
+ while (ancestors.length > 0 && ancestors.at(-1) !== parentEl) {
+ ancestors.pop();
+ }
+ if (ancestors.includes(data)) {
+ return '<Circular reference>';
+ }
+ ancestors.push(data);
+
+ // If not a plain object, return a string representation of the object
+ if (Object.getPrototypeOf(data) !== Object.prototype) {
+ return `<${data.constructor.name} instance>`;
+ }
+
+ const processedObj: Record<string, unknown> = {};
+ for (const [key, value] of Object.entries(data)) {
+ processedObj[key] = processToolResult(value, data);
+ }
+ return processedObj;
+ }
+
+ // 4. Handle Functions
+ if (typeof data === 'function') {
+ return '<Function object>';
+ }
+
+ // 5. Return primitives (strings, numbers, booleans) as-is
+ return data;
+ };
+
+ return {
+ result: processToolResult(toolResult),
+ stashed: window.__dtmcp?.stashedElements?.length ?? 0,
+ };
+ },
+ toolName,
+ params,
+ ...handles,
+ );
+
+ const elementHandles: ElementHandle[] = [];
+ for (let i = 0; i < (result.stashed ?? 0); i++) {
+ const elementHandle = await this.pptrPage.evaluateHandle(index => {
+ const el = window.__dtmcp?.stashedElements?.[index];
+ if (!el) {
+ throw new Error(`Stashed element at index ${index} not found`);
+ }
+ return el;
+ }, i);
+ elementHandles.push(elementHandle);
+ }
+
+ if (elementHandles.length) {
+ const oldHandles = [...this.extraHandles];
+ this.textSnapshot = await TextSnapshot.create(this, {
+ extraHandles: elementHandles,
+ });
+ response.includeSnapshot();
+
+ for (const handle of oldHandles) {
+ await handle
+ .dispose()
+ .catch(e => logger('Failed to dispose old handle', e));
+ }
+ }
+
+ const cdpElementIds = await Promise.all(
+ elementHandles.map(async (elementHandle, index) => {
+ const backendNodeId = await elementHandle.backendNodeId();
+ if (!backendNodeId) {
+ logger(
+ `No backendNodeId for stashed DOM element with index ${index}`,
+ );
+ return `stashed-${index}`;
+ }
+ const cdpElementId = this.resolveCdpElementId(backendNodeId);
+ if (!cdpElementId) {
+ logger(
+ `Could not get cdpElementId for backend node ${backendNodeId}`,
+ );
+ return `stashed-${index}`;
+ }
+ return cdpElementId;
+ }),
+ );
+
+ const recursivelyReplaceStashedElements = (node: unknown): unknown => {
+ if (Array.isArray(node)) {
+ return node.map(x => recursivelyReplaceStashedElements(x));
+ }
+ if (node !== null && typeof node === 'object') {
+ if (
+ 'stashedId' in node &&
+ typeof node.stashedId === 'string' &&
+ node.stashedId.startsWith('stashed-') &&
+ Object.keys(node).length === 1
+ ) {
+ const index = parseInt(node.stashedId.split('-')[1]);
+ return {uid: cdpElementIds[index]};
+ }
+ const resultObj: Record<string, unknown> = {};
+ for (const [key, value] of Object.entries(node)) {
+ resultObj[key] = recursivelyReplaceStashedElements(value);
+ }
+ return resultObj;
+ }
+ return node;
+ };
+
+ const resultWithUids = recursivelyReplaceStashedElements(result.result);
+ response.appendResponseLine(JSON.stringify(resultWithUids, null, 2));
+ }
+
async getElementByUid(uid: string): Promise<ElementHandle<Element>> {
if (!this.textSnapshot) {
throw new Error(
@@ -189,4 +383,37 @@ export class McpPage implements ContextPage {
}
return;
}
+
+ async getDevToolsData(): Promise<DevToolsData> {
+ try {
+ logger('Getting DevTools UI data');
+ const devtoolsPage = this.devToolsPage;
+ if (!devtoolsPage) {
+ logger('No DevTools page detected');
+ return {};
+ }
+ const {cdpRequestId, cdpBackendNodeId} = await devtoolsPage.evaluate(
+ async () => {
+ // @ts-expect-error no types
+ const UI = await import('/bundled/ui/legacy/legacy.js');
+ // @ts-expect-error no types
+ const SDK = await import('/bundled/core/sdk/sdk.js');
+ const request = UI.Context.Context.instance().flavor(
+ SDK.NetworkRequest.NetworkRequest,
+ );
+ const node = UI.Context.Context.instance().flavor(
+ SDK.DOMModel.DOMNode,
+ );
+ return {
+ cdpRequestId: request?.requestId(),
+ cdpBackendNodeId: node?.backendNodeId(),
+ };
+ },
+ );
+ return {cdpBackendNodeId, cdpRequestId};
+ } catch (err) {
+ logger('error getting devtools data', err);
+ }
+ return {};
+ }
}
diff --git a/src/McpResponse.ts b/src/McpResponse.ts
index 45e58735..fa487047 100644
--- a/src/McpResponse.ts
+++ b/src/McpResponse.ts
@@ -15,6 +15,7 @@ import {SnapshotFormatter} from './formatters/SnapshotFormatter.js';
import type {McpContext} from './McpContext.js';
import type {McpPage} from './McpPage.js';
import {UncaughtError} from './PageCollector.js';
+import {TextSnapshot} from './TextSnapshot.js';
import {DevTools, type Protocol} from './third_party/index.js';
import type {
ConsoleMessage,
@@ -443,11 +444,10 @@ export class McpResponse implements Response {
if (!this.#page) {
throw new Error('Response must have a page');
}
- await context.createTextSnapshot(
- this.#page,
- this.#snapshotParams.verbose,
- this.#devToolsData,
- );
+ this.#page.textSnapshot = await TextSnapshot.create(this.#page, {
+ verbose: this.#snapshotParams.verbose,
+ devtoolsData: this.#devToolsData,
+ });
const textSnapshot = this.#page.textSnapshot;
if (textSnapshot) {
const formatter = new SnapshotFormatter(textSnapshot);
diff --git a/src/TextSnapshot.ts b/src/TextSnapshot.ts
new file mode 100644
index 00000000..4f084e8e
--- /dev/null
+++ b/src/TextSnapshot.ts
@@ -0,0 +1,316 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {logger} from './logger.js';
+import type {McpPage} from './McpPage.js';
+import type {
+ Protocol,
+ SerializedAXNode,
+ ElementHandle,
+} from './third_party/index.js';
+import type {DevToolsData} from './tools/ToolDefinition.js';
+import type {TextSnapshotNode} from './types.js';
+
+export class TextSnapshot {
+ static nextSnapshotId = 1;
+
+ static resetCounter() {
+ TextSnapshot.nextSnapshotId = 1;
+ }
+
+ root: TextSnapshotNode;
+ idToNode: Map<string, TextSnapshotNode>;
+ snapshotId: string;
+ selectedElementUid?: string;
+ hasSelectedElement: boolean;
+ verbose: boolean;
+
+ constructor(data: {
+ root: TextSnapshotNode;
+ idToNode: Map<string, TextSnapshotNode>;
+ snapshotId: string;
+ selectedElementUid?: string;
+ hasSelectedElement: boolean;
+ verbose: boolean;
+ }) {
+ this.root = data.root;
+ this.idToNode = data.idToNode;
+ this.snapshotId = data.snapshotId;
+ this.selectedElementUid = data.selectedElementUid;
+ this.hasSelectedElement = data.hasSelectedElement;
+ this.verbose = data.verbose;
+ }
+
+ static async create(
+ page: McpPage,
+ options: {
+ verbose?: boolean;
+ devtoolsData?: DevToolsData;
+ extraHandles?: ElementHandle[];
+ } = {},
+ ): Promise<TextSnapshot> {
+ const verbose = options.verbose ?? false;
+ const rootNode = await page.pptrPage.accessibility.snapshot({
+ includeIframes: true,
+ interestingOnly: !verbose,
+ });
+ if (!rootNode) {
+ throw new Error('Failed to create accessibility snapshot');
+ }
+
+ const {uniqueBackendNodeIdToMcpId} = page;
+ const snapshotId = TextSnapshot.nextSnapshotId++;
+ // Iterate through the whole accessibility node tree and assign node ids that
+ // will be used for the tree serialization and mapping ids back to nodes.
+ let idCounter = 0;
+ const idToNode = new Map<string, TextSnapshotNode>();
+ const seenUniqueIds = new Set<string>();
+ const seenBackendNodeIds = new Set<number>();
+
+ const assignIds = (node: SerializedAXNode): TextSnapshotNode => {
+ let id = '';
+ // @ts-expect-error untyped backendNodeId.
+ const backendNodeId: number = node.backendNodeId;
+ // @ts-expect-error untyped loaderId.
+ const uniqueBackendId = `${node.loaderId}_${backendNodeId}`;
+ const existingMcpId = uniqueBackendNodeIdToMcpId.get(uniqueBackendId);
+ if (existingMcpId !== undefined) {
+ // Re-use MCP exposed ID if the uniqueId is the same.
+ id = existingMcpId;
+ } else {
+ // Only generate a new ID if we have not seen the node before.
+ id = `${snapshotId}_${idCounter++}`;
+ uniqueBackendNodeIdToMcpId.set(uniqueBackendId, id);
+ }
+ seenUniqueIds.add(uniqueBackendId);
+ seenBackendNodeIds.add(backendNodeId);
+
+ const nodeWithId: TextSnapshotNode = {
+ ...node,
+ id,
+ children: node.children
+ ? node.children.map(child => assignIds(child))
+ : [],
+ };
+
+ // The AXNode for an option doesn't contain its `value`.
+ // Therefore, set text content of the option as value.
+ if (node.role === 'option') {
+ const optionText = node.name;
+ if (optionText) {
+ nodeWithId.value = optionText.toString();
+ }
+ }
+
+ idToNode.set(nodeWithId.id, nodeWithId);
+ return nodeWithId;
+ };
+
+ const rootNodeWithId = assignIds(rootNode);
+
+ await TextSnapshot.insertExtraNodes(
+ page,
+ idToNode,
+ seenUniqueIds,
+ snapshotId,
+ idCounter,
+ rootNodeWithId,
+ seenBackendNodeIds,
+ options.extraHandles ?? [],
+ );
+
+ const snapshot = new TextSnapshot({
+ root: rootNodeWithId,
+ snapshotId: String(snapshotId),
+ idToNode,
+ hasSelectedElement: false,
+ verbose,
+ });
+
+ const data = options.devtoolsData ?? (await page.getDevToolsData());
+ if (data?.cdpBackendNodeId) {
+ snapshot.hasSelectedElement = true;
+ snapshot.selectedElementUid = page.resolveCdpElementId(
+ data.cdpBackendNodeId,
+ );
+ }
+
+ // Clean up unique IDs that we did not see anymore.
+ for (const key of uniqueBackendNodeIdToMcpId.keys()) {
+ if (!seenUniqueIds.has(key)) {
+ uniqueBackendNodeIdToMcpId.delete(key);
+ }
+ }
+
+ return snapshot;
+ }
+
+ // ExtraHandles represent DOM nodes which might not be part of the accessibility tree, e.g. DOM nodes
+ // returned by in-page tools. We insert them into the tree by finding the closest ancestor in the
+ // tree and inserting the node as a child. The ancestor's child nodes are re-parented if necessary.
+ private static async insertExtraNodes(
+ page: McpPage,
+ idToNode: Map<string, TextSnapshotNode>,
+ seenUniqueIds: Set<string>,
+ snapshotId: number,
+ idCounter: number,
+ rootNodeWithId: TextSnapshotNode,
+ seenBackendNodeIds: Set<number>,
+ extraHandles: ElementHandle[],
+ ): Promise<void> {
+ const {uniqueBackendNodeIdToMcpId} = page;
+
+ const createExtraNode = async (
+ handle: ElementHandle,
+ ): Promise<TextSnapshotNode | null> => {
+ const backendNodeId = await handle.backendNodeId();
+ if (!backendNodeId || seenBackendNodeIds.has(backendNodeId)) {
+ return null;
+ }
+ const uniqueBackendId = `custom_${backendNodeId}`;
+ if (seenUniqueIds.has(uniqueBackendId)) {
+ return null;
+ }
+ seenBackendNodeIds.add(backendNodeId);
+
+ let id = '';
+ const mcpId = uniqueBackendNodeIdToMcpId.get(uniqueBackendId);
+ if (mcpId !== undefined) {
+ id = mcpId;
+ } else {
+ id = `${snapshotId}_${idCounter++}`;
+ uniqueBackendNodeIdToMcpId.set(uniqueBackendId, id);
+ }
+ seenUniqueIds.add(uniqueBackendId);
+
+ const tagHandle = await handle.getProperty('localName');
+ const tagValue = await tagHandle.jsonValue();
+ const extraNode: TextSnapshotNode = {
+ role: tagValue,
+ id,
+ backendNodeId,
+ children: [],
+ elementHandle: async () => handle,
+ };
+ return extraNode;
+ };
+
+ const findAncestorNode = async (
+ handle: ElementHandle,
+ ): Promise<TextSnapshotNode | null> => {
+ let ancestorHandle = await handle.evaluateHandle(el => el.parentElement);
+
+ while (ancestorHandle) {
+ const ancestorElement = ancestorHandle.asElement();
+ if (!ancestorElement) {
+ await ancestorHandle.dispose();
+ return null;
+ }
+
+ const ancestorBackendId = await ancestorElement.backendNodeId();
+ if (ancestorBackendId) {
+ const ancestorNode = idToNode
+ .values()
+ .find(node => node.backendNodeId === ancestorBackendId);
+ if (ancestorNode) {
+ await ancestorHandle.dispose();
+ return ancestorNode;
+ }
+ }
+
+ const nextHandle = await ancestorElement.evaluateHandle(
+ el => el.parentElement,
+ );
+ await ancestorHandle.dispose();
+ ancestorHandle = nextHandle;
+ }
+ return null;
+ };
+
+ const findDescendantNodes = async (
+ backendNodeId: number,
+ ): Promise<Set<number>> => {
+ const descendantIds = new Set<number>();
+ try {
+ // @ts-expect-error internal API
+ const client = page.pptrPage._client();
+ if (client) {
+ const {node}: {node: Protocol.DOM.Node} = await client.send(
+ 'DOM.describeNode',
+ {
+ backendNodeId,
+ depth: -1,
+ pierce: true,
+ },
+ );
+ const collect = (node: Protocol.DOM.Node) => {
+ if (node.backendNodeId && node.backendNodeId !== backendNodeId) {
+ descendantIds.add(node.backendNodeId);
+ }
+ if (node.children) {
+ for (const child of node.children) {
+ collect(child);
+ }
+ }
+ };
+ collect(node);
+ }
+ } catch (e) {
+ logger(
+ `Failed to collect descendants for backend node ${backendNodeId}`,
+ e,
+ );
+ }
+ return descendantIds;
+ };
+
+ const moveChildNodes = (
+ attachTarget: TextSnapshotNode,
+ extraNode: TextSnapshotNode,
+ descendantIds: Set<number>,
+ ): number => {
+ let firstMovedIndex = -1;
+ if (descendantIds.size > 0 && attachTarget.children) {
+ const remainingChildren: TextSnapshotNode[] = [];
+ for (const child of attachTarget.children) {
+ if (child.backendNodeId && descendantIds.has(child.backendNodeId)) {
+ if (firstMovedIndex === -1) {
+ firstMovedIndex = remainingChildren.length;
+ }
+ extraNode.children.push(child);
+ } else {
+ remainingChildren.push(child);
+ }
+ }
+ attachTarget.children = remainingChildren;
+ }
+ return firstMovedIndex !== -1
+ ? firstMovedIndex
+ : attachTarget.children
+ ? attachTarget.children.length
+ : 0;
+ };
+
+ if (extraHandles.length) {
+ page.extraHandles = extraHandles;
+ }
+ for (const handle of page.extraHandles) {
+ const extraNode = await createExtraNode(handle);
+ if (!extraNode) {
+ continue;
+ }
+ idToNode.set(extraNode.id, extraNode);
+ const attachTarget = (await findAncestorNode(handle)) || rootNodeWithId;
+ if (extraNode.backendNodeId !== undefined) {
+ const descendantIds = await findDescendantNodes(
+ extraNode.backendNodeId,
+ );
+ const index = moveChildNodes(attachTarget, extraNode, descendantIds);
+ attachTarget.children.splice(index, 0, extraNode);
+ }
+ }
+ }
+}
diff --git a/src/formatters/SnapshotFormatter.ts b/src/formatters/SnapshotFormatter.ts
index d118fc17..bc13f641 100644
--- a/src/formatters/SnapshotFormatter.ts
+++ b/src/formatters/SnapshotFormatter.ts
@@ -4,7 +4,8 @@
* SPDX-License-Identifier: Apache-2.0
*/
-import type {TextSnapshot, TextSnapshotNode} from '../types.js';
+import type {TextSnapshot} from '../TextSnapshot.js';
+import type {TextSnapshotNode} from '../types.js';
export class SnapshotFormatter {
#snapshot: TextSnapshot;
diff --git a/src/tools/ToolDefinition.ts b/src/tools/ToolDefinition.ts
index 1c42915d..762c800c 100644
--- a/src/tools/ToolDefinition.ts
+++ b/src/tools/ToolDefinition.ts
@@ -204,7 +204,6 @@ export type Context = Readonly<{
timeout?: number,
page?: Page,
): Promise<Element>;
- getDevToolsData(page: ContextPage): Promise<DevToolsData>;
/**
* Returns a reqid for a cdpRequestId.
*/
@@ -249,6 +248,12 @@ export type ContextPage = Readonly<{
options?: {timeout?: number; handleDialog?: 'accept' | 'dismiss' | string},
): Promise<void>;
getInPageTools(): ToolGroup<InPageToolDefinition> | undefined;
+ executeInPageTool(
+ toolName: string,
+ params: Record<string, unknown>,
+ response: Response,
+ ): Promise<void>;
+ getDevToolsData(): Promise<DevToolsData>;
}>;
export function defineTool<Schema extends zod.ZodRawShape>(
diff --git a/src/tools/inPage.ts b/src/tools/inPage.ts
index 0cb1b6ba..5c339872 100644
--- a/src/tools/inPage.ts
+++ b/src/tools/inPage.ts
@@ -4,12 +4,7 @@
* SPDX-License-Identifier: Apache-2.0
*/
-import {
- zod,
- ajv,
- type JSONSchema7,
- type ElementHandle,
-} from '../third_party/index.js';
+import {zod, ajv, type JSONSchema7} from '../third_party/index.js';
import {ToolCategory} from './categories.js';
import {definePageTool} from './ToolDefinition.js';
@@ -32,6 +27,7 @@ declare global {
toolGroup?: ToolGroup<
ToolDefinition & {execute: (args: Record<string, unknown>) => unknown}
>;
+ stashedElements?: Element[];
executeTool?: (
toolName: string,
args: Record<string, unknown>,
@@ -92,22 +88,6 @@ export const executeInPageTool = definePageTool({
}
}
- // Creates array of ElementHandles from the UIDs in the params.
- // We do not replace the uids with the ElementsHandles yet, because
- // the `evaluate` function only turns them into DOM elements if they
- // are passed as non-nested arguments.
- const handles: ElementHandle[] = [];
- for (const value of Object.values(params)) {
- if (
- value instanceof Object &&
- 'uid' in value &&
- typeof value.uid === 'string' &&
- Object.keys(value).length === 1
- ) {
- handles.push(await request.page.getElementByUid(value.uid));
- }
- }
-
const toolGroup = request.page.getInPageTools();
const tool = toolGroup?.tools.find(t => t.name === toolName);
if (!tool) {
@@ -122,33 +102,6 @@ export const executeInPageTool = definePageTool({
);
}
- const result = await request.page.pptrPage.evaluate(
- async (name, args, ...elements) => {
- // Replace the UIDs with DOM elements.
- for (const [key, value] of Object.entries(args)) {
- if (
- value instanceof Object &&
- 'uid' in value &&
- typeof value.uid === 'string' &&
- Object.keys(value).length === 1
- ) {
- args[key] = elements.shift();
- }
- }
-
- if (!window.__dtmcp?.executeTool) {
- throw new Error('No tools found on the page');
- }
- const toolResult = await window.__dtmcp.executeTool(name, args);
-
- return {
- result: toolResult,
- };
- },
- toolName,
- params,
- ...handles,
- );
- response.appendResponseLine(JSON.stringify(result, null, 2));
+ await request.page.executeInPageTool(toolName, params, response);
},
});
diff --git a/src/tools/network.ts b/src/tools/network.ts
index 596afa54..181a2ed2 100644
--- a/src/tools/network.ts
+++ b/src/tools/network.ts
@@ -71,7 +71,7 @@ export const listNetworkRequests = definePageTool({
),
},
handler: async (request, response, context) => {
- const data = await context.getDevToolsData(request.page);
+ const data = await request.page.getDevToolsData();
response.attachDevToolsData(data);
const reqid = data?.cdpRequestId
? context.resolveCdpRequestId(request.page, data.cdpRequestId)
@@ -120,7 +120,7 @@ export const getNetworkRequest = definePageTool({
responseFilePath: request.params.responseFilePath,
});
} else {
- const data = await context.getDevToolsData(request.page);
+ const data = await request.page.getDevToolsData();
response.attachDevToolsData(data);
const reqid = data?.cdpRequestId
? context.resolveCdpRequestId(request.page, data.cdpRequestId)
diff --git a/src/types.ts b/src/types.ts
index 4efd8dc9..13e64f58 100644
--- a/src/types.ts
+++ b/src/types.ts
@@ -24,17 +24,6 @@ export interface GeolocationOptions {
longitude: number;
}
-export interface TextSnapshot {
- root: TextSnapshotNode;
- idToNode: Map<string, TextSnapshotNode>;
- snapshotId: string;
- selectedElementUid?: string;
- // It might happen that there is a selected element, but it is not part of the
- // snapshot. This flag indicates if there is any selected element.
- hasSelectedElement: boolean;
- verbose: boolean;
-}
-
export interface EmulationSettings {
networkConditions?: string;
cpuThrottlingRate?: number;
diff --git a/tests/McpContext.test.ts b/tests/McpContext.test.ts
index 31a6c88b..a33dc71e 100644
--- a/tests/McpContext.test.ts
+++ b/tests/McpContext.test.ts
@@ -10,6 +10,7 @@ import {afterEach, describe, it} from 'node:test';
import sinon from 'sinon';
import {NetworkFormatter} from '../src/formatters/NetworkFormatter.js';
+import {TextSnapshot} from '../src/TextSnapshot.js';
import type {HTTPResponse} from '../src/third_party/index.js';
import type {TraceResult} from '../src/trace-processing/parse.js';
@@ -30,9 +31,9 @@ describe('McpContext', () => {
value="Input"
/>`,
);
- await context.createTextSnapshot(context.getSelectedMcpPage());
+ page.textSnapshot = await TextSnapshot.create(page);
assert.ok(await page.getElementByUid('1_1'));
- await context.createTextSnapshot(context.getSelectedMcpPage());
+ page.textSnapshot = await TextSnapshot.create(page);
await page.getElementByUid('1_1');
});
});
@@ -90,7 +91,7 @@ describe('McpContext', () => {
async (_response, context) => {
const page = await context.newPage();
await context.createPagesSnapshot();
- assert.ok(context.getDevToolsPage(page.pptrPage));
+ assert.ok(page.devToolsPage);
},
{
autoOpenDevTools: true,
@@ -102,7 +103,9 @@ describe('McpContext', () => {
// Page 1: set content and snapshot
const page1 = context.getSelectedMcpPage();
await page1.pptrPage.setContent(html`<button>Page1 Button</button>`);
- await context.createTextSnapshot(page1, false, undefined);
+ page1.textSnapshot = await TextSnapshot.create(page1, {
+ verbose: false,
+ });
// Capture a uid from page1's snapshot (snapshotId=1, button is node 1)
const page1Uid = '1_1';
@@ -113,7 +116,9 @@ describe('McpContext', () => {
const page2 = await context.newPage();
context.selectPage(page2);
await page2.pptrPage.setContent(html`<button>Page2 Button</button>`);
- await context.createTextSnapshot(page2, false, undefined);
+ page2.textSnapshot = await TextSnapshot.create(page2, {
+ verbose: false,
+ });
// Page 2 is now selected. Page 1's uid should still resolve.
const node = context.getAXNodeByUid(page1Uid);
diff --git a/tests/TextSnapshot.test.ts b/tests/TextSnapshot.test.ts
new file mode 100644
index 00000000..7627ea9c
--- /dev/null
+++ b/tests/TextSnapshot.test.ts
@@ -0,0 +1,175 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import assert from 'node:assert';
+import {afterEach, describe, it} from 'node:test';
+
+import sinon from 'sinon';
+
+import {TextSnapshot} from '../src/TextSnapshot.js';
+import type {TextSnapshotNode} from '../src/types.js';
+
+import {html, withMcpContext} from './utils.js';
+
+describe('TextSnapshot', () => {
+ afterEach(() => {
+ sinon.restore();
+ TextSnapshot.resetCounter();
+ });
+
+ it('creates a snapshot', async () => {
+ await withMcpContext(async (_response, context) => {
+ const page = context.getSelectedMcpPage();
+ await page.pptrPage.setContent(html`<button>Click me</button>`);
+
+ const snapshot = await TextSnapshot.create(page);
+
+ assert.ok(snapshot);
+ assert.strictEqual(snapshot.snapshotId, '1');
+ assert.ok(snapshot.root);
+
+ let foundButton = false;
+ for (const node of snapshot.idToNode.values()) {
+ if (node.role === 'button' && node.name === 'Click me') {
+ foundButton = true;
+ break;
+ }
+ }
+ assert.ok(foundButton, 'Button should be in the snapshot');
+ });
+ });
+
+ it('inserts extraHandles into the snapshot correctly', async () => {
+ await withMcpContext(async (_response, context) => {
+ const page = context.getSelectedMcpPage();
+ await page.pptrPage.setContent(html`
+ <div
+ id="parent"
+ role="main"
+ >
+ <div
+ id="middle"
+ role="none"
+ >
+ <button id="child">Click me</button>
+ </div>
+ </div>
+ `);
+
+ const middleHandle = await page.pptrPage.$('#middle');
+ if (!middleHandle) {
+ throw new Error('middle element not found');
+ }
+
+ const backendNodeId = await middleHandle.backendNodeId();
+ if (!backendNodeId) {
+ throw new Error('Failed to get backendNodeId');
+ }
+
+ // Verify it is not in the snapshot by default (due to role="none")
+ const snapshotBefore = await TextSnapshot.create(page, {
+ verbose: false,
+ extraHandles: [],
+ });
+
+ let foundMiddleBefore = false;
+ for (const node of snapshotBefore.idToNode.values()) {
+ if (node.backendNodeId === backendNodeId) {
+ foundMiddleBefore = true;
+ break;
+ }
+ }
+ assert.ok(
+ !foundMiddleBefore,
+ 'Middle element should NOT be in the snapshot when not passed as extra handle',
+ );
+
+ // Now take snapshot with extra handle
+ const snapshot = await TextSnapshot.create(page, {
+ verbose: false,
+ extraHandles: [middleHandle],
+ });
+
+ // Find the extra node in idToNode
+ let extraNode: TextSnapshotNode | undefined;
+ for (const node of snapshot.idToNode.values()) {
+ if (node.backendNodeId === backendNodeId) {
+ extraNode = node;
+ break;
+ }
+ }
+
+ assert.ok(extraNode, 'Extra node should be in the snapshot');
+ assert.strictEqual(
+ extraNode.role,
+ 'div',
+ 'Extra node should have role "div"',
+ );
+
+ // Check if the child was moved to extraNode
+ const childHandle = await page.pptrPage.$('#child');
+ if (!childHandle) {
+ throw new Error('child element not found');
+ }
+ const childBackendNodeId = await childHandle.backendNodeId();
+
+ let foundChild = false;
+ for (const child of extraNode.children) {
+ if (child.backendNodeId === childBackendNodeId) {
+ foundChild = true;
+ break;
+ }
+ }
+ assert.ok(
+ foundChild,
+ 'Child node should be moved to extra node children',
+ );
+
+ // Find parent node in snapshot
+ const parentHandle = await page.pptrPage.$('#parent');
+ if (!parentHandle) {
+ throw new Error('parent element not found');
+ }
+ const parentBackendId = await parentHandle.backendNodeId();
+
+ let parentNode: TextSnapshotNode | undefined;
+ for (const node of snapshot.idToNode.values()) {
+ if (node.backendNodeId === parentBackendId) {
+ parentNode = node;
+ break;
+ }
+ }
+
+ assert.ok(parentNode, 'Parent node should be in snapshot');
+
+ // Check that child is NOT a child of parent anymore
+ let foundChildInParent = false;
+ for (const child of parentNode.children) {
+ if (child.backendNodeId === childBackendNodeId) {
+ foundChildInParent = true;
+ break;
+ }
+ }
+ assert.ok(
+ !foundChildInParent,
+ 'Child node should NOT be in parent children',
+ );
+
+ // Check that middle IS a child of parent
+ let foundMiddleInParent = false;
+ for (const child of parentNode.children) {
+ if (child.backendNodeId === backendNodeId) {
+ foundMiddleInParent = true;
+ break;
+ }
+ }
+ assert.ok(
+ foundMiddleInParent,
+ 'Middle node should be in parent children',
+ );
+ });
+ });
+});
diff --git a/tests/formatters/snapshotFormatter.test.ts b/tests/formatters/snapshotFormatter.test.ts
index 90b1f07f..39385286 100644
--- a/tests/formatters/snapshotFormatter.test.ts
+++ b/tests/formatters/snapshotFormatter.test.ts
@@ -10,7 +10,8 @@ import {describe, it} from 'node:test';
import type {ElementHandle} from 'puppeteer-core';
import {SnapshotFormatter} from '../../src/formatters/SnapshotFormatter.js';
-import type {TextSnapshot, TextSnapshotNode} from '../../src/types.js';
+import type {TextSnapshot} from '../../src/TextSnapshot.js';
+import type {TextSnapshotNode} from '../../src/types.js';
describe('snapshotFormatter', () => {
it('formats a snapshot with value properties', () => {
diff --git a/tests/tools/console.test.ts b/tests/tools/console.test.ts
index 82f27784..90c23de2 100644
--- a/tests/tools/console.test.ts
+++ b/tests/tools/console.test.ts
@@ -10,6 +10,7 @@ import {before, describe, it} from 'node:test';
import type {ParsedArguments} from '../../src/bin/chrome-devtools-mcp-cli-options.js';
import {loadIssueDescriptions} from '../../src/issue-descriptions.js';
import {McpResponse} from '../../src/McpResponse.js';
+import {TextSnapshot} from '../../src/TextSnapshot.js';
import {DevTools} from '../../src/third_party/index.js';
import {
getConsoleMessage,
@@ -205,7 +206,7 @@ describe('console', () => {
await page.pptrPage.setContent(
'<input type="text" name="username" />',
);
- await context.createTextSnapshot(page);
+ page.textSnapshot = await TextSnapshot.create(page);
await issuePromise;
await listConsoleMessages().handler(
{params: {}, page: context.getSelectedMcpPage()},
@@ -250,7 +251,7 @@ describe('console', () => {
});
</script>
`);
- await context.createTextSnapshot(page);
+ page.textSnapshot = await TextSnapshot.create(page);
await issuePromise;
const messages = context.getConsoleData(page);
let issueMsg;
diff --git a/tests/tools/inPage.test.ts b/tests/tools/inPage.test.ts
index d87bbea8..413efe39 100644
--- a/tests/tools/inPage.test.ts
+++ b/tests/tools/inPage.test.ts
@@ -7,11 +7,14 @@
import assert from 'node:assert';
import {describe, it} from 'node:test';
+import sinon from 'sinon';
+
import type {ParsedArguments} from '../../src/bin/chrome-devtools-mcp-cli-options.js';
import type {McpContext} from '../../src/McpContext.js';
import type {McpResponse} from '../../src/McpResponse.js';
-import type {ToolGroup, ToolDefinition} from '../../src/tools/inPage.js';
+import {TextSnapshot} from '../../src/TextSnapshot.js';
import {executeInPageTool, listInPageTools} from '../../src/tools/inPage.js';
+import type {ToolGroup, ToolDefinition} from '../../src/tools/inPage.js';
import {withMcpContext} from '../utils.js';
describe('inPage', () => {
@@ -208,7 +211,7 @@ describe('inPage', () => {
);
assert.strictEqual(
response.responseLines[0],
- JSON.stringify({result: 'result'}, null, 2),
+ JSON.stringify('result', null, 2),
);
},
undefined,
@@ -340,7 +343,7 @@ describe('inPage', () => {
);
assert.strictEqual(
response.responseLines[0],
- JSON.stringify({result: {foo: 'bar'}}, null, 2),
+ JSON.stringify({foo: 'bar'}, null, 2),
);
},
undefined,
@@ -428,11 +431,9 @@ describe('inPage', () => {
response.responseLines[0],
JSON.stringify(
{
- result: {
- isElement: true,
- tagName: 'DIV',
- id: 'test-id',
- },
+ isElement: true,
+ tagName: 'DIV',
+ id: 'test-id',
},
null,
2,
@@ -440,5 +441,338 @@ describe('inPage', () => {
);
});
});
+
+ it('processToolResult replaces functions with "<Function object>"', async () => {
+ await withMcpContext(
+ async (response, context) => {
+ await setupInPageTools(response, context, () => {
+ window.__dtmcp = {
+ toolGroup: {
+ name: 'test-group',
+ description: 'test description',
+ tools: [
+ {
+ name: 'test-tool',
+ description: 'test tool description',
+ inputSchema: {},
+ execute: () => ({
+ foo: 'bar',
+ func: () => undefined,
+ }),
+ },
+ ],
+ },
+ };
+ window.addEventListener('devtoolstooldiscovery', (e: Event) => {
+ // @ts-expect-error Event has `respondWith`
+ e.respondWith(window.__dtmcp?.toolGroup);
+ });
+ });
+
+ await executeInPageTool.handler(
+ {
+ params: {
+ toolName: 'test-tool',
+ params: JSON.stringify({}),
+ },
+ page: context.getSelectedMcpPage(),
+ },
+ response,
+ context,
+ );
+ assert.strictEqual(
+ response.responseLines[0],
+ JSON.stringify({foo: 'bar', func: '<Function object>'}, null, 2),
+ );
+ },
+ undefined,
+ {categoryInPageTools: true} as ParsedArguments,
+ );
+ });
+
+ it('processToolResult replaces circular references with "<Circular reference>"', async () => {
+ await withMcpContext(
+ async (response, context) => {
+ await setupInPageTools(response, context, () => {
+ window.__dtmcp = {
+ toolGroup: {
+ name: 'test-group',
+ description: 'test description',
+ tools: [
+ {
+ name: 'test-tool',
+ description: 'test tool description',
+ inputSchema: {},
+ execute: () => {
+ const obj: Record<string, unknown> = {foo: 'bar'};
+ obj.self = obj;
+ return obj;
+ },
+ },
+ ],
+ },
+ };
+ window.addEventListener('devtoolstooldiscovery', (e: Event) => {
+ // @ts-expect-error Event has `respondWith`
+ e.respondWith(window.__dtmcp?.toolGroup);
+ });
+ });
+
+ await executeInPageTool.handler(
+ {
+ params: {
+ toolName: 'test-tool',
+ params: JSON.stringify({}),
+ },
+ page: context.getSelectedMcpPage(),
+ },
+ response,
+ context,
+ );
+ assert.strictEqual(
+ response.responseLines[0],
+ JSON.stringify({foo: 'bar', self: '<Circular reference>'}, null, 2),
+ );
+ },
+ undefined,
+ {categoryInPageTools: true} as ParsedArguments,
+ );
+ });
+
+ it('processToolResult replaces non-plain objects with "<ConstructorName instance>"', async () => {
+ await withMcpContext(
+ async (response, context) => {
+ await setupInPageTools(response, context, () => {
+ class CustomClass {
+ val = 'value';
+ }
+ window.__dtmcp = {
+ toolGroup: {
+ name: 'test-group',
+ description: 'test description',
+ tools: [
+ {
+ name: 'test-tool',
+ description: 'test tool description',
+ inputSchema: {},
+ execute: () => ({
+ foo: 'bar',
+ custom: new CustomClass(),
+ }),
+ },
+ ],
+ },
+ };
+ window.addEventListener('devtoolstooldiscovery', (e: Event) => {
+ // @ts-expect-error Event has `respondWith`
+ e.respondWith(window.__dtmcp?.toolGroup);
+ });
+ });
+
+ await executeInPageTool.handler(
+ {
+ params: {
+ toolName: 'test-tool',
+ params: JSON.stringify({}),
+ },
+ page: context.getSelectedMcpPage(),
+ },
+ response,
+ context,
+ );
+ assert.strictEqual(
+ response.responseLines[0],
+ JSON.stringify(
+ {foo: 'bar', custom: '<CustomClass instance>'},
+ null,
+ 2,
+ ),
+ );
+ },
+ undefined,
+ {categoryInPageTools: true} as ParsedArguments,
+ );
+ });
+
+ it('stashDOMElement stashes elements and returns UID', async () => {
+ await withMcpContext(
+ async (response, context) => {
+ const page = await context.newPage();
+ response.setPage(page);
+
+ page.inPageTools = {
+ name: 'test-group',
+ description: 'test description',
+ tools: [
+ {
+ name: 'test-tool',
+ description: 'test tool description',
+ inputSchema: {},
+ },
+ ],
+ };
+
+ await page.pptrPage.evaluate(() => {
+ window.__dtmcp = {
+ executeTool: async () => {
+ const div = document.createElement('div');
+ div.id = 'test-element';
+ document.body.appendChild(div);
+ return div;
+ },
+ };
+ });
+
+ const stub = sinon
+ .stub(page, 'resolveCdpElementId')
+ .returns('mock-uid');
+
+ await executeInPageTool.handler(
+ {
+ params: {
+ toolName: 'test-tool',
+ params: JSON.stringify({}),
+ },
+ page: page,
+ },
+ response,
+ context,
+ );
+
+ assert.strictEqual(
+ response.responseLines[0],
+ JSON.stringify({uid: 'mock-uid'}, null, 2),
+ );
+
+ stub.restore();
+ },
+ undefined,
+ {categoryInPageTools: true} as ParsedArguments,
+ );
+ });
+
+ it('creates a new snapshot if the in-page tool response contains a DOM element', async () => {
+ await withMcpContext(
+ async (response, context) => {
+ const page = await context.newPage();
+ response.setPage(page);
+
+ page.inPageTools = {
+ name: 'test-group',
+ description: 'test description',
+ tools: [
+ {
+ name: 'test-tool',
+ description: 'test tool description',
+ inputSchema: {},
+ },
+ ],
+ };
+
+ await page.pptrPage.evaluate(() => {
+ window.__dtmcp = {
+ executeTool: async () => {
+ const div = document.createElement('div');
+ div.id = 'test-element';
+ document.body.appendChild(div);
+ return div;
+ },
+ };
+ });
+
+ const stubSnapshot = sinon
+ .stub(TextSnapshot, 'create')
+ .resolves({} as TextSnapshot);
+
+ const stubResolve = sinon
+ .stub(page, 'resolveCdpElementId')
+ .returns('mock-uid');
+
+ await executeInPageTool.handler(
+ {
+ params: {
+ toolName: 'test-tool',
+ params: JSON.stringify({}),
+ },
+ page: page,
+ },
+ response,
+ context,
+ );
+
+ assert.ok(
+ stubSnapshot.calledOnce,
+ 'Expected TextSnapshot.create to be called',
+ );
+ assert.strictEqual(
+ response.responseLines[0],
+ JSON.stringify({uid: 'mock-uid'}, null, 2),
+ );
+
+ stubResolve.restore();
+ stubSnapshot.restore();
+ },
+ undefined,
+ {categoryInPageTools: true} as ParsedArguments,
+ );
+ });
+
+ it('does not create a new snapshot if the in-page tool response does not contain a DOM element', async () => {
+ await withMcpContext(
+ async (response, context) => {
+ const page = await context.newPage();
+ response.setPage(page);
+
+ page.inPageTools = {
+ name: 'test-group',
+ description: 'test description',
+ tools: [
+ {
+ name: 'test-tool',
+ description: 'test tool description',
+ inputSchema: {},
+ },
+ ],
+ };
+
+ await page.pptrPage.evaluate(() => {
+ window.__dtmcp = {
+ executeTool: async () => {
+ return 'simple-result';
+ },
+ };
+ });
+
+ const stubSnapshot = sinon
+ .stub(TextSnapshot, 'create')
+ .resolves({} as TextSnapshot);
+
+ await executeInPageTool.handler(
+ {
+ params: {
+ toolName: 'test-tool',
+ params: JSON.stringify({}),
+ },
+ page: page,
+ },
+ response,
+ context,
+ );
+
+ assert.ok(
+ stubSnapshot.notCalled,
+ 'Expected TextSnapshot.create not to be called',
+ );
+ assert.strictEqual(
+ response.responseLines[0],
+ JSON.stringify('simple-result', null, 2),
+ );
+
+ stubSnapshot.restore();
+ },
+ undefined,
+ {categoryInPageTools: true} as ParsedArguments,
+ );
+ });
});
});
diff --git a/tests/tools/input.test.ts b/tests/tools/input.test.ts
index 5590e88c..b0033ec4 100644
--- a/tests/tools/input.test.ts
+++ b/tests/tools/input.test.ts
@@ -11,6 +11,7 @@ import {describe, it} from 'node:test';
import type {ParsedArguments} from '../../src/bin/chrome-devtools-mcp-cli-options.js';
import {McpResponse} from '../../src/McpResponse.js';
+import {TextSnapshot} from '../../src/TextSnapshot.js';
import {
click,
hover,
@@ -36,7 +37,9 @@ describe('input', () => {
await page.setContent(
html`<button onclick="this.innerText = 'clicked';">test</button>`,
);
- await context.createTextSnapshot(context.getSelectedMcpPage());
+ context.getSelectedMcpPage().textSnapshot = await TextSnapshot.create(
+ context.getSelectedMcpPage(),
+ );
await click.handler(
{
params: {
@@ -63,7 +66,9 @@ describe('input', () => {
>test</button
>`,
);
- await context.createTextSnapshot(context.getSelectedMcpPage());
+ context.getSelectedMcpPage().textSnapshot = await TextSnapshot.create(
+ context.getSelectedMcpPage(),
+ );
await click.handler(
{
params: {
@@ -98,7 +103,9 @@ describe('input', () => {
await withMcpContext(async (response, context) => {
const page = context.getSelectedPptrPage();
await page.goto(server.getRoute('/link'));
- await context.createTextSnapshot(context.getSelectedMcpPage());
+ context.getSelectedMcpPage().textSnapshot = await TextSnapshot.create(
+ context.getSelectedMcpPage(),
+ );
const clickPromise = click.handler(
{
params: {
@@ -141,7 +148,9 @@ describe('input', () => {
await withMcpContext(async (response, context) => {
const page = context.getSelectedPptrPage();
await page.goto(server.getRoute('/unstable'));
- await context.createTextSnapshot(context.getSelectedMcpPage());
+ context.getSelectedMcpPage().textSnapshot = await TextSnapshot.create(
+ context.getSelectedMcpPage(),
+ );
const handlerResolveTime = await click
.handler(
{
@@ -169,7 +178,9 @@ describe('input', () => {
await page.setContent(
html`<button onclick="this.innerText = 'clicked';">test</button>`,
);
- await context.createTextSnapshot(context.getSelectedMcpPage());
+ context.getSelectedMcpPage().textSnapshot = await TextSnapshot.create(
+ context.getSelectedMcpPage(),
+ );
await click.handler(
{
params: {
@@ -194,7 +205,9 @@ describe('input', () => {
await page.setContent(
html`<button onclick="this.innerText = 'clicked';">test</button>`,
);
- await context.createTextSnapshot(context.getSelectedMcpPage());
+ context.getSelectedMcpPage().textSnapshot = await TextSnapshot.create(
+ context.getSelectedMcpPage(),
+ );
await click.handler(
{
params: {
@@ -222,7 +235,9 @@ describe('input', () => {
await page.setContent(
html`<button onmouseover="this.innerText = 'hovered';">test</button>`,
);
- await context.createTextSnapshot(context.getSelectedMcpPage());
+ context.getSelectedMcpPage().textSnapshot = await TextSnapshot.create(
+ context.getSelectedMcpPage(),
+ );
await hover.handler(
{
params: {
@@ -253,7 +268,9 @@ describe('input', () => {
onclick="this.innerText = 'clicked'"
></div>`,
);
- await context.createTextSnapshot(context.getSelectedMcpPage());
+ context.getSelectedMcpPage().textSnapshot = await TextSnapshot.create(
+ context.getSelectedMcpPage(),
+ );
await clickAt.handler(
{
params: {
@@ -283,7 +300,9 @@ describe('input', () => {
ondblclick="this.innerText = 'dblclicked'"
></div>`,
);
- await context.createTextSnapshot(context.getSelectedMcpPage());
+ context.getSelectedMcpPage().textSnapshot = await TextSnapshot.create(
+ context.getSelectedMcpPage(),
+ );
await clickAt.handler(
{
params: {
@@ -311,7 +330,9 @@ describe('input', () => {
await withMcpContext(async (response, context) => {
const page = context.getSelectedPptrPage();
await page.setContent(html`<input />`);
- await context.createTextSnapshot(context.getSelectedMcpPage());
+ context.getSelectedMcpPage().textSnapshot = await TextSnapshot.create(
+ context.getSelectedMcpPage(),
+ );
await fill.handler(
{
params: {
@@ -341,7 +362,9 @@ describe('input', () => {
><option value="v2">two</option></select
>`,
);
- await context.createTextSnapshot(context.getSelectedMcpPage());
+ context.getSelectedMcpPage().textSnapshot = await TextSnapshot.create(
+ context.getSelectedMcpPage(),
+ );
await fill.handler(
{
params: {
@@ -369,7 +392,9 @@ describe('input', () => {
await withMcpContext(async (response, context) => {
const page = context.getSelectedPptrPage();
await page.setContent(html`<textarea role="combobox"></textarea>`);
- await context.createTextSnapshot(context.getSelectedMcpPage());
+ context.getSelectedMcpPage().textSnapshot = await TextSnapshot.create(
+ context.getSelectedMcpPage(),
+ );
await fill.handler(
{
params: {
@@ -398,7 +423,9 @@ describe('input', () => {
await withMcpContext(async (response, context) => {
const page = context.getSelectedPptrPage();
await page.setContent(html`<textarea></textarea>`);
- await context.createTextSnapshot(context.getSelectedMcpPage());
+ context.getSelectedMcpPage().textSnapshot = await TextSnapshot.create(
+ context.getSelectedMcpPage(),
+ );
page.setDefaultTimeout(1000);
await fill.handler(
{
@@ -431,7 +458,9 @@ describe('input', () => {
const page = context.getSelectedPptrPage();
await page.setContent(html`<textarea></textarea>`);
await page.click('textarea');
- await context.createTextSnapshot(context.getSelectedMcpPage());
+ context.getSelectedMcpPage().textSnapshot = await TextSnapshot.create(
+ context.getSelectedMcpPage(),
+ );
await typeText.handler(
{
params: {
@@ -457,7 +486,9 @@ describe('input', () => {
const page = context.getSelectedPptrPage();
await page.setContent(html`<textarea></textarea>`);
await page.click('textarea');
- await context.createTextSnapshot(context.getSelectedMcpPage());
+ context.getSelectedMcpPage().textSnapshot = await TextSnapshot.create(
+ context.getSelectedMcpPage(),
+ );
await typeText.handler(
{
params: {
@@ -494,7 +525,9 @@ describe('input', () => {
const page = context.getSelectedPptrPage();
await page.setContent(html`<textarea></textarea>`);
await page.click('textarea');
- await context.createTextSnapshot(context.getSelectedMcpPage());
+ context.getSelectedMcpPage().textSnapshot = await TextSnapshot.create(
+ context.getSelectedMcpPage(),
+ );
try {
await typeText.handler(
{
@@ -528,7 +561,9 @@ describe('input', () => {
/>
</form>`,
);
- await context.createTextSnapshot(context.getSelectedMcpPage());
+ context.getSelectedMcpPage().textSnapshot = await TextSnapshot.create(
+ context.getSelectedMcpPage(),
+ );
// Fill email
const response1 = new McpResponse({} as ParsedArguments);
@@ -622,7 +657,9 @@ describe('input', () => {
});
</script>`,
);
- await context.createTextSnapshot(context.getSelectedMcpPage());
+ context.getSelectedMcpPage().textSnapshot = await TextSnapshot.create(
+ context.getSelectedMcpPage(),
+ );
await drag.handler(
{
params: {
@@ -666,7 +703,9 @@ describe('input', () => {
/>
</form>`,
);
- await context.createTextSnapshot(context.getSelectedMcpPage());
+ context.getSelectedMcpPage().textSnapshot = await TextSnapshot.create(
+ context.getSelectedMcpPage(),
+ );
await fillForm.handler(
{
params: {
@@ -721,7 +760,9 @@ describe('input', () => {
/>
</form>`,
);
- await context.createTextSnapshot(context.getSelectedMcpPage());
+ context.getSelectedMcpPage().textSnapshot = await TextSnapshot.create(
+ context.getSelectedMcpPage(),
+ );
await uploadFile.handler(
{
params: {
@@ -764,7 +805,9 @@ describe('input', () => {
});
</script>`,
);
- await context.createTextSnapshot(context.getSelectedMcpPage());
+ context.getSelectedMcpPage().textSnapshot = await TextSnapshot.create(
+ context.getSelectedMcpPage(),
+ );
await uploadFile.handler(
{
params: {
@@ -798,7 +841,9 @@ describe('input', () => {
await withMcpContext(async (response, context) => {
const page = context.getSelectedPptrPage();
await page.setContent(html`<div>Not a file input</div>`);
- await context.createTextSnapshot(context.getSelectedMcpPage());
+ context.getSelectedMcpPage().textSnapshot = await TextSnapshot.create(
+ context.getSelectedMcpPage(),
+ );
await assert.rejects(
uploadFile.handler(
@@ -864,7 +909,9 @@ describe('input', () => {
document.addEventListener('keyup', e => logs.push('u' + e.key));
</script>`,
);
- await context.createTextSnapshot(context.getSelectedMcpPage());
+ context.getSelectedMcpPage().textSnapshot = await TextSnapshot.create(
+ context.getSelectedMcpPage(),
+ );
await pressKey.handler(
{
diff --git a/tests/tools/screenshot.test.ts b/tests/tools/screenshot.test.ts
index 9d177f9b..b6aee504 100644
--- a/tests/tools/screenshot.test.ts
+++ b/tests/tools/screenshot.test.ts
@@ -10,6 +10,7 @@ import {tmpdir} from 'node:os';
import {join} from 'node:path';
import {describe, it} from 'node:test';
+import {TextSnapshot} from '../../src/TextSnapshot.js';
import {screenshot} from '../../src/tools/screenshot.js';
import {screenshots} from '../snapshot.js';
import {html, withMcpContext} from '../utils.js';
@@ -155,7 +156,9 @@ describe('screenshot', () => {
const page = context.getSelectedPptrPage();
await page.setContent(fixture.html);
- await context.createTextSnapshot(context.getSelectedMcpPage());
+ context.getSelectedMcpPage().textSnapshot = await TextSnapshot.create(
+ context.getSelectedMcpPage(),
+ );
await screenshot.handler(
{
params: {
diff --git a/tests/tools/script.test.ts b/tests/tools/script.test.ts
index b0d57678..c87048fb 100644
--- a/tests/tools/script.test.ts
+++ b/tests/tools/script.test.ts
@@ -9,6 +9,7 @@ import path from 'node:path';
import {describe, it} from 'node:test';
import type {ParsedArguments} from '../../src/bin/chrome-devtools-mcp-cli-options.js';
+import {TextSnapshot} from '../../src/TextSnapshot.js';
import {installExtension} from '../../src/tools/extensions.js';
import {evaluateScript} from '../../src/tools/script.js';
import {serverHooks} from '../server.js';
@@ -201,7 +202,9 @@ describe('script', () => {
await page.setContent(html`<button id="test">test</button>`);
- await context.createTextSnapshot(context.getSelectedMcpPage());
+ context.getSelectedMcpPage().textSnapshot = await TextSnapshot.create(
+ context.getSelectedMcpPage(),
+ );
await evaluateScript().handler(
{
@@ -226,7 +229,9 @@ describe('script', () => {
await page.setContent(html`<button id="test">test</button>`);
- await context.createTextSnapshot(context.getSelectedMcpPage());
+ context.getSelectedMcpPage().textSnapshot = await TextSnapshot.create(
+ context.getSelectedMcpPage(),
+ );
await evaluateScript().handler(
{
@@ -255,7 +260,9 @@ describe('script', () => {
await withMcpContext(async (response, context) => {
const page = context.getSelectedPptrPage();
await page.goto(server.getRoute('/main'));
- await context.createTextSnapshot(context.getSelectedMcpPage());
+ context.getSelectedMcpPage().textSnapshot = await TextSnapshot.create(
+ context.getSelectedMcpPage(),
+ );
await evaluateScript().handler(
{
params: {
diff --git a/tests/utils.ts b/tests/utils.ts
index 811f164e..c8bc1a20 100644
--- a/tests/utils.ts
+++ b/tests/utils.ts
@@ -25,6 +25,7 @@ import sinon from 'sinon';
import type {ParsedArguments} from '../src/bin/chrome-devtools-mcp-cli-options.js';
import {McpContext} from '../src/McpContext.js';
import {McpResponse} from '../src/McpResponse.js';
+import {TextSnapshot} from '../src/TextSnapshot.js';
import {DevTools} from '../src/third_party/index.js';
import {stableIdSymbol} from '../src/utils/id.js';
@@ -118,6 +119,7 @@ export async function withMcpContext(
args: ParsedArguments = {} as ParsedArguments,
) {
await withBrowser(async browser => {
+ TextSnapshot.resetCounter();
const response = new McpResponse(args);
if (context) {
context.dispose();