Skip to content

Chrome DevTools for coding agents

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

import zlib from 'node:zlib';

import type {ParsedArguments} from '../config/mcp-options.js';
import {zod, DevTools} from '../third_party/index.js';
import {
  parseRawTraceBuffer,
  traceResultIsSuccess,
  type InsightName,
  type TraceResult,
} from '../processors/PerformanceTrace.js';
import {logger} from '../utils/logger.js';
import {NetworkOverridesFormatter} from '../formatters/NetworkOverridesFormatter.js';

import {ToolCategory} from './categories.js';
import {
  definePageTool,
  type Context,
  type Response,
  type ContextPage,
  type PageToolFactory,
} from './ToolDefinition.js';

const filePathSchema = zod
  .string()
  .optional()
  .describe(
    'The absolute file path, or a file path relative to the current working directory, to save the raw trace data. For example, trace.json.gz (compressed) or trace.json (uncompressed).',
  );

export const startTrace: PageToolFactory = definePageTool(() => ({
  name: 'performance_start_trace',
  description: `Start a performance trace on the target webpage. Use to find frontend performance issues, Core Web Vitals (LCP, INP, CLS), and improve page load speed.`,
  annotations: {
    category: ToolCategory.PERFORMANCE,
    readOnlyHint: false,
  },
  schema: {
    reload: zod
      .boolean()
      .default(true)
      .describe(
        'Determines if, once tracing has started, the target page should be automatically reloaded. Navigate the page to the right URL using the navigate_page tool BEFORE starting the trace if reload or autoStop is set to true.',
      ),
    autoStop: zod
      .boolean()
      .default(true)
      .describe(
        'Determines if the trace recording should be automatically stopped.',
      ),
    ignoreCache: zod
      .boolean()
      .optional()
      .describe(
        'Whether to bypass the HTTP cache when reloading the page, to measure a cold page load. Only applies if reload is true. Active network mocks always disable the page HTTP cache.',
      ),
    filePath: filePathSchema,
  },
  blockedByDialog: true,
  concurrency: 'exclusive',
  verifyFilesSchema: {
    filePath: true,
  },
  handler: async (request, response, context) => {
    if (context.isRunningPerformanceTrace()) {
      response.appendResponseLine(
        'Error: a performance trace is already running. Use performance_stop_trace to stop it. Only one trace can be running at any given time.',
      );
      return;
    }
    const page = request.page;
    const networkOverrides = page.listNetworkMocks();
    const {warning} = new NetworkOverridesFormatter(networkOverrides).toJSON();
    if (warning) {
      response.appendResponseLine(warning);
    }
    page.setIsRunningPerformanceTrace(true);

    const pageUrlForTracing = page.pptrPage.url();

    try {
      if (request.params.reload) {
        // Before starting the recording, navigate to about:blank to clear out any state.
        // We use `load` because `networkidle0` is known to be flaky for about:blank in Puppeteer.
        await page.pptrPage.goto('about:blank', {
          waitUntil: 'load',
        });
      }

      const categories = [
        '-*',
        ...DevTools.TracingDefaultCategories,
        // These categories are optional in DevTools, but enabled by default in the DevTools UI, so we enable them here too.
        ...DevTools.TracingOptionalCategories.JsSampling,
        ...DevTools.TracingOptionalCategories.Screenshot,
      ];
      await page.pptrPage.tracing.start({
        categories,
        bufferSize: 1200 * 1000,
      });

      if (request.params.reload) {
        const ignoreCache =
          request.params.ignoreCache === true && networkOverrides.length === 0;
        if (ignoreCache) {
          // Disable the HTTP cache so that the main document and all
          // subresources are fetched from the network, like a hard reload.
          await page.pptrPage.setCacheEnabled(false);
        }
        try {
          await page.pptrPage.goto(pageUrlForTracing, {
            waitUntil: ['load'],
          });
        } finally {
          if (ignoreCache) {
            await page.pptrPage.setCacheEnabled(true);
          }
        }
      }

      if (request.params.autoStop) {
        await new Promise(resolve => setTimeout(resolve, 5_000));
        await stopTracingAndAppendOutput(
          page,
          response,
          context,
          request.params.filePath,
        );
      } else {
        response.appendResponseLine(
          `The performance trace is being recorded. Use performance_stop_trace to stop it.`,
        );
      }
    } catch (error) {
      // If a setup step (navigation, tracing.start) throws before
      // stopTracingAndAppendOutput runs, the running flag would otherwise stay
      // stuck `true` for the rest of the session, blocking all future traces.
      // Unwind here: stop tracing if it was started and clear the flag. When
      // autoStop already ran stopTracingAndAppendOutput the flag is already
      // false and this is a no-op.
      if (context.isRunningPerformanceTrace()) {
        try {
          await page.pptrPage.tracing.stop();
        } catch {
          // Tracing may not have started yet; ignore.
        }
        page.setIsRunningPerformanceTrace(false);
      }
      throw error;
    }
  },
}));

