Skip to content

Chrome DevTools for coding agents

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

import assert from 'node:assert';
import {describe, it} from 'node:test';

import sinon from 'sinon';

import {UncaughtError} from '../src/collectors/PageCollector.js';
import type {ReadonlyServerConfig} from '../src/config/ServerConfig.js';
import type {TargetUniverse} from '../src/devtools/DevtoolsUtils.js';
import {LogpointManager} from '../src/LogpointManager.js';
import {McpPage, replaceHtmlElementsWithUids} from '../src/McpPage.js';
import {
  DevTools,
  Frame,
  Locator,
  ScreenRecorder,
  type JSONSchema7Definition,
} from '../src/third_party/index.js';
import {TextSnapshot} from '../src/TextSnapshot.js';
import type {TextSnapshotNode} from '../src/types.js';
import {
  createMockCDPSession,
  createMockDialog,
  createMockMcpResponse,
  createMockPuppeteerPage,
  createMockPuppeteerTarget,
  createMockServerConfig,
  createMockAuthenticatorId,
  createMockTargetUniverse,
  createMockWebAuthnModel,
  createMockWebMCPTool,
} from './mocks.js';
import {serverHooks} from './server.js';
import {getMockRequest, html, withMcpContext} from './utils.js';

describe('replaceHtmlElementsWithUids', () => {
  it('does nothing for boolean schemas', () => {
    const schemaTrue: JSONSchema7Definition = true;
    const schemaFalse: JSONSchema7Definition = false;

    replaceHtmlElementsWithUids(schemaTrue);
    replaceHtmlElementsWithUids(schemaFalse);

    assert.strictEqual(schemaTrue, true);
    assert.strictEqual(schemaFalse, false);
  });

  it('replaces HTMLElement type with uid string', () => {
    const schema: JSONSchema7Definition = {
      type: 'object',
      properties: {
        foo: {type: 'string'},
        bar: {type: 'number'},
      },
      required: ['foo'],
    };
    Object.assign(schema, {'x-mcp-type': 'HTMLElement'});

    replaceHtmlElementsWithUids(schema);

    if (typeof schema === 'object') {
      assert.deepStrictEqual(schema.properties, {
        uid: {type: 'string'},
      });
      assert.deepStrictEqual(schema.required, ['uid']);
    } else {
      assert.fail('Schema should be an object');
    }
  });

  it('does not replace if x-mcp-type is not HTMLElement', () => {
    const schema: JSONSchema7Definition = {
      type: 'object',
      properties: {
        foo: {type: 'string'},
      },
    };
    Object.assign(schema, {'x-mcp-type': 'OtherType'});

    replaceHtmlElementsWithUids(schema);

    if (typeof schema === 'object') {
      assert.deepStrictEqual(schema.properties, {
        foo: {type: 'string'},
      });
      assert.strictEqual(schema.required, undefined);
    } else {
      assert.fail('Schema should be an object');
    }
  });

  it('recurses into nested properties', () => {
    const schema: JSONSchema7Definition = {
      type: 'object',
      properties: {
        element: {
          type: 'object',
          properties: {
            foo: {type: 'string'},
          },
        },
        other: {
          type: 'string',
        },
      },
    };
    if (typeof schema === 'object' && schema.properties) {
      Object.assign(schema.properties.element, {'x-mcp-type': 'HTMLElement'});
    }

    replaceHtmlElementsWithUids(schema);

    if (
      typeof schema === 'object' &&
      schema.properties &&
      typeof schema.properties.element === 'object'
    ) {
      const elementSchema = schema.properties.element;
      assert.deepStrictEqual(elementSchema.properties, {
        uid: {type: 'string'},
      });
      assert.deepStrictEqual(elementSchema.required, ['uid']);
    } else {
      assert.fail('Unexpected schema structure');
    }
  });

  it('recurses into array items (single schema object)', () => {
    const schema: JSONSchema7Definition = {
      type: 'array',
      items: {
        type: 'object',
      },
    };
    if (typeof schema === 'object' && typeof schema.items === 'object') {
      Object.assign(schema.items, {'x-mcp-type': 'HTMLElement'});
    }

    replaceHtmlElementsWithUids(schema);

    if (typeof schema === 'object' && typeof schema.items === 'object') {
      const itemsSchema = schema.items;
      if (!Array.isArray(itemsSchema)) {
        assert.deepStrictEqual(itemsSchema.properties, {
          uid: {type: 'string'},
        });
        assert.deepStrictEqual(itemsSchema.required, ['uid']);
      } else {
        assert.fail('items should not be an array in this test case');
      }
    } else {
      assert.fail('Unexpected schema structure');
    }
  });

  it('recurses into array items (array of schemas)', () => {
    const schema: JSONSchema7Definition = {
      type: 'array',
      items: [
        {
          type: 'object',
        },
        {
          type: 'string',
        },
      ],
    };
    if (typeof schema === 'object' && Array.isArray(schema.items)) {
      Object.assign(schema.items[0], {'x-mcp-type': 'HTMLElement'});
    }

    replaceHtmlElementsWithUids(schema);

    if (typeof schema === 'object' && Array.isArray(schema.items)) {
      const firstItem = schema.items[0];
      if (typeof firstItem === 'object') {
        assert.deepStrictEqual(firstItem.properties, {
          uid: {type: 'string'},
        });
        assert.deepStrictEqual(firstItem.required, ['uid']);
      } else {
        assert.fail('First item should be an object');
      }

      const secondItem = schema.items[1];
      if (typeof secondItem === 'object') {
        assert.strictEqual(secondItem.properties, undefined);
      } else {
        assert.fail('Second item should be an object');
      }
    } else {
      assert.fail('Unexpected schema structure');
    }
  });

  it('recurses into anyOf', () => {
    const schema: JSONSchema7Definition = {
      anyOf: [
        {
          type: 'object',
        },
        {
          type: 'string',
        },
      ],
    };
    if (typeof schema === 'object' && Array.isArray(schema.anyOf)) {
      Object.assign(schema.anyOf[0], {'x-mcp-type': 'HTMLElement'});
    }

    replaceHtmlElementsWithUids(schema);

    if (typeof schema === 'object' && Array.isArray(schema.anyOf)) {
      const firstItem = schema.anyOf[0];
      if (typeof firstItem === 'object') {
        assert.deepStrictEqual(firstItem.properties, {
          uid: {type: 'string'},
        });
      } else {
        assert.fail('First item should be an object');
      }
    } else {
      assert.fail('Unexpected schema structure');
    }
  });

  it('recurses into allOf', () => {
    const schema: JSONSchema7Definition = {
      allOf: [
        {
          type: 'object',
        },
      ],
    };
    if (typeof schema === 'object' && Array.isArray(schema.allOf)) {
      Object.assign(schema.allOf[0], {'x-mcp-type': 'HTMLElement'});
    }

    replaceHtmlElementsWithUids(schema);

    if (typeof schema === 'object' && Array.isArray(schema.allOf)) {
      const firstItem = schema.allOf[0];
      if (typeof firstItem === 'object') {
        assert.deepStrictEqual(firstItem.properties, {
          uid: {type: 'string'},
        });
      } else {
        assert.fail('First item should be an object');
      }
    } else {
      assert.fail('Unexpected schema structure');
    }
  });

  it('recurses into oneOf', () => {
    const schema: JSONSchema7Definition = {
      oneOf: [
        {
          type: 'object',
        },
      ],
    };
    if (typeof schema === 'object' && Array.isArray(schema.oneOf)) {
      Object.assign(schema.oneOf[0], {'x-mcp-type': 'HTMLElement'});
    }

    replaceHtmlElementsWithUids(schema);

    if (typeof schema === 'object' && Array.isArray(schema.oneOf)) {
      const firstItem = schema.oneOf[0];
      if (typeof firstItem === 'object') {
        assert.deepStrictEqual(firstItem.properties, {
          uid: {type: 'string'},
        });
      } else {
        assert.fail('First item should be an object');
      }
    } else {
      assert.fail('Unexpected schema structure');
    }
  });
});

