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.tsindex 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.tsindex 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;+// SnapshottextSnapshot: 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 CPUconst 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 CPUconst networkMultiplier = getNetworkMultiplierFromString(this.networkConditions,);- this.pptrPage.setDefaultNavigationTimeout(+ this.#pptrPage.setDefaultNavigationTimeout(this.#navigationTimeout * networkMultiplier * cpuMultiplier,);}diff --git a/src/McpResponse.ts b/src/McpResponse.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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();