export const stopTrace: PageToolFactory = definePageTool(
  (args: ParsedArguments) => ({
    name: 'performance_stop_trace',
    description:
      'Stop the active performance trace recording on the target webpage.',
    annotations: {
      category: ToolCategory.PERFORMANCE,
      readOnlyHint: false,
    },
    schema: {
      filePath: filePathSchema,
    },
    blockedByDialog: true,
    concurrency: 'exclusive',
    verifyFilesSchema: {
      filePath: true,
    },
    handler: async (request, response, context) => {
      if (!context.isRunningPerformanceTrace()) {
        response.appendResponseLine(
          'Error: no active performance trace recording to stop.',
        );
        return;
      }
      const page = request.page;
      if (!page.isRunningPerformanceTrace()) {
        const tracedPage = context
          .getPages()
          .find(p => p.isRunningPerformanceTrace());
        const pageHint = tracedPage ? ` on page ${tracedPage.id}` : '';
        const actionHint = tracedPage
          ? args.pageIdRouting
            ? `Pass pageId: ${tracedPage.id} to performance_stop_trace to stop it.`
            : `Select page ${tracedPage.id} with select_page first, then call performance_stop_trace.`
          : 'Select the page that started the trace and try again.';
        response.appendResponseLine(
          `Error: the active performance trace is running${pageHint}, not on page ${page.id}. ${actionHint}`,
        );
        return;
      }
      const {warning} = new NetworkOverridesFormatter(
        page.listNetworkMocks(),
      ).toJSON();
      if (warning) {
        response.appendResponseLine(warning);
      }
      await stopTracingAndAppendOutput(
        page,
        response,
        context,
        request.params.filePath,
      );
    },
  }),
);

export const analyzeInsight: PageToolFactory = definePageTool(() => ({
  name: 'performance_analyze_insight',
  description:
    'Provides more detailed information on a specific Performance Insight of an insight set that was highlighted in the results of a trace recording.',
  annotations: {
    category: ToolCategory.PERFORMANCE,
    readOnlyHint: true,
  },
  schema: {
    insightSetId: zod
      .string()
      .describe(
        'The id for the specific insight set. Only use the ids given in the "Available insight sets" list.',
      ),
    insightName: zod
      .string()
      .describe(
        'The name of the Insight you want more information on. For example: "DocumentLatency" or "LCPBreakdown"',
      ),
  },
  blockedByDialog: false,
  concurrency: 'exclusive',
  verifyFilesSchema: {},
  handler: async (request, response, context) => {
    const lastRecording = context.recordedTraces().at(-1);
    if (!lastRecording) {
      response.appendResponseLine(
        'No recorded traces found. Record a performance trace so you have Insights to analyze.',
      );
      return;
    }

    response.attachTraceInsight(
      lastRecording,
      request.params.insightSetId,
      request.params.insightName as InsightName,
    );
  },
}));

async function stopTracingAndAppendOutput(
  page: ContextPage,
  response: Response,
  context: Context,
  filePath?: string,
): Promise<void> {
  try {
    const traceEventsBuffer = await page.pptrPage.tracing.stop();
    if (filePath && traceEventsBuffer) {
      let dataToWrite: Uint8Array = traceEventsBuffer;
      if (filePath.endsWith('.gz')) {
        dataToWrite = await new Promise((resolve, reject) => {
          zlib.gzip(traceEventsBuffer, (error, result) => {
            if (error) {
              reject(error);
            } else {
              resolve(result);
            }
          });
        });
      }
      const file = await context.saveFile(
        dataToWrite,
        filePath,
        filePath.endsWith('.gz') ? '.gz' : '.json',
      );
      response.appendResponseLine(
        `The raw trace data was saved to ${file.filename}.`,
      );
    }
    const result = await parseRawTraceBuffer(traceEventsBuffer, {
      cpuThrottling: page.cpuThrottlingRate,
      networkThrottling: page.networkConditions ?? undefined,
    });
    response.appendResponseLine('The performance trace has been stopped.');
    if (traceResultIsSuccess(result)) {
      if (context.isCruxEnabled()) {
        await populateCruxData(result);
      }
      context.storeTraceRecording(result);
      response.attachTraceSummary(result);
    } else {
      throw new Error(
        `There was an unexpected error parsing the trace: ${result.error}`,
      );
    }
  } finally {
    page.setIsRunningPerformanceTrace(false);
  }
}

/** We tell CrUXManager to fetch data so it's available when DevTools.PerformanceTraceFormatter is invoked */
async function populateCruxData(result: TraceResult): Promise<void> {
  logger?.('populateCruxData called');
  const cruxManager = DevTools.CrUXManager.CrUXManager.instance();
  // go/jtfbx. Yes, we're aware this API key is public. ;)
  cruxManager.setEndpointForTesting(
    'https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=AIzaSyBn5gimNjhiEyA_euicSKko6IlD3HdgUfk',
  );
  const cruxSetting =
    DevTools.Common.Settings.Settings.instance().createSetting('field-data', {
      enabled: true,
    });
  cruxSetting.set({enabled: true});

  // Gather URLs to fetch CrUX data for
  const urls = [...(result.parsedTrace.insights?.values() ?? [])].map(c =>
    c.url.toString(),
  );
  urls.push(result.parsedTrace.data.Meta.mainFrameURL);
  const urlSet = new Set(urls);

  if (urlSet.size === 0) {
    logger?.('No URLs found for CrUX data');
    return;
  }

  logger?.(
    `Fetching CrUX data for ${urlSet.size} URLs: ${Array.from(urlSet).join(', ')}`,
  );
  const cruxData = await Promise.all(
    Array.from(urlSet).map(async url => {
      const data = await cruxManager.getFieldDataForPage(url);
      logger?.(`CrUX data for ${url}: ${data ? 'found' : 'not found'}`);
      return data;
    }),
  );

  result.parsedTrace.metadata.cruxFieldData = cruxData;
}