Skip to content

Chrome DevTools for coding agents

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

/**
 * Sinon-based mock factories for McpPage, McpContext, McpResponse and
 * the underlying Puppeteer Page.
 *
 * Uses sinon.createStubInstance() so all methods are automatically stubbed
 * from the real class prototype — no hand-rolled interface definitions needed.
 *
 * Usage example:
 *
 *   const page = createMockMcpPage();
 *   const context = createMockMcpContext({selectedPage: page});
 *   const response = createMockMcpResponse();
 *
 *   await myTool.handler({params: {networkConditions: 'Slow 3G'}, page}, response, context);
 *
 *   sinon.assert.calledOnceWithExactly(page.emulate, {networkConditions: 'Slow 3G'});
 */

import './setupDevTools.js';

import {
  EventEmitter,
  type Frame,
  type Mouse,
  type SerializedAXNode,
} from 'puppeteer-core';
import sinon from 'sinon';

import type {ParsedArguments} from '../src/config/mcp-options.js';
import {ServerConfig} from '../src/config/ServerConfig.js';
import type {TargetUniverse} from '../src/devtools/DevtoolsUtils.js';
import {McpContext} from '../src/McpContext.js';
import {McpPage} from '../src/McpPage.js';
import {McpResponse} from '../src/McpResponse.js';
import {McpWorker, type WorkerType} from '../src/McpWorker.js';
import {TaskRunner, type TaskQueue} from '../src/utils/TaskRunner.js';
import type {
  DuplicateStringGroup,
  HeapSnapshotAggregate,
  HeapSnapshotAggregateData,
  HeapSnapshotClassDiff,
  HeapSnapshotClassDiffTotals,
  HeapSnapshotDetailedClassDiff,
  HeapSnapshotDiff,
  HeapSnapshotDiffObject,
} from '../src/processors/HeapSnapshotManager.js';
import {
  Accessibility,
  CdpBrowser,
  CdpExtension,
  CdpFrame,
  CdpHTTPRequest,
  CdpMouse,
  CdpPage,
  CDPSession,
  Connection,
  ConsoleMessage,
  DevTools,
  Dialog,
  ElementHandle,
  Locator,
  Target,
  TargetType,
  Tracing,
  WebWorker,
  WebMCP,
  WebMCPTool,
  type Browser,
  type ResourceType,
  type BrowserContext,
  type ConsoleMessageLocation,
  type ConsoleMessageType,
  type Extension,
  type JSHandle,
  type Page,
  type Protocol,
  type Realm,
  type Result,
  type RunnerResult,
} from '../src/third_party/index.js';

export type MockPuppeteerPage = sinon.SinonStubbedInstance<Page> & {
  webmcp: sinon.SinonStubbedInstance<WebMCP>;
  tracing: sinon.SinonStubbedInstance<Tracing>;
  mouse: sinon.SinonStubbedInstance<Mouse>;
  accessibility: sinon.SinonStubbedInstance<Accessibility>;
  cdpSession: {
    on: sinon.SinonStub;
    off: sinon.SinonStub;
    send: sinon.SinonStub;
    target: sinon.SinonStub;
    emit: (eventName: string | symbol | number, data?: unknown) => void;
  };
};

export type MockMcpPage = sinon.SinonStubbedInstance<McpPage> & {
  pptrPage: MockPuppeteerPage;
  target: sinon.SinonStubbedInstance<MockTarget>;
};
export type MockMcpContext = sinon.SinonStubbedInstance<McpContext>;
export type MockMcpResponse = sinon.SinonStubbedInstance<McpResponse>;

export interface ProtocolAXNode extends SerializedAXNode {
  loaderId?: string;
  backendNodeId?: number;
  children?: ProtocolAXNode[];
  elementHandle: () => Promise<ElementHandle<Element> | null>;
}

export function createMockAXNode(
  role: string,
  options: {
    name?: string;
    loaderId?: string;
    backendNodeId?: number;
    children?: ProtocolAXNode[];
  } = {},
): ProtocolAXNode {
  return {
    role,
    name: options.name,
    loaderId: options.loaderId,
    backendNodeId: options.backendNodeId,
    children: options.children,
    elementHandle: async () => null,
  };
}
export type MockDOMNode = sinon.SinonStubbedInstance<DevTools.DOMModel.DOMNode>;
export type MockCSSProperty =
  sinon.SinonStubbedInstance<DevTools.CSSProperty.CSSProperty>;
export type MockCSSStyleDeclaration =
  sinon.SinonStubbedInstance<DevTools.CSSStyleDeclaration.CSSStyleDeclaration>;
export type MockCSSMatchedStyles =
  sinon.SinonStubbedInstance<DevTools.CSSMatchedStyles.CSSMatchedStyles>;
export type MockCSSStyleRule =
  sinon.SinonStubbedInstance<DevTools.CSSRule.CSSStyleRule>;
export type MockCSSKeyframesRule =
  sinon.SinonStubbedInstance<DevTools.CSSRule.CSSKeyframesRule>;
export type MockCSSAtRule =
  sinon.SinonStubbedInstance<DevTools.CSSRule.CSSAtRule>;
export type MockCSSPositionTryRule =
  sinon.SinonStubbedInstance<DevTools.CSSRule.CSSPositionTryRule>;
export type MockCSSRegisteredProperty =
  sinon.SinonStubbedInstance<DevTools.CSSMatchedStyles.CSSRegisteredProperty>;
export type MockCSSFunctionRule =
  sinon.SinonStubbedInstance<DevTools.CSSRule.CSSFunctionRule>;

interface StubbedEventEmitter<Self> {
  on: sinon.SinonStub<
    [type: PropertyKey, handler: (event: unknown, eventData: never) => void],
    Self
  >;
  off: sinon.SinonStub<
    [type: PropertyKey, handler?: (event: unknown, eventData: never) => void],
    Self
  >;
  once: sinon.SinonStub<
    [type: PropertyKey, handler: (event: unknown, eventData: never) => void],
    Self
  >;
  emit: sinon.SinonStub<[type: PropertyKey, event: unknown], boolean>;
  listenerCount: sinon.SinonStub<[type: PropertyKey], number>;
  removeAllListeners: sinon.SinonStub<[type?: PropertyKey], Self>;
}

