Skip to content

Chrome DevTools for coding agents

13.8 KB
Raw Blame
/**
 * @license
 * Copyright 2025 Google LLC
 * SPDX-License-Identifier: Apache-2.0
 */

import {FakeIssuesManager} from '../devtools/DevtoolsUtils.js';
import {
  DevTools,
  FrameEvent,
  type CDPSession,
  type ConsoleMessage,
  type Protocol,
  type Issue,
  type Frame,
  type Handler,
  type HTTPRequest,
  type Page,
  type PageEvents as PuppeteerPageEvents,
} from '../third_party/index.js';
import {
  createIdGenerator,
  stableIdSymbol,
  type WithSymbolId,
} from '../utils/id.js';
import {logger} from '../utils/logger.js';

import {DEFAULT_MAX_NAVIGATION_SAVED} from './constants.js';

export class UncaughtError {
  readonly details: Protocol.Runtime.ExceptionDetails;
  readonly targetId: string;
  readonly session?: CDPSession;

  constructor(
    details: Protocol.Runtime.ExceptionDetails,
    targetId: string,
    session?: CDPSession,
  ) {
    this.details = details;
    this.targetId = targetId;
    this.session = session;
  }
}

interface PageEvents extends PuppeteerPageEvents {
  devtoolsAggregatedIssue: DevTools.AggregatedIssue;
  uncaughtError: UncaughtError;
}

export type ListenerMap<EventMap extends PageEvents = PageEvents> = {
  [
    K in keyof EventMap as string extends K
      ? never
      : number extends K
        ? never
        : symbol extends K
          ? never
          : K
  ]?: (event: EventMap[K]) => void;
};

export interface PageCollectorOptions {
  maxResourcesPerNavigation?: number;
  maxNavigationSaved?: number;
}

export class PageCollector<T> {
  protected pptrPage: Page;
  #listeners?: ListenerMap<PageEvents>;
  #pendingSameDocumentNavigation = false;
  #frameNavigatedWithinDocumentTarget?: Frame;
  protected readonly maxNavigationSaved: number;

  /**
   * This maps a Page to a list of navigations with a sub-list
   * of all collected resources.
   * The newer navigations come first.
   */
  protected storage: Array<Array<WithSymbolId<T>>> = [[]];

  constructor(
    page: Page,
    listeners: (collector: (item: T) => void) => ListenerMap<PageEvents>,
    {
      maxResourcesPerNavigation,
      maxNavigationSaved = DEFAULT_MAX_NAVIGATION_SAVED,
    }: PageCollectorOptions = {},
  ) {
    this.pptrPage = page;
    this.maxNavigationSaved = maxNavigationSaved;
    this.#attachFrameNavigatedWithinDocumentListener();

    const idGenerator = createIdGenerator();

    const listenerMap = listeners(value => {
      const withId = value as WithSymbolId<T>;
      withId[stableIdSymbol] = idGenerator();
      this.storage[0].push(withId);
      if (
        maxResourcesPerNavigation !== undefined &&
        this.storage[0].length > maxResourcesPerNavigation
      ) {
        this.storage[0].splice(
          0,
          this.storage[0].length - maxResourcesPerNavigation,
        );
      }
    });

    listenerMap['framenavigated'] = (frame: Frame) => {
      // Only split the storage on main frame navigation
      if (frame !== this.pptrPage.mainFrame()) {
        return;
      }
      // Re-attach the listener to the current main frame: a cross-document
      // navigation may have replaced the frame object, so the reference
      // captured at construction time would be stale.
      this.#attachFrameNavigatedWithinDocumentListener();
      // Same-document (SPA) navigations also emit `framenavigated`, but they
      // must not rotate the retained history. Puppeteer emits
      // `FrameNavigatedWithinDocument` right before `FrameNavigated` for such
      // navigations, so consume the flag here to skip the split.
      if (this.#pendingSameDocumentNavigation) {
        this.#pendingSameDocumentNavigation = false;
        return;
      }
      this.splitAfterNavigation();
    };

    for (const [name, listener] of Object.entries(listenerMap)) {
      this.pptrPage.on(name, listener as Handler<unknown>);
    }

    this.#listeners = listenerMap;
  }

  dispose(): void {
    this.#detachFrameNavigatedWithinDocumentListener();
    if (this.#listeners) {
      for (const [name, listener] of Object.entries(this.#listeners)) {
        this.pptrPage.off(name, listener as Handler<unknown>);
      }
    }
  }

  // Puppeteer emits this right before the page-level navigation event for
  // same-document (SPA) navigations, which lets `framenavigated` skip the
  // history rotation for those navigations.
  #onFrameNavigatedWithinDocument = (): void => {
    this.#pendingSameDocumentNavigation = true;
  };

