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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.snapshotindex 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 wiDevTools 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 iFailed 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 windoDevTools 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.tsindex 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', () => {