/**
 * Wires a Sinon-stubbed Puppeteer EventEmitter subclass to a real Puppeteer
 * `EventEmitter` instance (`sinon.createStubInstance` skips constructors, so
 * EventEmitter's private fields are not initialized on the stub itself).
 */
function stubEventEmitter<Self>(stub: StubbedEventEmitter<Self> & Self): void {
  const emitter = new EventEmitter<Record<PropertyKey, unknown>>();
  stub.on.callsFake((eventName, handler) => {
    emitter.on(eventName, handler);
    return stub;
  });
  stub.off.callsFake((eventName, handler) => {
    emitter.off(eventName, handler);
    return stub;
  });
  stub.once.callsFake((eventName, handler) => {
    emitter.once(eventName, handler);
    return stub;
  });
  stub.emit.callsFake((eventName, data) => {
    return emitter.emit(eventName, data);
  });
  stub.listenerCount.callsFake(eventName => {
    return emitter.listenerCount(eventName);
  });
  stub.removeAllListeners.callsFake(eventName => {
    emitter.removeAllListeners(eventName);
    return stub;
  });
}

export function createMockPuppeteerBrowser(): sinon.SinonStubbedInstance<Browser> {
  const browser = sinon.createStubInstance(
    CdpBrowser,
  ) as unknown as sinon.SinonStubbedInstance<Browser>;
  sinon.stub(browser, 'connected').get(() => true);
  browser.close.resolves();
  browser.disconnect.resolves();
  browser.restrictNetwork.resolves();
  browser.pages.resolves([]);
  browser.targets.returns([]);
  browser.browserContexts.returns([]);
  browser.process.returns(null);
  stubEventEmitter(browser);

  return browser;
}

export class MockCDPSession extends CDPSession {
  override connection(): Connection | undefined {
    return undefined;
  }
  override get detached(): boolean {
    return false;
  }
  override send(): Promise<never> {
    throw new Error('Not implemented');
  }
  override detach(): Promise<void> {
    throw new Error('Not implemented');
  }
  override id(): string {
    return '';
  }
}

export function createMockCDPSession(): sinon.SinonStubbedInstance<MockCDPSession> {
  const session = sinon.createStubInstance(MockCDPSession);
  const connection = sinon.createStubInstance(Connection);
  connection.session.returns(session);
  session.connection.returns(connection);
  session.id.returns('<mock-session-id>');
  session.send.resolves();
  session.detach.resolves();
  stubEventEmitter(session);
  return session;
}

export function createMockHTTPRequest(
  options: {
    url?: string;
    resourceType?: ResourceType;
  } = {},
): sinon.SinonStubbedInstance<CdpHTTPRequest> {
  const request = sinon.createStubInstance(CdpHTTPRequest);
  request.url.returns(options.url ?? 'https://example.com/app.js');
  request.method.returns('GET');
  request.resourceType.returns(options.resourceType ?? 'script');
  request.headers.returns({});
  request.continue.resolves();
  request.respond.resolves();
  request.abort.resolves();
  return request;
}

export function createMockPuppeteerPage(): MockPuppeteerPage {
  const pptrPage = sinon.createStubInstance(CdpPage);
  const page = pptrPage as unknown as sinon.SinonStubbedInstance<Page>;
  stubEventEmitter(page);

  // mainFrame() must return a stable object so tests can pass it back into
  // page.emit('framenavigated', mainFrame) and have it recognized as the
  // same frame instance across calls. It needs real on/off/emit so the
  // PageCollector can subscribe to FrameNavigatedWithinDocument and tests
  // can trigger it.
  const mainFrameStub = sinon.createStubInstance(CdpFrame);
  mainFrameStub.page.returns(pptrPage);
  stubEventEmitter(mainFrameStub);
  // SinonStubbedInstance<CdpFrame> is not assignable to Frame due to private fields.
  page.mainFrame.returns(mainFrameStub as unknown as Frame);

  // _client() is a private internal Puppeteer API used by ConsoleCollector
  // in the McpPage constructor. Not on the CdpPage prototype, so added
  // explicitly. It needs real on/off/emit behavior so tests can trigger CDP
  // events directly via cdpSession.emit(...).
  const cdpListener = new EventEmitter<Record<PropertyKey, unknown>>();
  const cdpSession = {
    on: sinon.stub().callsFake(cdpListener.on.bind(cdpListener)),
    off: sinon.stub().callsFake(cdpListener.off.bind(cdpListener)),
    send: sinon.stub().resolves({}),
    target: sinon.stub().returns({_targetId: '<mock>'}),
    emit: (eventName: PropertyKey, data?: unknown): void => {
      cdpListener.emit(eventName, data);
    },
  };
  // @ts-expect-error internal API
  page._client = sinon.stub().returns(cdpSession);

  const webmcp = sinon.createStubInstance(WebMCP);
  webmcp.tools.returns([]);
  Object.defineProperty(page, 'webmcp', {
    value: webmcp,
    writable: true,
    configurable: true,
  });

  // The real `tracing` getter reads a private field, which throws on a stub
  // instance, so it is replaced with a stubbed Tracing instance.
  const tracing = sinon.createStubInstance(Tracing);
  Object.defineProperty(page, 'tracing', {
    value: tracing,
    writable: true,
    configurable: true,
  });

  const mouse = sinon.createStubInstance(
    CdpMouse,
  ) as unknown as sinon.SinonStubbedInstance<Mouse>;
  Object.defineProperty(page, 'mouse', {
    value: mouse,
    writable: true,
    configurable: true,
  });

  const accessibility = sinon.createStubInstance(Accessibility);
  Object.defineProperty(page, 'accessibility', {
    value: accessibility,
    writable: true,
    configurable: true,
  });

  page.emulateFocusedPage.resolves();
  page.evaluateHandle.resolves(createMockElementHandle().handle);

  return Object.assign(page, {
    webmcp,
    tracing,
    mouse,
    accessibility,
    cdpSession,
  });
}