  #attachFrameNavigatedWithinDocumentListener(): void {
    this.#detachFrameNavigatedWithinDocumentListener();
    this.#frameNavigatedWithinDocumentTarget = this.pptrPage.mainFrame();
    this.#frameNavigatedWithinDocumentTarget.on(
      FrameEvent.FrameNavigatedWithinDocument,
      this.#onFrameNavigatedWithinDocument,
    );
  }

  #detachFrameNavigatedWithinDocumentListener(): void {
    if (this.#frameNavigatedWithinDocumentTarget) {
      this.#frameNavigatedWithinDocumentTarget.off(
        FrameEvent.FrameNavigatedWithinDocument,
        this.#onFrameNavigatedWithinDocument,
      );
      this.#frameNavigatedWithinDocumentTarget = undefined;
    }
  }

  protected splitAfterNavigation(): void {
    // Add the latest navigation first
    this.storage.unshift([]);
    this.storage.splice(this.maxNavigationSaved);
  }

  getData(includePreservedData?: boolean): T[] {
    if (!includePreservedData) {
      return this.storage[0];
    }

    const data: T[] = [];
    for (let index = this.maxNavigationSaved; index >= 0; index--) {
      if (this.storage[index]) {
        data.push(...this.storage[index]);
      }
    }
    return data;
  }

  getIdForResource(resource: WithSymbolId<T>): number {
    return resource[stableIdSymbol] ?? -1;
  }

  getById(stableId: number): T {
    const item = this.find(item => item[stableIdSymbol] === stableId);

    if (!item) {
      throw new Error('Request not found for selected page');
    }

    return item;
  }

  find(
    filter: (item: WithSymbolId<T>) => boolean,
  ): WithSymbolId<T> | undefined {
    for (const navigation of this.storage) {
      const item = navigation.find(filter);
      if (item) {
        return item;
      }
    }
    return;
  }
}

export class ConsoleCollector extends PageCollector<
  ConsoleMessage | Error | DevTools.AggregatedIssue | UncaughtError
> {
  static readonly MAX_MESSAGES_PER_NAVIGATION = 10_000;

  #subscriber?: PageEventSubscriber;

  constructor(
    page: Page,
    listeners: (
      collector: (
        item: ConsoleMessage | Error | DevTools.AggregatedIssue | UncaughtError,
      ) => void,
    ) => ListenerMap<PageEvents>,
    {
      maxResourcesPerNavigation = ConsoleCollector.MAX_MESSAGES_PER_NAVIGATION,
      maxNavigationSaved,
    }: PageCollectorOptions = {},
  ) {
    super(page, listeners, {maxResourcesPerNavigation, maxNavigationSaved});
    this.#subscriber = new PageEventSubscriber(this.pptrPage);
    this.#subscriber.subscribe();
  }

  override dispose(): void {
    super.dispose();
    this.#subscriber?.unsubscribe();
  }
}

class PageEventSubscriber {
  #issueManager = new FakeIssuesManager();
  #issueAggregator = new DevTools.IssueAggregator(this.#issueManager);
  #seenKeys = new Set<string>();
  #seenIssues = new Set<DevTools.AggregatedIssue>();
  #page: Page;
  #session: CDPSession;
  #targetId: string;
  #pendingSameDocumentNavigation = false;
  #frameNavigatedWithinDocumentTarget?: Frame;

  constructor(page: Page) {
    this.#page = page;
    // @ts-expect-error use existing CDP client (internal Puppeteer API).
    this.#session = this.#page._client() as CDPSession;
    // @ts-expect-error use internal Puppeteer API to get target ID
    this.#targetId = this.#session.target()._targetId;
  }

