Skip to content

Chrome DevTools for coding agents

chore: show a message when DevTools comments are unavailable (#2932)

yulunz6f3444152541
diff --git a/src/McpPage.ts b/src/McpPage.ts
index 5b0ae627..a3d2c366 100644
--- a/src/McpPage.ts
+++ b/src/McpPage.ts
@@ -516,16 +516,20 @@ export class McpPage implements ContextPage {
return this.#commentBridge;
}
+ /**
+ * Returns the comment bridge attached to the DevTools page, or undefined if
+ * the DevTools page does not support DevTools comments.
+ */
async ensureDevToolsCommentBridge(
devtoolsPage: Page,
- ): Promise<DevToolsCommentBridge> {
+ ): Promise<DevToolsCommentBridge | undefined> {
if (!this.#commentBridge) {
this.#commentBridge = new DevToolsCommentBridge({
onNotification: this.#onNotification,
});
}
- await this.#commentBridge.attach(devtoolsPage);
- return this.#commentBridge;
+ const attached = await this.#commentBridge.attach(devtoolsPage);
+ return attached ? this.#commentBridge : undefined;
}
async getDevToolsPage(): Promise<Page | undefined> {
diff --git a/src/devtools/DevToolsCommentBridge.ts b/src/devtools/DevToolsCommentBridge.ts
index 02004b20..378c8866 100644
--- a/src/devtools/DevToolsCommentBridge.ts
+++ b/src/devtools/DevToolsCommentBridge.ts
@@ -34,37 +34,79 @@ export class DevToolsCommentBridge {
return this.#attachedPages.has(devtoolsPage);
}
- async attach(devtoolsPage: Page): Promise<void> {
+ /**
+ * Attaches to the DevTools page if it exposes the CD4A bridge.
+ *
+ * Returns false if the bridge does not exist, e.g., because the connected
+ * Chrome version does not support DevTools comments or the feature is
+ * disabled, or if the comment event binding could not be installed.
+ * Negative results are not cached so that a DevTools window that has not
+ * finished loading yet is checked again on the next call.
+ */
+ async attach(devtoolsPage: Page): Promise<boolean> {
if (this.#attachedPages.has(devtoolsPage)) {
- return;
+ return true;
+ }
+
+ try {
+ const hasBridge = await devtoolsPage.evaluate(() => {
+ return Boolean(window.universe?.cd4aBridge);
+ });
+ if (!hasBridge) {
+ return false;
+ }
+ } catch (e) {
+ logger?.('DevToolsCommentBridge: evaluate failed', e);
+ return false;
}
- this.#attachedPages.add(devtoolsPage);
try {
await devtoolsPage.exposeFunction('__onDevToolsCommentEvent', () => {
this.#handleCommentEvent();
});
} catch (e) {
+ // The binding may already exist, e.g., exposed by a previous bridge.
+ // Whether it is usable is checked in the page below.
logger?.(
'DevToolsCommentBridge: exposeFunction already bound or failed',
e,
);
}
+ let attached = false;
try {
- await devtoolsPage.evaluate(() => {
+ attached = await devtoolsPage.evaluate(() => {
+ const cd4aBridge = window.universe?.cd4aBridge;
+ if (
+ !cd4aBridge ||
+ typeof window.__onDevToolsCommentEvent !== 'function'
+ ) {
+ return false;
+ }
+ if (window.__onDevToolsCommentListener) {
+ cd4aBridge.removeEventListener(
+ 'CommentThreadsChanged',
+ window.__onDevToolsCommentListener,
+ );
+ }
window.__onDevToolsCommentListener = () => {
window.__onDevToolsCommentEvent?.();
};
- window.universe?.cd4aBridge?.addEventListener(
+ cd4aBridge.addEventListener(
'CommentThreadsChanged',
window.__onDevToolsCommentListener,
);
- window.universe?.cd4aBridge?.setAgentAttached(true);
+ cd4aBridge.setAgentAttached(true);
+ return true;
});
} catch (e) {
logger?.('DevToolsCommentBridge: evaluate failed', e);
}
+ if (!attached) {
+ return false;
+ }
+ this.#attachedPages.add(devtoolsPage);
+ return true;
}
async getComments(devtoolsPage: Page): Promise<CD4ACommentThread[]> {
diff --git a/src/tools/ToolDefinition.ts b/src/tools/ToolDefinition.ts
index 73c502a9..cbbf8519 100644
--- a/src/tools/ToolDefinition.ts
+++ b/src/tools/ToolDefinition.ts
@@ -433,7 +433,7 @@ export type ContextPage = Readonly<{
openDevTools(): Promise<Page | undefined>;
ensureDevToolsCommentBridge(
devtoolsPage: Page,
- ): Promise<DevToolsCommentBridge>;
+ ): Promise<DevToolsCommentBridge | undefined>;
}>;
export function defineTool<Schema extends zod.ZodRawShape>(
diff --git a/src/tools/comments.ts b/src/tools/comments.ts
index 04981570..ae5fb312 100644
--- a/src/tools/comments.ts
+++ b/src/tools/comments.ts
@@ -14,6 +14,9 @@ import {definePageTool} from './ToolDefinition.js';
export type CommentThreadPayload = CD4ACommentThread;
export type RevealTargetPayload = CD4ARevealTarget;
+const DEVTOOLS_COMMENTS_UNAVAILABLE_MESSAGE =
+ 'DevTools comments are not working right now. Possible reasons: the connected Chrome version does not support DevTools comments, the feature is disabled, or the DevTools window has not finished loading. Try again later, or continue without DevTools comments.';
+
export const openDevtools = definePageTool(() => ({
name: 'open_devtools',
description: 'Open a DevTools window for the selected page.',
@@ -60,6 +63,10 @@ export const getDevtoolsComments = definePageTool(() => ({
}
const bridge = await page.ensureDevToolsCommentBridge(devtoolsPage);
+ if (!bridge) {
+ response.appendResponseLine(DEVTOOLS_COMMENTS_UNAVAILABLE_MESSAGE);
+ return;
+ }
const threads = await bridge.getComments(devtoolsPage);
response.setDevToolsComments(threads);
@@ -100,6 +107,11 @@ export const resolveDevtoolsComment = definePageTool(() => ({
return;
}
+ if (!(await page.ensureDevToolsCommentBridge(devtoolsPage))) {
+ response.appendResponseLine(DEVTOOLS_COMMENTS_UNAVAILABLE_MESSAGE);
+ return;
+ }
+
const {threadId, replyText} = request.params;
const success = await devtoolsPage.evaluate(
(id: string, reply: string | undefined) => {
@@ -165,6 +177,11 @@ export const revealInDevtools = definePageTool(() => ({
return;
}
+ if (!(await page.ensureDevToolsCommentBridge(devtoolsPage))) {
+ response.appendResponseLine(DEVTOOLS_COMMENTS_UNAVAILABLE_MESSAGE);
+ return;
+ }
+
const {panelName, uid, reqid} = request.params;
let backendNodeId: number | undefined;
let targetId: string | undefined;
diff --git a/tests/McpPage.test.ts b/tests/McpPage.test.ts
index 0bfe47ec..03e8a360 100644
--- a/tests/McpPage.test.ts
+++ b/tests/McpPage.test.ts
@@ -854,6 +854,7 @@ describe('McpPage', () => {
it('creates and attaches commentBridge when openDevTools is called', async () => {
const {mcpPage, pptrPage} = await createMcpPage();
const devtoolsPage = createMockPuppeteerPage();
+ devtoolsPage.evaluate.resolves(true);
pptrPage.openDevTools.resolves(devtoolsPage);
assert.strictEqual(mcpPage.commentBridge, undefined);
@@ -864,6 +865,28 @@ describe('McpPage', () => {
sinon.assert.calledOnce(devtoolsPage.exposeFunction);
});
+ it('returns the commentBridge when the DevTools page has a CD4A bridge', async () => {
+ const {mcpPage} = await createMcpPage();
+ const devtoolsPage = createMockPuppeteerPage();
+ devtoolsPage.evaluate.resolves(true);
+
+ const bridge = await mcpPage.ensureDevToolsCommentBridge(devtoolsPage);
+
+ assert.notStrictEqual(bridge, undefined);
+ assert.strictEqual(bridge, mcpPage.commentBridge);
+ });
+
+ it('returns undefined when the DevTools page has no CD4A bridge', async () => {
+ const {mcpPage} = await createMcpPage();
+ const devtoolsPage = createMockPuppeteerPage();
+ devtoolsPage.evaluate.resolves(false);
+
+ const bridge = await mcpPage.ensureDevToolsCommentBridge(devtoolsPage);
+
+ assert.strictEqual(bridge, undefined);
+ sinon.assert.notCalled(devtoolsPage.exposeFunction);
+ });
+
it('disposes commentBridge on mcpPage.dispose()', async () => {
const {mcpPage, pptrPage} = await createMcpPage();
const devtoolsPage = createMockPuppeteerPage();
@@ -886,7 +909,8 @@ describe('McpPage', () => {
const {mcpPage, pptrPage} = await createMcpPage();
pptrPage.hasDevTools.resolves(true);
const devtoolsPage = createMockPuppeteerPage();
- devtoolsPage.evaluate.resolves({
+ devtoolsPage.evaluate.resolves(true);
+ devtoolsPage.evaluate.onThirdCall().resolves({
cdpRequestId: 'req-1',
cdpBackendNodeId: 10,
});
@@ -901,7 +925,7 @@ describe('McpPage', () => {
});
assert.notStrictEqual(mcpPage.commentBridge, undefined);
sinon.assert.calledOnce(devtoolsPage.exposeFunction);
- sinon.assert.calledTwice(devtoolsPage.evaluate);
+ sinon.assert.calledThrice(devtoolsPage.evaluate);
});
});
diff --git a/tests/devtools/DevToolsCommentBridge.test.ts b/tests/devtools/DevToolsCommentBridge.test.ts
index 54bbc812..c4a8a9d9 100644
--- a/tests/devtools/DevToolsCommentBridge.test.ts
+++ b/tests/devtools/DevToolsCommentBridge.test.ts
@@ -26,30 +26,101 @@ describe('DevToolsCommentBridge', () => {
it('attaches to DevTools page and registers function and evaluation', async () => {
const devtoolsPage = createMockPuppeteerPage();
+ devtoolsPage.evaluate.resolves(true);
const bridge = new DevToolsCommentBridge();
assert.strictEqual(bridge.isAttached(devtoolsPage), false);
- await bridge.attach(devtoolsPage);
+ assert.strictEqual(await bridge.attach(devtoolsPage), true);
assert.strictEqual(bridge.isAttached(devtoolsPage), true);
sinon.assert.calledOnce(devtoolsPage.exposeFunction);
- sinon.assert.calledOnce(devtoolsPage.evaluate);
+ sinon.assert.calledTwice(devtoolsPage.evaluate);
});
it('is idempotent when attaching to the same DevTools page', async () => {
const devtoolsPage = createMockPuppeteerPage();
+ devtoolsPage.evaluate.resolves(true);
const bridge = new DevToolsCommentBridge();
- await bridge.attach(devtoolsPage);
- await bridge.attach(devtoolsPage);
+ assert.strictEqual(await bridge.attach(devtoolsPage), true);
+ assert.strictEqual(await bridge.attach(devtoolsPage), true);
sinon.assert.calledOnce(devtoolsPage.exposeFunction);
+ sinon.assert.calledTwice(devtoolsPage.evaluate);
+ });
+
+ it('does not attach when the DevTools page has no CD4A bridge', async () => {
+ const devtoolsPage = createMockPuppeteerPage();
+ devtoolsPage.evaluate.resolves(false);
+ const bridge = new DevToolsCommentBridge();
+
+ assert.strictEqual(await bridge.attach(devtoolsPage), false);
+
+ assert.strictEqual(bridge.isAttached(devtoolsPage), false);
sinon.assert.calledOnce(devtoolsPage.evaluate);
+ sinon.assert.notCalled(devtoolsPage.exposeFunction);
+ });
+
+ it('checks for the CD4A bridge again after a failed attach', async () => {
+ const devtoolsPage = createMockPuppeteerPage();
+ devtoolsPage.evaluate.resolves(true);
+ devtoolsPage.evaluate.onFirstCall().resolves(false);
+ const bridge = new DevToolsCommentBridge();
+
+ assert.strictEqual(await bridge.attach(devtoolsPage), false);
+ assert.strictEqual(await bridge.attach(devtoolsPage), true);
+
+ assert.strictEqual(bridge.isAttached(devtoolsPage), true);
+ sinon.assert.calledThrice(devtoolsPage.evaluate);
+ sinon.assert.calledOnce(devtoolsPage.exposeFunction);
+ });
+
+ it('does not attach when evaluation fails', async () => {
+ const devtoolsPage = createMockPuppeteerPage();
+ devtoolsPage.evaluate.rejects(new Error('Target closed'));
+ const bridge = new DevToolsCommentBridge();
+
+ assert.strictEqual(await bridge.attach(devtoolsPage), false);
+
+ assert.strictEqual(bridge.isAttached(devtoolsPage), false);
+ sinon.assert.notCalled(devtoolsPage.exposeFunction);
+ });
+
+ it('attaches when the comment event binding already exists', async () => {
+ const devtoolsPage = createMockPuppeteerPage();
+ devtoolsPage.evaluate.resolves(true);
+ devtoolsPage.exposeFunction.rejects(
+ new Error(
+ "Failed to add page binding with name __onDevToolsCommentEvent: window['__onDevToolsCommentEvent'] already exists!",
+ ),
+ );
+ const bridge = new DevToolsCommentBridge();
+
+ assert.strictEqual(await bridge.attach(devtoolsPage), true);
+
+ assert.strictEqual(bridge.isAttached(devtoolsPage), true);
+ sinon.assert.calledOnce(devtoolsPage.exposeFunction);
+ sinon.assert.calledTwice(devtoolsPage.evaluate);
+ });
+
+ it('does not attach when the comment event binding is unavailable', async () => {
+ const devtoolsPage = createMockPuppeteerPage();
+ devtoolsPage.evaluate.onFirstCall().resolves(true);
+ devtoolsPage.evaluate.onSecondCall().resolves(false);
+ devtoolsPage.exposeFunction.rejects(new Error('Target closed'));
+ const bridge = new DevToolsCommentBridge();
+
+ assert.strictEqual(await bridge.attach(devtoolsPage), false);
+
+ assert.strictEqual(bridge.isAttached(devtoolsPage), false);
+ sinon.assert.calledOnce(devtoolsPage.exposeFunction);
+ sinon.assert.calledTwice(devtoolsPage.evaluate);
});
it('debounces comment notifications', async () => {
const devtoolsPage = createMockPuppeteerPage();
+ devtoolsPage.evaluate.resolves(true);
const onNotification = sinon.stub();
let exposedCallback: (() => void) | undefined;
@@ -89,6 +160,7 @@ describe('DevToolsCommentBridge', () => {
it('clears debounce timer on dispose', async () => {
const devtoolsPage = createMockPuppeteerPage();
+ devtoolsPage.evaluate.resolves(true);
const onNotification = sinon.stub();
let exposedCallback: (() => void) | undefined;
@@ -117,7 +189,7 @@ describe('DevToolsCommentBridge', () => {
clock.tick(200);
sinon.assert.notCalled(onNotification);
- sinon.assert.calledTwice(devtoolsPage.evaluate);
+ sinon.assert.calledThrice(devtoolsPage.evaluate);
});
it('retrieves comments via getComments', async () => {
diff --git a/tests/tools/comments.test.js.snapshot b/tests/tools/comments.test.js.snapshot
index 97fbf4e0..b73450d4 100644
--- a/tests/tools/comments.test.js.snapshot
+++ b/tests/tools/comments.test.js.snapshot
@@ -2,6 +2,10 @@ exports[`comments tools > get_devtools_comments > reports error when DevTools wi
DevTools window is not open for this page. Call open_devtools first to open DevTools.
`;
+exports[`comments tools > get_devtools_comments > reports when DevTools comments are unavailable 1`] = `
+DevTools comments are not working right now. Possible reasons: the connected Chrome version does not support DevTools comments, the feature is disabled, or the DevTools window has not finished loading. Try again later, or continue without DevTools comments.
+`;
+
exports[`comments tools > resolve_devtools_comment > reports error when DevTools window is not open 1`] = `
DevTools window is not open for this page. Call open_devtools first to open DevTools.
`;
@@ -10,6 +14,10 @@ exports[`comments tools > resolve_devtools_comment > reports error when thread i
Failed to resolve comment thread "comment-nonexistent". Thread not found.
`;
+exports[`comments tools > resolve_devtools_comment > reports when DevTools comments are unavailable 1`] = `
+DevTools comments are not working right now. Possible reasons: the connected Chrome version does not support DevTools comments, the feature is disabled, or the DevTools window has not finished loading. Try again later, or continue without DevTools comments.
+`;
+
exports[`comments tools > resolve_devtools_comment > resolves comment thread and appends reply text 1`] = `
Comment thread comment-1 resolved successfully.
Agent reply added: "Updated background color in index.css"
@@ -19,6 +27,10 @@ exports[`comments tools > reveal_in_devtools > reports error when DevTools windo
DevTools window is not open for this page. Call open_devtools first to open DevTools.
`;
+exports[`comments tools > reveal_in_devtools > reports when DevTools comments are unavailable 1`] = `
+DevTools comments are not working right now. Possible reasons: the connected Chrome version does not support DevTools comments, the feature is disabled, or the DevTools window has not finished loading. Try again later, or continue without DevTools comments.
+`;
+
exports[`comments tools > reveal_in_devtools > reveals element by snapshot uid 1`] = `
Navigated to elements panel (revealing element uid-header [backend node 101]) in DevTools.
`;
diff --git a/tests/tools/comments.test.ts b/tests/tools/comments.test.ts
index 6033bfc4..321537d2 100644
--- a/tests/tools/comments.test.ts
+++ b/tests/tools/comments.test.ts
@@ -112,6 +112,28 @@ describe('comments tools', () => {
sinon.assert.calledOnceWithExactly(bridge.getComments, devtoolsPage);
sinon.assert.calledOnceWithExactly(response.setDevToolsComments, []);
});
+
+ it('reports when DevTools comments are unavailable', async t => {
+ const {page, context, response, args} = createHandlerMocks();
+ const lines = trackResponseLines(response);
+ const devtoolsPage = createMockPuppeteerPage();
+ page.getDevToolsPage.resolves(devtoolsPage);
+ page.ensureDevToolsCommentBridge.resolves(undefined);
+
+ await getDevtoolsComments(args).handler(
+ {params: {}, page},
+ response,
+ context,
+ );
+
+ sinon.assert.calledOnceWithExactly(
+ page.ensureDevToolsCommentBridge,
+ devtoolsPage,
+ );
+ sinon.assert.calledOnce(response.appendResponseLine);
+ t.assert.snapshot(lines.join('\n'));
+ sinon.assert.notCalled(response.setDevToolsComments);
+ });
});
describe('resolve_devtools_comment', () => {
@@ -135,6 +157,9 @@ describe('comments tools', () => {
const lines = trackResponseLines(response);
const devtoolsPage = createMockPuppeteerPage();
page.getDevToolsPage.resolves(devtoolsPage);
+ page.ensureDevToolsCommentBridge.resolves(
+ sinon.createStubInstance(DevToolsCommentBridge),
+ );
devtoolsPage.evaluate.resolves(true);
await resolveDevtoolsComment(args).handler(
@@ -158,6 +183,9 @@ describe('comments tools', () => {
const lines = trackResponseLines(response);
const devtoolsPage = createMockPuppeteerPage();
page.getDevToolsPage.resolves(devtoolsPage);
+ page.ensureDevToolsCommentBridge.resolves(
+ sinon.createStubInstance(DevToolsCommentBridge),
+ );
devtoolsPage.evaluate.resolves(false);
await resolveDevtoolsComment(args).handler(
@@ -169,6 +197,28 @@ describe('comments tools', () => {
sinon.assert.calledOnce(devtoolsPage.evaluate);
t.assert.snapshot(lines.join('\n'));
});
+
+ it('reports when DevTools comments are unavailable', async t => {
+ const {page, context, response, args} = createHandlerMocks();
+ const lines = trackResponseLines(response);
+ const devtoolsPage = createMockPuppeteerPage();
+ page.getDevToolsPage.resolves(devtoolsPage);
+ page.ensureDevToolsCommentBridge.resolves(undefined);
+
+ await resolveDevtoolsComment(args).handler(
+ {params: {threadId: 'comment-1'}, page},
+ response,
+ context,
+ );
+
+ sinon.assert.calledOnceWithExactly(
+ page.ensureDevToolsCommentBridge,
+ devtoolsPage,
+ );
+ sinon.assert.calledOnce(response.appendResponseLine);
+ t.assert.snapshot(lines.join('\n'));
+ sinon.assert.notCalled(devtoolsPage.evaluate);
+ });
});
describe('reveal_in_devtools', () => {
@@ -192,6 +242,9 @@ describe('comments tools', () => {
const lines = trackResponseLines(response);
const devtoolsPage = createMockPuppeteerPage();
page.getDevToolsPage.resolves(devtoolsPage);
+ page.ensureDevToolsCommentBridge.resolves(
+ sinon.createStubInstance(DevToolsCommentBridge),
+ );
page.resolveUidToBackendNodeId.resolves({
backendNodeId: 101,
targetId: 'target-1',
@@ -223,6 +276,9 @@ describe('comments tools', () => {
const lines = trackResponseLines(response);
const devtoolsPage = createMockPuppeteerPage();
page.getDevToolsPage.resolves(devtoolsPage);
+ page.ensureDevToolsCommentBridge.resolves(
+ sinon.createStubInstance(DevToolsCommentBridge),
+ );
page.resolveReqidToCdpRequestId.returns('cdp-req-123');
devtoolsPage.evaluate.resolves(undefined);
@@ -248,6 +304,9 @@ describe('comments tools', () => {
const lines = trackResponseLines(response);
const devtoolsPage = createMockPuppeteerPage();
page.getDevToolsPage.resolves(devtoolsPage);
+ page.ensureDevToolsCommentBridge.resolves(
+ sinon.createStubInstance(DevToolsCommentBridge),
+ );
page.resolveUidToBackendNodeId.resolves(undefined);
page.resolveReqidToCdpRequestId.returns(undefined);
devtoolsPage.evaluate.resolves(undefined);
@@ -272,6 +331,9 @@ describe('comments tools', () => {
const {page, context, response, args} = createHandlerMocks();
const devtoolsPage = createMockPuppeteerPage();
page.getDevToolsPage.resolves(devtoolsPage);
+ page.ensureDevToolsCommentBridge.resolves(
+ sinon.createStubInstance(DevToolsCommentBridge),
+ );
page.resolveUidToBackendNodeId.resolves({
backendNodeId: 101,
targetId: 'target-1',
@@ -299,6 +361,29 @@ describe('comments tools', () => {
'Revealed target (revealing element uid-header [backend node 101]) in DevTools.',
);
});
+
+ it('reports when DevTools comments are unavailable', async t => {
+ const {page, context, response, args} = createHandlerMocks();
+ const lines = trackResponseLines(response);
+ const devtoolsPage = createMockPuppeteerPage();
+ page.getDevToolsPage.resolves(devtoolsPage);
+ page.ensureDevToolsCommentBridge.resolves(undefined);
+
+ await revealInDevtools(args).handler(
+ {params: {panelName: 'elements', uid: 'uid-header'}, page},
+ response,
+ context,
+ );
+
+ sinon.assert.calledOnceWithExactly(
+ page.ensureDevToolsCommentBridge,
+ devtoolsPage,
+ );
+ sinon.assert.calledOnce(response.appendResponseLine);
+ t.assert.snapshot(lines.join('\n'));
+ sinon.assert.notCalled(page.resolveUidToBackendNodeId);
+ sinon.assert.notCalled(devtoolsPage.evaluate);
+ });
});
describe('open_devtools', () => {