Chrome DevTools for coding agents
/**
* @license
* Copyright 2025 Google LLC
* SPDX-License-Identifier: Apache-2.0
*/
import type {
Target,
Page,
Protocol,
CdpPage,
Dialog,
PredefinedNetworkConditions,
} from '../third_party/index.js';
import {logger} from './logger.js';
export type DialogAction = 'accept' | 'dismiss' | string;
export class WaitForHelper {
#abortController = new AbortController();
#page: CdpPage;
#publicPage: Page;
#stableDomTimeout: number;
#stableDomFor: number;
#expectNavigationIn: number;
#navigationTimeout: number;
#dialogHandled = false;
/** Track all dialogs as they pause the renderer. */
#dialogDetected = false;
#initialUrl: string;
#loadedNewDocument = false;
#openedPages = new Set<Target>();
constructor(
page: Page,
cpuTimeoutMultiplier: number,
networkTimeoutMultiplier: number,
) {
this.#stableDomTimeout = 3000 * cpuTimeoutMultiplier;
this.#stableDomFor = 100 * cpuTimeoutMultiplier;
this.#expectNavigationIn = 100 * cpuTimeoutMultiplier;
this.#navigationTimeout = 3000 * networkTimeoutMultiplier;
this.#page = page as unknown as CdpPage;
this.#publicPage = page;
this.#initialUrl = page.url();
}
/**
* A wrapper that executes a action and waits for
* a potential navigation, after which it waits
* for the DOM to be stable before returning.
*/
async waitForStableDom(): Promise<void> {
// Bound the setup evaluation against the stable-DOM timeout. Without this
// cap a paused renderer (e.g. an open dialog) would make evaluateHandle
// hang until protocolTimeout (default 180s) inside the context queue.
using stableDomObserver = await Promise.race([
this.#page.evaluateHandle(timeout => {
let timeoutId: ReturnType<typeof setTimeout>;
function callback(): void {
clearTimeout(timeoutId);
timeoutId = setTimeout(() => {
domObserver.resolver.resolve();
domObserver.observer.disconnect();
}, timeout);
}
const domObserver = {
resolver: Promise.withResolvers<void>(),
observer: new MutationObserver(callback),
};
// It's possible that the DOM is not gonna change so we
// need to start the timeout initially.
callback();
domObserver.observer.observe(document.body, {
childList: true,
subtree: true,
attributes: true,
});
return domObserver;
}, this.#stableDomFor),
this.timeout(this.#stableDomTimeout) as Promise<undefined>,
]).catch(() => undefined);
if (!stableDomObserver) {
return;
}
this.#abortController.signal.addEventListener('abort', async () => {
try {
await stableDomObserver.evaluate(observer => {
observer.observer.disconnect();
observer.resolver.resolve();
});
} catch {
// Ignored cleanup errors
}
});
return await Promise.race([
stableDomObserver.evaluate(async observer => {
return await observer.resolver.promise;
}),
this.timeout(this.#stableDomTimeout).then(() => {
throw new Error('Timeout');
}),
]);
}
timeout(time: number): Promise<void> {
if (this.#abortController.signal.aborted) {
return Promise.resolve();
}
return new Promise<void>(res => {
const id = setTimeout(res, time);
this.#abortController.signal.addEventListener('abort', () => {
res();
clearTimeout(id);
});
});
}
async waitForEventsAfterAction(
action: (signal: AbortSignal) => Promise<unknown>,
options?: {
timeout?: number;
waitForStableDom?: boolean;
expectNavigationIn?: number;
handleDialog?:
DialogAction | Partial<Record<Protocol.Page.DialogType, DialogAction>>;
},
): Promise<WaitForEventsResult> {
if (this.#abortController.signal.aborted) {
throw new Error("Can't re-use a WaitForHelper");
}
const dialogHandler = (
dialog: Pick<Dialog, 'accept' | 'dismiss' | 'type'>,
): void => {
this.#dialogDetected = true;
let actionToTake: DialogAction | undefined;
if (typeof options?.handleDialog === 'object') {
actionToTake = options.handleDialog[dialog.type()];
} else {
actionToTake = options?.handleDialog;
}
if (actionToTake) {
this.#dialogHandled = true;
if (actionToTake === 'dismiss') {
void dialog.dismiss();
} else if (actionToTake === 'accept') {
void dialog.accept();
} else {
void dialog.accept(actionToTake);
}
} else {
this.#abortController.abort(
new Error('Action interrupted by a dialog'),
);
}
};
this.#page.on('dialog', dialogHandler);
this.#abortController.signal.addEventListener('abort', () => {
this.#page.off('dialog', dialogHandler);
});
const popupHandler = (page: Page | null): void => {
if (page) {
this.#openedPages.add(page.target());
}
};
this.#publicPage.on('popup', popupHandler);
this.#abortController.signal.addEventListener('abort', () => {
this.#publicPage.off('popup', popupHandler);
});
// CDP reports each new document the main frame commits, a reload or a
// back/forward cache restore included, with `Page.frameNavigated`, while
// a same-document navigation comes as `Page.navigatedWithinDocument`.
const frameNavigatedHandler = (
event: Protocol.Page.FrameNavigatedEvent,
): void => {
if (!event.frame.parentId) {
this.#loadedNewDocument = true;
}
};
const client = this.#page._client();
client.on('Page.frameNavigated', frameNavigatedHandler);
this.#abortController.signal.addEventListener('abort', () => {
client.off('Page.frameNavigated', frameNavigatedHandler);
});
// A scoped AbortController used to clean up navigation probe listeners.
// When aborted (either after navigation detection finishes or if this.#abortController
// aborts), it removes CDP navigation probe listeners and automatically
// detaches the abort listener from this.#abortController.signal.
const navigationAbortController = new AbortController();
const navigationStartedResolvers = Promise.withResolvers<boolean>();
const navigationListener = (
event: Protocol.Page.FrameStartedNavigatingEvent,
): void => {
if (event.frameId !== this.#page.mainFrame()._id) {
return;
}
if (
event.navigationType === 'sameDocument' ||
event.navigationType === 'historySameDocument'
) {
return;
}
navigationStartedResolvers.resolve(true);
};
const requestedNavigationListener = (
event: Protocol.Page.FrameRequestedNavigationEvent,
): void => {
if (event.frameId === this.#page.mainFrame()._id) {
navigationStartedResolvers.resolve(true);
}
};
this.#page._client().on('Page.frameStartedNavigating', navigationListener);
this.#page
._client()
.on('Page.frameRequestedNavigation', requestedNavigationListener);
navigationAbortController.signal.addEventListener('abort', () => {
this.#page
._client()
.off('Page.frameStartedNavigating', navigationListener);
this.#page
._client()
.off('Page.frameRequestedNavigation', requestedNavigationListener);
});
this.#abortController.signal.addEventListener(
'abort',
() => {
navigationStartedResolvers.resolve(false);
navigationAbortController.abort();
},
{signal: navigationAbortController.signal},
);
// Puppeteer's waitForNavigation must be started before the action runs so that
// it captures the pre-action loader ID. If started after the action triggers navigation,
// it risks recording the new loader ID and hanging until timeout.
// If no navigation occurs, this.#abortController will cancel it in the finally block.
const navigationFinished = this.#page
.waitForNavigation({
timeout: 0,
signal: this.#abortController.signal,
ignoreSameDocumentNavigation: true,
})
.then(result => {
navigationStartedResolvers.resolve(true);
return result;
})
.catch(error => {
if (
this.#abortController.signal.aborted ||
(error instanceof Error && error.name === 'AbortError')
) {
return;
}
logger?.(error);
});
try {
await action(this.#abortController.signal);
} catch (error) {
// Clear up pending promises
this.#abortController.abort();
throw error;
}
const expectNavigationIn =
options?.expectNavigationIn ?? this.#expectNavigationIn;
const navigationStarted = await Promise.race([
navigationStartedResolvers.promise,
this.timeout(expectNavigationIn).then(() => {
navigationStartedResolvers.resolve(false);
return false;
}),
]);
navigationAbortController.abort();
try {
// Only await navigation if one was actually initiated; otherwise, the
// pending waitForNavigation promise will be cancelled when this.#abortController aborts.
if (navigationStarted) {
await Promise.race([
navigationFinished,
this.timeout(options?.timeout ?? this.#navigationTimeout),
]);
}
if (this.#dialogDetected) {
return this.#getResult();
}
// Wait for stable dom after navigation so we execute in
// the correct context
if (options?.waitForStableDom !== false) {
await this.waitForStableDom();
}
} catch (error) {
logger?.(error);
} finally {
this.#abortController.abort();
}
return this.#getResult();
}
#getResult(): WaitForEventsResult {
const urlAfterAction = this.#page.url();
return {
...(urlAfterAction !== this.#initialUrl || this.#loadedNewDocument
? {navigatedToUrl: urlAfterAction}
: {}),
dialogHandled: this.#dialogHandled,
...(this.#openedPages.size ? {openedPages: this.#openedPages} : {}),
};
}
}
export interface WaitForEventsResult {
/**
* The URL the page navigated to during the action, if a navigation
* occurred.
*/
navigatedToUrl?: string;
/**
* Whether a dialog was automatically handled during the action.
*/
dialogHandled?: boolean;
openedPages?: Set<Target>;
}
export function getNetworkMultiplierFromString(
condition: string | null,
): number {
const puppeteerCondition =
condition as keyof typeof PredefinedNetworkConditions;
switch (puppeteerCondition) {
case 'Fast 4G':
return 1;
case 'Slow 4G':
return 2.5;
case 'Fast 3G':
return 5;
case 'Slow 3G':
return 10;
}
return 1;
}