Skip to content

Chrome DevTools for coding agents

refactor: lazily initialize McpPage from Target and enumerate targets in McpContext (#2812)

Alex Rudenko545cbe3c0183
diff --git a/src/McpContext.ts b/src/McpContext.ts
index f42a2841..3972671e 100644
--- a/src/McpContext.ts
+++ b/src/McpContext.ts
@@ -95,7 +95,7 @@ export class McpContext implements Context {
#extensionServiceWorkers: ExtensionServiceWorker[] = [];
- #mcpPages = new Map<Page, McpPage>();
+ #mcpPages = new Map<Target, McpPage>();
#selectedPage?: McpPage;
#selectedPageFallback?: {wasClosed: boolean};
@@ -106,7 +106,6 @@ export class McpContext implements Context {
null;
#reconnectNotice = false;
- #extensionPages = new WeakMap<Target, Page>();
#extensionServiceWorkerMap = new WeakMap<Target, string>();
#nextExtensionServiceWorkerId = 1;
@@ -161,6 +160,7 @@ export class McpContext implements Context {
for (const mcpPage of this.#mcpPages.values()) {
mcpPage.dispose();
}
+ this.#selectedPage?.dispose();
this.#mcpPages.clear();
// Isolated contexts are intentionally not closed here.
// Either the entire browser will be closed or we disconnect
@@ -168,21 +168,12 @@ export class McpContext implements Context {
this.#isolatedContexts.clear();
}
- #onTargetCreated = async (target: Target) => {
+ #onTargetCreated = (target: Target) => {
try {
- const url = target.url();
- if (
- !isAllowedUrl(url, {
- categoryExtensions: this.#options.categoryExtensions,
- })
- ) {
+ if (!this.#isPageTarget(target)) {
return;
}
- const page = await target.page();
- if (!page) {
- return;
- }
- void this.#createMcpPage(page);
+ this.#createMcpPage(target);
} catch (err) {
this.logger?.('Error handling targetcreated', err);
}
@@ -190,20 +181,10 @@ export class McpContext implements Context {
#onTargetDestroyed = (target: Target) => {
try {
- let foundPage: Page | undefined;
- for (const page of this.#mcpPages.keys()) {
- if (page.target() === target) {
- foundPage = page;
- break;
- }
- }
- if (!foundPage) {
- return;
- }
- const mcpPage = this.#mcpPages.get(foundPage);
+ const mcpPage = this.#mcpPages.get(target);
if (mcpPage) {
mcpPage.dispose();
- this.#mcpPages.delete(foundPage);
+ this.#mcpPages.delete(target);
}
} catch (err) {
this.logger?.('Error handling targetdestroyed', err);
@@ -351,9 +332,10 @@ export class McpContext implements Context {
} else {
page = await this.browser.newPage({background});
}
- const mcpPage = await this.#createMcpPage(page);
- await this.createPagesSnapshot();
+ const mcpPage = this.#createMcpPage(page.target());
+ await mcpPage.init();
this.selectPage(mcpPage);
+ await this.createPagesSnapshot();
return mcpPage;
}
async closePage(pageId: number): Promise<void> {
@@ -361,11 +343,8 @@ export class McpContext implements Context {
throw new Error(CLOSE_PAGE_ERROR);
}
const page = this.getPageById(pageId);
- if (page) {
- page.dispose();
- this.#mcpPages.delete(page.pptrPage);
- }
- await page.pptrPage.close({runBeforeUnload: false});
+ this.#mcpPages.delete(page.target);
+ await page.close();
}
get #hasNetworkBlockOrAllowlist(): boolean {
@@ -419,7 +398,7 @@ export class McpContext implements Context {
if (!page) {
throw new Error('No page selected');
}
- if (page.pptrPage.isClosed()) {
+ if (page.isClosed()) {
throw new Error(
'The selected page has been closed. Call list_pages to see open pages.',
);
@@ -436,8 +415,8 @@ export class McpContext implements Context {
return undefined;
}
}
- if (targetPage?.pptrPage?.isClosed() === false) {
- return targetPage.pptrPage.url();
+ if (targetPage && !targetPage.isClosed()) {
+ return targetPage.url();
}
return undefined;
}
@@ -485,6 +464,13 @@ export class McpContext implements Context {
}
selectPage(newPage: McpPage): void {
+ if (
+ this.#selectedPage &&
+ this.#selectedPage !== newPage &&
+ !this.#mcpPages.has(this.#selectedPage.target)
+ ) {
+ this.#selectedPage.dispose();
+ }
this.#selectedPage = newPage;
newPage.updateTimeouts();
}
@@ -560,36 +546,41 @@ export class McpContext implements Context {
return contextToName;
}
- async #createMcpPage(page: Page): Promise<McpPage> {
- let mcpPage = this.#mcpPages.get(page);
+ #createMcpPage(target: Target): McpPage {
+ let mcpPage =
+ this.#mcpPages.get(target) ??
+ (this.#selectedPage?.target === target ? this.#selectedPage : undefined);
if (!mcpPage) {
- mcpPage = new McpPage(page, nextPageId++, {
+ mcpPage = new McpPage(target, nextPageId++, {
locatorClass: this.#locatorClass,
hasNetworkBlockOrAllowlist: this.#hasNetworkBlockOrAllowlist,
isolatedContextName: this.#getBrowserContextToNameMap().get(
- page.browserContext(),
+ target.browserContext(),
),
navigationTimeout: this.#options.navigationTimeout,
sourceMaps: this.#options.sourceMaps,
onNotification: this.#options.onNotification,
});
- this.#mcpPages.set(page, mcpPage);
- await mcpPage.init();
}
+ this.#mcpPages.set(target, mcpPage);
return mcpPage;
}
- async createPagesSnapshot(): Promise<Page[]> {
- const allPages = await this.#fetchBrowserPages();
+ async createPagesSnapshot(): Promise<McpPage[]> {
+ const allTargets = this.#fetchPageTargets();
- await Promise.allSettled(allPages.map(page => this.#createMcpPage(page)));
+ for (const target of allTargets) {
+ this.#createMcpPage(target);
+ }
- // Prune orphaned #mcpPages entries (pages that no longer exist).
- const currentPages = new Set(allPages);
- for (const [page, mcpPage] of this.#mcpPages) {
- if (!currentPages.has(page)) {
- mcpPage.dispose();
- this.#mcpPages.delete(page);
+ // Prune orphaned #mcpPages entries (targets that no longer exist).
+ const currentTargets = new Set(allTargets);
+ for (const [target, mcpPage] of this.#mcpPages) {
+ if (!currentTargets.has(target)) {
+ if (mcpPage !== this.#selectedPage || mcpPage.isClosed()) {
+ mcpPage.dispose();
+ }
+ this.#mcpPages.delete(target);
}
}
@@ -599,70 +590,62 @@ export class McpContext implements Context {
// `isClosed()` instead of `pages` membership avoids silently swapping a
// live page that is momentarily missing from the snapshot.
this.#selectedPageFallback = undefined;
- if (
- (!this.#selectedPage || this.#selectedPage.pptrPage.isClosed()) &&
- pages[0]
- ) {
+ if ((!this.#selectedPage || this.#selectedPage.isClosed()) && pages[0]) {
// Record the automatic change so the response can surface it. Skipped on
// first connect, when there was no prior selection to replace.
if (this.#selectedPage) {
this.#selectedPageFallback = {
- wasClosed: this.#selectedPage.pptrPage.isClosed(),
+ wasClosed: this.#selectedPage.isClosed(),
};
}
this.selectPage(pages[0]);
}
- return pages.map(p => p.pptrPage);
+ if (this.#selectedPage && !this.#selectedPage.isClosed()) {
+ await this.#selectedPage.init();
+ }
+
+ return pages;
}
- async #fetchBrowserPages(): Promise<Page[]> {
- const allPages = (
- await this.browser.pages(this.#options.experimentalIncludeAllPages)
- ).filter(page => {
- if (
- !this.#options.experimentalDevToolsDebugging &&
- page.url().startsWith('devtools://')
- ) {
- return false;
- }
- return isAllowedUrl(page.url(), {
+ #isPageTarget(target: Target): boolean {
+ const existingMcpPage = this.#mcpPages.get(target);
+ const url = existingMcpPage ? existingMcpPage.url() : target.url();
+ if (
+ !this.#options.experimentalDevToolsDebugging &&
+ url.startsWith('devtools://')
+ ) {
+ return false;
+ }
+ if (
+ !isAllowedUrl(url, {
categoryExtensions: this.#options.categoryExtensions,
- });
- });
-
- if (this.#options.categoryExtensions) {
- const allTargets = this.browser.targets();
- const extensionTargets = allTargets.filter(target => {
- return (
- target.url().startsWith('chrome-extension://') &&
- target.type() === 'page'
- );
- });
-
- await Promise.allSettled(
- extensionTargets.map(async target => {
- try {
- let page = await target.page();
- if (!page) {
- page = await target.asPage();
- }
- this.#extensionPages.set(target, page);
- if (
- page &&
- isAllowedUrl(page.url(), {categoryExtensions: true}) &&
- !allPages.includes(page)
- ) {
- allPages.push(page);
- }
- } catch (e) {
- this.logger?.('Failed to get page for extension target', e);
- }
- }),
- );
+ })
+ ) {
+ return false;
+ }
+ const type = target.type();
+ if (type === 'page') {
+ return true;
+ }
+ if (
+ this.#options.experimentalIncludeAllPages &&
+ (type === 'background_page' || type === 'webview')
+ ) {
+ return true;
}
+ if (
+ this.#options.experimentalDevToolsDebugging &&
+ type === 'other' &&
+ url.startsWith('devtools://')
+ ) {
+ return true;
+ }
+ return false;
+ }
- return allPages;
+ #fetchPageTargets(): Target[] {
+ return this.browser.targets().filter(target => this.#isPageTarget(target));
}
getExtensionServiceWorkers(): ExtensionServiceWorker[] {
diff --git a/src/McpPage.ts b/src/McpPage.ts
index 8a5550ab..21a7dafb 100644
--- a/src/McpPage.ts
+++ b/src/McpPage.ts
@@ -76,6 +76,7 @@ import {
type WebMCPTool,
type Protocol,
type Page,
+ type Target,
type ConsoleMessage,
type HTTPRequest,
DevTools,
@@ -115,12 +116,17 @@ function isBackendNodeId(
*
* Internal class consumed only by McpContext. Fields are public for direct
* read/write access. The dialog field is private because it requires an
- * event listener lifecycle managed by the constructor/dispose pair.
+ * event listener lifecycle managed by the init/dispose pair.
*/
export class McpPage implements ContextPage {
- readonly pptrPage: Page;
+ readonly target: Target;
readonly id: number;
+ #pptrPage?: Page;
+ #initPromise?: Promise<void>;
+ #disposed = false;
+ #closed = false;
+
// Snapshot
textSnapshot: TextSnapshot | null = null;
uniqueBackendNodeIdToMcpId = new Map<string, string>();
@@ -139,8 +145,8 @@ export class McpPage implements ContextPage {
thirdPartyDeveloperTools: ToolGroups = [];
- networkCollector: NetworkCollector;
- consoleCollector: ConsoleCollector;
+ #networkCollector?: NetworkCollector;
+ #consoleCollector?: ConsoleCollector;
#hasNetworkBlockOrAllowlist: boolean;
#locatorClass: typeof Locator;
@@ -150,7 +156,7 @@ export class McpPage implements ContextPage {
#onNotification?: (message: string) => void;
constructor(
- page: Page,
+ target: Target,
id: number,
options: {
hasNetworkBlockOrAllowlist: boolean;
@@ -166,35 +172,146 @@ export class McpPage implements ContextPage {
this.#navigationTimeout = options.navigationTimeout ?? NAVIGATION_TIMEOUT;
this.#sourceMaps = options.sourceMaps ?? true;
this.#onNotification = options.onNotification;
- this.pptrPage = page;
+ this.target = target;
this.id = id;
this.isolatedContextName = options.isolatedContextName;
this.#dialogHandler = (dialog: Dialog): void => {
this.#dialog = dialog;
};
- page.on('dialog', this.#dialogHandler);
+ }
- this.networkCollector = new NetworkCollector(page);
- this.consoleCollector = new ConsoleCollector(page, collect => {
- return {
- console: event => {
- collect(event);
- },
- uncaughtError: event => {
- collect(event);
- },
- devtoolsAggregatedIssue: event => {
- collect(event);
- },
- } as ListenerMap;
- });
+ get pptrPage(): Page {
+ if (!this.#pptrPage) {
+ throw new Error(
+ `McpPage (id=${this.id}) is not initialized. Call init() first.`,
+ );
+ }
+ return this.#pptrPage;
+ }
+
+ get networkCollector(): NetworkCollector {
+ if (!this.#networkCollector) {
+ throw new Error(
+ `McpPage (id=${this.id}) is not initialized. Call init() first.`,
+ );
+ }
+ return this.#networkCollector;
+ }
+
+ set networkCollector(collector: NetworkCollector) {
+ this.#networkCollector = collector;
+ }
+
+ get consoleCollector(): ConsoleCollector {
+ if (!this.#consoleCollector) {
+ throw new Error(
+ `McpPage (id=${this.id}) is not initialized. Call init() first.`,
+ );
+ }
+ return this.#consoleCollector;
+ }
+
+ url(): string {
+ return this.#pptrPage ? this.#pptrPage.url() : this.target.url();
+ }
+
+ async getTitle(): Promise<string> {
+ if (this.#pptrPage) {
+ return Promise.race([
+ this.#pptrPage.title().catch(() => ''),
+ new Promise<string>(resolve => setTimeout(() => resolve(''), 1000)),
+ ]);
+ }
+ if (
+ '_getTargetInfo' in this.target &&
+ typeof this.target._getTargetInfo === 'function'
+ ) {
+ const info = this.target._getTargetInfo();
+ if (
+ info &&
+ typeof info === 'object' &&
+ 'title' in info &&
+ typeof info.title === 'string' &&
+ info.title !== this.target.url()
+ ) {
+ return info.title;
+ }
+ }
+ return '';
+ }
+
+ isClosed(): boolean {
+ if (this.#closed) {
+ return true;
+ }
+ if (this.#pptrPage) {
+ return this.#pptrPage.isClosed();
+ }
+ return this.#disposed;
+ }
+
+ async close(): Promise<void> {
+ this.#closed = true;
+ const page =
+ this.#pptrPage ??
+ (await this.target.page()) ??
+ (await this.target.asPage());
+ this.dispose();
+ await page?.close({runBeforeUnload: false});
}
async init(): Promise<void> {
+ if (this.#disposed) {
+ throw new Error(`McpPage (id=${this.id}) has already been disposed.`);
+ }
+ if (this.#initPromise) {
+ return this.#initPromise;
+ }
+ this.#initPromise = this.#doInit();
+ try {
+ await this.#initPromise;
+ } catch (err) {
+ this.#initPromise = undefined;
+ throw err;
+ }
+ }
+
+ async #doInit(): Promise<void> {
+ if (!this.#pptrPage) {
+ const page = (await this.target.page()) ?? (await this.target.asPage());
+ if (!page) {
+ throw new Error(
+ `Failed to initialize Puppeteer Page for target ${this.target.url()}`,
+ );
+ }
+ if (this.#disposed) {
+ return;
+ }
+ this.#pptrPage = page;
+ page.on('dialog', this.#dialogHandler);
+ this.#networkCollector = new NetworkCollector(page);
+ this.#consoleCollector = new ConsoleCollector(page, collect => {
+ return {
+ console: event => {
+ collect(event);
+ },
+ uncaughtError: event => {
+ collect(event);
+ },
+ devtoolsAggregatedIssue: event => {
+ collect(event);
+ },
+ };
+ });
+ }
+ this.updateTimeouts();
await Promise.allSettled([
this.#initDevToolsUniverseNoThrow(),
this.#initFocusEmulationNoThrow(),
]);
+ if (this.#disposed) {
+ this.dispose();
+ }
}
async #initFocusEmulationNoThrow(): Promise<void> {
@@ -478,11 +595,12 @@ export class McpPage implements ContextPage {
}
dispose(): void {
+ this.#disposed = true;
this.#commentBridge?.dispose();
this.#commentBridge = undefined;
- this.pptrPage.off('dialog', this.#dialogHandler);
- this.networkCollector.dispose();
- this.consoleCollector.dispose();
+ this.#pptrPage?.off('dialog', this.#dialogHandler);
+ this.#networkCollector?.dispose();
+ this.#consoleCollector?.dispose();
const devtoolsUniverse = this.#devtoolsUniverse;
this.#devtoolsUniverse = undefined;
devtoolsUniverse?.universe.dispose();
@@ -737,7 +855,7 @@ export class McpPage implements ContextPage {
async resolveUidToBackendNodeId(
uid: string,
): Promise<{backendNodeId: number; targetId?: string} | undefined> {
- const target = this.pptrPage.target();
+ const target = this.target;
const targetId =
Boolean(target) &&
'_targetId' in target &&
@@ -978,17 +1096,20 @@ export class McpPage implements ContextPage {
}
updateTimeouts() {
+ if (!this.#pptrPage) {
+ return;
+ }
// For waiters 5sec timeout should be sufficient.
// Increased in case we throttle the CPU
const cpuMultiplier = this.cpuThrottlingRate;
- this.pptrPage.setDefaultTimeout(DEFAULT_TIMEOUT * cpuMultiplier);
+ this.#pptrPage.setDefaultTimeout(DEFAULT_TIMEOUT * cpuMultiplier);
// 10sec should be enough for the load event to be emitted during
// navigations.
// Increased in case we throttle the network requests or the CPU
const networkMultiplier = getNetworkMultiplierFromString(
this.networkConditions,
);
- this.pptrPage.setDefaultNavigationTimeout(
+ this.#pptrPage.setDefaultNavigationTimeout(
this.#navigationTimeout * networkMultiplier * cpuMultiplier,
);
}
diff --git a/src/McpResponse.ts b/src/McpResponse.ts
index 0e4e7f2f..f6e29db9 100644
--- a/src/McpResponse.ts
+++ b/src/McpResponse.ts
@@ -43,7 +43,6 @@ import {DevTools, getToonEncode, getGcfEncode} from './third_party/index.js';
import type {
ConsoleMessage,
ImageContent,
- Page,
ResourceType,
TextContent,
Extension,
@@ -1000,7 +999,7 @@ Call ${handleDialog(this.#args).name} to handle it before continuing.`);
acc: {regularPages: McpPage[]; extensionPages: McpPage[]},
mcpPage: McpPage,
) => {
- if (mcpPage.pptrPage.url().startsWith('chrome-extension://')) {
+ if (mcpPage.url().startsWith('chrome-extension://')) {
acc.extensionPages.push(mcpPage);
} else {
acc.regularPages.push(mcpPage);
@@ -1030,10 +1029,10 @@ Call ${handleDialog(this.#args).name} to handle it before continuing.`);
const contextLabel = isolatedContextName
? ` isolatedContext=${isolatedContextName}`
: '';
- const title = await fetchPageTitle(mcpPage.pptrPage);
+ const title = await mcpPage.getTitle();
const pageLabel = title
- ? `${truncateTitle(title)} (${mcpPage.pptrPage.url()})`
- : mcpPage.pptrPage.url();
+ ? `${truncateTitle(title)} (${mcpPage.url()})`
+ : mcpPage.url();
parts.push(
`${mcpPage.id}: ${pageLabel}${context.isPageSelected(mcpPage) ? ' [selected]' : ''}${contextLabel}`,
);
@@ -1052,10 +1051,10 @@ Call ${handleDialog(this.#args).name} to handle it before continuing.`);
const contextLabel = isolatedContextName
? ` isolatedContext=${isolatedContextName}`
: '';
- const title = await fetchPageTitle(mcpPage.pptrPage);
+ const title = await mcpPage.getTitle();
const pageLabel = title
- ? `${truncateTitle(title)} (${mcpPage.pptrPage.url()})`
- : mcpPage.pptrPage.url();
+ ? `${truncateTitle(title)} (${mcpPage.url()})`
+ : mcpPage.url();
response.push(
`${mcpPage.id}: ${pageLabel}${context.isPageSelected(mcpPage) ? ' [selected]' : ''}${contextLabel}`,
);
@@ -1623,13 +1622,6 @@ function truncateTitle(title: string, maxLength = 50): string {
return title.slice(0, maxLength - 3) + '...';
}
-async function fetchPageTitle(page: Page): Promise<string> {
- return Promise.race([
- page.title().catch(() => ''),
- new Promise<string>(resolve => setTimeout(() => resolve(''), 1000)),
- ]);
-}
-
function createStructuredPage(
mcpPage: McpPage,
context: McpContext,
@@ -1645,7 +1637,7 @@ function createStructuredPage(
isolatedContext?: string;
} = {
id: mcpPage.id,
- url: mcpPage.pptrPage.url(),
+ url: mcpPage.url(),
title,
selected: context.isPageSelected(mcpPage),
};
diff --git a/src/ToolHandler.ts b/src/ToolHandler.ts
index 19c3d1c3..61115bdc 100644
--- a/src/ToolHandler.ts
+++ b/src/ToolHandler.ts
@@ -217,6 +217,7 @@ export class ToolHandler {
!this.serverArgs.slim
? context.getPageById(pageId)
: context.getSelectedMcpPage();
+ await page?.init();
response.setPage(page);
if (this.tool.blockedByDialog) {
page.throwIfDialogOpen();
diff --git a/src/collectors/PageCollector.ts b/src/collectors/PageCollector.ts
index ee0a0d4f..a3c80c0e 100644
--- a/src/collectors/PageCollector.ts
+++ b/src/collectors/PageCollector.ts
@@ -42,7 +42,15 @@ interface PageEvents extends PuppeteerPageEvents {
}
export type ListenerMap<EventMap extends PageEvents = PageEvents> = {
- [K in keyof EventMap]?: (event: EventMap[K]) => void;
+ [
+ K in keyof EventMap as string extends K
+ ? never
+ : number extends K
+ ? never
+ : symbol extends K
+ ? never
+ : K
+ ]?: (event: EventMap[K]) => void;
};
export class PageCollector<T> {
diff --git a/src/third_party/index.ts b/src/third_party/index.ts
index 6699fb06..973b5387 100644
--- a/src/third_party/index.ts
+++ b/src/third_party/index.ts
@@ -53,6 +53,8 @@ export {
KnownDevices,
CDPSessionEvent,
ScreenRecorder,
+ Target,
+ TargetType,
TimeoutError,
} from 'puppeteer-core';
export {default as puppeteer} from 'puppeteer-core';
diff --git a/src/tools/ToolDefinition.ts b/src/tools/ToolDefinition.ts
index 1c534ee9..539a6aa6 100644
--- a/src/tools/ToolDefinition.ts
+++ b/src/tools/ToolDefinition.ts
@@ -369,6 +369,7 @@ export type ContextPage = Readonly<{
readonly pptrPage: Page;
readonly cpuThrottlingRate: number;
readonly networkConditions: string | null;
+ init(): Promise<void>;
getAXNodeByUid(uid: string): TextSnapshotNode | undefined;
getElementByUid(uid: string): Promise<ElementHandle<Element>>;
getMatchedStylesForUid(uid: string): Promise<MatchedStyles>;
diff --git a/src/tools/pages.ts b/src/tools/pages.ts
index 7ed6d125..6f1840c8 100644
--- a/src/tools/pages.ts
+++ b/src/tools/pages.ts
@@ -59,6 +59,7 @@ export const selectPage = defineTool((args: ParsedArguments) => ({
verifyFilesSchema: {},
handler: async (request, response, context) => {
const page = context.getPageById(request.params.pageId);
+ await page.init();
context.selectPage(page);
response.setIncludePages(true);
response.setListThirdPartyDeveloperTools();
diff --git a/src/tools/script.ts b/src/tools/script.ts
index bcb22ecd..50501dac 100644
--- a/src/tools/script.ts
+++ b/src/tools/script.ts
@@ -135,6 +135,7 @@ Example with arguments: \`(el) => el.innerText\`
cliArgs.pageIdRouting && request.params.pageId
? context.getPageById(request.params.pageId)
: context.getSelectedMcpPage();
+ await mcpPage.init();
const page: Page = mcpPage.pptrPage;
const args: Array<JSHandle<unknown>> = [];
diff --git a/tests/McpContext.test.ts b/tests/McpContext.test.ts
index bc377c97..b2a24d48 100644
--- a/tests/McpContext.test.ts
+++ b/tests/McpContext.test.ts
@@ -308,12 +308,12 @@ describe('McpContext', () => {
const page = await context.newPage();
assert.ok(context.isPageSelected(page));
- // A live page that is temporarily missing from the pages list must keep
+ // A live page that is temporarily missing from the targets list must keep
// its selection — only a genuinely closed page is replaced.
- const pages = await context.browser.pages();
+ const targets = context.browser.targets();
const stub = sinon
- .stub(context.browser, 'pages')
- .resolves(pages.filter(otherPage => otherPage !== page.pptrPage));
+ .stub(context.browser, 'targets')
+ .returns(targets.filter(otherTarget => otherTarget !== page.target));
try {
await context.createPagesSnapshot();
} finally {
@@ -328,6 +328,27 @@ describe('McpContext', () => {
});
});
+ it('enumerates page targets without initializing unselected pages', async () => {
+ await withMcpContext(async (_response, context) => {
+ const selectedPage = context.getSelectedMcpPage();
+ const unselectedPptrPage = await context.browser.newPage();
+ const unselectedTarget = unselectedPptrPage.target();
+
+ await context.createPagesSnapshot();
+
+ const unselectedMcpPage = context
+ .getPages()
+ .find(p => p.target === unselectedTarget);
+ assert.ok(unselectedMcpPage, 'unselected target should be discovered');
+ assert.notStrictEqual(unselectedMcpPage, selectedPage);
+ assert.throws(() => unselectedMcpPage.pptrPage, /is not initialized/);
+
+ await unselectedMcpPage.init();
+ assert.strictEqual(unselectedMcpPage.pptrPage, unselectedPptrPage);
+ await unselectedPptrPage.close();
+ });
+ });
+
it('continues page ids across contexts so stale ids do not resolve', async () => {
await withBrowser(async browser => {
const options = {
diff --git a/tests/McpPage.test.ts b/tests/McpPage.test.ts
index 6fdfd107..d1d2f6b9 100644
--- a/tests/McpPage.test.ts
+++ b/tests/McpPage.test.ts
@@ -14,10 +14,9 @@ import {McpPage} from '../src/McpPage.js';
import {replaceHtmlElementsWithUids} from '../src/McpPage.js';
import {DevTools, Locator} from '../src/third_party/index.js';
import type {JSONSchema7Definition} from '../src/third_party/index.js';
-import type {Page} from '../src/third_party/index.js';
import {TextSnapshot} from '../src/TextSnapshot.js';
import type {TextSnapshotNode} from '../src/types.js';
-import {createMockPuppeteerPage} from './mocks.js';
+import {createMockPuppeteerPage, createMockPuppeteerTarget} from './mocks.js';
import {serverHooks} from './server.js';
import {getMockRequest, html, withMcpContext} from './utils.js';
@@ -270,9 +269,13 @@ describe('replaceHtmlElementsWithUids', () => {
});
describe('McpPage', () => {
- function createMcpPage(options: {hasNetworkBlockOrAllowlist?: boolean} = {}) {
+ async function createMcpPage(
+ options: {hasNetworkBlockOrAllowlist?: boolean} = {},
+ ) {
const pptrPage = createMockPuppeteerPage();
- const mcpPage = new McpPage(pptrPage as unknown as Page, 1, {
+ pptrPage.emulateFocusedPage.resolves();
+ const target = createMockPuppeteerTarget({page: pptrPage});
+ const mcpPage = new McpPage(target, 1, {
hasNetworkBlockOrAllowlist: options.hasNetworkBlockOrAllowlist ?? false,
locatorClass: Locator,
});
@@ -282,7 +285,8 @@ describe('McpPage', () => {
sinon
.stub(mcpPage, 'devtoolsUniverse')
.get(() => ({session: mockSession}) as unknown as TargetUniverse);
- return {mcpPage, pptrPage, mockSession};
+ await mcpPage.init();
+ return {mcpPage, pptrPage, target, mockSession};
}
function getUidForNode(mcpPage: McpPage, matcher: string): string {
@@ -298,13 +302,96 @@ describe('McpPage', () => {
throw new Error(`Target element "${matcher}" not found in snapshot`);
}
+ describe('lazy initialization', () => {
+ afterEach(() => {
+ sinon.restore();
+ });
+
+ it('does not initialize Puppeteer Page in constructor and throws if pptrPage is accessed before init()', async () => {
+ const pptrPage = createMockPuppeteerPage();
+ pptrPage.emulateFocusedPage.resolves();
+ const target = createMockPuppeteerTarget({
+ page: pptrPage,
+ url: 'https://target-only.example.com',
+ title: 'Target Title',
+ });
+ const mcpPage = new McpPage(target, 1, {
+ hasNetworkBlockOrAllowlist: false,
+ locatorClass: Locator,
+ });
+
+ sinon.assert.notCalled(target.page);
+ sinon.assert.notCalled(target.asPage);
+ assert.throws(() => mcpPage.pptrPage, /not initialized/);
+ assert.strictEqual(mcpPage.url(), 'https://target-only.example.com');
+ assert.strictEqual(await mcpPage.getTitle(), 'Target Title');
+
+ await mcpPage.init();
+
+ sinon.assert.calledOnce(target.page);
+ assert.strictEqual(mcpPage.pptrPage, pptrPage);
+ });
+
+ it('falls back to target.asPage() when target.page() returns null', async () => {
+ const pptrPage = createMockPuppeteerPage();
+ pptrPage.emulateFocusedPage.resolves();
+ const target = createMockPuppeteerTarget({page: pptrPage});
+ target.page.resolves(null);
+
+ const mcpPage = new McpPage(target, 1, {
+ hasNetworkBlockOrAllowlist: false,
+ locatorClass: Locator,
+ });
+
+ await mcpPage.init();
+
+ sinon.assert.calledOnce(target.page);
+ sinon.assert.calledOnce(target.asPage);
+ assert.strictEqual(mcpPage.pptrPage, pptrPage);
+ });
+
+ it('disposes safely before init() is called and rejects subsequent init()', async () => {
+ const target = createMockPuppeteerTarget();
+ const mcpPage = new McpPage(target, 1, {
+ hasNetworkBlockOrAllowlist: false,
+ locatorClass: Locator,
+ });
+
+ assert.strictEqual(mcpPage.isClosed(), false);
+ mcpPage.dispose();
+ assert.strictEqual(mcpPage.isClosed(), true);
+ await assert.rejects(
+ () => mcpPage.init(),
+ /McpPage \(id=1\) has already been disposed/,
+ );
+ sinon.assert.notCalled(target.page);
+ });
+
+ it('closes the underlying page without running init()', async () => {
+ const pptrPage = createMockPuppeteerPage();
+ const target = createMockPuppeteerTarget({page: pptrPage});
+ const mcpPage = new McpPage(target, 1, {
+ hasNetworkBlockOrAllowlist: false,
+ locatorClass: Locator,
+ });
+
+ await mcpPage.close();
+
+ assert.strictEqual(mcpPage.isClosed(), true);
+ sinon.assert.calledOnceWithExactly(pptrPage.close, {
+ runBeforeUnload: false,
+ });
+ sinon.assert.notCalled(pptrPage.emulateFocusedPage);
+ });
+ });
+
describe('emulate()', () => {
afterEach(() => {
sinon.restore();
});
it('calls emulateNetworkConditions with offline settings', async () => {
- const {mcpPage, pptrPage} = createMcpPage();
+ const {mcpPage, pptrPage} = await createMcpPage();
await mcpPage.emulate({networkConditions: 'Offline'});
assert.strictEqual(mcpPage.networkConditions, 'Offline');
sinon.assert.calledOnceWithExactly(pptrPage.emulateNetworkConditions, {
@@ -316,7 +403,7 @@ describe('McpPage', () => {
});
it('calls emulateNetworkConditions with the predefined condition', async () => {
- const {mcpPage, pptrPage} = createMcpPage();
+ const {mcpPage, pptrPage} = await createMcpPage();
await mcpPage.emulate({networkConditions: 'Slow 3G'});
assert.strictEqual(mcpPage.networkConditions, 'Slow 3G');
sinon.assert.calledOnceWithExactly(pptrPage.emulateNetworkConditions, {
@@ -327,7 +414,7 @@ describe('McpPage', () => {
});
it('calls emulateNetworkConditions(null) when networkConditions is omitted', async () => {
- const {mcpPage, pptrPage} = createMcpPage();
+ const {mcpPage, pptrPage} = await createMcpPage();
await mcpPage.emulate({networkConditions: 'Slow 3G'});
await mcpPage.emulate({});
assert.strictEqual(mcpPage.networkConditions, null);
@@ -339,14 +426,14 @@ describe('McpPage', () => {
});
it('does not call emulateNetworkConditions for unknown values', async () => {
- const {mcpPage, pptrPage} = createMcpPage();
+ const {mcpPage, pptrPage} = await createMcpPage();
await mcpPage.emulate({networkConditions: 'Slow 11G'});
assert.strictEqual(mcpPage.networkConditions, null);
sinon.assert.notCalled(pptrPage.emulateNetworkConditions);
});
it('throws when networkConditions is set with network blocking enabled', async () => {
- const {mcpPage, pptrPage} = createMcpPage({
+ const {mcpPage, pptrPage} = await createMcpPage({
hasNetworkBlockOrAllowlist: true,
});
await assert.rejects(
@@ -357,14 +444,14 @@ describe('McpPage', () => {
});
it('calls emulateCPUThrottling with the given rate', async () => {
- const {mcpPage, pptrPage} = createMcpPage();
+ const {mcpPage, pptrPage} = await createMcpPage();
await mcpPage.emulate({cpuThrottlingRate: 4});
assert.strictEqual(mcpPage.cpuThrottlingRate, 4);
sinon.assert.calledOnceWithExactly(pptrPage.emulateCPUThrottling, 4);
});
it('calls emulateCPUThrottling(1) to reset throttling', async () => {
- const {mcpPage, pptrPage} = createMcpPage();
+ const {mcpPage, pptrPage} = await createMcpPage();
await mcpPage.emulate({cpuThrottlingRate: 4});
await mcpPage.emulate({cpuThrottlingRate: 1});
assert.strictEqual(mcpPage.cpuThrottlingRate, 1);
@@ -376,7 +463,7 @@ describe('McpPage', () => {
});
it('sends Emulation.setCPUThrottlingRate to secondary session if present', async () => {
- const {mcpPage, pptrPage, mockSession} = createMcpPage();
+ const {mcpPage, pptrPage, mockSession} = await createMcpPage();
await mcpPage.emulate({cpuThrottlingRate: 4});
sinon.assert.calledOnceWithExactly(pptrPage.emulateCPUThrottling, 4);
sinon.assert.calledOnceWithExactly(
@@ -387,7 +474,7 @@ describe('McpPage', () => {
});
it('sends Emulation.setCPUThrottlingRate with rate 1 to secondary session when cpuThrottlingRate is omitted', async () => {
- const {mcpPage, pptrPage, mockSession} = createMcpPage();
+ const {mcpPage, pptrPage, mockSession} = await createMcpPage();
await mcpPage.emulate({});
sinon.assert.calledOnceWithExactly(pptrPage.emulateCPUThrottling, 1);
sinon.assert.calledOnceWithExactly(
@@ -398,7 +485,7 @@ describe('McpPage', () => {
});
it('calls setGeolocation with the given coordinates', async () => {
- const {mcpPage, pptrPage} = createMcpPage();
+ const {mcpPage, pptrPage} = await createMcpPage();
await mcpPage.emulate({
geolocation: {latitude: 48.137154, longitude: 11.576124},
});
@@ -413,7 +500,7 @@ describe('McpPage', () => {
});
it('calls setGeolocation with (0, 0) when geolocation is omitted', async () => {
- const {mcpPage, pptrPage} = createMcpPage();
+ const {mcpPage, pptrPage} = await createMcpPage();
await mcpPage.emulate({
geolocation: {latitude: 48.137154, longitude: 11.576124},
});
@@ -427,7 +514,7 @@ describe('McpPage', () => {
});
it('calls setUserAgent with the given user agent', async () => {
- const {mcpPage, pptrPage} = createMcpPage();
+ const {mcpPage, pptrPage} = await createMcpPage();
await mcpPage.emulate({userAgent: 'TestUA/1.0'});
assert.strictEqual(mcpPage.userAgent, 'TestUA/1.0');
sinon.assert.calledOnceWithExactly(pptrPage.setUserAgent, {
@@ -436,7 +523,7 @@ describe('McpPage', () => {
});
it('calls setUserAgent with undefined to clear the user agent', async () => {
- const {mcpPage, pptrPage} = createMcpPage();
+ const {mcpPage, pptrPage} = await createMcpPage();
await mcpPage.emulate({userAgent: 'TestUA/1.0'});
await mcpPage.emulate({userAgent: ''});
assert.strictEqual(mcpPage.userAgent, null);
@@ -447,7 +534,7 @@ describe('McpPage', () => {
});
it('calls emulateMediaFeatures with dark color scheme', async () => {
- const {mcpPage, pptrPage} = createMcpPage();
+ const {mcpPage, pptrPage} = await createMcpPage();
await mcpPage.emulate({colorScheme: 'dark'});
assert.strictEqual(mcpPage.colorScheme, 'dark');
sinon.assert.calledOnceWithExactly(pptrPage.emulateMediaFeatures, [
@@ -456,7 +543,7 @@ describe('McpPage', () => {
});
it('calls emulateMediaFeatures with empty string to reset color scheme', async () => {
- const {mcpPage, pptrPage} = createMcpPage();
+ const {mcpPage, pptrPage} = await createMcpPage();
await mcpPage.emulate({colorScheme: 'dark'});
await mcpPage.emulate({colorScheme: 'auto'});
assert.strictEqual(mcpPage.colorScheme, null);
@@ -467,7 +554,7 @@ describe('McpPage', () => {
});
it('calls setViewport with the given dimensions merged with defaults', async () => {
- const {mcpPage, pptrPage} = createMcpPage();
+ const {mcpPage, pptrPage} = await createMcpPage();
await mcpPage.emulate({
viewport: {
width: 400,
@@ -493,7 +580,7 @@ describe('McpPage', () => {
});
it('calls setViewport(null) when viewport is omitted', async () => {
- const {mcpPage, pptrPage} = createMcpPage();
+ const {mcpPage, pptrPage} = await createMcpPage();
await mcpPage.emulate({viewport: {width: 400, height: 400}});
await mcpPage.emulate({});
assert.strictEqual(mcpPage.viewport, null);
@@ -502,7 +589,7 @@ describe('McpPage', () => {
});
it('calls setExtraHTTPHeaders with the given headers', async () => {
- const {mcpPage, pptrPage} = createMcpPage();
+ const {mcpPage, pptrPage} = await createMcpPage();
await mcpPage.emulate({
extraHttpHeaders: {'X-Custom-Header': 'test-value'},
});
@@ -515,7 +602,7 @@ describe('McpPage', () => {
});
it('clears extraHttpHeaders when empty object is passed', async () => {
- const {mcpPage, pptrPage} = createMcpPage();
+ const {mcpPage, pptrPage} = await createMcpPage();
await mcpPage.emulate({
extraHttpHeaders: {'X-Custom-Header': 'test-value'},
});
@@ -535,7 +622,7 @@ describe('McpPage', () => {
});
it('re-applies previously configured viewport emulation', async () => {
- const {mcpPage, pptrPage} = createMcpPage();
+ const {mcpPage, pptrPage} = await createMcpPage();
await mcpPage.emulate({
viewport: {
width: 400,
@@ -562,7 +649,7 @@ describe('McpPage', () => {
});
it('re-applies previously configured network and cpu throttling emulation', async () => {
- const {mcpPage, pptrPage} = createMcpPage();
+ const {mcpPage, pptrPage} = await createMcpPage();
await mcpPage.emulate({
networkConditions: 'Slow 3G',
cpuThrottlingRate: 4,
@@ -578,8 +665,8 @@ describe('McpPage', () => {
});
describe('getNetworkRequests', () => {
- it('delegates to networkCollector.getData with includePreservedRequests', () => {
- const {mcpPage} = createMcpPage();
+ it('delegates to networkCollector.getData with includePreservedRequests', async () => {
+ const {mcpPage} = await createMcpPage();
const stub = sinon.stub(mcpPage.networkCollector, 'getData').returns([]);
mcpPage.getNetworkRequests(true);
@@ -594,8 +681,8 @@ describe('McpPage', () => {
});
describe('getNetworkRequestById', () => {
- it('delegates to networkCollector.getById', () => {
- const {mcpPage} = createMcpPage();
+ it('delegates to networkCollector.getById', async () => {
+ const {mcpPage} = await createMcpPage();
const mockRequest = getMockRequest();
const stub = sinon
.stub(mcpPage.networkCollector, 'getById')
@@ -745,7 +832,7 @@ describe('McpPage', () => {
});
it('does not create commentBridge on construction or getDevToolsPage', async () => {
- const {mcpPage, pptrPage} = createMcpPage();
+ const {mcpPage, pptrPage} = await createMcpPage();
pptrPage.hasDevTools.resolves(true);
const devtoolsPage = createMockPuppeteerPage();
pptrPage.openDevTools.resolves(devtoolsPage);
@@ -758,7 +845,7 @@ describe('McpPage', () => {
});
it('creates and attaches commentBridge when openDevTools is called', async () => {
- const {mcpPage, pptrPage} = createMcpPage();
+ const {mcpPage, pptrPage} = await createMcpPage();
const devtoolsPage = createMockPuppeteerPage();
pptrPage.openDevTools.resolves(devtoolsPage);
@@ -771,7 +858,7 @@ describe('McpPage', () => {
});
it('disposes commentBridge on mcpPage.dispose()', async () => {
- const {mcpPage, pptrPage} = createMcpPage();
+ const {mcpPage, pptrPage} = await createMcpPage();
const devtoolsPage = createMockPuppeteerPage();
pptrPage.openDevTools.resolves(devtoolsPage);
@@ -789,7 +876,7 @@ describe('McpPage', () => {
});
it('creates and attaches commentBridge when getDevToolsData is called', async () => {
- const {mcpPage, pptrPage} = createMcpPage();
+ const {mcpPage, pptrPage} = await createMcpPage();
pptrPage.hasDevTools.resolves(true);
const devtoolsPage = createMockPuppeteerPage();
devtoolsPage.evaluate.resolves({
@@ -842,7 +929,7 @@ describe('McpPage', () => {
});
it('throws when snapshot has not been captured', async () => {
- const {mcpPage} = createMcpPage();
+ const {mcpPage} = await createMcpPage();
await assert.rejects(
() => mcpPage.getMatchedStylesForUid('node_1'),
/No snapshot found for page/,
@@ -850,7 +937,7 @@ describe('McpPage', () => {
});
it('throws when element uid is not found in snapshot', async () => {
- const {mcpPage} = createMcpPage();
+ const {mcpPage} = await createMcpPage();
const rootNode: TextSnapshotNode = {
id: '1_0',
role: 'root',
@@ -871,7 +958,7 @@ describe('McpPage', () => {
});
it('throws when element has no backendNodeId', async () => {
- const {mcpPage} = createMcpPage();
+ const {mcpPage} = await createMcpPage();
const node: TextSnapshotNode = {
id: '1_1',
role: 'button',
diff --git a/tests/ToolHandler.test.ts b/tests/ToolHandler.test.ts
index 2d35baf1..a0393b49 100644
--- a/tests/ToolHandler.test.ts
+++ b/tests/ToolHandler.test.ts
@@ -74,8 +74,8 @@ describe('ToolHandler', () => {
assert.strictEqual(toolHandler.disabled, false);
await toolHandler.handle({pageId: 1});
- assert.strictEqual(mockContext.getPageById.calledOnce, true);
- assert.strictEqual(mockContext.getPageById.calledWith(1), true);
+ sinon.assert.calledOnceWithExactly(mockContext.getPageById, 1);
+ sinon.assert.calledOnceWithExactly(mockPage.init);
assert.strictEqual(handlerCalled, true);
});
@@ -119,7 +119,8 @@ describe('ToolHandler', () => {
assert.strictEqual(toolHandler.disabled, false);
await toolHandler.handle({});
- assert.strictEqual(mockContext.getSelectedMcpPage.calledOnce, true);
+ sinon.assert.calledOnceWithExactly(mockContext.getSelectedMcpPage);
+ sinon.assert.calledOnceWithExactly(mockPage.init);
assert.strictEqual(handlerCalled, true);
});
diff --git a/tests/mocks.ts b/tests/mocks.ts
index 08b97ac8..f340b879 100644
--- a/tests/mocks.ts
+++ b/tests/mocks.ts
@@ -46,9 +46,13 @@ import {
Dialog,
ElementHandle,
Locator,
+ Target,
+ TargetType,
} from '../src/third_party/index.js';
import type {
Browser,
+ BrowserContext,
+ CDPSession,
Extension,
Page,
Protocol,
@@ -58,6 +62,7 @@ import type {
export type MockMcpPage = sinon.SinonStubbedInstance<McpPage> & {
pptrPage: sinon.SinonStubbedInstance<Page>;
+ target: sinon.SinonStubbedInstance<MockTarget>;
};
export type MockMcpContext = sinon.SinonStubbedInstance<McpContext>;
export type MockMcpResponse = sinon.SinonStubbedInstance<McpResponse>;
@@ -192,16 +197,88 @@ export function createMockPuppeteerPage(): sinon.SinonStubbedInstance<Page> {
return page;
}
+export class MockTarget extends Target {
+ override asPage(): Promise<Page> {
+ throw new Error('Not implemented');
+ }
+ override url(): string {
+ return '';
+ }
+ override createCDPSession(): Promise<CDPSession> {
+ throw new Error('Not implemented');
+ }
+ override type(): TargetType {
+ return TargetType.PAGE;
+ }
+ override browser(): Browser {
+ throw new Error('Not implemented');
+ }
+ override browserContext(): BrowserContext {
+ throw new Error('Not implemented');
+ }
+ override opener(): Target | undefined {
+ return undefined;
+ }
+ _getTargetInfo(): Protocol.Target.TargetInfo {
+ throw new Error('Not implemented');
+ }
+}
+
+export function createMockPuppeteerTarget(
+ options: {
+ page?: sinon.SinonStubbedInstance<Page>;
+ url?: string;
+ title?: string;
+ } = {},
+): sinon.SinonStubbedInstance<MockTarget> {
+ const target = sinon.createStubInstance(MockTarget);
+ const page = options.page ?? createMockPuppeteerPage();
+ page.target.returns(target);
+ target.page.resolves(page);
+ target.asPage.resolves(page);
+ target.url.returns(options.url ?? 'https://example.com');
+ target._getTargetInfo.returns({
+ targetId: '<mock-target-id>',
+ type: 'page',
+ title: options.title ?? '',
+ url: options.url ?? 'https://example.com',
+ attached: true,
+ canAccessOpener: false,
+ });
+ return target;
+}
+
export function createMockMcpPage(
- options: {pptrPage?: sinon.SinonStubbedInstance<Page>} = {},
+ options: {
+ pptrPage?: sinon.SinonStubbedInstance<Page>;
+ target?: sinon.SinonStubbedInstance<MockTarget>;
+ } = {},
): MockMcpPage {
const page = sinon.createStubInstance(McpPage);
const pptrPage = options.pptrPage ?? createMockPuppeteerPage();
+ const target = options.target ?? createMockPuppeteerTarget({page: pptrPage});
+ page.init.resolves();
+ page.close.callsFake(async () => {
+ await pptrPage.close({runBeforeUnload: false});
+ });
+ page.url.callsFake(() => pptrPage.url());
+ page.getTitle.callsFake(async () => (await pptrPage.title()) ?? '');
+ page.isClosed.callsFake(() => Boolean(pptrPage.isClosed()));
page.waitForEventsAfterAction.callsFake(async action => {
await action(new AbortController().signal);
return {};
});
- return Object.assign(page, {pptrPage});
+ Object.defineProperty(page, 'pptrPage', {
+ value: pptrPage,
+ writable: true,
+ configurable: true,
+ });
+ Object.defineProperty(page, 'target', {
+ value: target,
+ writable: true,
+ configurable: true,
+ });
+ return Object.assign(page, {pptrPage, target});
}
export function createMockDialog(
diff --git a/tests/tools/pwa.test.ts b/tests/tools/pwa.test.ts
index 773faaf3..4a9ef471 100644
--- a/tests/tools/pwa.test.ts
+++ b/tests/tools/pwa.test.ts
@@ -309,9 +309,10 @@ describe('pwa', () => {
);
await context.createPagesSnapshot();
const appPage = context.getPages().find(page => {
- return page.pptrPage.url() === startUrl;
+ return page.url() === startUrl;
});
assert.ok(appPage, 'the launched app page should be listed');
+ await appPage.init();
context.selectPage(appPage);
response.resetResponseLineForTesting();