describe('McpPage', () => {
  describe('network overrides', () => {
    it('rejects changing overrides during recording and allows clearing after stopping', async () => {
      const pptrPage = createMockPuppeteerPage();
      const page = new McpPage(createMockPuppeteerTarget({page: pptrPage}), 1, {
        config: createMockServerConfig(),
        locatorClass: Locator,
      });
      await page.mockNetwork({
        kind: 'file',
        urlPattern: '*://*:*/*.js',
        responseFilePath: '/tmp/app.js',
        loadResponseFile: async () => new Uint8Array(),
      });
      page.setIsRunningPerformanceTrace(true);
      await assert.rejects(
        page.mockNetwork({
          urlPattern: '*://*:*/*.js',
          kind: 'file',
          responseFilePath: '/tmp/app.js',
          loadResponseFile: async () => new Uint8Array(),
        }),
        /trace is running/,
      );
      await assert.rejects(page.removeNetworkMocks({}), /trace is running/);
      page.setIsRunningPerformanceTrace(false);
      await page.removeNetworkMocks({});
      assert.deepStrictEqual(page.listNetworkMocks(), []);
      page.dispose();
    });
    it('initializes interception and releases it when overrides are cleared', async () => {
      const pptrPage = createMockPuppeteerPage();
      const page = new McpPage(createMockPuppeteerTarget({page: pptrPage}), 1, {
        config: createMockServerConfig(),
        locatorClass: Locator,
      });
      const overrides = await page.mockNetwork({
        kind: 'file',
        urlPattern: '*://*:*/*.js',
        responseFilePath: '/tmp/replacement.js',
        loadResponseFile: async () => new Uint8Array(),
      });
      assert.deepStrictEqual(page.listNetworkMocks(), [overrides]);
      sinon.assert.calledOnceWithExactly(pptrPage.setCacheEnabled, false);
      sinon.assert.calledOnceWithExactly(pptrPage.setRequestInterception, true);
      await page.removeNetworkMocks({});
      assert.deepStrictEqual(page.listNetworkMocks(), []);
      sinon.assert.calledWithExactly(
        pptrPage.setRequestInterception.secondCall,
        false,
      );
      sinon.assert.calledWithExactly(pptrPage.setCacheEnabled.secondCall, true);
      page.dispose();
    });

    it('rejects setting overrides after disposal', async () => {
      const pptrPage = createMockPuppeteerPage();
      const page = new McpPage(createMockPuppeteerTarget({page: pptrPage}), 1, {
        config: createMockServerConfig(),
        locatorClass: Locator,
      });
      page.dispose();
      await assert.rejects(
        page.mockNetwork({
          kind: 'file',
          urlPattern: '*://*:*/*.js',
          responseFilePath: '/tmp/replacement.js',
          loadResponseFile: async () => new Uint8Array(),
        }),
        /already been disposed/,
      );
      sinon.assert.notCalled(pptrPage.setRequestInterception);
    });

    it('filters and removes network mocks without clearing unrelated routes', async () => {
      const pptrPage = createMockPuppeteerPage();
      const page = new McpPage(createMockPuppeteerTarget({page: pptrPage}), 1, {
        config: createMockServerConfig(),
        locatorClass: Locator,
      });
      const script = await page.mockNetwork({
        urlPattern: '*://*:*/*app.js',
        resourceType: 'script',
        kind: 'file',
        responseFilePath: '/tmp/app.js',
        loadResponseFile: async () => new Uint8Array(),
      });
      await page.mockNetwork({
        resourceType: 'image',
        kind: 'file',
        responseFilePath: '/tmp/app.js',
        loadResponseFile: async () => new Uint8Array(),
      });
      assert.deepStrictEqual(page.listNetworkMocks({resourceType: 'script'}), [
        script,
      ]);
      assert.equal(await page.removeNetworkMocks({resourceType: 'image'}), 1);
      assert.deepStrictEqual(page.listNetworkMocks(), [script]);
      sinon.assert.calledOnceWithExactly(pptrPage.setRequestInterception, true);
      await page.removeNetworkMocks({});
      page.dispose();
    });
  });

  async function createMcpPage(options: {config?: ReadonlyServerConfig} = {}) {
    const pptrPage = createMockPuppeteerPage();
    pptrPage.emulateFocusedPage.resolves();
    const target = createMockPuppeteerTarget({page: pptrPage});
    const mcpPage = new McpPage(target, 1, {
      config: options.config ?? createMockServerConfig(),
      locatorClass: Locator,
    });
    const mockSession = {
      send: sinon.stub().resolves(),
    };
    sinon
      .stub(mcpPage, 'devtoolsUniverse')
      .get(() => ({session: mockSession}) as unknown as TargetUniverse);
    await mcpPage.init();
    return {mcpPage, pptrPage, target, mockSession};
  }

  function getUidForNode(mcpPage: McpPage, matcher: string): string {
    const textSnapshot = mcpPage.textSnapshot;
    if (!textSnapshot) {
      throw new Error('No textSnapshot on mcpPage');
    }
    for (const [uid, node] of textSnapshot.idToNode) {
      if (node.name?.includes(matcher)) {
        return uid;
      }
    }
    throw new Error(`Target element "${matcher}" not found in snapshot`);
  }

  describe('lazy initialization', () => {
    for (const replaceNetworkCollector of [false, true]) {
      it(`forwards the navigation limit to collectors (replacement: ${replaceNetworkCollector})`, async () => {
        const pptrPage = createMockPuppeteerPage();
        const target = createMockPuppeteerTarget({page: pptrPage});
        const mcpPage = new McpPage(target, 1, {
          config: createMockServerConfig({maxNavigationSaved: 5}),
          locatorClass: Locator,
        });
        await mcpPage.init();
        if (replaceNetworkCollector) {
          await mcpPage.setUpNetworkCollectorForTesting();
        }
        const requests = [];
        const errors = [];
        for (let navigation = 0; navigation < 7; navigation++) {
          const request = getMockRequest({
            url: `http://example.com/nav${navigation}`,
            navigationRequest: true,
            frame: pptrPage.mainFrame(),
          });
          requests.push(request);
          pptrPage.emit('request', request);
          pptrPage.emit('framenavigated', pptrPage.mainFrame());
          const error = new UncaughtError(
            {
              exceptionId: navigation,
              text: `error-${navigation}`,
              lineNumber: 0,
              columnNumber: 0,
            },
            '<mock>',
          );
          errors.push(error);
          pptrPage.emit('uncaughtError', error);
        }
        assert.deepStrictEqual(
          mcpPage.networkCollector.getData(true),
          requests.slice(-5),
        );
        assert.deepStrictEqual(
          mcpPage.consoleCollector.getData(true),
          errors.slice(-5),
        );
        mcpPage.dispose();
      });
    }

    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, {
        config: createMockServerConfig(),
        locatorClass: Locator,
      });

      sinon.assert.notCalled(target.page);
      sinon.assert.notCalled(target.asPage);
      assert.throws(() => mcpPage.pptrPage, /not initialized/);
      await assert.rejects(
        () => mcpPage.discoverThirdPartyDeveloperTools(),
        /not initialized/,
      );
      assert.throws(() => mcpPage.getWebMcpTools(), /not initialized/);
      assert.strictEqual(mcpPage.url(), 'https://target-only.example.com');
      assert.strictEqual(mcpPage.getTitle(), 'Target Title');

      await mcpPage.init();

      sinon.assert.calledOnce(target.page);
      assert.strictEqual(mcpPage.pptrPage, pptrPage);
      assert.strictEqual(mcpPage.getTitle(), 'Target Title');
      sinon.assert.notCalled(pptrPage.title);
    });

    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, {
        config: createMockServerConfig(),
        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, {
        config: createMockServerConfig(),
        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, {
        config: createMockServerConfig(),
        locatorClass: Locator,
      });

      await mcpPage.close();

      assert.strictEqual(mcpPage.isClosed(), true);
      sinon.assert.calledOnceWithExactly(pptrPage.close, {
        runBeforeUnload: false,
      });
      sinon.assert.notCalled(pptrPage.emulateFocusedPage);
    });

    it('stops and clears an active screenRecorder on dispose()', async () => {
      const target = createMockPuppeteerTarget();
      const mcpPage = new McpPage(target, 1, {
        config: createMockServerConfig(),
        locatorClass: Locator,
      });
      const recorder = sinon.createStubInstance(ScreenRecorder);
      recorder.stop.resolves();
      mcpPage.setScreenRecorder({recorder, filePath: '/tmp/video.mp4'});

      mcpPage.dispose();

      sinon.assert.calledOnceWithExactly(recorder.stop);
      assert.strictEqual(mcpPage.getScreenRecorder(), null);
    });
  });

  describe('focus emulation', () => {
    function createPage() {
      const pptrPage = createMockPuppeteerPage();
      pptrPage.emulateFocusedPage.resolves();
      const target = createMockPuppeteerTarget({page: pptrPage});
      const mcpPage = new McpPage(target, 1, {
        config: createMockServerConfig(),
        locatorClass: Locator,
      });
      return {mcpPage, pptrPage, target};
    }

    it('requests focus once on default initialization', async () => {
      const {mcpPage, pptrPage, target} = createPage();

      await mcpPage.init();
      await mcpPage.init();
      await mcpPage.init({emulateFocus: false});

      sinon.assert.calledOnceWithExactly(pptrPage.emulateFocusedPage, true);
      sinon.assert.calledOnceWithExactly(target.page);
    });

    it('initializes without focus until a tool requests it', async () => {
      const {mcpPage, pptrPage, target} = createPage();

      await mcpPage.init({emulateFocus: false});
      await mcpPage.init({emulateFocus: false});

      assert.strictEqual(mcpPage.pptrPage, pptrPage);
      sinon.assert.notCalled(pptrPage.emulateFocusedPage);

      await mcpPage.init();
      await mcpPage.init();

      sinon.assert.calledOnceWithExactly(pptrPage.emulateFocusedPage, true);
      sinon.assert.calledOnceWithExactly(target.page);
    });

    it('shares initialization and requests focus once for concurrent callers', async () => {
      const {mcpPage, pptrPage, target} = createPage();

      await Promise.all([
        mcpPage.init({emulateFocus: false}),
        mcpPage.init(),
        mcpPage.init(),
      ]);

      sinon.assert.calledOnceWithExactly(target.page);
      sinon.assert.calledOnceWithExactly(pptrPage.emulateFocusedPage, true);
    });

    it('retries a failed focus request and retains successful emulation', async () => {
      const {mcpPage, pptrPage} = createPage();
      pptrPage.emulateFocusedPage
        .onFirstCall()
        .rejects(new Error('Target closed'));

      await mcpPage.init();
      await mcpPage.init();
      await mcpPage.init();

      assert.strictEqual(mcpPage.pptrPage, pptrPage);
      sinon.assert.calledTwice(pptrPage.emulateFocusedPage);
      sinon.assert.alwaysCalledWithExactly(pptrPage.emulateFocusedPage, true);
    });

    it('does not wait for or duplicate a pending focus request', async () => {
      const {mcpPage, pptrPage} = createPage();
      const focus = Promise.withResolvers<void>();
      pptrPage.emulateFocusedPage.returns(focus.promise);

      try {
        await Promise.all([mcpPage.init(), mcpPage.init()]);
        sinon.assert.calledOnceWithExactly(pptrPage.emulateFocusedPage, true);
      } finally {
        focus.resolve();
      }
    });

    it('skips focus when disposed during initialization', async () => {
      const {mcpPage, pptrPage, target} = createPage();
      const page = Promise.withResolvers<typeof pptrPage>();
      target.page.returns(page.promise);

      const initialization = mcpPage.init();
      mcpPage.dispose();
      page.resolve(pptrPage);
      await initialization;

      sinon.assert.notCalled(pptrPage.emulateFocusedPage);
      await assert.rejects(mcpPage.init(), /already been disposed/);
    });

    it('retries base initialization after a failure before requesting focus', async () => {
      const {mcpPage, pptrPage, target} = createPage();
      target.page.onFirstCall().rejects(new Error('Target unavailable'));

      await assert.rejects(mcpPage.init(), /Target unavailable/);
      sinon.assert.notCalled(pptrPage.emulateFocusedPage);

      await mcpPage.init();

      sinon.assert.calledTwice(target.page);
      sinon.assert.calledOnceWithExactly(pptrPage.emulateFocusedPage, true);
    });
  });

  describe('getLatestConsoleMessageId() and getConsoleDataAfter()', () => {
    function createUncaughtError(exceptionId: number): UncaughtError {
      return new UncaughtError(
        {
          exceptionId,
          text: `error-${exceptionId}`,
          lineNumber: 0,
          columnNumber: 0,
        },
        '<mock>',
      );
    }

    it('getLatestConsoleMessageId() returns 0 and getConsoleDataAfter() nothing for an empty collector', async () => {
      const {mcpPage} = await createMcpPage();

      assert.strictEqual(mcpPage.getLatestConsoleMessageId(), 0);
      assert.deepStrictEqual(mcpPage.getConsoleDataAfter(0), []);
    });

    it('getLatestConsoleMessageId() includes messages from an earlier navigation', async () => {
      const {mcpPage, pptrPage} = await createMcpPage();
      const error = createUncaughtError(1);
      pptrPage.emit('uncaughtError', error);
      pptrPage.emit('framenavigated', pptrPage.mainFrame());

      const id = mcpPage.getLatestConsoleMessageId();

      assert.strictEqual(id, mcpPage.consoleCollector.getIdForResource(error));
      assert.deepStrictEqual(mcpPage.getConsoleDataAfter(id), []);
    });

    it('getConsoleDataAfter() returns the messages after the id, from an earlier navigation too', async () => {
      const {mcpPage, pptrPage} = await createMcpPage();
      pptrPage.emit('uncaughtError', createUncaughtError(1));
      const id = mcpPage.getLatestConsoleMessageId();
      const beforeNavigation = createUncaughtError(2);
      pptrPage.emit('uncaughtError', beforeNavigation);
      pptrPage.emit('framenavigated', pptrPage.mainFrame());
      const afterNavigation = createUncaughtError(3);
      pptrPage.emit('uncaughtError', afterNavigation);

      assert.deepStrictEqual(mcpPage.getConsoleDataAfter(id), [
        beforeNavigation,
        afterNavigation,
      ]);
    });
  });

  describe('getTitle()', () => {
    function createPage(url: string, title: string): McpPage {
      const target = createMockPuppeteerTarget({url, title});
      return new McpPage(target, 1, {
        config: createMockServerConfig(),
        locatorClass: Locator,
      });
    }

    function targetInfo(url: string, title: string) {
      return {
        targetId: '<mock-target-id>',
        type: 'page',
        title,
        url,
        attached: true,
        canAccessOpener: false,
      };
    }

    it('prefers fresh target info over cached target info', () => {
      const mcpPage = createPage(
        'http://127.0.0.1:8080/titled.html',
        '127.0.0.1:8080/titled.html',
      );
      assert.strictEqual(
        mcpPage.getTitle(
          targetInfo('http://127.0.0.1:8080/titled.html', 'Real Title'),
        ),
        'Real Title',
      );
    });

    it('ignores Chrome URL placeholder titles', () => {
      assert.strictEqual(
        createPage(
          'http://127.0.0.1:8080/titled.html',
          '127.0.0.1:8080/titled.html',
        ).getTitle(),
        '',
      );
      assert.strictEqual(
        createPage('https://example.com/', 'example.com').getTitle(),
        '',
      );
      assert.strictEqual(
        createPage('about:blank', 'about:blank').getTitle(),
        '',
      );
    });

    it('exposes the target id', () => {
      assert.strictEqual(
        createPage('https://example.com', '').targetId,
        '<mock-target-id>',
      );
    });
  });

  describe('emulate()', () => {
    it('calls emulateNetworkConditions with offline settings', async () => {
      const {mcpPage, pptrPage} = await createMcpPage();
      await mcpPage.emulate({networkConditions: 'Offline'});
      assert.strictEqual(mcpPage.networkConditions, 'Offline');
      sinon.assert.calledOnceWithExactly(pptrPage.emulateNetworkConditions, {
        offline: true,
        download: 0,
        upload: 0,
        latency: 0,
      });
    });

    it('calls emulateNetworkConditions with the predefined condition', async () => {
      const {mcpPage, pptrPage} = await createMcpPage();
      await mcpPage.emulate({networkConditions: 'Slow 3G'});
      assert.strictEqual(mcpPage.networkConditions, 'Slow 3G');
      sinon.assert.calledOnceWithExactly(pptrPage.emulateNetworkConditions, {
        download: 50000,
        upload: 50000,
        latency: 2000,
      });
    });

    it('calls emulateNetworkConditions(null) when networkConditions is omitted', async () => {
      const {mcpPage, pptrPage} = await createMcpPage();
      await mcpPage.emulate({networkConditions: 'Slow 3G'});
      await mcpPage.emulate({});
      assert.strictEqual(mcpPage.networkConditions, null);
      sinon.assert.calledTwice(pptrPage.emulateNetworkConditions);
      sinon.assert.calledWithExactly(
        pptrPage.emulateNetworkConditions.secondCall,
        null,
      );
    });

    it('does not call emulateNetworkConditions for unknown values', async () => {
      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} = await createMcpPage({
        config: createMockServerConfig({
          blockedUrlPattern: ['*://blocked.example.com/*'],
        }),
      });
      await assert.rejects(
        () => mcpPage.emulate({networkConditions: 'Slow 3G'}),
        /Network throttling is not supported when network blocking/,
      );
      sinon.assert.notCalled(pptrPage.emulateNetworkConditions);
    });

    it('calls emulateCPUThrottling with the given rate', async () => {
      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} = await createMcpPage();
      await mcpPage.emulate({cpuThrottlingRate: 4});
      await mcpPage.emulate({cpuThrottlingRate: 1});
      assert.strictEqual(mcpPage.cpuThrottlingRate, 1);
      sinon.assert.calledTwice(pptrPage.emulateCPUThrottling);
      sinon.assert.calledWithExactly(
        pptrPage.emulateCPUThrottling.secondCall,
        1,
      );
    });

    it('sends Emulation.setCPUThrottlingRate to secondary session if present', async () => {
      const {mcpPage, pptrPage, mockSession} = await createMcpPage();
      await mcpPage.emulate({cpuThrottlingRate: 4});
      sinon.assert.calledOnceWithExactly(pptrPage.emulateCPUThrottling, 4);
      sinon.assert.calledOnceWithExactly(
        mockSession.send,
        'Emulation.setCPUThrottlingRate',
        {rate: 4},
      );
    });

    it('sends Emulation.setCPUThrottlingRate with rate 1 to secondary session when cpuThrottlingRate is omitted', async () => {
      const {mcpPage, pptrPage, mockSession} = await createMcpPage();
      await mcpPage.emulate({});
      sinon.assert.calledOnceWithExactly(pptrPage.emulateCPUThrottling, 1);
      sinon.assert.calledOnceWithExactly(
        mockSession.send,
        'Emulation.setCPUThrottlingRate',
        {rate: 1},
      );
    });

    it('calls setGeolocation with the given coordinates', async () => {
      const {mcpPage, pptrPage} = await createMcpPage();
      await mcpPage.emulate({
        geolocation: {latitude: 48.137154, longitude: 11.576124},
      });
      assert.deepStrictEqual(mcpPage.geolocation, {
        latitude: 48.137154,
        longitude: 11.576124,
      });
      sinon.assert.calledOnceWithExactly(pptrPage.setGeolocation, {
        latitude: 48.137154,
        longitude: 11.576124,
      });
    });

    it('clears the geolocation override when geolocation is omitted', async () => {
      const {mcpPage, pptrPage} = await createMcpPage();
      await mcpPage.emulate({
        geolocation: {latitude: 48.137154, longitude: 11.576124},
      });
      await mcpPage.emulate({});
      assert.strictEqual(mcpPage.geolocation, null);
      sinon.assert.calledTwice(pptrPage.setGeolocation);
      sinon.assert.calledWithExactly(pptrPage.setGeolocation.secondCall, null);
    });

    it('calls setUserAgent with the given user agent', async () => {
      const {mcpPage, pptrPage} = await createMcpPage();
      await mcpPage.emulate({userAgent: 'TestUA/1.0'});
      assert.strictEqual(mcpPage.userAgent, 'TestUA/1.0');
      sinon.assert.calledOnceWithExactly(pptrPage.setUserAgent, {
        userAgent: 'TestUA/1.0',
      });
    });

    it('calls setUserAgent with undefined to clear the user agent', async () => {
      const {mcpPage, pptrPage} = await createMcpPage();
      await mcpPage.emulate({userAgent: 'TestUA/1.0'});
      await mcpPage.emulate({userAgent: ''});
      assert.strictEqual(mcpPage.userAgent, null);
      sinon.assert.calledTwice(pptrPage.setUserAgent);
      sinon.assert.calledWithExactly(pptrPage.setUserAgent.secondCall, {
        userAgent: undefined,
      });
    });

    describe('media features', () => {
      it('emulates all media features in a single call', async () => {
        const {mcpPage, pptrPage} = await createMcpPage();
        await mcpPage.emulate({
          colorScheme: 'dark',
          forcedColors: 'active',
          prefersContrast: 'more',
          prefersReducedMotion: 'reduce',
        });
        assert.strictEqual(mcpPage.colorScheme, 'dark');
        assert.strictEqual(mcpPage.forcedColors, 'active');
        assert.strictEqual(mcpPage.prefersContrast, 'more');
        assert.strictEqual(mcpPage.prefersReducedMotion, 'reduce');
        sinon.assert.calledOnceWithExactly(pptrPage.emulateMediaFeatures, [
          {name: 'prefers-color-scheme', value: 'dark'},
          {name: 'forced-colors', value: 'active'},
          {name: 'prefers-contrast', value: 'more'},
          {name: 'prefers-reduced-motion', value: 'reduce'},
        ]);
      });

      it('resets media features set to auto', async () => {
        const {mcpPage, pptrPage} = await createMcpPage();
        await mcpPage.emulate({
          colorScheme: 'dark',
          forcedColors: 'active',
          prefersContrast: 'more',
          prefersReducedMotion: 'reduce',
        });
        await mcpPage.emulate({
          colorScheme: 'auto',
          forcedColors: 'auto',
          prefersContrast: 'auto',
          prefersReducedMotion: 'auto',
        });
        assert.strictEqual(mcpPage.colorScheme, null);
        assert.strictEqual(mcpPage.forcedColors, null);
        assert.strictEqual(mcpPage.prefersContrast, null);
        assert.strictEqual(mcpPage.prefersReducedMotion, null);
        sinon.assert.calledTwice(pptrPage.emulateMediaFeatures);
        sinon.assert.calledWithExactly(
          pptrPage.emulateMediaFeatures.secondCall,
          [
            {name: 'prefers-color-scheme', value: ''},
            {name: 'forced-colors', value: ''},
            {name: 'prefers-contrast', value: ''},
            {name: 'prefers-reduced-motion', value: ''},
          ],
        );
      });

      it('resets omitted media features', async () => {
        const {mcpPage, pptrPage} = await createMcpPage();
        await mcpPage.emulate({forcedColors: 'active'});
        await mcpPage.emulate({prefersContrast: 'less'});
        assert.strictEqual(mcpPage.forcedColors, null);
        assert.strictEqual(mcpPage.prefersContrast, 'less');
        sinon.assert.calledTwice(pptrPage.emulateMediaFeatures);
        sinon.assert.calledWithExactly(
          pptrPage.emulateMediaFeatures.secondCall,
          [
            {name: 'prefers-color-scheme', value: ''},
            {name: 'forced-colors', value: ''},
            {name: 'prefers-contrast', value: 'less'},
            {name: 'prefers-reduced-motion', value: ''},
          ],
        );
      });
    });

    it('calls setViewport with the given dimensions merged with defaults', async () => {
      const {mcpPage, pptrPage} = await createMcpPage();
      await mcpPage.emulate({
        viewport: {
          width: 400,
          height: 400,
        },
      });
      assert.deepStrictEqual(mcpPage.viewport, {
        width: 400,
        height: 400,
        deviceScaleFactor: 1,
        isMobile: false,
        hasTouch: false,
        isLandscape: false,
      });
      sinon.assert.calledOnceWithExactly(pptrPage.setViewport, {
        width: 400,
        height: 400,
        deviceScaleFactor: 1,
        isMobile: false,
        hasTouch: false,
        isLandscape: false,
      });
    });

    it('calls setViewport(null) when viewport is omitted', async () => {
      const {mcpPage, pptrPage} = await createMcpPage();
      await mcpPage.emulate({viewport: {width: 400, height: 400}});
      await mcpPage.emulate({});
      assert.strictEqual(mcpPage.viewport, null);
      sinon.assert.calledTwice(pptrPage.setViewport);
      sinon.assert.calledWithExactly(pptrPage.setViewport.secondCall, null);
    });

    it('does not store a viewport that setViewport rejects', async () => {
      const {mcpPage, pptrPage} = await createMcpPage();
      pptrPage.setViewport.rejects(new Error('Invalid parameters'));

      await assert.rejects(
        () => mcpPage.emulate({viewport: {width: 800.5, height: 600}}),
        /Invalid parameters/,
      );

      assert.strictEqual(mcpPage.viewport, null);
    });

    it('keeps the previous viewport when setViewport rejects a new one', async () => {
      const {mcpPage, pptrPage} = await createMcpPage();
      await mcpPage.emulate({viewport: {width: 400, height: 400}});
      pptrPage.setViewport.rejects(new Error('Invalid parameters'));

      await assert.rejects(
        () =>
          mcpPage.emulate({
            viewport: {width: 20000000, height: 600},
            cpuThrottlingRate: 4,
          }),
        /Invalid parameters/,
      );

      assert.deepStrictEqual(mcpPage.viewport, {
        width: 400,
        height: 400,
        deviceScaleFactor: 1,
        isMobile: false,
        hasTouch: false,
        isLandscape: false,
      });
      assert.strictEqual(mcpPage.cpuThrottlingRate, 4);
    });

    it('calls setExtraHTTPHeaders with the given headers', async () => {
      const {mcpPage, pptrPage} = await createMcpPage();
      await mcpPage.emulate({
        extraHttpHeaders: {'X-Custom-Header': 'test-value'},
      });
      assert.deepStrictEqual(mcpPage.emulationSettings.extraHttpHeaders, {
        'X-Custom-Header': 'test-value',
      });
      sinon.assert.calledOnceWithExactly(pptrPage.setExtraHTTPHeaders, {
        'X-Custom-Header': 'test-value',
      });
    });

    it('clears extraHttpHeaders when empty object is passed', async () => {
      const {mcpPage, pptrPage} = await createMcpPage();
      await mcpPage.emulate({
        extraHttpHeaders: {'X-Custom-Header': 'test-value'},
      });
      await mcpPage.emulate({extraHttpHeaders: {}});
      assert.strictEqual(mcpPage.emulationSettings.extraHttpHeaders, undefined);
      sinon.assert.calledTwice(pptrPage.setExtraHTTPHeaders);
      sinon.assert.calledWithExactly(
        pptrPage.setExtraHTTPHeaders.secondCall,
        {},
      );
    });
  });

  describe('restoreEmulation()', () => {
    it('re-applies previously configured viewport emulation', async () => {
      const {mcpPage, pptrPage} = await createMcpPage();
      await mcpPage.emulate({
        viewport: {
          width: 400,
          height: 400,
          deviceScaleFactor: 1,
          isMobile: false,
          hasTouch: false,
          isLandscape: false,
        },
      });
      sinon.assert.calledOnce(pptrPage.setViewport);

      await mcpPage.restoreEmulation();

      // A different width first, because Chrome ignores an override that is
      // identical to the last one of this session (see restoreEmulation).
      sinon.assert.calledThrice(pptrPage.setViewport);
      sinon.assert.calledWithExactly(pptrPage.setViewport.secondCall, {
        width: 399,
        height: 400,
        deviceScaleFactor: 1,
        isMobile: false,
        hasTouch: false,
        isLandscape: false,
      });
      sinon.assert.calledWithExactly(pptrPage.setViewport.thirdCall, {
        width: 400,
        height: 400,
        deviceScaleFactor: 1,
        isMobile: false,
        hasTouch: false,
        isLandscape: false,
      });
    });

    it('does not send a scratch viewport when none was configured', async () => {
      const {mcpPage, pptrPage} = await createMcpPage();
      await mcpPage.emulate({cpuThrottlingRate: 4});
      pptrPage.setViewport.resetHistory();

      await mcpPage.restoreEmulation();

      sinon.assert.calledOnceWithExactly(pptrPage.setViewport, null);
    });

    it('re-applies previously configured network and cpu throttling emulation', async () => {
      const {mcpPage, pptrPage} = await createMcpPage();
      await mcpPage.emulate({
        networkConditions: 'Slow 3G',
        cpuThrottlingRate: 4,
      });
      sinon.assert.calledOnce(pptrPage.emulateNetworkConditions);
      sinon.assert.calledOnce(pptrPage.emulateCPUThrottling);

      await mcpPage.restoreEmulation();

      sinon.assert.calledTwice(pptrPage.emulateNetworkConditions);
      sinon.assert.calledTwice(pptrPage.emulateCPUThrottling);
    });
  });

  describe('clearNetworkConditions()', () => {
    it('clears networkConditions and updates timeouts while keeping other emulation settings', async () => {
      const config = createMockServerConfig();
      const {mcpPage, pptrPage} = await createMcpPage({config});
      await mcpPage.emulate({
        networkConditions: 'Slow 3G',
        cpuThrottlingRate: 2,
      });
      pptrPage.emulateNetworkConditions.resetHistory();
      pptrPage.setDefaultTimeout.resetHistory();
      pptrPage.setDefaultNavigationTimeout.resetHistory();
      config.commit(
        createMockServerConfig({
          blockedUrlPattern: ['https://example.com/*'],
        }),
      );

      await mcpPage.clearNetworkConditions();

      assert.strictEqual(mcpPage.networkConditions, null);
      assert.strictEqual(mcpPage.cpuThrottlingRate, 2);
      sinon.assert.calledOnceWithExactly(
        pptrPage.emulateNetworkConditions,
        null,
      );
      sinon.assert.calledOnceWithExactly(pptrPage.setDefaultTimeout, 10_000);
      sinon.assert.calledOnceWithExactly(
        pptrPage.setDefaultNavigationTimeout,
        20_000,
      );
      await mcpPage.restoreEmulation();
    });

    it('does nothing when networkConditions is not set', async () => {
      const {mcpPage, pptrPage} = await createMcpPage();
      pptrPage.setDefaultTimeout.resetHistory();
      pptrPage.setDefaultNavigationTimeout.resetHistory();

      await mcpPage.clearNetworkConditions();

      sinon.assert.notCalled(pptrPage.emulateNetworkConditions);
      sinon.assert.notCalled(pptrPage.setDefaultTimeout);
      sinon.assert.notCalled(pptrPage.setDefaultNavigationTimeout);
    });
  });

  describe('getNetworkRequests', () => {
    it('delegates to networkCollector.getData with includePreservedRequests', async () => {
      const {mcpPage} = await createMcpPage();
      const stub = sinon.stub(mcpPage.networkCollector, 'getData').returns([]);

      mcpPage.getNetworkRequests(true);
      sinon.assert.calledOnceWithExactly(stub, true);

      mcpPage.getNetworkRequests(false);
      sinon.assert.calledWithExactly(stub.secondCall, false);

      mcpPage.getNetworkRequests();
      sinon.assert.calledWithExactly(stub.thirdCall, undefined);
    });
  });

  describe('getNetworkRequestById', () => {
    it('delegates to networkCollector.getById', async () => {
      const {mcpPage} = await createMcpPage();
      const mockRequest = getMockRequest();
      const stub = sinon
        .stub(mcpPage.networkCollector, 'getById')
        .returns(mockRequest);

      const result = mcpPage.getNetworkRequestById(42);
      sinon.assert.calledOnceWithExactly(stub, 42);
      assert.strictEqual(result, mockRequest);
    });
  });

  describe('network collection with redirects', () => {
    const server = serverHooks();

    it('collects real browser requests across server-side and client-side redirects', async () => {
      server.addRoute('/redirect', async (_req, res) => {
        res.writeHead(302, {
          Location: server.getRoute('/redirected'),
        });
        res.end();
      });

      server.addHtmlRoute(
        '/redirected',
        html`<script>
          document.location.href = '/redirected-page';
        </script>`,
      );

      server.addHtmlRoute('/redirected-page', html`<main>Redirected</main>`);

      await withMcpContext(async (_response, context) => {
        const mcpPage = context.getSelectedMcpPage();
        await mcpPage.setUpNetworkCollectorForTesting();
        const page = mcpPage.pptrPage;

        await page.goto(server.getRoute('/redirect'), {
          waitUntil: 'networkidle0',
        });

        const requests = mcpPage.getNetworkRequests(true);
        const urls = requests.map(req => req.url());

        assert.ok(urls.some(url => url.includes('/redirect')));
        assert.ok(urls.some(url => url.includes('/redirected')));
        assert.ok(urls.some(url => url.includes('/redirected-page')));
      });
    });
  });

  describe('waitForTextOnPage()', () => {
    it('finds text on the page', async () => {
      await withMcpContext(async (_response, context) => {
        const mcpPage = context.getSelectedMcpPage();
        const page = mcpPage.pptrPage;

        await page.setContent(
          html`<main><span>Hello</span><span> </span><div>World</div></main>`,
        );

        const element = await mcpPage.waitForTextOnPage(['Hello']);
        assert.ok(element);
      });
    });

    it('works with any-match array', async () => {
      await withMcpContext(async (_response, context) => {
        const mcpPage = context.getSelectedMcpPage();
        const page = mcpPage.pptrPage;

        await page.setContent(
          html`<main><span>Status</span><div>Error</div></main>`,
        );

        const element = await mcpPage.waitForTextOnPage(['Complete', 'Error']);
        assert.ok(element);
      });
    });

    it('works with any-match array when element shows up later', async () => {
      await withMcpContext(async (_response, context) => {
        const mcpPage = context.getSelectedMcpPage();
        const page = mcpPage.pptrPage;

        const waitPromise = mcpPage.waitForTextOnPage(['Complete', 'Error']);

        await page.setContent(
          html`<main
            ><span>Hello</span><span> </span><div>Complete</div></main
          >`,
        );

        const element = await waitPromise;
        assert.ok(element);
      });
    });

    it('works with element that shows up later', async () => {
      await withMcpContext(async (_response, context) => {
        const mcpPage = context.getSelectedMcpPage();
        const page = mcpPage.pptrPage;

        const waitPromise = mcpPage.waitForTextOnPage(['Hello World']);

        await page.setContent(
          html`<main><span>Hello</span><span> </span><div>World</div></main>`,
        );

        const element = await waitPromise;
        assert.ok(element);
      });
    });

    it('works with aria elements', async () => {
      await withMcpContext(async (_response, context) => {
        const mcpPage = context.getSelectedMcpPage();
        const page = mcpPage.pptrPage;

        await page.setContent(
          html`<main><h1>Header</h1><div>Text</div></main>`,
        );

        const element = await mcpPage.waitForTextOnPage(['Header']);
        assert.ok(element);
      });
    });

    it('works with iframe content', async () => {
      await withMcpContext(async (_response, context) => {
        const mcpPage = context.getSelectedMcpPage();
        const page = mcpPage.pptrPage;

        await page.setContent(
          html`<h1>Top level</h1>
            <iframe srcdoc="<p>Hello iframe</p>"></iframe>`,
        );

        const element = await mcpPage.waitForTextOnPage(['Hello iframe']);
        assert.ok(element);
      });
    });

    it('preserves default matching for hidden DOM text', async () => {
      await withMcpContext(async (_response, context) => {
        const mcpPage = context.getSelectedMcpPage();
        await mcpPage.pptrPage.setContent(
          '<p style="display:none">Saved successfully</p>',
        );

        const element = await mcpPage.waitForTextOnPage(
          ['Saved successfully'],
          {timeout: 500},
        );
        assert.ok(element);
      });
    });

    it('waits for hidden text to become visible when requested', async () => {
      await withMcpContext(async (_response, context) => {
        const mcpPage = context.getSelectedMcpPage();
        const page = mcpPage.pptrPage;
        await page.setContent(
          '<p id="saved" style="display:none">Saved successfully</p>',
        );

        await page.evaluate(() => {
          setTimeout(() => {
            document.getElementById('saved')!.style.display = 'block';
          }, 250);
        });
        const element = await mcpPage.waitForTextOnPage(
          ['Saved successfully'],
          {timeout: 1500, visible: true},
        );
        assert.ok(element);
      });
    });

    it('times out when visible text never appears', async () => {
      await withMcpContext(async (_response, context) => {
        const mcpPage = context.getSelectedMcpPage();
        await mcpPage.pptrPage.setContent(
          '<p style="display:none">Saved successfully</p>',
        );

        await assert.rejects(
          mcpPage.waitForTextOnPage(['Saved successfully'], {
            timeout: 300,
            visible: true,
          }),
          /Timed out/,
        );
      });
    });

    it('visible text remains immediately matchable when requested', async () => {
      await withMcpContext(async (_response, context) => {
        const mcpPage = context.getSelectedMcpPage();
        await mcpPage.pptrPage.setContent('<p>Visible from the start</p>');
        assert.ok(
          await mcpPage.waitForTextOnPage(['Visible from the start'], {
            timeout: 500,
            visible: true,
          }),
        );
      });
    });

    it('finds text in an iframe attached while waiting', async () => {
      await withMcpContext(async (_response, context) => {
        const mcpPage = context.getSelectedMcpPage();
        const page = mcpPage.pptrPage;
        await page.setContent('<main>Waiting for the frame</main>');

        const listenersBefore = page.listenerCount('frameattached');
        const waitPromise = mcpPage.waitForTextOnPage(
          ['Arrived in a late iframe'],
          {timeout: 1500},
        );
        await page.evaluate(() => {
          const frame = document.createElement('iframe');
          frame.srcdoc = '<p>Arrived in a late iframe</p>';
          document.body.appendChild(frame);
        });

        const element = await waitPromise;
        assert.ok(element);
        assert.strictEqual(
          page.listenerCount('frameattached'),
          listenersBefore,
        );
      });
    });

    it('cleans the frame listener after a timed out wait', async () => {
      await withMcpContext(async (_response, context) => {
        const mcpPage = context.getSelectedMcpPage();
        const page = mcpPage.pptrPage;
        await page.setContent('<main>No matching text</main>');

        const listenersBefore = page.listenerCount('frameattached');
        await assert.rejects(
          mcpPage.waitForTextOnPage(['Text that never appears'], {
            timeout: 250,
          }),
        );
        assert.strictEqual(
          page.listenerCount('frameattached'),
          listenersBefore,
        );
      });
    });

    it('applies visible matching to frames attached while waiting', async () => {
      const {mcpPage, pptrPage} = await createMcpPage();
      pptrPage.frames.returns([]);
      const initialRace = Locator.race([]);
      sinon.stub(initialRace, 'wait').returns(new Promise(() => {}));
      const lateRace = Locator.race([]);
      const lateRaceSetTimeout = sinon
        .stub(lateRace, 'setTimeout')
        .returns(lateRace);
      sinon.stub(lateRace, 'wait').resolves();
      const race = sinon.stub(Locator, 'race');
      race.onFirstCall().returns(initialRace);
      race.onSecondCall().returns(lateRace);
      const frameLocator = sinon.createStubInstance<Locator<Element>>(Locator);
      frameLocator.setVisibility.returns(frameLocator);
      const lateFrame = sinon.createStubInstance(Frame);
      lateFrame.locator.returns(frameLocator);

      const waitPromise = mcpPage.waitForTextOnPage(['Saved'], {visible: true});
      pptrPage.emit('frameattached', lateFrame);
      await waitPromise;

      sinon.assert.calledWithExactly(lateFrame.locator.firstCall, 'aria/Saved');
      sinon.assert.calledWithExactly(
        lateFrame.locator.secondCall,
        'text/Saved',
      );
      sinon.assert.calledTwice(frameLocator.setVisibility);
      sinon.assert.alwaysCalledWithExactly(
        frameLocator.setVisibility,
        'visible',
      );
      sinon.assert.calledOnceWithExactly(lateRaceSetTimeout, 0);
    });
  });

  describe('DevToolsCommentBridge lifecycle', () => {
    it('does not create commentBridge on construction or getDevToolsPage', async () => {
      const {mcpPage, pptrPage} = await createMcpPage({
        config: createMockServerConfig({devtoolsComments: true}),
      });
      pptrPage.hasDevTools.resolves(true);
      const devtoolsPage = createMockPuppeteerPage();
      pptrPage.openDevTools.resolves(devtoolsPage);

      assert.strictEqual(mcpPage.commentBridge, undefined);

      const retrieved = await mcpPage.getDevToolsPage();
      assert.strictEqual(retrieved, devtoolsPage);
      assert.strictEqual(mcpPage.commentBridge, undefined);
    });

    it('waits for the DevTools universe when openDevTools is called', async () => {
      const {mcpPage, pptrPage} = await createMcpPage({
        config: createMockServerConfig({devtoolsComments: true}),
      });
      const devtoolsPage = createMockPuppeteerPage();
      pptrPage.openDevTools.resolves(devtoolsPage);

      const result = await mcpPage.openDevTools();

      assert.strictEqual(result, devtoolsPage);
      sinon.assert.calledOnceWithMatch(
        devtoolsPage.waitForFunction,
        sinon.match.func,
        {timeout: 5_000},
      );
      sinon.assert.callOrder(
        pptrPage.openDevTools,
        devtoolsPage.waitForFunction,
      );
      assert.strictEqual(mcpPage.commentBridge, undefined);
      sinon.assert.notCalled(devtoolsPage.exposeFunction);
    });

    it('returns the DevTools page when the DevTools universe wait times out', async () => {
      const {mcpPage, pptrPage} = await createMcpPage();
      const devtoolsPage = createMockPuppeteerPage();
      devtoolsPage.waitForFunction.rejects(new Error('Timed out'));
      pptrPage.openDevTools.resolves(devtoolsPage);

      const result = await mcpPage.openDevTools();

      assert.strictEqual(result, devtoolsPage);
    });

    it('returns the commentBridge when the DevTools page has a CD4A bridge', async () => {
      const {mcpPage} = await createMcpPage();
      const devtoolsPage = createMockPuppeteerPage();
      devtoolsPage.evaluate.resolves(true);

      const bridge = await mcpPage.ensureDevToolsCommentBridge(devtoolsPage);

      assert.notStrictEqual(bridge, undefined);
      assert.strictEqual(bridge, mcpPage.commentBridge);
    });

    it('returns undefined when the DevTools page has no CD4A bridge', async () => {
      const {mcpPage} = await createMcpPage();
      const devtoolsPage = createMockPuppeteerPage();
      devtoolsPage.evaluate.resolves(false);

      const bridge = await mcpPage.ensureDevToolsCommentBridge(devtoolsPage);

      assert.strictEqual(bridge, undefined);
      sinon.assert.notCalled(devtoolsPage.exposeFunction);
    });

    it('disposes commentBridge on mcpPage.dispose()', async () => {
      const {mcpPage, pptrPage} = await createMcpPage({
        config: createMockServerConfig({devtoolsComments: true}),
      });
      const devtoolsPage = createMockPuppeteerPage();
      pptrPage.openDevTools.resolves(devtoolsPage);

      await mcpPage.ensureDevToolsCommentBridge(devtoolsPage);
      const bridge = mcpPage.commentBridge;
      assert.ok(bridge);

      const disposeSpy = sinon.spy(bridge, 'dispose');
      mcpPage.dispose();

      sinon.assert.calledOnce(disposeSpy);
      assert.strictEqual(mcpPage.commentBridge, undefined);
    });

    it('creates and attaches commentBridge when getDevToolsData is called', async () => {
      const {mcpPage, pptrPage} = await createMcpPage({
        config: createMockServerConfig({devtoolsComments: true}),
      });
      pptrPage.hasDevTools.resolves(true);
      const devtoolsPage = createMockPuppeteerPage();
      devtoolsPage.evaluate.resolves(true);
      devtoolsPage.evaluate.onThirdCall().resolves({
        cdpRequestId: 'req-1',
        cdpBackendNodeId: 10,
      });
      pptrPage.openDevTools.resolves(devtoolsPage);

      assert.strictEqual(mcpPage.commentBridge, undefined);

      const data = await mcpPage.getDevToolsData();
      assert.deepStrictEqual(data, {
        cdpRequestId: 'req-1',
        cdpBackendNodeId: 10,
      });
      assert.notStrictEqual(mcpPage.commentBridge, undefined);
      sinon.assert.calledOnce(devtoolsPage.exposeFunction);
      sinon.assert.calledThrice(devtoolsPage.evaluate);
    });

    it('disposes and clears commentBridge on mcpPage.disposeCommentBridge()', async () => {
      const {mcpPage, pptrPage} = await createMcpPage({
        config: createMockServerConfig({devtoolsComments: true}),
      });
      const devtoolsPage = createMockPuppeteerPage();
      pptrPage.openDevTools.resolves(devtoolsPage);

      await mcpPage.ensureDevToolsCommentBridge(devtoolsPage);
      const bridge = mcpPage.commentBridge;
      assert.ok(bridge);

      const disposeSpy = sinon.spy(bridge, 'dispose');
      mcpPage.disposeCommentBridge();

      sinon.assert.calledOnceWithExactly(disposeSpy);
      assert.strictEqual(mcpPage.commentBridge, undefined);
    });

    it('does not re-attach commentBridge in getDevToolsData() when devtoolsComments is disabled', async () => {
      const config = createMockServerConfig({devtoolsComments: true});
      const {mcpPage, pptrPage} = await createMcpPage({config});
      pptrPage.hasDevTools.resolves(true);
      const devtoolsPage = createMockPuppeteerPage();
      devtoolsPage.evaluate.resolves(true);
      pptrPage.openDevTools.resolves(devtoolsPage);

      await mcpPage.ensureDevToolsCommentBridge(devtoolsPage);
      assert.notStrictEqual(mcpPage.commentBridge, undefined);

      config.commit(createMockServerConfig());
      mcpPage.disposeCommentBridge();
      assert.strictEqual(mcpPage.commentBridge, undefined);
      devtoolsPage.exposeFunction.resetHistory();
      devtoolsPage.evaluate.reset();
      devtoolsPage.evaluate.resolves({
        cdpRequestId: 'req-2',
        cdpBackendNodeId: 20,
      });

      const data = await mcpPage.getDevToolsData();

      assert.deepStrictEqual(data, {
        cdpRequestId: 'req-2',
        cdpBackendNodeId: 20,
      });
      assert.strictEqual(mcpPage.commentBridge, undefined);
      sinon.assert.notCalled(devtoolsPage.exposeFunction);
      sinon.assert.calledOnce(devtoolsPage.evaluate);
    });

    it('re-attaches commentBridge when ensureDevToolsCommentBridge() is called after disposeCommentBridge()', async () => {
      const {mcpPage, pptrPage} = await createMcpPage({
        config: createMockServerConfig({devtoolsComments: true}),
      });
      const devtoolsPage = createMockPuppeteerPage();
      devtoolsPage.evaluate.resolves(true);
      pptrPage.openDevTools.resolves(devtoolsPage);

      await mcpPage.ensureDevToolsCommentBridge(devtoolsPage);
      mcpPage.disposeCommentBridge();
      assert.strictEqual(mcpPage.commentBridge, undefined);

      const bridge = await mcpPage.ensureDevToolsCommentBridge(devtoolsPage);

      assert.notStrictEqual(bridge, undefined);
      assert.strictEqual(bridge, mcpPage.commentBridge);
    });
  });

  describe('syncSourceMaps()', () => {
    it('does nothing before init() initializes the DevTools universe', () => {
      const config = createMockServerConfig({sourceMaps: false});
      const target = createMockPuppeteerTarget();
      const mcpPage = new McpPage(target, 1, {
        config,
        locatorClass: Locator,
      });

      mcpPage.syncSourceMaps();

      assert.strictEqual(mcpPage.devtoolsUniverse, undefined);
      sinon.assert.notCalled(target.page);
    });

    it('updates JS and CSS source map settings on an initialized DevTools universe', async () => {
      const config = createMockServerConfig();
      const pptrPage = createMockPuppeteerPage();
      pptrPage.createCDPSession.resolves(createMockCDPSession());
      const target = createMockPuppeteerTarget({page: pptrPage});
      const mcpPage = new McpPage(target, 1, {
        config,
        locatorClass: Locator,
      });
      await mcpPage.init();

      config.commit(createMockServerConfig({sourceMaps: false}));
      mcpPage.syncSourceMaps();

      const settings = mcpPage.devtoolsUniverse?.universe.settings;
      assert.ok(settings);
      assert.strictEqual(
        settings
          .resolve(DevTools.SDKSettings.jsSourceMapsEnabledSettingDescriptor)
          .get(),
        false,
      );
      assert.strictEqual(
        settings
          .resolve(DevTools.SDKSettings.cssSourceMapsEnabledSettingDescriptor)
          .get(),
        false,
      );
    });

    it('reads updated sourceMaps from config when initialized later', async () => {
      const config = createMockServerConfig();
      const pptrPage = createMockPuppeteerPage();
      pptrPage.createCDPSession.resolves(createMockCDPSession());
      const target = createMockPuppeteerTarget({page: pptrPage});
      const mcpPage = new McpPage(target, 1, {
        config,
        locatorClass: Locator,
      });

      config.commit(createMockServerConfig({sourceMaps: false}));
      await mcpPage.init();

      const settings = mcpPage.devtoolsUniverse?.universe.settings;
      assert.ok(settings);
      assert.strictEqual(
        settings
          .resolve(DevTools.SDKSettings.jsSourceMapsEnabledSettingDescriptor)
          .get(),
        false,
      );
      assert.strictEqual(
        settings
          .resolve(DevTools.SDKSettings.cssSourceMapsEnabledSettingDescriptor)
          .get(),
        false,
      );
    });
  });

  describe('resolveBackendNodeId()', () => {
    function createSnapshotWithNodes(
      nodes: Array<{id: string; backendNodeId?: number}>,
      verbose = false,
    ): TextSnapshot {
      const idToNode = new Map<string, TextSnapshotNode>();
      const children: TextSnapshotNode[] = [];
      for (const n of nodes) {
        const node: TextSnapshotNode = {
          id: n.id,
          role: 'generic',
          backendNodeId: n.backendNodeId,
          children: [],
          elementHandle: async () => null,
        };
        idToNode.set(n.id, node);
        children.push(node);
      }
      const rootNode: TextSnapshotNode = {
        id: '1_0',
        role: 'root',
        children,
        elementHandle: async () => null,
      };
      return new TextSnapshot({
        root: rootNode,
        idToNode,
        snapshotId: '1',
        hasSelectedElement: false,
        verbose,
      });
    }

    it('returns uid from existing textSnapshot without regenerating', async () => {
      const {mcpPage} = await createMcpPage();
      mcpPage.textSnapshot = createSnapshotWithNodes([
        {id: '1_1', backendNodeId: 42},
      ]);
      const createStub = sinon.stub(TextSnapshot, 'create');

      const uid = await mcpPage.resolveBackendNodeId(42);

      assert.strictEqual(uid, '1_1');
      sinon.assert.notCalled(createStub);
    });

    it('creates textSnapshot when textSnapshot is null', async () => {
      const {mcpPage} = await createMcpPage();
      const snapshot = createSnapshotWithNodes([
        {id: '1_1', backendNodeId: 42},
      ]);
      const createStub = sinon.stub(TextSnapshot, 'create').resolves(snapshot);

      const uid = await mcpPage.resolveBackendNodeId(42);

      assert.strictEqual(uid, '1_1');
      sinon.assert.calledOnceWithExactly(createStub, mcpPage, {verbose: false});
      assert.strictEqual(mcpPage.textSnapshot, snapshot);
    });

    it('regenerates textSnapshot when backendNodeId is not in existing snapshot', async () => {
      const {mcpPage} = await createMcpPage();
      mcpPage.textSnapshot = createSnapshotWithNodes([
        {id: '1_1', backendNodeId: 10},
      ]);
      const updatedSnapshot = createSnapshotWithNodes([
        {id: '2_1', backendNodeId: 42},
      ]);
      const createStub = sinon
        .stub(TextSnapshot, 'create')
        .resolves(updatedSnapshot);

      const uid = await mcpPage.resolveBackendNodeId(42);

      assert.strictEqual(uid, '2_1');
      sinon.assert.calledOnceWithExactly(createStub, mcpPage, {verbose: false});
      assert.strictEqual(mcpPage.textSnapshot, updatedSnapshot);
    });

    it('falls back to verbose textSnapshot when backendNodeId is not in non-verbose snapshot', async () => {
      const {mcpPage} = await createMcpPage();
      const nonVerboseSnapshot = createSnapshotWithNodes(
        [{id: '1_1', backendNodeId: 10}],
        false,
      );
      const verboseSnapshot = createSnapshotWithNodes(
        [{id: '2_5', backendNodeId: 30}],
        true,
      );
      const createStub = sinon.stub(TextSnapshot, 'create');
      createStub.onFirstCall().resolves(nonVerboseSnapshot);
      createStub.onSecondCall().resolves(verboseSnapshot);

      const uid = await mcpPage.resolveBackendNodeId(30);

      assert.strictEqual(uid, '2_5');
      sinon.assert.calledTwice(createStub);
      sinon.assert.calledWithExactly(createStub.firstCall, mcpPage, {
        verbose: false,
      });
      sinon.assert.calledWithExactly(createStub.secondCall, mcpPage, {
        verbose: true,
      });
      assert.strictEqual(mcpPage.textSnapshot, verboseSnapshot);
    });
  });

  describe('getMatchedStylesForUid()', () => {
    const server = serverHooks();

    function getSelectors(
      matchedStyles: DevTools.CSSMatchedStyles.CSSMatchedStyles,
    ): string[] {
      const styles = matchedStyles.nodeStyles();
      assert.ok(styles.length > 0);
      const selectors: string[] = [];
      for (const s of styles) {
        if (s.parentRule instanceof DevTools.CSSRule.CSSStyleRule) {
          selectors.push(s.parentRule.selectorText());
        }
      }
      return selectors;
    }

    async function getSelectorsForUid(
      uid: string,
      mcpPage: McpPage,
    ): Promise<string[]> {
      const matchedStyles = await mcpPage.getMatchedStylesForUid(uid);
      assert.ok(matchedStyles);
      return getSelectors(matchedStyles);
    }

    it('throws when snapshot has not been captured', async () => {
      const {mcpPage} = await createMcpPage();
      await assert.rejects(
        () => mcpPage.getMatchedStylesForUid('node_1'),
        /No snapshot found for page/,
      );
    });

    it('throws when element uid is not found in snapshot', async () => {
      const {mcpPage} = await createMcpPage();
      const rootNode: TextSnapshotNode = {
        id: '1_0',
        role: 'root',
        children: [],
        elementHandle: async () => null,
      };
      mcpPage.textSnapshot = new TextSnapshot({
        root: rootNode,
        idToNode: new Map<string, TextSnapshotNode>(),
        snapshotId: '1',
        hasSelectedElement: false,
        verbose: false,
      });
      await assert.rejects(
        () => mcpPage.getMatchedStylesForUid('node_1'),
        /Element uid "node_1" not found on page/,
      );
    });

    it('throws when element has no backendNodeId', async () => {
      const {mcpPage} = await createMcpPage();
      const node: TextSnapshotNode = {
        id: '1_1',
        role: 'button',
        children: [],
        elementHandle: async () => null,
      };
      const idToNode = new Map<string, TextSnapshotNode>([['node_1', node]]);
      mcpPage.textSnapshot = new TextSnapshot({
        root: node,
        idToNode,
        snapshotId: '1',
        hasSelectedElement: false,
        verbose: false,
      });
      await assert.rejects(
        () => mcpPage.getMatchedStylesForUid('node_1'),
        /Failed to resolve backend node ID for element with uid "node_1"/,
      );
    });

    it('retrieves matched styles across elements, shadow roots, and iframes', async () => {
      server.addHtmlRoute(
        '/iframe_content.html',
        html`
          <style>
            .frame-btn {
              background-color: purple;
              color: white;
            }
          </style>
          <button
            id="iframe-btn"
            class="frame-btn"
            >Iframe Button</button
          >
        `,
      );
      server.addHtmlRoute(
        '/styles_combined_test.html',
        html`
          <style>
            .btn-primary {
              color: blue;
              font-size: 14px;
            }
            #my-button {
              color: green;
            }
          </style>
          <button
            id="my-button"
            class="btn-primary"
            style="font-size: 16px; padding: 8px;"
          >
            Click Me
          </button>
          <div id="open-host"></div>
          <div id="closed-host"></div>
          <iframe
            id="child-frame"
            src="/iframe_content.html"
          ></iframe>
          <script>
            const openHost = document.getElementById('open-host');
            const openRoot = openHost.attachShadow({mode: 'open'});
            openRoot.innerHTML = \`
              <style>
                .shadow-btn-open {
                  color: rgb(100, 200, 50);
                }
              </style>
              <button class="shadow-btn-open">Open Shadow Button</button>
            \`;

            const closedHost = document.getElementById('closed-host');
            const closedRoot = closedHost.attachShadow({mode: 'closed'});
            closedRoot.innerHTML = \`
              <style>
                .shadow-btn-closed {
                  color: rgb(200, 50, 100);
                }
              </style>
              <button class="shadow-btn-closed">Closed Shadow Button</button>
            \`;
          </script>
        `,
      );

      await withMcpContext(async (_, context) => {
        const mcpPage = context.getSelectedMcpPage();
        await mcpPage.pptrPage.goto(
          server.getRoute('/styles_combined_test.html'),
        );
        const frame = await mcpPage.pptrPage.waitForFrame(
          f => f.url() === server.getRoute('/iframe_content.html'),
        );
        if (!frame) {
          throw new Error('Child frame not found');
        }
        await frame.waitForSelector('#iframe-btn');

        mcpPage.textSnapshot = await TextSnapshot.create(mcpPage);

        // 1. Regular element
        {
          const uid = getUidForNode(mcpPage, 'Click Me');
          const matchedStyles = await mcpPage.getMatchedStylesForUid(uid);
          const inlineStyle = matchedStyles
            .nodeStyles()
            .find(s => s.type === DevTools.CSSStyleDeclaration.Type.Inline);
          assert.ok(inlineStyle);
          const selectors = getSelectors(matchedStyles);
          assert.ok(selectors.includes('#my-button'));
          assert.ok(selectors.includes('.btn-primary'));
        }

        // 2. Open shadow root
        {
          const uid = getUidForNode(mcpPage, 'Open Shadow Button');
          const selectors = await getSelectorsForUid(uid, mcpPage);
          assert.ok(selectors.includes('.shadow-btn-open'));
        }

        // 3. Closed shadow root
        {
          const uid = getUidForNode(mcpPage, 'Closed Shadow Button');
          const selectors = await getSelectorsForUid(uid, mcpPage);
          assert.ok(selectors.includes('.shadow-btn-closed'));
        }

        // 4. Iframe
        {
          const uid = getUidForNode(mcpPage, 'Iframe Button');
          const selectors = await getSelectorsForUid(uid, mcpPage);
          assert.ok(selectors.includes('.frame-btn'));
        }
      });
    });
  });

  describe('executeThirdPartyDeveloperTool()', () => {
    it('appends "Tool returned no result." and skips cleanup evaluate when the tool returns undefined and stashed is 0', async () => {
      const {mcpPage, pptrPage} = await createMcpPage();
      const response = createMockMcpResponse();
      pptrPage.evaluate.resolves({result: undefined, stashed: 0});

      await mcpPage.executeThirdPartyDeveloperTool('my-tool', {}, response);

      sinon.assert.calledOnce(pptrPage.evaluate);
      sinon.assert.calledOnceWithExactly(
        response.appendResponseLine,
        'Tool returned no result.',
      );
    });

    it('preserves the original evaluateHandle error when stashedElements cleanup fails', async () => {
      const {mcpPage, pptrPage} = await createMcpPage();
      const response = createMockMcpResponse();
      pptrPage.evaluate
        .onFirstCall()
        .resolves({result: '{"stashedId":"stashed-0"}', stashed: 1});
      pptrPage.evaluateHandle.rejects(
        new Error('Execution context was destroyed'),
      );
      pptrPage.evaluate.onSecondCall().rejects(new Error('Target closed'));

      await assert.rejects(
        () => mcpPage.executeThirdPartyDeveloperTool('my-tool', {}, response),
        /Execution context was destroyed/,
      );

      sinon.assert.calledTwice(pptrPage.evaluate);
      sinon.assert.notCalled(response.appendResponseLine);
    });
  });

  describe('WebMCP third-party developer tools', () => {
    it('filters WebMCP tools by annotations.debugging in discoverThirdPartyDeveloperTools()', async () => {
      const {mcpPage, pptrPage} = await createMcpPage();

      const debuggingTool = createMockWebMCPTool({
        name: 'debug_tool',
        description: 'A debugging WebMCP tool',
        inputSchema: {type: 'object'},
        annotations: {debugging: true},
      });
      const nonDebuggingTool = createMockWebMCPTool({
        name: 'user_tool',
        description: 'A non-debugging WebMCP tool',
        inputSchema: {type: 'object'},
        annotations: {debugging: false},
      });
      const unannotatedTool = createMockWebMCPTool({
        name: 'legacy_webmcp_tool',
        description: 'A WebMCP tool without debugging annotation',
        inputSchema: {type: 'object'},
      });
      pptrPage.webmcp.tools.returns([
        debuggingTool,
        nonDebuggingTool,
        unannotatedTool,
      ]);

      const groups = await mcpPage.discoverThirdPartyDeveloperTools();
      assert.deepStrictEqual(groups, [
        {
          name: 'WebMCP Tools',
          description: 'Tools exposed via WebMCP',
          tools: [
            {
              name: 'debug_tool',
              description: 'A debugging WebMCP tool',
              inputSchema: {type: 'object'},
            },
          ],
        },
      ]);
    });

    it('combines WebMCP debugging tools and devtoolstooldiscovery tools in discoverThirdPartyDeveloperTools()', async () => {
      const {mcpPage, pptrPage} = await createMcpPage();

      const debuggingTool = createMockWebMCPTool({
        name: 'debug_tool',
        description: 'A debugging WebMCP tool',
        annotations: {debugging: true},
      });
      pptrPage.webmcp.tools.returns([debuggingTool]);
      pptrPage.cdpSession.send.resolves({
        listeners: [{type: 'devtoolstooldiscovery'}],
      });
      pptrPage.evaluate.resolves([
        {
          name: 'Custom Tools',
          description: 'Tools exposed via event',
          tools: [
            {
              name: 'custom_tool',
              description: 'A custom tool',
              inputSchema: {
                type: 'object',
                properties: {
                  el: {
                    'x-mcp-type': 'HTMLElement',
                  },
                },
              },
            },
          ],
        },
      ]);

      const groups = await mcpPage.discoverThirdPartyDeveloperTools();
      assert.deepStrictEqual(groups, [
        {
          name: 'WebMCP Tools',
          description: 'Tools exposed via WebMCP',
          tools: [
            {
              name: 'debug_tool',
              description: 'A debugging WebMCP tool',
              inputSchema: {},
            },
          ],
        },
        {
          name: 'Custom Tools',
          description: 'Tools exposed via event',
          tools: [
            {
              name: 'custom_tool',
              description: 'A custom tool',
              inputSchema: {
                type: 'object',
                properties: {
                  el: {
                    'x-mcp-type': 'HTMLElement',
                    properties: {uid: {type: 'string'}},
                    required: ['uid'],
                  },
                },
              },
            },
          ],
        },
      ]);
    });

    it('reflects dynamically added and removed WebMCP debugging tools in discoverThirdPartyDeveloperTools()', async () => {
      const {mcpPage, pptrPage} = await createMcpPage();

      assert.deepStrictEqual(
        await mcpPage.discoverThirdPartyDeveloperTools(),
        [],
      );

      const debuggingTool = createMockWebMCPTool({
        name: 'dynamic_debug_tool',
        description: 'Added dynamically',
        inputSchema: {type: 'object'},
        annotations: {debugging: true},
      });
      pptrPage.webmcp.tools.returns([debuggingTool]);

      assert.deepStrictEqual(await mcpPage.discoverThirdPartyDeveloperTools(), [
        {
          name: 'WebMCP Tools',
          description: 'Tools exposed via WebMCP',
          tools: [
            {
              name: 'dynamic_debug_tool',
              description: 'Added dynamically',
              inputSchema: {type: 'object'},
            },
          ],
        },
      ]);

      pptrPage.webmcp.tools.returns([]);
      assert.deepStrictEqual(
        await mcpPage.discoverThirdPartyDeveloperTools(),
        [],
      );
    });

    it('executes a WebMCP tool in executeThirdPartyDeveloperTool()', async () => {
      const {mcpPage, pptrPage} = await createMcpPage();
      const mockTool = createMockWebMCPTool({
        name: 'webmcp_tool',
        description: 'A WebMCP tool',
        annotations: {debugging: true},
      });
      mockTool.execute.resolves({
        id: 'call-1',
        status: 'Completed',
        output: {result: 42},
      });
      pptrPage.webmcp.tools.returns([mockTool]);
      const response = createMockMcpResponse();

      await mcpPage.executeThirdPartyDeveloperTool(
        'webmcp_tool',
        {x: 21},
        response,
      );

      sinon.assert.calledOnceWithExactly(mockTool.execute, {x: 21});
      sinon.assert.calledOnceWithExactly(
        response.appendResponseLine,
        JSON.stringify({result: 42}, null, 2),
      );
      sinon.assert.notCalled(pptrPage.evaluate);
    });

    it('appends "Tool returned no result." when WebMCP tool output is undefined in executeThirdPartyDeveloperTool()', async () => {
      const {mcpPage, pptrPage} = await createMcpPage();
      const mockTool = createMockWebMCPTool({
        name: 'webmcp_void_tool',
        annotations: {debugging: true},
      });
      mockTool.execute.resolves({
        id: 'call-1',
        status: 'Completed',
        output: undefined,
      });
      pptrPage.webmcp.tools.returns([mockTool]);
      const response = createMockMcpResponse();

      await mcpPage.executeThirdPartyDeveloperTool(
        'webmcp_void_tool',
        {},
        response,
      );

      sinon.assert.calledOnceWithExactly(mockTool.execute, {});
      sinon.assert.calledOnceWithExactly(
        response.appendResponseLine,
        'Tool returned no result.',
      );
    });

    it('does not execute non-debugging WebMCP tools in executeThirdPartyDeveloperTool()', async () => {
      const {mcpPage, pptrPage} = await createMcpPage();
      const nonDebuggingTool = createMockWebMCPTool({
        name: 'user_tool',
        annotations: {debugging: false},
      });
      pptrPage.webmcp.tools.returns([nonDebuggingTool]);
      pptrPage.evaluate.rejects(new Error('No tools found on the page'));
      const response = createMockMcpResponse();

      await assert.rejects(
        () => mcpPage.executeThirdPartyDeveloperTool('user_tool', {}, response),
        /No tools found on the page/,
      );
      sinon.assert.notCalled(nonDebuggingTool.execute);
    });

    it('throws when WebMCP tool execution fails in executeThirdPartyDeveloperTool()', async () => {
      const {mcpPage, pptrPage} = await createMcpPage();
      const mockTool = createMockWebMCPTool({
        name: 'webmcp_tool',
        annotations: {debugging: true},
      });
      mockTool.execute.resolves({
        id: 'call-1',
        status: 'Error',
        errorText: 'Execution failed in page',
      });
      pptrPage.webmcp.tools.returns([mockTool]);
      const response = createMockMcpResponse();

      await assert.rejects(
        () =>
          mcpPage.executeThirdPartyDeveloperTool('webmcp_tool', {}, response),
        /Execution failed in page/,
      );
    });

    it('throws the exception description when the WebMCP tool throws in executeThirdPartyDeveloperTool()', async () => {
      const {mcpPage, pptrPage} = await createMcpPage();
      const mockTool = createMockWebMCPTool({
        name: 'webmcp_tool',
        annotations: {debugging: true},
      });
      mockTool.execute.resolves({
        id: 'call-1',
        status: 'Error',
        errorText: '',
        exception: {
          type: 'object',
          subtype: 'error',
          className: 'Error',
          description: 'Error: boom\n    at foo (app.js:1:1)',
          objectId: '1',
        },
      });
      pptrPage.webmcp.tools.returns([mockTool]);
      const response = createMockMcpResponse();

      await assert.rejects(
        () =>
          mcpPage.executeThirdPartyDeveloperTool('webmcp_tool', {}, response),
        {message: 'Error: boom\n    at foo (app.js:1:1)'},
      );
    });

    it('excludes debugging WebMCP tools from getWebMcpTools()', async () => {
      const {mcpPage, pptrPage} = await createMcpPage();

      const debuggingTool = createMockWebMCPTool({
        name: 'debug_tool',
        description: 'A debugging WebMCP tool',
        annotations: {debugging: true},
      });
      const nonDebuggingTool = createMockWebMCPTool({
        name: 'user_tool',
        description: 'A non-debugging WebMCP tool',
        annotations: {debugging: false},
      });
      const unannotatedTool = createMockWebMCPTool({
        name: 'legacy_webmcp_tool',
        description: 'A WebMCP tool without debugging annotation',
      });
      pptrPage.webmcp.tools.returns([
        debuggingTool,
        nonDebuggingTool,
        unannotatedTool,
      ]);

      assert.deepStrictEqual(mcpPage.getWebMcpTools(), [
        nonDebuggingTool,
        unannotatedTool,
      ]);
    });
  });

  describe('dialogs', () => {
    it('returns the dialog and throws when unhandled', async () => {
      const {mcpPage, pptrPage} = await createMcpPage();
      const dialog = createMockDialog({type: 'alert', message: 'hello'});

      pptrPage.emit('dialog', dialog);

      assert.strictEqual(mcpPage.getDialog(), dialog);
      assert.throws(() => mcpPage.throwIfDialogOpen(), {
        message: 'A dialog is open (alert: hello).',
      });
    });

    it('clears the dialog and does not throw when handled', async () => {
      const {mcpPage, pptrPage} = await createMcpPage();
      const dialog = createMockDialog({
        type: 'alert',
        message: 'hello',
        handled: true,
      });

      pptrPage.emit('dialog', dialog);

      assert.strictEqual(mcpPage.getDialog(), undefined);
      assert.doesNotThrow(() => mcpPage.throwIfDialogOpen());
    });
  });

  describe('configureWebAuthn()', () => {
    const DEFAULT_OPTIONS = {
      protocol: DevTools.Protocol.WebAuthn.AuthenticatorProtocol.Ctap2,
      transport: DevTools.Protocol.WebAuthn.AuthenticatorTransport.Internal,
      hasResidentKey: true,
      hasUserVerification: true,
      isUserVerified: true,
      automaticPresenceSimulation: true,
    };
    const CDP_ERROR = 'Could not find a virtual authenticator matching the ID';

    async function createWebAuthnPage() {
      const pptrPage = createMockPuppeteerPage();
      pptrPage.emulateFocusedPage.resolves();
      const mcpPage = new McpPage(
        createMockPuppeteerTarget({page: pptrPage}),
        1,
        {config: createMockServerConfig(), locatorClass: Locator},
      );
      const model = createMockWebAuthnModel();
      let universe: TargetUniverse | undefined =
        createMockTargetUniverse(model);
      sinon.stub(mcpPage, 'devtoolsUniverse').get(() => universe);
      await mcpPage.init();
      return {
        mcpPage,
        model,
        detachUniverse: () => {
          universe = undefined;
        },
      };
    }

    async function assertFailsWithCdpError(
      promise: Promise<unknown>,
    ): Promise<void> {
      await assert.rejects(promise, {
        message: `Failed to configure WebAuthn for page 1: ${CDP_ERROR}`,
      });
    }

    it('creates an authenticator with defaults', async () => {
      const {mcpPage, model} = await createWebAuthnPage();
      model.addAuthenticator.resolves(createMockAuthenticatorId('auth-1'));

      const result = await mcpPage.configureWebAuthn({enabled: true});

      sinon.assert.calledOnceWithExactly(
        model.setVirtualAuthEnvEnabled,
        true,
        false,
      );
      sinon.assert.calledOnceWithExactly(
        model.addAuthenticator,
        DEFAULT_OPTIONS,
      );
      sinon.assert.calledOnceWithExactly(
        model.getCredentials,
        createMockAuthenticatorId('auth-1'),
      );
      assert.deepStrictEqual(result, {
        protocol: 'ctap2',
        transport: 'internal',
        hasResidentKey: true,
        hasUserVerification: true,
        isUserVerified: true,
        credentials: [],
      });
      assert.deepStrictEqual(mcpPage.getWebAuthnAuthenticator(), {
        protocol: 'ctap2',
        transport: 'internal',
        hasResidentKey: true,
        hasUserVerification: true,
        isUserVerified: true,
      });
    });

    it('updates isUserVerified in place and keeps omitted options', async () => {
      const {mcpPage, model} = await createWebAuthnPage();
      model.addAuthenticator.resolves(createMockAuthenticatorId('auth-1'));
      await mcpPage.configureWebAuthn({enabled: true, transport: 'usb'});

      const result = await mcpPage.configureWebAuthn({
        enabled: true,
        isUserVerified: false,
      });

      sinon.assert.calledOnceWithExactly(
        model.setVirtualAuthEnvEnabled,
        true,
        false,
      );
      sinon.assert.calledOnceWithExactly(model.addAuthenticator, {
        ...DEFAULT_OPTIONS,
        transport: DevTools.Protocol.WebAuthn.AuthenticatorTransport.Usb,
      });
      sinon.assert.notCalled(model.removeAuthenticator);
      sinon.assert.calledOnceWithExactly(
        model.setUserVerified,
        createMockAuthenticatorId('auth-1'),
        false,
      );
      assert.strictEqual(result?.transport, 'usb');
      assert.strictEqual(result.isUserVerified, false);
    });

    it('replaces the authenticator and keeps isUserVerified when a creation option changes', async () => {
      const {mcpPage, model} = await createWebAuthnPage();
      model.addAuthenticator
        .onFirstCall()
        .resolves(createMockAuthenticatorId('auth-1'));
      model.addAuthenticator
        .onSecondCall()
        .resolves(createMockAuthenticatorId('auth-2'));
      await mcpPage.configureWebAuthn({enabled: true, isUserVerified: false});

      const result = await mcpPage.configureWebAuthn({
        enabled: true,
        transport: 'nfc',
      });

      sinon.assert.calledOnceWithExactly(
        model.removeAuthenticator,
        createMockAuthenticatorId('auth-1'),
      );
      sinon.assert.calledWithExactly(model.addAuthenticator.secondCall, {
        ...DEFAULT_OPTIONS,
        transport: DevTools.Protocol.WebAuthn.AuthenticatorTransport.Nfc,
        isUserVerified: false,
      });
      sinon.assert.notCalled(model.setUserVerified);
      sinon.assert.calledWithExactly(
        model.getCredentials.secondCall,
        createMockAuthenticatorId('auth-2'),
      );
      assert.strictEqual(result?.transport, 'nfc');
    });

    it('creates a u2f authenticator without resident keys or user verification after a ctap2 one', async () => {
      const {mcpPage, model} = await createWebAuthnPage();
      model.addAuthenticator
        .onFirstCall()
        .resolves(createMockAuthenticatorId('auth-1'));
      model.addAuthenticator
        .onSecondCall()
        .resolves(createMockAuthenticatorId('auth-2'));
      await mcpPage.configureWebAuthn({enabled: true});

      const result = await mcpPage.configureWebAuthn({
        enabled: true,
        protocol: 'u2f',
      });

      sinon.assert.calledWithExactly(model.addAuthenticator.secondCall, {
        ...DEFAULT_OPTIONS,
        protocol: DevTools.Protocol.WebAuthn.AuthenticatorProtocol.U2f,
        hasResidentKey: false,
        hasUserVerification: false,
      });
      assert.strictEqual(result?.hasResidentKey, false);
      assert.strictEqual(result.hasUserVerification, false);
    });

    it('rejects hasResidentKey or hasUserVerification for u2f before calling CDP', async () => {
      const {mcpPage, model} = await createWebAuthnPage();
      model.addAuthenticator.resolves(createMockAuthenticatorId('auth-1'));
      await mcpPage.configureWebAuthn({enabled: true});
      const before = mcpPage.getWebAuthnAuthenticator();

      for (const option of ['hasResidentKey', 'hasUserVerification']) {
        await assert.rejects(
          mcpPage.configureWebAuthn({
            enabled: true,
            protocol: 'u2f',
            [option]: true,
          }),
          {
            message:
              "protocol 'u2f' does not support hasResidentKey or hasUserVerification. Set them to false or omit them.",
          },
        );
      }

      sinon.assert.calledOnce(model.addAuthenticator);
      sinon.assert.notCalled(model.removeAuthenticator);
      assert.deepStrictEqual(mcpPage.getWebAuthnAuthenticator(), before);
    });

    it('disables the virtual authenticator environment', async () => {
      const {mcpPage, model} = await createWebAuthnPage();
      model.addAuthenticator.resolves(createMockAuthenticatorId('auth-1'));
      await mcpPage.configureWebAuthn({enabled: true});

      assert.strictEqual(
        await mcpPage.configureWebAuthn({enabled: false}),
        undefined,
      );

      sinon.assert.calledWithExactly(
        model.setVirtualAuthEnvEnabled.secondCall,
        false,
      );
      sinon.assert.notCalled(model.removeAuthenticator);
      assert.strictEqual(mcpPage.getWebAuthnAuthenticator(), undefined);
    });

    it('disables the virtual authenticator environment that another client enabled', async () => {
      const {mcpPage, model} = await createWebAuthnPage();

      await mcpPage.configureWebAuthn({enabled: false});

      sinon.assert.calledOnceWithExactly(model.setVirtualAuthEnvEnabled, false);
      sinon.assert.notCalled(model.addAuthenticator);
    });

    it('lists stored credentials', async () => {
      const {mcpPage, model} = await createWebAuthnPage();
      model.addAuthenticator.resolves(createMockAuthenticatorId('auth-1'));
      model.getCredentials.resolves([
        {
          credentialId: 'Y3JlZA==',
          isResidentCredential: true,
          rpId: 'example.com',
          privateKey: 'a2V5',
          userHandle: 'dXNlcg==',
          signCount: 2,
          userName: 'alice',
        },
      ]);

      const result = await mcpPage.configureWebAuthn({enabled: true});

      assert.deepStrictEqual(result?.credentials, [
        {
          credentialId: 'Y3JlZA==',
          rpId: 'example.com',
          isResidentCredential: true,
          userName: 'alice',
          signCount: 2,
        },
      ]);
    });

    it('throws when the page has no WebAuthn model', async () => {
      const {mcpPage, detachUniverse} = await createWebAuthnPage();
      detachUniverse();

      await assert.rejects(mcpPage.configureWebAuthn({enabled: true}), {
        message: 'WebAuthn is not available for page 1.',
      });
    });

    it('throws the CDP error when enabling the environment fails', async () => {
      const {mcpPage, model} = await createWebAuthnPage();
      model.setVirtualAuthEnvEnabled.rejects(new Error(CDP_ERROR));

      await assertFailsWithCdpError(mcpPage.configureWebAuthn({enabled: true}));

      sinon.assert.notCalled(model.addAuthenticator);
      assert.strictEqual(mcpPage.getWebAuthnAuthenticator(), undefined);
    });

    it('throws the CDP error when adding the authenticator fails', async () => {
      const {mcpPage, model} = await createWebAuthnPage();
      model.addAuthenticator.rejects(new Error(CDP_ERROR));

      await assertFailsWithCdpError(mcpPage.configureWebAuthn({enabled: true}));

      sinon.assert.notCalled(model.getCredentials);
      assert.strictEqual(mcpPage.getWebAuthnAuthenticator(), undefined);
    });

    it('throws the CDP error when removing the replaced authenticator fails', async () => {
      const {mcpPage, model} = await createWebAuthnPage();
      model.addAuthenticator.resolves(createMockAuthenticatorId('auth-1'));
      await mcpPage.configureWebAuthn({enabled: true});
      model.removeAuthenticator.rejects(new Error(CDP_ERROR));

      await assertFailsWithCdpError(
        mcpPage.configureWebAuthn({enabled: true, transport: 'usb'}),
      );

      sinon.assert.calledOnce(model.addAuthenticator);
      assert.strictEqual(mcpPage.getWebAuthnAuthenticator(), undefined);
    });

    it('throws the CDP error when disabling the environment fails', async () => {
      const {mcpPage, model} = await createWebAuthnPage();
      model.setVirtualAuthEnvEnabled
        .withArgs(false)
        .rejects(new Error(CDP_ERROR));

      await assertFailsWithCdpError(
        mcpPage.configureWebAuthn({enabled: false}),
      );
    });

    it('throws the CDP error and removes the authenticator when setting isUserVerified fails', async () => {
      const {mcpPage, model} = await createWebAuthnPage();
      model.addAuthenticator.resolves(createMockAuthenticatorId('auth-1'));
      await mcpPage.configureWebAuthn({enabled: true});
      model.setUserVerified.rejects(new Error(CDP_ERROR));

      await assertFailsWithCdpError(
        mcpPage.configureWebAuthn({enabled: true, isUserVerified: false}),
      );

      sinon.assert.calledOnceWithExactly(
        model.removeAuthenticator,
        createMockAuthenticatorId('auth-1'),
      );
      assert.strictEqual(mcpPage.getWebAuthnAuthenticator(), undefined);
    });

    it('creates a new authenticator on the call after reading credentials fails', async () => {
      const {mcpPage, model} = await createWebAuthnPage();
      model.addAuthenticator
        .onFirstCall()
        .resolves(createMockAuthenticatorId('auth-1'));
      model.addAuthenticator
        .onSecondCall()
        .resolves(createMockAuthenticatorId('auth-2'));
      model.getCredentials.onFirstCall().rejects(new Error(CDP_ERROR));
      await assertFailsWithCdpError(mcpPage.configureWebAuthn({enabled: true}));

      await mcpPage.configureWebAuthn({enabled: true});

      sinon.assert.calledOnceWithExactly(
        model.removeAuthenticator,
        createMockAuthenticatorId('auth-1'),
      );
      sinon.assert.calledWithExactly(
        model.setVirtualAuthEnvEnabled.secondCall,
        true,
        false,
      );
      sinon.assert.calledWithExactly(
        model.addAuthenticator.secondCall,
        DEFAULT_OPTIONS,
      );
      sinon.assert.calledWithExactly(
        model.getCredentials.secondCall,
        createMockAuthenticatorId('auth-2'),
      );
    });
  });
});

