Skip to content

Chrome DevTools for coding agents

feat(wait_for): support opt-in visible text matching (#3212)

Robert McConnelleef92da078c3
diff --git a/docs/tool-reference.md b/docs/tool-reference.md
index aedca776..55891167 100644
--- a/docs/tool-reference.md
+++ b/docs/tool-reference.md
@@ -263,13 +263,14 @@
### `wait_for`
-**Description:** Wait for the specified text to appear on the selected page.
+**Description:** Wait for the specified text to appear on the selected page. By default, hidden text is also matched. Set visible to true to wait until the matched text is visible.
**Parameters:**
- **pageId** (number) **(required)**: Targets a specific page by ID.
- **text** (array) **(required)**: Non-empty list of texts. Resolves when any value appears on the page.
- **timeout** (integer) _(optional)_: Maximum wait time in milliseconds. If set to 0, the default timeout will be used.
+- **visible** (boolean) _(optional)_: If true, wait until the matching text is visible. By default, hidden text also counts.
---
diff --git a/src/McpPage.ts b/src/McpPage.ts
index c731f081..eea0e4fd 100644
--- a/src/McpPage.ts
+++ b/src/McpPage.ts
@@ -1353,15 +1353,24 @@ export class McpPage implements ContextPage {
);
}
- waitForTextOnPage(text: string[], timeout?: number): Promise<Element> {
+ waitForTextOnPage(
+ text: string[],
+ options: {timeout?: number; visible?: boolean} = {},
+ ): Promise<Element> {
+ const {timeout, visible} = options;
const frames = this.pptrPage.frames();
let locator = this.#locatorClass.race(
frames.flatMap(frame =>
- text.flatMap(value => [
- frame.locator(`aria/${value}`),
- frame.locator(`text/${value}`),
- ]),
+ text.flatMap(value => {
+ const locators = [
+ frame.locator(`aria/${value}`),
+ frame.locator(`text/${value}`),
+ ];
+ return visible
+ ? locators.map(locator => locator.setVisibility('visible'))
+ : locators;
+ }),
),
);
diff --git a/src/telemetry/tool_call_metrics.json b/src/telemetry/tool_call_metrics.json
index 45b5fd1a..70829f85 100644
--- a/src/telemetry/tool_call_metrics.json
+++ b/src/telemetry/tool_call_metrics.json
@@ -708,6 +708,10 @@
{
"name": "page_id",
"argType": "number"
+ },
+ {
+ "name": "visible",
+ "argType": "boolean"
}
]
},
diff --git a/src/tools/ToolDefinition.ts b/src/tools/ToolDefinition.ts
index 97feefe3..78dbf180 100644
--- a/src/tools/ToolDefinition.ts
+++ b/src/tools/ToolDefinition.ts
@@ -532,7 +532,10 @@ export type ContextPage = Readonly<{
prefersReducedMotion?: PrefersReducedMotion | 'auto';
viewport?: Viewport;
}): Promise<void>;
- waitForTextOnPage(text: string[], timeout?: number): Promise<Element>;
+ waitForTextOnPage(
+ text: string[],
+ options?: {timeout?: number; visible?: boolean},
+ ): Promise<Element>;
getDevToolsPage(): Promise<Page | undefined>;
openDevTools(): Promise<Page | undefined>;
ensureDevToolsCommentBridge(
diff --git a/src/tools/snapshot.ts b/src/tools/snapshot.ts
index 25855d96..c9419238 100644
--- a/src/tools/snapshot.ts
+++ b/src/tools/snapshot.ts
@@ -48,7 +48,7 @@ in the DevTools Elements panel (if any).`,
export const waitFor = definePageTool(() => ({
name: 'wait_for',
- description: `Wait for the specified text to appear on the selected page.`,
+ description: `Wait for the specified text to appear on the selected page. By default, hidden text is also matched. Set visible to true to wait until the matched text is visible.`,
annotations: {
category: ToolCategory.NAVIGATION,
readOnlyHint: true,
@@ -61,13 +61,23 @@ export const waitFor = definePageTool(() => ({
'Non-empty list of texts. Resolves when any value appears on the page.',
),
...timeoutSchema,
+ visible: zod
+ .boolean()
+ .default(false)
+ .optional()
+ .describe(
+ 'If true, wait until the matching text is visible. By default, hidden text also counts.',
+ ),
},
blockedByDialog: true,
concurrency: 'page',
verifyFilesSchema: {},
handler: async (request, response) => {
const page = request.page;
- await page.waitForTextOnPage(request.params.text, request.params.timeout);
+ await page.waitForTextOnPage(request.params.text, {
+ timeout: request.params.timeout,
+ visible: request.params.visible,
+ });
response.appendResponseLine(
`Element matching one of ${JSON.stringify(request.params.text)} found.`,
diff --git a/tests/McpPage.test.ts b/tests/McpPage.test.ts
index 0a0a15d0..b546077c 100644
--- a/tests/McpPage.test.ts
+++ b/tests/McpPage.test.ts
@@ -1154,6 +1154,72 @@ describe('McpPage', () => {
assert.ok(element);
});
});
+
+ it('preserves default matching for hidden DOM text', async () => {
+ await withMcpContext(async (_response, context) => {
+ const mcpPage = context.getSelectedMcpPage();
+ await mcpPage.pptrPage.setContent(
+ '<p style="display:none">Saved successfully</p>',
+ );
+
+ const element = await mcpPage.waitForTextOnPage(
+ ['Saved successfully'],
+ {timeout: 500},
+ );
+ assert.ok(element);
+ });
+ });
+
+ it('waits for hidden text to become visible when requested', async () => {
+ await withMcpContext(async (_response, context) => {
+ const mcpPage = context.getSelectedMcpPage();
+ const page = mcpPage.pptrPage;
+ await page.setContent(
+ '<p id="saved" style="display:none">Saved successfully</p>',
+ );
+
+ await page.evaluate(() => {
+ setTimeout(() => {
+ document.getElementById('saved')!.style.display = 'block';
+ }, 250);
+ });
+ const element = await mcpPage.waitForTextOnPage(
+ ['Saved successfully'],
+ {timeout: 1500, visible: true},
+ );
+ assert.ok(element);
+ });
+ });
+
+ it('times out when visible text never appears', async () => {
+ await withMcpContext(async (_response, context) => {
+ const mcpPage = context.getSelectedMcpPage();
+ await mcpPage.pptrPage.setContent(
+ '<p style="display:none">Saved successfully</p>',
+ );
+
+ await assert.rejects(
+ mcpPage.waitForTextOnPage(['Saved successfully'], {
+ timeout: 300,
+ visible: true,
+ }),
+ /Timed out/,
+ );
+ });
+ });
+
+ it('visible text remains immediately matchable when requested', async () => {
+ await withMcpContext(async (_response, context) => {
+ const mcpPage = context.getSelectedMcpPage();
+ await mcpPage.pptrPage.setContent('<p>Visible from the start</p>');
+ assert.ok(
+ await mcpPage.waitForTextOnPage(['Visible from the start'], {
+ timeout: 500,
+ visible: true,
+ }),
+ );
+ });
+ });
});
describe('DevToolsCommentBridge lifecycle', () => {
diff --git a/tests/tools/snapshot.test.ts b/tests/tools/snapshot.test.ts
index 720ba927..05597648 100644
--- a/tests/tools/snapshot.test.ts
+++ b/tests/tools/snapshot.test.ts
@@ -44,11 +44,10 @@ describe('snapshot', () => {
response,
context,
);
- sinon.assert.calledOnceWithExactly(
- page.waitForTextOnPage,
- ['Hello'],
- undefined,
- );
+ sinon.assert.calledOnceWithExactly(page.waitForTextOnPage, ['Hello'], {
+ timeout: undefined,
+ visible: undefined,
+ });
sinon.assert.calledOnceWithExactly(
response.appendResponseLine,
'Element matching one of ["Hello"] found.',
@@ -66,7 +65,7 @@ describe('snapshot', () => {
sinon.assert.calledOnceWithExactly(
page.waitForTextOnPage,
['Complete', 'Error'],
- 5000,
+ {timeout: 5000, visible: undefined},
);
sinon.assert.calledOnceWithExactly(
response.appendResponseLine,
@@ -74,5 +73,18 @@ describe('snapshot', () => {
);
sinon.assert.calledOnceWithExactly(response.includeSnapshot);
});
+
+ it('forwards visible:true to the page matcher', async () => {
+ const {page, context, response, args} = createHandlerMocks();
+ await waitFor(args).handler(
+ {params: {text: ['Saved'], timeout: 2000, visible: true}, page},
+ response,
+ context,
+ );
+ sinon.assert.calledOnceWithExactly(page.waitForTextOnPage, ['Saved'], {
+ timeout: 2000,
+ visible: true,
+ });
+ });
});
});