Skip to content

Chrome DevTools for coding agents

refactor: move comments formatting to CommentFormatter class (#2719)

Alex Rudenkoe3cded0f43b0
diff --git a/src/McpResponse.ts b/src/McpResponse.ts
index 7fff12e2..c3942a5f 100644
--- a/src/McpResponse.ts
+++ b/src/McpResponse.ts
@@ -7,6 +7,10 @@
import type {WebMCPTool} from 'puppeteer-core';
import type {ParsedArguments} from './config/mcp-options.js';
+import {
+ CommentFormatter,
+ type StructuredCommentThread,
+} from './formatters/CommentFormatter.js';
import {ConsoleFormatter} from './formatters/ConsoleFormatter.js';
import {
HeapSnapshotFormatter,
@@ -51,7 +55,7 @@ import {
getInsightOutput,
getTraceSummary,
} from './processors/PerformanceTrace.js';
-import type {PaginationOptions} from './types.js';
+import type {CD4ACommentThread, PaginationOptions} from './types.js';
import type {WithSymbolId} from './utils/id.js';
import {stableIdSymbol} from './utils/id.js';
import {paginate} from './utils/pagination.js';
@@ -125,6 +129,7 @@ export class McpResponse implements Response {
#error?: Error;
#attachedWaitForResult?: WaitForEventsResult;
#reconnectNotice = false;
+ #devToolsComments?: CD4ACommentThread[];
get #deviceScope(): DevTools.CrUXManager.DeviceScope {
return this.#page?.viewport?.isMobile ? 'PHONE' : 'DESKTOP';
@@ -327,6 +332,14 @@ export class McpResponse implements Response {
this.#attachedWaitForResult = result;
}
+ setDevToolsComments(threads: CD4ACommentThread[]): void {
+ this.#devToolsComments = threads;
+ }
+
+ get devToolsComments(): readonly CD4ACommentThread[] | undefined {
+ return this.#devToolsComments;
+ }
+
setHeapSnapshotAggregates(
aggregateData: HeapSnapshotAggregateData,
options?: PaginationOptions,
@@ -668,6 +681,22 @@ export class McpResponse implements Response {
);
}
+ async #handleComments(): Promise<CommentFormatter | undefined> {
+ const comments = this.#devToolsComments;
+ if (!comments) {
+ return undefined;
+ }
+ const page = this.#page;
+ return await CommentFormatter.from(comments, {
+ resolveBackendNodeId: page
+ ? (id: number) => page.resolveBackendNodeId(id)
+ : undefined,
+ resolveCdpRequestId: page
+ ? (id: string) => page.resolveCdpRequestId(id)
+ : undefined,
+ });
+ }
+
async handle(
context: McpContext,
dataFormat: DataFormat = 'default',
@@ -683,6 +712,7 @@ export class McpResponse implements Response {
webmcpTools,
consoleMessages,
networkRequests,
+ comments,
] = await Promise.all([
this.#handleSnapshot(context),
this.#handleAttachedNetworkRequest(context),
@@ -691,6 +721,7 @@ export class McpResponse implements Response {
this.#handleWebMCP(),
this.#handleConsoleList(context),
this.#handleNetworkRequestList(context),
+ this.#handleComments(),
]);
if (this.#includeExtensionServiceWorkers) {
@@ -716,6 +747,7 @@ export class McpResponse implements Response {
lighthouseResult: this.#attachedLighthouseResult,
thirdPartyDeveloperTools,
webmcpTools,
+ comments,
errorMessage: this.#error?.message,
},
dataFormat,
@@ -746,6 +778,7 @@ export class McpResponse implements Response {
lighthouseResult?: LighthouseData;
thirdPartyDeveloperTools?: ToolGroups;
webmcpTools?: WebMCPTool[];
+ comments?: CommentFormatter;
errorMessage?: string;
},
dataFormat: DataFormat = 'default',
@@ -805,6 +838,7 @@ export class McpResponse implements Response {
heapSnapshotObjectDetails?: DevTools.HeapSnapshotModel.HeapSnapshotModel.ObjectInfo;
extensionServiceWorkers?: object[];
extensionPages?: object[];
+ comments?: StructuredCommentThread[];
errorMessage?: string;
navigatedToUrl?: string;
geolocation?: {latitude: number; longitude: number};
@@ -1392,6 +1426,14 @@ Call ${handleDialog.name} to handle it before continuing.`);
}
}
+ if (data.comments) {
+ const commentsJson = data.comments.toJSON();
+ structuredContent.comments = commentsJson;
+ response.push(
+ compactEncode ? compactEncode(commentsJson) : data.comments.toString(),
+ );
+ }
+
if (data.errorMessage) {
response.push(`Error: ${data.errorMessage}`);
structuredContent.errorMessage = data.errorMessage;
diff --git a/src/formatters/CommentFormatter.ts b/src/formatters/CommentFormatter.ts
new file mode 100644
index 00000000..3d210ee6
--- /dev/null
+++ b/src/formatters/CommentFormatter.ts
@@ -0,0 +1,109 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type {CD4ACommentThread, CD4AEditorAnchorSignature} from '../types.js';
+
+export interface CommentFormatterOptions {
+ resolveBackendNodeId?: (backendNodeId: number) => Promise<string | undefined>;
+ resolveCdpRequestId?: (cdpRequestId: string) => number | undefined;
+}
+
+export interface StructuredCommentThread {
+ id: string;
+ text: string;
+ elementUid?: string;
+ reqid?: number;
+ editor?: CD4AEditorAnchorSignature;
+}
+
+function formatCommentThread(thread: StructuredCommentThread): string {
+ const lines: string[] = [
+ `### Thread: ${thread.id}`,
+ `- Comment: ${thread.text}`,
+ ];
+ if (thread.elementUid) {
+ lines.push(`- Target element (snapshot UID): ${thread.elementUid}`);
+ }
+ if (thread.reqid !== undefined) {
+ lines.push(`- Network request ID (reqid): ${thread.reqid}`);
+ }
+ if (thread.editor) {
+ const location = thread.editor.filePath
+ ? `${thread.editor.filePath}:${thread.editor.lineNumber}`
+ : `line ${thread.editor.lineNumber}`;
+ lines.push(`- Editor location: ${location}`);
+ }
+ return lines.join('\n');
+}
+
+function formatComments(threads: readonly StructuredCommentThread[]): string {
+ if (threads.length === 0) {
+ return 'No open DevTools comments found.';
+ }
+ const lines: string[] = [
+ `Found ${threads.length} DevTools comment thread(s):`,
+ ];
+ for (const thread of threads) {
+ lines.push(`\n${formatCommentThread(thread)}`);
+ }
+ return lines.join('\n');
+}
+
+export class CommentFormatter {
+ readonly #threads: readonly StructuredCommentThread[];
+
+ constructor(threads: readonly StructuredCommentThread[]) {
+ this.#threads = threads;
+ }
+
+ static async from(
+ threads: readonly CD4ACommentThread[],
+ options?: CommentFormatterOptions,
+ ): Promise<CommentFormatter> {
+ const structuredThreads: StructuredCommentThread[] = [];
+ for (const thread of threads) {
+ let elementUid: string | undefined;
+ const resolveBackendNodeId = options?.resolveBackendNodeId;
+ if (thread.backendNodeId !== undefined && resolveBackendNodeId) {
+ elementUid = await resolveBackendNodeId(thread.backendNodeId);
+ }
+
+ let reqid: number | undefined;
+ const resolveCdpRequestId = options?.resolveCdpRequestId;
+ if (thread.networkRequestId !== undefined && resolveCdpRequestId) {
+ reqid = resolveCdpRequestId(thread.networkRequestId);
+ }
+
+ const item: StructuredCommentThread = {
+ id: thread.id,
+ text: thread.text,
+ };
+ if (elementUid) {
+ item.elementUid = elementUid;
+ }
+ if (reqid !== undefined) {
+ item.reqid = reqid;
+ }
+ if (thread.editor) {
+ item.editor = thread.editor;
+ }
+ structuredThreads.push(item);
+ }
+ return new CommentFormatter(structuredThreads);
+ }
+
+ static formatThread(thread: StructuredCommentThread): string {
+ return formatCommentThread(thread);
+ }
+
+ toJSON(): StructuredCommentThread[] {
+ return [...this.#threads];
+ }
+
+ toString(): string {
+ return formatComments(this.toJSON());
+ }
+}
diff --git a/src/tools/ToolDefinition.ts b/src/tools/ToolDefinition.ts
index 3bed3f94..1919a1e6 100644
--- a/src/tools/ToolDefinition.ts
+++ b/src/tools/ToolDefinition.ts
@@ -35,6 +35,7 @@ import type {
TextSnapshotNode,
GeolocationOptions,
ExtensionServiceWorker,
+ CD4ACommentThread,
} from '../types.js';
import type {PaginationOptions} from '../types.js';
import type {
@@ -194,6 +195,7 @@ export interface Response {
setListThirdPartyDeveloperTools(): void;
setListWebMcpTools(): void;
attachWaitForResult(result: WaitForEventsResult): void;
+ setDevToolsComments(threads: CD4ACommentThread[]): void;
}
export type SupportedExtensions =
diff --git a/src/tools/comments.ts b/src/tools/comments.ts
index ef2dc036..f6d6fdcb 100644
--- a/src/tools/comments.ts
+++ b/src/tools/comments.ts
@@ -68,40 +68,7 @@ export const getDevtoolsComments = definePageTool({
return window.universe?.cd4aBridge?.getCommentThreads() ?? [];
});
- if (threads.length === 0) {
- response.appendResponseLine('No open DevTools comments found.');
- return;
- }
-
- response.appendResponseLine(
- `Found ${threads.length} DevTools comment thread(s):`,
- );
- for (const thread of threads) {
- response.appendResponseLine(`\n### Thread: ${thread.id}`);
- response.appendResponseLine(`- Comment: ${thread.text}`);
- if (thread.backendNodeId !== undefined) {
- const elementUid = await page.resolveBackendNodeId(
- thread.backendNodeId,
- );
- if (elementUid) {
- response.appendResponseLine(
- `- Target element (snapshot UID): ${elementUid}`,
- );
- }
- }
- if (thread.networkRequestId) {
- const reqid = page.resolveCdpRequestId(thread.networkRequestId);
- if (reqid !== undefined) {
- response.appendResponseLine(`- Network request ID (reqid): ${reqid}`);
- }
- }
- if (thread.editor) {
- const location = thread.editor.filePath
- ? `${thread.editor.filePath}:${thread.editor.lineNumber}`
- : `line ${thread.editor.lineNumber}`;
- response.appendResponseLine(`- Editor location: ${location}`);
- }
- }
+ response.setDevToolsComments(threads);
},
});
diff --git a/tests/formatters/CommentFormatter.test.js.snapshot b/tests/formatters/CommentFormatter.test.js.snapshot
new file mode 100644
index 00000000..fb63475d
--- /dev/null
+++ b/tests/formatters/CommentFormatter.test.js.snapshot
@@ -0,0 +1,99 @@
+exports[`CommentFormatter > formats comments with targets and editor locations toJSON 1`] = `
+[
+ {
+ "id": "comment-1",
+ "text": "Fix the color contrast here",
+ "elementUid": "element-uid-42",
+ "reqid": 7,
+ "editor": {
+ "filePath": "src/style.css",
+ "lineNumber": 10
+ }
+ }
+]
+`;
+
+exports[`CommentFormatter > formats comments with targets and editor locations toString 1`] = `
+Found 1 DevTools comment thread(s):
+
+### Thread: comment-1
+- Comment: Fix the color contrast here
+- Target element (snapshot UID): element-uid-42
+- Network request ID (reqid): 7
+- Editor location: src/style.css:10
+`;
+
+exports[`CommentFormatter > formats editor location when filePath is missing toJSON 1`] = `
+[
+ {
+ "id": "comment-2",
+ "text": "Review this script line",
+ "editor": {
+ "lineNumber": 25
+ }
+ }
+]
+`;
+
+exports[`CommentFormatter > formats editor location when filePath is missing toString 1`] = `
+Found 1 DevTools comment thread(s):
+
+### Thread: comment-2
+- Comment: Review this script line
+- Editor location: line 25
+`;
+
+exports[`CommentFormatter > formats empty comments list toJSON 1`] = `
+[]
+`;
+
+exports[`CommentFormatter > formats empty comments list toString 1`] = `
+No open DevTools comments found.
+`;
+
+exports[`CommentFormatter > formats single thread using static formatThread 1`] = `
+### Thread: comment-3
+- Comment: Check padding
+- Target element (snapshot UID): node-99
+`;
+
+exports[`CommentFormatter > omits unresolved targets when from() resolves undefined toJSON 1`] = `
+[
+ {
+ "id": "comment-2",
+ "text": "Fix heading font size"
+ }
+]
+`;
+
+exports[`CommentFormatter > omits unresolved targets when from() resolves undefined toString 1`] = `
+Found 1 DevTools comment thread(s):
+
+### Thread: comment-2
+- Comment: Fix heading font size
+`;
+
+exports[`CommentFormatter > resolves targets using from() method toJSON 1`] = `
+[
+ {
+ "id": "comment-1",
+ "text": "Fix the color contrast here",
+ "elementUid": "element-uid-42",
+ "reqid": 7,
+ "editor": {
+ "filePath": "src/style.css",
+ "lineNumber": 10
+ }
+ }
+]
+`;
+
+exports[`CommentFormatter > resolves targets using from() method toString 1`] = `
+Found 1 DevTools comment thread(s):
+
+### Thread: comment-1
+- Comment: Fix the color contrast here
+- Target element (snapshot UID): element-uid-42
+- Network request ID (reqid): 7
+- Editor location: src/style.css:10
+`;
diff --git a/tests/formatters/CommentFormatter.test.ts b/tests/formatters/CommentFormatter.test.ts
new file mode 100644
index 00000000..bcac6a13
--- /dev/null
+++ b/tests/formatters/CommentFormatter.test.ts
@@ -0,0 +1,124 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {afterEach, describe, it} from 'node:test';
+
+import sinon from 'sinon';
+
+import {
+ CommentFormatter,
+ type StructuredCommentThread,
+} from '../../src/formatters/CommentFormatter.js';
+import type {CD4ACommentThread} from '../../src/types.js';
+
+describe('CommentFormatter', () => {
+ afterEach(() => {
+ sinon.restore();
+ });
+
+ function formatterTest(
+ label: string,
+ setup: (t: it.TestContext) => CommentFormatter | Promise<CommentFormatter>,
+ ) {
+ it(label + ' toString', async t => {
+ const formatter = await setup(t);
+ t.assert.snapshot(formatter.toString());
+ });
+ it(label + ' toJSON', async t => {
+ const formatter = await setup(t);
+ t.assert.snapshot(JSON.stringify(formatter.toJSON(), null, 2));
+ });
+ }
+
+ formatterTest('formats empty comments list', () => {
+ return new CommentFormatter([]);
+ });
+
+ formatterTest('formats comments with targets and editor locations', () => {
+ const thread: StructuredCommentThread = {
+ id: 'comment-1',
+ text: 'Fix the color contrast here',
+ elementUid: 'element-uid-42',
+ reqid: 7,
+ editor: {
+ filePath: 'src/style.css',
+ lineNumber: 10,
+ },
+ };
+ return new CommentFormatter([thread]);
+ });
+
+ formatterTest('formats editor location when filePath is missing', () => {
+ const thread: StructuredCommentThread = {
+ id: 'comment-2',
+ text: 'Review this script line',
+ editor: {
+ lineNumber: 25,
+ },
+ };
+ return new CommentFormatter([thread]);
+ });
+
+ it('formats single thread using static formatThread', t => {
+ const thread: StructuredCommentThread = {
+ id: 'comment-3',
+ text: 'Check padding',
+ elementUid: 'node-99',
+ };
+ t.assert.snapshot(CommentFormatter.formatThread(thread));
+ });
+
+ formatterTest('resolves targets using from() method', async () => {
+ const rawThread: CD4ACommentThread = {
+ id: 'comment-1',
+ text: 'Fix the color contrast here',
+ backendNodeId: 42,
+ networkRequestId: 'req-99',
+ editor: {
+ filePath: 'src/style.css',
+ lineNumber: 10,
+ },
+ };
+
+ const resolveBackendNodeId = sinon.stub().resolves('element-uid-42');
+ const resolveCdpRequestId = sinon.stub().returns(7);
+
+ const formatter = await CommentFormatter.from([rawThread], {
+ resolveBackendNodeId,
+ resolveCdpRequestId,
+ });
+
+ sinon.assert.calledOnceWithExactly(resolveBackendNodeId, 42);
+ sinon.assert.calledOnceWithExactly(resolveCdpRequestId, 'req-99');
+
+ return formatter;
+ });
+
+ formatterTest(
+ 'omits unresolved targets when from() resolves undefined',
+ async () => {
+ const rawThread: CD4ACommentThread = {
+ id: 'comment-2',
+ text: 'Fix heading font size',
+ backendNodeId: 42,
+ networkRequestId: 'req-99',
+ };
+
+ const resolveBackendNodeId = sinon.stub().resolves(undefined);
+ const resolveCdpRequestId = sinon.stub().returns(undefined);
+
+ const formatter = await CommentFormatter.from([rawThread], {
+ resolveBackendNodeId,
+ resolveCdpRequestId,
+ });
+
+ sinon.assert.calledOnceWithExactly(resolveBackendNodeId, 42);
+ sinon.assert.calledOnceWithExactly(resolveCdpRequestId, 'req-99');
+
+ return formatter;
+ },
+ );
+});
diff --git a/tests/tools/comments.test.ts b/tests/tools/comments.test.ts
index 5fb331b6..aab44699 100644
--- a/tests/tools/comments.test.ts
+++ b/tests/tools/comments.test.ts
@@ -45,34 +45,14 @@ describe('comments tools', () => {
response.appendResponseLine,
'DevTools window is not open for this page. Call open_devtools first to open DevTools.',
);
+ sinon.assert.notCalled(response.setDevToolsComments);
t.assert.snapshot(lines.join('\n'));
});
- it('reports message when no comments are found', async t => {
+ it('fetches comments and sets them on response', async () => {
const {page, context, response} = createHandlerMocks();
- const lines = trackResponseLines(response);
- const devtoolsPage = createMockPuppeteerPage();
- page.getDevToolsPage.resolves(devtoolsPage);
- devtoolsPage.evaluate.resolves([]);
-
- await getDevtoolsComments.handler({params: {}, page}, response, context);
-
- sinon.assert.calledOnce(page.getDevToolsPage);
- sinon.assert.calledOnce(devtoolsPage.evaluate);
- sinon.assert.calledOnceWithExactly(
- response.appendResponseLine,
- 'No open DevTools comments found.',
- );
- t.assert.snapshot(lines.join('\n'));
- });
-
- it('formats comment threads with text, targets, and editor location', async t => {
- const {page, context, response} = createHandlerMocks();
- const lines = trackResponseLines(response);
const devtoolsPage = createMockPuppeteerPage();
page.getDevToolsPage.resolves(devtoolsPage);
- page.resolveBackendNodeId.resolves('element-uid-42');
- page.resolveCdpRequestId.returns(7);
const mockThread: CommentThreadPayload = {
id: 'comment-1',
@@ -91,31 +71,22 @@ describe('comments tools', () => {
sinon.assert.calledOnce(page.getDevToolsPage);
sinon.assert.calledOnce(devtoolsPage.evaluate);
- sinon.assert.calledOnceWithExactly(page.resolveBackendNodeId, 42);
- sinon.assert.calledOnceWithExactly(page.resolveCdpRequestId, 'req-99');
- t.assert.snapshot(lines.join('\n'));
+ sinon.assert.calledOnceWithExactly(response.setDevToolsComments, [
+ mockThread,
+ ]);
});
- it('omits target element and network request ID if resolution returns undefined', async t => {
+ it('sets empty comments list when no comments are found', async () => {
const {page, context, response} = createHandlerMocks();
- const lines = trackResponseLines(response);
const devtoolsPage = createMockPuppeteerPage();
page.getDevToolsPage.resolves(devtoolsPage);
- page.resolveBackendNodeId.resolves(undefined);
- page.resolveCdpRequestId.returns(undefined);
-
- const mockThread: CommentThreadPayload = {
- id: 'comment-2',
- text: 'Fix heading font size',
- backendNodeId: 42,
- networkRequestId: 'req-99',
- };
-
- devtoolsPage.evaluate.resolves([mockThread]);
+ devtoolsPage.evaluate.resolves([]);
await getDevtoolsComments.handler({params: {}, page}, response, context);
- t.assert.snapshot(lines.join('\n'));
+ sinon.assert.calledOnce(page.getDevToolsPage);
+ sinon.assert.calledOnce(devtoolsPage.evaluate);
+ sinon.assert.calledOnceWithExactly(response.setDevToolsComments, []);
});
});