describe('McpPage logpoints', () => {
  async function createMcpPageWithUniverse() {
    const pptrPage = createMockPuppeteerPage();
    pptrPage.emulateFocusedPage.resolves();
    const target = createMockPuppeteerTarget({page: pptrPage});
    const mcpPage = new McpPage(target, 1, {
      config: createMockServerConfig(),
      locatorClass: Locator,
    });
    const universe = sinon.createStubInstance(
      DevTools.Foundation.Universe.Universe,
    );
    sinon.stub(mcpPage, 'devtoolsUniverse').get((): TargetUniverse => ({
      universe,
      target: sinon.createStubInstance(DevTools.Target),
      session: createMockCDPSession(),
    }));
    await mcpPage.init();
    return mcpPage;
  }

  it('setLogpoints with an empty list creates no LogpointManager', async () => {
    const setLogpoints = sinon.stub(LogpointManager.prototype, 'setLogpoints');
    const mcpPage = await createMcpPageWithUniverse();

    assert.deepStrictEqual(await mcpPage.setLogpoints([]), []);

    sinon.assert.notCalled(setLogpoints);
  });

  it('setLogpoints creates one LogpointManager and forwards the list', async () => {
    const setLogpoints = sinon
      .stub(LogpointManager.prototype, 'setLogpoints')
      .resolves([]);
    const mcpPage = await createMcpPageWithUniverse();
    const logpoints = [{url: 'app.js', lineNumber: 2, expression: `'x'`}];

    await mcpPage.setLogpoints(logpoints);
    await mcpPage.setLogpoints([]);

    sinon.assert.calledTwice(setLogpoints);
    sinon.assert.calledWithExactly(setLogpoints.firstCall, logpoints);
    sinon.assert.calledWithExactly(setLogpoints.secondCall, []);
    assert.strictEqual(
      setLogpoints.firstCall.thisValue,
      setLogpoints.secondCall.thisValue,
    );
  });

  it('dispose releases the LogpointManager', async () => {
    sinon.stub(LogpointManager.prototype, 'setLogpoints').resolves([]);
    const dispose = sinon.stub(LogpointManager.prototype, 'dispose');
    const mcpPage = await createMcpPageWithUniverse();
    await mcpPage.setLogpoints([
      {url: 'app.js', lineNumber: 2, expression: `'x'`},
    ]);

    mcpPage.dispose();

    sinon.assert.calledOnce(dispose);
  });
});