Skip to content

Chrome DevTools for coding agents

feat: add background parameter to new_page tool (#837)

adam jonesd7568881ba4a
diff --git a/docs/tool-reference.md b/docs/tool-reference.md
index a8605b83..93858193 100644
--- a/docs/tool-reference.md
+++ b/docs/tool-reference.md
@@ -170,6 +170,7 @@
**Parameters:**
- **url** (string) **(required)**: URL to load in a new page.
+- **background** (boolean) _(optional)_: Whether to open the page in the background without bringing it to the front. Default is false (foreground).
- **timeout** (integer) _(optional)_: Maximum wait time in milliseconds. If set to 0, the default timeout will be used.
---
diff --git a/src/McpContext.ts b/src/McpContext.ts
index 7335a130..a3bcddbb 100644
--- a/src/McpContext.ts
+++ b/src/McpContext.ts
@@ -265,8 +265,8 @@ export class McpContext implements Context {
return this.#consoleCollector.getById(this.getSelectedPage(), id);
}
- async newPage(): Promise<Page> {
- const page = await this.browser.newPage();
+ async newPage(background?: boolean): Promise<Page> {
+ const page = await this.browser.newPage({background});
await this.createPagesSnapshot();
this.selectPage(page);
this.#networkCollector.addPage(page);
diff --git a/src/tools/ToolDefinition.ts b/src/tools/ToolDefinition.ts
index 11b01a44..ae68cfba 100644
--- a/src/tools/ToolDefinition.ts
+++ b/src/tools/ToolDefinition.ts
@@ -110,7 +110,7 @@ export type Context = Readonly<{
getPageById(pageId: number): Page;
getPageId(page: Page): number | undefined;
isPageSelected(page: Page): boolean;
- newPage(): Promise<Page>;
+ newPage(background?: boolean): Promise<Page>;
closePage(pageId: number): Promise<void>;
selectPage(page: Page): void;
getElementByUid(uid: string): Promise<ElementHandle<Element>>;
diff --git a/src/tools/pages.ts b/src/tools/pages.ts
index 7ad9426e..106de86e 100644
--- a/src/tools/pages.ts
+++ b/src/tools/pages.ts
@@ -87,10 +87,16 @@ export const newPage = defineTool({
},
schema: {
url: zod.string().describe('URL to load in a new page.'),
+ background: zod
+ .boolean()
+ .optional()
+ .describe(
+ 'Whether to open the page in the background without bringing it to the front. Default is false (foreground).',
+ ),
...timeoutSchema,
},
handler: async (request, response, context) => {
- const page = await context.newPage();
+ const page = await context.newPage(request.params.background);
await context.waitForEventsAfterAction(async () => {
await page.goto(request.params.url, {
diff --git a/tests/tools/pages.test.ts b/tests/tools/pages.test.ts
index d20a7a6c..da0fd13f 100644
--- a/tests/tools/pages.test.ts
+++ b/tests/tools/pages.test.ts
@@ -43,6 +43,30 @@ describe('pages', () => {
assert.ok(response.includePages);
});
});
+ it('create a page in the background', async () => {
+ await withMcpContext(async (response, context) => {
+ const originalPage = context.getPageById(1);
+ assert.strictEqual(originalPage, context.getSelectedPage());
+ // Ensure original page has focus
+ await originalPage.bringToFront();
+ assert.strictEqual(
+ await originalPage.evaluate(() => document.hasFocus()),
+ true,
+ );
+ await newPage.handler(
+ {params: {url: 'about:blank', background: true}},
+ response,
+ context,
+ );
+ // New page should be selected but original should retain focus
+ assert.strictEqual(context.getPageById(2), context.getSelectedPage());
+ assert.strictEqual(
+ await originalPage.evaluate(() => document.hasFocus()),
+ true,
+ );
+ assert.ok(response.includePages);
+ });
+ });
});
describe('close_page', () => {
it('closes a page', async () => {