export function createMockWebMCPTool(options: {
  name: string;
  description?: string;
  inputSchema?: object;
  annotations?: Protocol.WebMCP.Annotation & {debugging?: boolean};
}): sinon.SinonStubbedInstance<WebMCPTool> {
  const tool = sinon.createStubInstance(WebMCPTool);
  tool.name = options.name;
  tool.description = options.description ?? '';
  tool.inputSchema = options.inputSchema;
  tool.annotations = options.annotations;
  return tool;
}

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;
    type?: TargetType;
  } = {},
): 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.type.returns(options.type ?? TargetType.PAGE);
  target.url.returns(options.url ?? 'https://example.com');
  target._getTargetInfo.returns({
    targetId: '<mock-target-id>',
    type: options.type ?? 'page',
    title: options.title ?? '',
    url: options.url ?? 'https://example.com',
    attached: true,
    canAccessOpener: false,
  });
  return target;
}

export function createMockMcpPage(
  options: {
    id?: number;
    pptrPage?: MockPuppeteerPage;
    target?: sinon.SinonStubbedInstance<MockTarget>;
  } = {},
): MockMcpPage {
  const page = sinon.createStubInstance(McpPage);
  page.emulationSettings = {};
  if (options.id !== undefined) {
    Object.defineProperty(page, 'id', {value: options.id});
  }
  const pptrPage = options.pptrPage ?? createMockPuppeteerPage();
  const target = options.target ?? createMockPuppeteerTarget({page: pptrPage});
  page.init.resolves();
  page.listNetworkMocks.returns([]);
  page.close.callsFake(async () => {
    await pptrPage.close({runBeforeUnload: false});
  });
  page.url.callsFake(() => pptrPage.url());
  page.getTitle.returns('');
  page.isClosed.callsFake(() => Boolean(pptrPage.isClosed()));
  page.waitForEventsAfterAction.callsFake(async action => {
    await action(new AbortController().signal);
    return {};
  });
  page.getWebMcpTools.returns([]);
  page.getLatestConsoleMessageId.returns(0);
  page.getConsoleDataAfter.returns([]);
  page.discoverThirdPartyDeveloperTools.resolves([]);
  page.getWebAuthnAuthenticator.returns(undefined);
  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(
  options: {
    type?: Protocol.Page.DialogType;
    message?: string;
    handled?: boolean;
  } = {},
): sinon.SinonStubbedInstance<Dialog> {
  const dialog = sinon.createStubInstance(Dialog);
  dialog.type.returns(options.type ?? 'alert');
  dialog.message.returns(options.message ?? '');
  sinon.stub(dialog, 'handled').get(() => options.handled ?? false);
  return dialog;
}

export function createMockElementHandle(): {
  handle: sinon.SinonStubbedInstance<ElementHandle<Element>>;
  locator: sinon.SinonStubbedInstance<Locator<Element>>;
} {
  const handle =
    sinon.createStubInstance<ElementHandle<Element>>(ElementHandle);
  handle.remoteObject.returns({type: 'object', objectId: '<mock-object-id>'});
  handle.dispose.resolves();
  const locator = sinon.createStubInstance<Locator<Element>>(Locator);
  locator.setTimeout.returns(locator);
  handle.asLocator.returns(locator);
  return {handle, locator};
}

export function createMockTarget(): sinon.SinonStubbedInstance<MockTarget> {
  return createMockPuppeteerTarget();
}

// Concrete subclass of Puppeteer's abstract WebWorker so sinon.createStubInstance
// can stub it without an `as unknown as` cast, mirroring MockTarget above.
class MockWebWorker extends WebWorker {
  mainRealm(): Realm {
    throw new Error('Not implemented');
  }
  get client(): CDPSession {
    throw new Error('Not implemented');
  }
}

export function createMockWebWorker(): sinon.SinonStubbedInstance<MockWebWorker> {
  return sinon.createStubInstance(MockWebWorker);
}

export function createMockMcpWorker(
  options: {
    id?: string;
    type?: WorkerType;
    url?: string;
    worker?: WebWorker;
  } = {},
): McpWorker {
  // A real McpWorker over a stubbed Target, so `url`/`worker()` resolve through
  // the same code paths as in production rather than through stubbed getters.
  const target = createMockTarget();
  target.url.returns(
    options.url ?? 'chrome-extension://mock-extension-id/sw.js',
  );
  target.worker.resolves(options.worker ?? null);
  return new McpWorker(
    options.id ?? 'sw-1',
    options.type ?? 'service_worker',
    target,
  );
}

export function createMockMcpContext(
  options: {selectedPage?: MockMcpPage; taskRunner?: TaskRunner} = {},
): MockMcpContext {
  const context = sinon.createStubInstance(McpContext);
  const page = options.selectedPage ?? createMockMcpPage();
  context.getSelectedMcpPage.returns(page satisfies McpPage);
  context.getPages.returns([page]);
  context.getTargetInfos.resolves(new Map());
  // Real queues, so handler tests observe the real scheduling.
  const taskRunner = options.taskRunner ?? new TaskRunner();
  const taskQueue = taskRunner.createQueue();
  Object.defineProperty(context, 'taskQueue', {value: taskQueue});
  const pageTaskQueues = new Map<number, TaskQueue>();
  context.pageTaskQueue.callsFake(pageId => {
    let queue = pageTaskQueues.get(pageId);
    if (!queue) {
      queue = taskRunner.createQueue(taskQueue);
      pageTaskQueues.set(pageId, queue);
    }
    return queue;
  });

  return context;
}

export function createMockWebAuthnModel(): sinon.SinonStubbedInstance<DevTools.WebAuthnModel.WebAuthnModel> {
  const model = sinon.createStubInstance(DevTools.WebAuthnModel.WebAuthnModel);
  model.setVirtualAuthEnvEnabled.resolves();
  model.getCredentials.resolves([]);
  return model;
}

function isAuthenticatorId(
  id: unknown,
): id is DevTools.Protocol.WebAuthn.AuthenticatorId {
  return typeof id === 'string';
}

export function createMockAuthenticatorId(
  id: string,
): DevTools.Protocol.WebAuthn.AuthenticatorId {
  if (!isAuthenticatorId(id)) {
    throw new Error(`Invalid authenticator id: ${id}`);
  }
  return id;
}

export function createMockTargetUniverse(
  model: NonNullable<ReturnType<DevTools.Target['model']>>,
): TargetUniverse {
  const target = sinon.createStubInstance(DevTools.Target);
  target.model.returns(model);
  return {
    target,
    universe: sinon.createStubInstance(DevTools.Foundation.Universe.Universe),
    session: createMockCDPSession(),
  };
}

export function createMockMcpResponse(): MockMcpResponse {
  return sinon.createStubInstance(McpResponse);
}

/**
 * Convenience helper — creates a mock page, context and response in one call.
 *
 *   const {page, context, response} = createHandlerMocks();
 */
export function createHandlerMocks(options: Partial<ParsedArguments> = {}): {
  page: MockMcpPage;
  context: MockMcpContext;
  response: MockMcpResponse;
  args: ParsedArguments;
} {
  const page = createMockMcpPage();
  const context = createMockMcpContext({selectedPage: page});
  const response = createMockMcpResponse();
  const args = createMockParsedArguments(options);
  return {page, context, response, args};
}

export function createMockRunnerResult(
  lhrOverrides: Partial<Result> = {},
): RunnerResult {
  const lhr = {
    finalDisplayedUrl: 'http://localhost',
    mainDocumentUrl: 'http://localhost',
    categories: {},
    audits: {},
    timing: {total: 0},
    ...lhrOverrides,
  };
  return {
    lhr: lhr as unknown as Result,
    report: '',
    artifacts: {} as unknown as RunnerResult['artifacts'],
  };
}

type RuleOrigin = 'regular' | 'user-agent' | 'injected' | 'inspector';

function isBackendNodeId(
  id: unknown,
): id is DevTools.Protocol.DOM.BackendNodeId {
  return typeof id === 'number';
}

export interface MockDOMNodeOptions {
  selector?: string;
  backendNodeId?: number;
}

export function createMockDOMNode(
  options: MockDOMNodeOptions = {},
): MockDOMNode {
  const node = sinon.createStubInstance(DevTools.DOMModel.DOMNode);
  const selector = options.selector ?? 'button';
  const backendNodeId = options.backendNodeId ?? 1;
  if (isBackendNodeId(backendNodeId)) {
    node.backendNodeId.returns(backendNodeId);
  }
  node.simpleSelector.returns(selector);
  node.nodeNameInCorrectCase.returns(selector.split(/[#.]/)[0] || selector);
  return node;
}

export interface MockCSSPropertyOptions {
  important?: boolean;
  parsedOk?: boolean;
  disabled?: boolean;
}

export function createMockCSSProperty(
  name: string,
  value: string,
  options: MockCSSPropertyOptions = {},
): MockCSSProperty {
  const ownerStyle = sinon.createStubInstance(
    DevTools.CSSStyleDeclaration.CSSStyleDeclaration,
  );
  ownerStyle.parentRule = null;
  const prop = sinon.stub(
    new DevTools.CSSProperty.CSSProperty(
      ownerStyle,
      0,
      name,
      value,
      options.important ?? false,
      options.disabled ?? false,
      options.parsedOk ?? true,
      false,
    ),
  );
  prop.parseValue.callThrough();
  return prop;
}

export interface MockCSSStyleDeclarationOptions {
  rule?: DevTools.CSSRule.CSSRule | null;
  type?: DevTools.CSSStyleDeclaration.Type;
  animationName?: string;
  range?: {
    startLine: number;
    startColumn: number;
    endLine: number;
    endColumn: number;
  };
}

export function createMockCSSStyleDeclaration(
  properties: DevTools.CSSProperty.CSSProperty[],
  options: MockCSSStyleDeclarationOptions = {},
): MockCSSStyleDeclaration {
  const style = sinon.createStubInstance(
    DevTools.CSSStyleDeclaration.CSSStyleDeclaration,
  );
  style.type = options.type ?? DevTools.CSSStyleDeclaration.Type.Regular;
  style.allProperties.returns(properties);
  style.leadingProperties.returns(properties);
  style.parentRule = options.rule ?? null;
  style.animationName.returns(options.animationName ?? '');
  if (options.range) {
    Object.assign(style, {range: options.range});
  }
  for (const prop of properties) {
    prop.ownerStyle = style;
  }
  return style;
}

export function createMockCSSInlineStyle(
  properties: DevTools.CSSProperty.CSSProperty[],
): MockCSSStyleDeclaration {
  return createMockCSSStyleDeclaration(properties, {
    type: DevTools.CSSStyleDeclaration.Type.Inline,
  });
}

export interface MockRuleOptions {
  sourceURL?: string;
  lineNumber?: number;
  columnNumber?: number;
  origin?: RuleOrigin;
  isConstructed?: boolean;
  nestingSelectors?: string[];
  selectors?: Array<{text: string}>;
  layers?: Array<{text?: string}>;
  media?: Array<{text: string}>;
  containerQueries?: Array<{
    text?: string;
    name?: string;
    getContainerForNode?: (nodeId: number) => Promise<unknown>;
  }>;
  scopes?: Array<{text: string}>;
  supports?: Array<{text: string}>;
  startingStyles?: unknown[];
  navigations?: Array<{text?: string}>;
  ruleTypes?: DevTools.Protocol.CSS.CSSRuleType[];
}

export function synthesizeRuleTypes(
  options: MockRuleOptions,
): DevTools.Protocol.CSS.CSSRuleType[] | undefined {
  if (options.ruleTypes !== undefined) {
    return options.ruleTypes;
  }
  const ruleTypes: DevTools.Protocol.CSS.CSSRuleType[] = [];
  const mappings: Array<
    [unknown[] | undefined, DevTools.Protocol.CSS.CSSRuleType]
  > = [
    [options.navigations, DevTools.Protocol.CSS.CSSRuleType.NavigationRule],
    [options.nestingSelectors, DevTools.Protocol.CSS.CSSRuleType.StyleRule],
    [
      options.startingStyles,
      DevTools.Protocol.CSS.CSSRuleType.StartingStyleRule,
    ],
    [options.scopes, DevTools.Protocol.CSS.CSSRuleType.ScopeRule],
    [options.supports, DevTools.Protocol.CSS.CSSRuleType.SupportsRule],
    [options.containerQueries, DevTools.Protocol.CSS.CSSRuleType.ContainerRule],
    [options.media, DevTools.Protocol.CSS.CSSRuleType.MediaRule],
    [options.layers, DevTools.Protocol.CSS.CSSRuleType.LayerRule],
  ];
  for (const [items, ruleType] of mappings) {
    if (items) {
      for (let i = 0; i < items.length; i++) {
        ruleTypes.push(ruleType);
      }
    }
  }
  return ruleTypes.length > 0 ? ruleTypes : undefined;
}

export function attachRuleMeta(
  rule: sinon.SinonStubbedInstance<DevTools.CSSRule.CSSRule>,
  sourceURL?: string,
  origin: RuleOrigin = 'regular',
  isConstructed = false,
): void {
  rule.isUserAgent.returns(origin === 'user-agent');
  rule.isInjected.returns(origin === 'injected');
  rule.isViaInspector.returns(origin === 'inspector');
  if (sourceURL || isConstructed) {
    const header = {
      sourceURL: sourceURL ?? '',
      lineNumberInSource: (line: number) => line,
      columnNumberInSource: (_line: number, col: number) => col,
      isConstructedByNew: () => isConstructed,
    };
    Object.assign(rule, {header});
  }
  Object.defineProperty(rule, 'sourceURL', {
    value: sourceURL,
    writable: true,
    configurable: true,
  });
}

function createCSSValue(text: string) {
  return {
    text,
    rebase() {
      // no-op
    },
  };
}

export function createMockCSSStyleRule(
  selector: string,
  options: MockRuleOptions = {},
): MockCSSStyleRule {
  const rule = sinon.createStubInstance(DevTools.CSSRule.CSSStyleRule);
  attachRuleMeta(
    rule,
    options.sourceURL,
    options.origin,
    options.isConstructed ?? false,
  );
  rule.selectorText.returns(selector);
  rule.lineNumberInSource.returns(options.lineNumber ?? -1);
  rule.columnNumberInSource.returns(options.columnNumber);
  const selectors = options.selectors
    ? options.selectors.map(s => ({...createCSSValue(s.text), ...s}))
    : [createCSSValue(selector)];
  Object.assign(rule, {
    selectors,
    nestingSelectors: options.nestingSelectors,
    layers: options.layers,
    media: options.media,
    containerQueries: options.containerQueries,
    scopes: options.scopes,
    supports: options.supports,
    startingStyles: options.startingStyles,
    navigations: options.navigations,
    ruleTypes: synthesizeRuleTypes(options),
  });
  return rule;
}

export function createMockCSSKeyframesRule(
  name: string,
  keyframes: Array<{
    key: string;
    properties: DevTools.CSSProperty.CSSProperty[];
    sourceURL?: string;
    range?: {
      startLine: number;
      startColumn: number;
      endLine: number;
      endColumn: number;
    };
  }>,
): MockCSSKeyframesRule {
  const rule = sinon.createStubInstance(DevTools.CSSRule.CSSKeyframesRule);
  const mockKeyframes = [];
  for (const kf of keyframes) {
    const kfMock = sinon.createStubInstance(DevTools.CSSRule.CSSKeyframeRule);
    attachRuleMeta(kfMock, kf.sourceURL);
    const style = createMockCSSStyleDeclaration(kf.properties, {
      rule: kfMock,
      range: kf.range,
    });
    kfMock.key.returns(createCSSValue(kf.key));
    Object.assign(kfMock, {style});
    mockKeyframes.push(kfMock);
  }
  rule.name.returns(createCSSValue(name));
  rule.keyframes.returns(mockKeyframes);
  return rule;
}

export function createMockCSSAtRule(
  type: string,
  options: {
    name?: string;
    subsection?: string;
    properties: DevTools.CSSProperty.CSSProperty[];
    sourceURL?: string;
    origin?: RuleOrigin;
    range?: {
      startLine: number;
      startColumn: number;
      endLine: number;
      endColumn: number;
    };
  },
): MockCSSAtRule {
  const rule = sinon.createStubInstance(DevTools.CSSRule.CSSAtRule);
  attachRuleMeta(rule, options.sourceURL, options.origin);
  const style = createMockCSSStyleDeclaration(options.properties, {
    rule,
    range: options.range,
  });
  rule.type.returns(type);
  rule.name.returns(options.name ? createCSSValue(options.name) : null);
  rule.subsection.returns(options.subsection ?? null);
  Object.assign(rule, {style});
  return rule;
}

export function createMockCSSPositionTryRule(
  name: string,
  options: {
    active?: boolean;
    properties: DevTools.CSSProperty.CSSProperty[];
    sourceURL?: string;
    range?: {
      startLine: number;
      startColumn: number;
      endLine: number;
      endColumn: number;
    };
  },
): MockCSSPositionTryRule {
  const rule = sinon.createStubInstance(DevTools.CSSRule.CSSPositionTryRule);
  attachRuleMeta(rule, options.sourceURL);
  const style = createMockCSSStyleDeclaration(options.properties, {
    rule,
    range: options.range,
  });
  rule.name.returns(createCSSValue(name));
  rule.active.returns(options.active ?? false);
  Object.assign(rule, {style});
  return rule;
}

export function createMockCSSRegisteredProperty(
  name: string,
  options: {
    syntax?: string;
    inherits?: boolean;
    initialValue?: string;
    sourceURL?: string;
    range?: {
      startLine: number;
      startColumn: number;
      endLine: number;
      endColumn: number;
    };
    isProgrammatic?: boolean;
  } = {},
): MockCSSRegisteredProperty {
  const properties = [
    createMockCSSProperty('syntax', options.syntax ?? '"*"'),
    createMockCSSProperty('inherits', String(options.inherits ?? false)),
  ];
  if (options.initialValue) {
    properties.push(
      createMockCSSProperty('initial-value', options.initialValue),
    );
  }

  let parentRule: sinon.SinonStubbedInstance<DevTools.CSSRule.CSSPropertyRule> | null =
    null;
  if (!options.isProgrammatic) {
    const mockRule = sinon.createStubInstance(DevTools.CSSRule.CSSPropertyRule);
    attachRuleMeta(mockRule, options.sourceURL);
    mockRule.propertyName.returns(createCSSValue(name));
    parentRule = mockRule;
  }

  const style = createMockCSSStyleDeclaration(properties, {
    rule: parentRule,
    range: options.range,
  });
  if (parentRule) {
    Object.assign(parentRule, {style});
  }

  const prop = sinon.createStubInstance(
    DevTools.CSSMatchedStyles.CSSRegisteredProperty,
  );
  prop.propertyName.returns(name);
  prop.inherits.returns(options.inherits ?? false);
  prop.syntax.returns(options.syntax ?? '"*"');
  prop.initialValue.returns(options.initialValue ?? null);
  prop.style.returns(style);
  return prop;
}

export function createMockCSSFunctionRule(
  nameWithParams: string,
  options: {
    functionName?: string;
    properties: DevTools.CSSProperty.CSSProperty[];
    sourceURL?: string;
    range?: {
      startLine: number;
      startColumn: number;
      endLine: number;
      endColumn: number;
    };
  },
): MockCSSFunctionRule {
  const rule = sinon.createStubInstance(DevTools.CSSRule.CSSFunctionRule);
  attachRuleMeta(rule, options.sourceURL);
  const style = createMockCSSStyleDeclaration(options.properties, {
    rule,
    range: options.range,
  });
  const baseName =
    options.functionName ?? nameWithParams.split('(')[0] ?? nameWithParams;
  rule.functionName.returns(createCSSValue(baseName));
  rule.nameWithParameters.returns(nameWithParams);
  Object.assign(rule, {style});
  return rule;
}

export interface MockCSSMatchedStylesParams {
  node?: string | DevTools.DOMModel.DOMNode;
  nodeStyles?: DevTools.CSSStyleDeclaration.CSSStyleDeclaration[];
  inheritedStyles?: DevTools.CSSStyleDeclaration.CSSStyleDeclaration[];
  keyframes?: DevTools.CSSRule.CSSKeyframesRule[];
  atRules?: DevTools.CSSRule.CSSAtRule[];
  positionTryRules?: DevTools.CSSRule.CSSPositionTryRule[];
  registeredProperties?: DevTools.CSSMatchedStyles.CSSRegisteredProperty[];
  functionRules?: DevTools.CSSRule.CSSFunctionRule[];
  parentNode?: string | DevTools.DOMModel.DOMNode;
  nodeForStyleMap?: Map<
    DevTools.CSSStyleDeclaration.CSSStyleDeclaration,
    DevTools.DOMModel.DOMNode
  >;
  pseudoStyles?: Map<
    DevTools.Protocol.DOM.PseudoType,
    DevTools.CSSStyleDeclaration.CSSStyleDeclaration[]
  >;
  customHighlights?: Map<
    string,
    DevTools.CSSStyleDeclaration.CSSStyleDeclaration[]
  >;
  propertyStates?: Map<DevTools.CSSProperty.CSSProperty, string>;
  matchingSelectorsMap?: Map<unknown, number[]>;
  cssVariables?: Record<string, string>;
}

export function createMockCSSMatchedStyles(
  params: MockCSSMatchedStylesParams = {},
): MockCSSMatchedStyles {
  const mockNode =
    typeof params.node === 'string'
      ? createMockDOMNode({selector: params.node})
      : (params.node ?? createMockDOMNode());

  const inheritedStyles = params.inheritedStyles ?? [];
  const nodeStyles = params.nodeStyles
    ? [...params.nodeStyles, ...inheritedStyles]
    : inheritedStyles;

  const defaultParentNode =
    typeof params.parentNode === 'string'
      ? createMockDOMNode({selector: params.parentNode})
      : params.parentNode;
  const nodeForStyleMap = params.nodeForStyleMap ?? new Map();

  const pseudoStylesMap = params.pseudoStyles ?? new Map();
  const pseudoTypes = new Set(pseudoStylesMap.keys());
  const customHighlights = params.customHighlights ?? new Map();

  const propertyStates = params.propertyStates ?? new Map();

  const mock = sinon.createStubInstance(
    DevTools.CSSMatchedStyles.CSSMatchedStyles,
  );
  mock.node.returns(mockNode);
  mock.nodeStyles.returns(nodeStyles);
  mock.inheritedStyles.returns(inheritedStyles);
  mock.keyframes.returns(params.keyframes ?? []);
  mock.atRules.returns(params.atRules ?? []);
  mock.positionTryRules.returns(params.positionTryRules ?? []);
  mock.registeredProperties.returns(params.registeredProperties ?? []);
  mock.functionRules.returns(params.functionRules ?? []);
  mock.pseudoTypes.returns(pseudoTypes);
  mock.customHighlightPseudoNames.returns(new Set(customHighlights.keys()));

  mock.nodeForStyle.callsFake(
    style => nodeForStyleMap.get(style) ?? defaultParentNode ?? null,
  );
  mock.isInherited.callsFake(style =>
    Boolean(inheritedStyles.find(inheritedStyle => inheritedStyle === style)),
  );
  mock.pseudoStyles.callsFake(type => pseudoStylesMap.get(type) ?? []);
  mock.customHighlightPseudoStyles.callsFake(
    name => customHighlights.get(name) ?? [],
  );
  mock.propertyState.callsFake(prop => propertyStates.get(prop) ?? 'Active');
  mock.getMatchingSelectors.callsFake(
    rule => params.matchingSelectorsMap?.get(rule) ?? [],
  );
  mock.propertyMatchers.callThrough();
  mock.computeCSSVariable.callsFake((_style, name) => {
    const value = params.cssVariables?.[name];
    return value !== undefined
      ? {
          value,
          declaration: new DevTools.CSSMatchedStyles.CSSValueSource(
            createMockCSSProperty(name, value),
          ),
        }
      : null;
  });

  return mock;
}

export function createMockExtension(
  options: {
    id?: string;
    path?: string;
    name?: string;
    version?: string;
    enabled?: boolean;
  } = {},
): Extension {
  const extension = sinon.createStubInstance(CdpExtension);
  sinon.stub(extension, 'id').value(options.id ?? 'mock-extension-id');
  sinon
    .stub(extension, 'path')
    .value(options.path ?? '/path/to/mock/extension');
  sinon.stub(extension, 'name').value(options.name ?? 'Mock Extension');
  sinon.stub(extension, 'version').value(options.version ?? '1.0.0');
  sinon.stub(extension, 'enabled').value(options.enabled ?? true);
  return extension as unknown as Extension;
}

export function createMockHeapSnapshotStats(): DevTools.HeapSnapshotModel.HeapSnapshotModel.Statistics {
  return {
    total: 1000,
    native: {total: 200, typedArrays: 50},
    v8heap: {
      total: 800,
      code: 50,
      jsArrays: 150,
      strings: 200,
      system: 400,
    },
  };
}

export function createMockHeapSnapshotStaticData(): DevTools.HeapSnapshotModel.HeapSnapshotModel.StaticData {
  return new DevTools.HeapSnapshotModel.HeapSnapshotModel.StaticData(
    10,
    0,
    1000,
    100,
  );
}

export function createMockNativeContextSizes(): DevTools.HeapSnapshotModel.HeapSnapshotModel.NativeContextSizes {
  return {
    nativeContexts: [],
    sharedSize: 0,
    noAttributionSize: 0,
  };
}

export function createMockRetainedByContextSummary(): DevTools.HeapSnapshotModel.HeapSnapshotModel.RetainedByContextSummary {
  return {
    contextCount: 0,
    retainedByContextSize: 0,
    retainedByContextCount: 0,
    notRetainedByContextSize: 0,
    notRetainedByContextCount: 0,
    totalSize: 0,
  };
}

export function createMockHeapSnapshotAggregateData(): HeapSnapshotAggregateData {
  return {
    aggregates: [],
    objectCount: 0,
    totalSelfSize: 0,
  };
}

export function createMockItemsRange(): DevTools.HeapSnapshotModel.HeapSnapshotModel.ItemsRange {
  return new DevTools.HeapSnapshotModel.HeapSnapshotModel.ItemsRange(
    0,
    0,
    0,
    [],
  );
}

export function createMockRetainingPaths(): DevTools.HeapSnapshotModel.HeapSnapshotModel.RetainingPaths {
  return {
    paths: [],
    limitsReached: {
      depth: false,
      nodes: false,
      siblings: false,
    },
  };
}

export function createMockDominatorChain(): DevTools.HeapSnapshotModel.HeapSnapshotModel.DominatorChain {
  return [];
}

export function createMockClassDiff(
  options: Partial<HeapSnapshotClassDiff> = {},
): HeapSnapshotClassDiff {
  return {
    index: options.index ?? 0,
    className: options.className ?? 'TestClass',
    addedCount: options.addedCount ?? 1,
    removedCount: options.removedCount ?? 0,
    countDelta: options.countDelta ?? 1,
    addedSize: options.addedSize ?? 10,
    removedSize: options.removedSize ?? 0,
    sizeDelta: options.sizeDelta ?? 10,
  };
}

export function createMockClassDiffTotals(
  options: Partial<HeapSnapshotClassDiffTotals> = {},
): HeapSnapshotClassDiffTotals {
  return {
    addedCount: options.addedCount ?? 1,
    removedCount: options.removedCount ?? 0,
    countDelta: options.countDelta ?? 1,
    addedSize: options.addedSize ?? 10,
    removedSize: options.removedSize ?? 0,
    sizeDelta: options.sizeDelta ?? 10,
  };
}

export function createMockHeapSnapshotDiff(
  options: Partial<HeapSnapshotDiff> = {},
): HeapSnapshotDiff {
  return {
    classDiffs: options.classDiffs ?? [createMockClassDiff()],
    totals: options.totals ?? createMockClassDiffTotals(),
  };
}

export function createMockDiffObject(
  options: Partial<HeapSnapshotDiffObject> = {},
): HeapSnapshotDiffObject {
  return {
    id: options.id ?? 1,
    selfSize: options.selfSize ?? 10,
    change: options.change ?? 'added',
  };
}

export function createMockDetailedClassDiff(
  options: Partial<HeapSnapshotDetailedClassDiff> = {},
): HeapSnapshotDetailedClassDiff {
  return {
    classDiff: options.classDiff ?? createMockClassDiff(),
    objects: options.objects ?? [createMockDiffObject()],
  };
}

export function createMockDuplicateStrings(): DuplicateStringGroup[] {
  return [];
}

export function createMockObjectInfo(): DevTools.HeapSnapshotModel.HeapSnapshotModel.ObjectInfo {
  return {
    id: 1,
    nodeIndex: 0,
    name: 'Object',
    type: 'object',
    selfSize: 100,
    retainedSize: 200,
    distance: 1,
    edgeCount: 2,
    retainerCount: 1,
    detachedness:
      DevTools.HeapSnapshotModel.HeapSnapshotModel.DOMLinkState.ATTACHED,
  };
}

export function createMockContextAnalysisResult(): DevTools.HeapSnapshotModel.HeapSnapshotModel.ContextAnalysisResult {
  return {
    scopes: [
      {
        scopeInfoNodeIndex: 30,
        scopeInfoNodeId: 303,
        scriptNodeIndex: 7,
        scriptNodeId: 301,
        scriptName: 'test.js',
        scopeName: 'createClosure',
        scopeStart: 14,
        scopeEnd: 104,
        contextFieldCount: 2,
        contexts: [
          {
            contextNodeIndex: 10,
            contextNodeId: 101,
            retainedSize: 5000,
            deadFieldsRetainedSizeSum: 2000,
            deadFields: [
              {
                name: 'dead',
                valueNodeIndex: 50,
                valueNodeId: 202,
                valueName: 'Object',
                valueType: 'object',
                selfSize: 200,
                retainedSize: 2000,
              },
            ],
          },
          {
            contextNodeIndex: 11,
            contextNodeId: 102,
            retainedSize: 1000,
            deadFieldsRetainedSizeSum: 500,
            deadFields: [
              {
                name: 'alsoDead',
                valueNodeIndex: 60,
                valueNodeId: 204,
                valueName: 'Array',
                valueType: 'object',
                selfSize: 100,
                retainedSize: 500,
              },
            ],
          },
        ],
      },
      {
        scopeInfoNodeIndex: 40,
        scopeInfoNodeId: 313,
        scriptNodeIndex: 8,
        scriptNodeId: 311,
        scriptName: 'other-scope.js',
        scopeName: 'createOtherClosure',
        scopeStart: 20,
        scopeEnd: 60,
        contextFieldCount: 1,
        contexts: [
          {
            contextNodeIndex: 12,
            contextNodeId: 111,
            retainedSize: 3000,
            deadFieldsRetainedSizeSum: 1500,
            deadFields: [
              {
                name: 'captured',
                valueNodeIndex: 70,
                valueNodeId: 206,
                valueName: 'Map',
                valueType: 'object',
                selfSize: 150,
                retainedSize: 1500,
              },
            ],
          },
        ],
      },
    ],
    scriptsWithoutScopes: [
      {
        scriptNodeIndex: 9,
        scriptNodeId: 401,
        scriptName: 'other.js',
        contextCount: 2,
      },
    ],
  };
}

export function stripUndefined<T extends object>(options: T): T {
  const result = {...options};
  for (const [key, value] of Object.entries(result)) {
    if (value === undefined) {
      Reflect.deleteProperty(result, key);
    }
  }
  return result;
}

export function createMockParsedArguments(
  options: Partial<ParsedArguments> = {},
): ParsedArguments {
  const defaultArgs = ServerConfig.applyDefaults(
    {},
    {suppressUsageStatisticsNotice: true},
  );
  return {...defaultArgs, ...stripUndefined(options)};
}

export function createMockServerConfig(
  options: Partial<ParsedArguments> = {},
): ServerConfig {
  const definedOptions = stripUndefined(options);
  return new ServerConfig({
    cliArgs: definedOptions,
    fileArgs: {},
    configPath: definedOptions.config,
    resolved: createMockParsedArguments(definedOptions),
  });
}

export function createMockHeapSnapshotNode(
  options: Partial<DevTools.HeapSnapshotModel.HeapSnapshotModel.Node> = {},
): DevTools.HeapSnapshotModel.HeapSnapshotModel.Node {
  return {
    id: options.id ?? 1,
    name: options.name ?? 'Node',
    distance: options.distance ?? 1,
    nodeIndex: options.nodeIndex ?? 0,
    retainedSize: options.retainedSize ?? 100,
    selfSize: options.selfSize ?? 10,
    type: options.type ?? 'object',
    canBeQueried: options.canBeQueried ?? false,
    detachedDOMTreeNode: options.detachedDOMTreeNode ?? false,
    ignored: options.ignored ?? false,
    isAddedNotRemoved: options.isAddedNotRemoved ?? null,
  };
}

export function createMockHeapSnapshotEdge(
  options: Partial<DevTools.HeapSnapshotModel.HeapSnapshotModel.Edge> = {},
): DevTools.HeapSnapshotModel.HeapSnapshotModel.Edge {
  return {
    name: options.name ?? 'edge',
    type: options.type ?? 'property',
    edgeIndex: options.edgeIndex ?? 0,
    isAddedNotRemoved: options.isAddedNotRemoved ?? null,
    node: options.node ?? createMockHeapSnapshotNode(),
  };
}

export function createMockHeapSnapshotAggregate(
  options: Partial<HeapSnapshotAggregate> = {},
): HeapSnapshotAggregate {
  return {
    id: options.id ?? 1,
    className: options.className ?? 'Object',
    count: options.count ?? 1,
    selfSize: options.selfSize ?? 10,
    retainedSize: options.retainedSize ?? 100,
  };
}

export function createMockConsoleMessage(
  options: {
    type?: ConsoleMessageType;
    text?: string;
    args?: JSHandle[];
    location?: ConsoleMessageLocation;
  } = {},
): sinon.SinonStubbedInstance<ConsoleMessage> {
  const message = sinon.createStubInstance(ConsoleMessage);
  message.type.returns(options.type ?? 'log');
  message.text.returns(options.text ?? '');
  message.args.returns(options.args ?? []);
  message.location.returns(options.location ?? {});
  return message;
}