  #resetIssueAggregator(): void {
    this.#issueManager = new FakeIssuesManager();
    if (this.#issueAggregator) {
      this.#issueAggregator.removeEventListener(
        DevTools.IssueAggregatorEvents.AGGREGATED_ISSUE_UPDATED,
        this.#onAggregatedIssue,
      );
    }
    this.#issueAggregator = new DevTools.IssueAggregator(this.#issueManager);
    this.#issueAggregator.addEventListener(
      DevTools.IssueAggregatorEvents.AGGREGATED_ISSUE_UPDATED,
      this.#onAggregatedIssue,
    );
  }

  subscribe(): void {
    this.#resetIssueAggregator();
    this.#page.on('framenavigated', this.#onFrameNavigated);
    this.#page.on('issue', this.#onIssueAdded);
    this.#session.on('Runtime.exceptionThrown', this.#onExceptionThrown);
    this.#attachFrameNavigatedWithinDocumentListener();
  }

  unsubscribe(): void {
    this.#seenKeys.clear();
    this.#seenIssues.clear();
    this.#detachFrameNavigatedWithinDocumentListener();
    this.#page.off('framenavigated', this.#onFrameNavigated);
    this.#page.off('issue', this.#onIssueAdded);
    this.#session.off('Runtime.exceptionThrown', this.#onExceptionThrown);
    if (this.#issueAggregator) {
      this.#issueAggregator.removeEventListener(
        DevTools.IssueAggregatorEvents.AGGREGATED_ISSUE_UPDATED,
        this.#onAggregatedIssue,
      );
    }
  }

  #onAggregatedIssue = (
    event: DevTools.Common.EventTarget.EventTargetEvent<DevTools.AggregatedIssue>,
  ): void => {
    if (this.#seenIssues.has(event.data)) {
      return;
    }
    this.#seenIssues.add(event.data);
    this.#page.emit('devtoolsAggregatedIssue', event.data);
  };

  #onExceptionThrown = (event: Protocol.Runtime.ExceptionThrownEvent): void => {
    this.#page.emit(
      'uncaughtError',
      new UncaughtError(event.exceptionDetails, this.#targetId, this.#session),
    );
  };

  // On navigation, we reset issue aggregation.
  #onFrameNavigated = (frame: Frame): void => {
    // Only split the storage on main frame navigation
    if (frame !== frame.page().mainFrame()) {
      return;
    }
    // Re-attach the listener to the current main frame: a cross-document
    // navigation may have replaced the frame object, so the reference
    // captured at construction time would be stale.
    this.#attachFrameNavigatedWithinDocumentListener();
    if (this.#pendingSameDocumentNavigation) {
      this.#pendingSameDocumentNavigation = false;
      return;
    }
    this.#seenKeys.clear();
    this.#seenIssues.clear();
    this.#resetIssueAggregator();
  };

  // Puppeteer emits this right before the page-level navigation event for
  // same-document (SPA) navigations, which lets `framenavigated` skip the
  // issue aggregation reset for those navigations.
  #onFrameNavigatedWithinDocument = (): void => {
    this.#pendingSameDocumentNavigation = true;
  };

  #attachFrameNavigatedWithinDocumentListener(): void {
    this.#detachFrameNavigatedWithinDocumentListener();
    this.#frameNavigatedWithinDocumentTarget = this.#page.mainFrame();
    this.#frameNavigatedWithinDocumentTarget.on(
      FrameEvent.FrameNavigatedWithinDocument,
      this.#onFrameNavigatedWithinDocument,
    );
  }

  #detachFrameNavigatedWithinDocumentListener(): void {
    if (this.#frameNavigatedWithinDocumentTarget) {
      this.#frameNavigatedWithinDocumentTarget.off(
        FrameEvent.FrameNavigatedWithinDocument,
        this.#onFrameNavigatedWithinDocument,
      );
      this.#frameNavigatedWithinDocumentTarget = undefined;
    }
  }

  #onIssueAdded = (inspectorIssue: Issue): void => {
    try {
      // @ts-expect-error The types are missmatched but they
      // are coming from CDP
      if (!DevTools.isIssueCodeSupported(inspectorIssue.code)) {
        return;
      }
      const issue = DevTools.createIssuesFromProtocolIssue(
        null,
        // @ts-expect-error Protocol types diverge.
        inspectorIssue,
      )[0];
      if (!issue) {
        logger?.('No issue mapping for for the issue: ', inspectorIssue.code);
        return;
      }

      const primaryKey = issue.primaryKey();
      if (this.#seenKeys.has(primaryKey)) {
        return;
      }
      this.#seenKeys.add(primaryKey);
      this.#issueManager.dispatchEventToListeners(
        DevTools.IssuesManagerEvents.ISSUE_ADDED,
        {
          issue,
          // @ts-expect-error We don't care that issues model is null
          issuesModel: null,
        },
      );
    } catch (error) {
      logger?.('Error creating a new issue', error);
    }
  };
}

export class NetworkCollector extends PageCollector<HTTPRequest> {
  static readonly MAX_REQUESTS_PER_NAVIGATION = 1_000;

  /** The navigation request that started the latest navigation, if any. */
  #navigationRequest?: HTTPRequest;

  constructor(
    page: Page,
    {
      maxResourcesPerNavigation = NetworkCollector.MAX_REQUESTS_PER_NAVIGATION,
      maxNavigationSaved,
    }: PageCollectorOptions = {},
    listeners: (
      collector: (item: HTTPRequest) => void,
    ) => ListenerMap<PageEvents> = collect => {
      return {
        request: req => {
          // With the debugger `createTargetUniverse()` starts, initiator stacks
          // carry up to 32 async parents, which no tool reads.
          const stack = req.initiator()?.stack;
          if (stack) {
            delete stack.parent;
          }
          collect(req);
        },
      } as ListenerMap;
    },
  ) {
    super(page, listeners, {maxResourcesPerNavigation, maxNavigationSaved});
  }
  override splitAfterNavigation(): void {
    const requests = this.storage[0];

    // A navigation without a request, such as a back/forward cache restore or
    // about:blank, must not claim the request of the previous navigation.
    const lastRequestIdx = requests.findLastIndex(request => {
      return (
        request !== this.#navigationRequest &&
        request.frame() === this.pptrPage.mainFrame() &&
        request.isNavigationRequest()
      );
    });

    // Keep all requests since the last navigation request including that
    // navigation request itself.
    // Keep the reference
    if (lastRequestIdx !== -1) {
      this.#navigationRequest = requests[lastRequestIdx];
      const fromCurrentNavigation = requests.splice(lastRequestIdx);
      this.storage.unshift(fromCurrentNavigation);
    } else {
      this.#navigationRequest = undefined;
      this.storage.unshift([]);
    }
    this.storage.splice(this.maxNavigationSaved);
  }
}