Chrome DevTools for coding agents
/**
* @license
* Copyright 2026 Google LLC
* SPDX-License-Identifier: Apache-2.0
*/
import assert from 'node:assert';
import {ChildProcess} from 'node:child_process';
import {getEventListeners} from 'node:events';
import path from 'node:path';
import {afterEach, describe, it} from 'node:test';
import {pathToFileURL} from 'node:url';
import sinon from 'sinon';
import {ConfigLocator} from '../src/config/ConfigLocator.js';
import {ConfigParser} from '../src/config/ConfigParser.js';
import type {McpContext} from '../src/McpContext.js';
import {McpPage} from '../src/McpPage.js';
import {McpResponse, type DataFormat} from '../src/McpResponse.js';
import {ClearcutLogger} from '../src/telemetry/ClearcutLogger.js';
import {FilePersistence} from '../src/telemetry/persistence.js';
import {McpClient, WatchdogMessageType} from '../src/telemetry/types.js';
import {WatchdogClient} from '../src/telemetry/WatchdogClient.js';
import {
ProtocolError,
ProtocolErrorCode,
zod,
} from '../src/third_party/index.js';
import {TOOL_CALL_TIMEOUT_MS, ToolHandler} from '../src/ToolHandler.js';
import {ToolCategory} from '../src/tools/categories.js';
import {emulate} from '../src/tools/emulation.js';
import {pressKey, typeText} from '../src/tools/input.js';
import {
defineBrowserlessTool,
definePageTool,
type AnyToolDefinition,
type BrowserlessToolDefinition,
type DefinedPageTool,
type DevToolsData,
type ToolDefinition,
type ToolConcurrency,
} from '../src/tools/ToolDefinition.js';
import {evaluateScript} from '../src/tools/script.js';
import {mockNetwork} from '../src/tools/network.js';
import {selectPage} from '../src/tools/pages.js';
import {createTools} from '../src/tools/tools.js';
import {TaskRunner, type TaskQueue} from '../src/utils/TaskRunner.js';
import {createMockMcpContext, createMockMcpPage} from './mocks.js';
import {getMockBrowser, settle, withMcpContext} from './utils.js';
describe('ToolHandler', () => {
/** Runs `fn` as a task on `queue`. */
async function runOn(queue: TaskQueue, fn: () => Promise<void>) {
using guard = await queue.scheduleTask();
await fn();
}
afterEach(() => {
ClearcutLogger.resetForTesting();
});
function parseConfig(argv: string[] = []) {
const locator = new ConfigLocator();
sinon.stub(locator, 'locate').returns(undefined);
return new ConfigParser(
'1.0.0',
['node', 'script.js', ...argv],
{
CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS: 'true',
},
false,
locator,
).parseConfig();
}
it('calls getPageById for page scoped tools when pageId is provided', async () => {
let handlerCalled = false;
const config = parseConfig();
const tool = definePageTool(() => ({
name: 'page_tool',
description: 'A page scoped tool',
annotations: {
category: ToolCategory.INPUT,
readOnlyHint: false,
},
schema: {},
blockedByDialog: false,
concurrency: 'exclusive',
verifyFilesSchema: {},
handler: async () => {
handlerCalled = true;
},
}))(config.resolved);
const mockContext = createMockMcpContext();
const mockProcess = sinon.createStubInstance(ChildProcess);
mockContext.ensureBrowser.resolves(getMockBrowser({process: mockProcess}));
const mockPage = sinon.createStubInstance(McpPage);
mockContext.getPageById.returns(mockPage);
const toolHandler = new ToolHandler(
tool,
config,
async () => mockContext,
sinon.spy(),
);
assert.strictEqual(toolHandler.disabled, false);
await toolHandler.handle({pageId: 1});
sinon.assert.calledOnceWithExactly(mockContext.getPageById, 1);
sinon.assert.calledOnceWithExactly(mockPage.init, {emulateFocus: true});
assert.strictEqual(handlerCalled, true);
});
describe('cancellation', () => {
const modes: Array<ToolConcurrency | 'browserless'> = [
'exclusive',
'page',
'none',
'browserless',
];
for (const mode of modes) {
for (const rejects of [false, true]) {
const outcome = rejects ? 'failure' : 'completion';
it(`logs abort and retains running queues until late ${outcome} (${mode})`, async () => {
const started = Promise.withResolvers<void>();
const execution = Promise.withResolvers<void>();
const config = parseConfig();
const definition = {
name: 'cancelled_tool',
description: 'A tool awaiting an external operation',
annotations: {category: ToolCategory.INPUT, readOnlyHint: false},
schema: {},
blockedByDialog: false,
verifyFilesSchema: {},
handler: async () => {
started.resolve();
await execution.promise;
},
} satisfies Omit<
BrowserlessToolDefinition,
'browserless' | 'concurrency'
>;
const tool =
mode === 'browserless'
? defineBrowserlessTool(() => definition)(config.resolved)
: definePageTool(() => ({...definition, concurrency: mode}))(
config.resolved,
);
const runner = new TaskRunner();
const page = createMockMcpPage();
const context = createMockMcpContext({taskRunner: runner});
context.ensureBrowser.resolves(getMockBrowser());
context.getPageById.returns(page);
const queue =
mode === 'page' ? context.pageTaskQueue(1) : context.taskQueue;
const schedule = sinon.spy(queue, 'scheduleTask');
const responseHandle = sinon
.stub(McpResponse.prototype, 'handle')
.resolves({content: [], structuredContent: {}});
const responseError = sinon.spy(McpResponse.prototype, 'setError');
const telemetry = sinon.createStubInstance(ClearcutLogger);
sinon.stub(ClearcutLogger, 'get').returns(telemetry);
sinon.stub(Date, 'now').returns(1_000);
const abandonBrowser = sinon.spy();
const controller = new AbortController();
const handler = new ToolHandler(
tool,
config,
async () => context,
abandonBrowser,
);
const args = mode === 'browserless' ? {} : {pageId: 1};
const pending = handler.handle(args, {signal: controller.signal});
await started.promise;
if (mode === 'none' || mode === 'browserless') {
sinon.assert.notCalled(schedule);
} else {
sinon.assert.calledOnceWithExactly(schedule, controller.signal);
}
controller.abort();
await assert.rejects(pending, {name: 'AbortError'});
const invocation = {
toolName: tool.name,
params: args,
schema: tool.schema,
success: false,
latencyMs: 0,
devToolsData: undefined,
pageUrl: undefined,
};
sinon.assert.calledOnceWithExactly(
telemetry.logToolInvocation,
invocation,
);
assert.deepStrictEqual(
getEventListeners(controller.signal, 'abort'),
[],
);
const acquired = sinon.spy();
const probe = queue.scheduleTask().then(guard => {
acquired();
return guard;
});
await settle();
if (mode === 'exclusive' || mode === 'page') {
sinon.assert.notCalled(acquired);
} else {
sinon.assert.calledOnceWithExactly(acquired);
}
if (mode === 'page') {
using unrelated = await context.pageTaskQueue(2).scheduleTask();
}
if (rejects) {
execution.reject(new Error('late failure'));
} else {
execution.resolve();
}
(await probe)[Symbol.dispose]();
await settle();
sinon.assert.calledOnceWithExactly(acquired);
sinon.assert.notCalled(responseHandle);
sinon.assert.notCalled(responseError);
sinon.assert.notCalled(context.getDevToolsData);
sinon.assert.calledOnceWithExactly(
telemetry.logToolInvocation,
invocation,
);
sinon.assert.notCalled(abandonBrowser);
const lateProbe = await queue.scheduleTask();
lateProbe[Symbol.dispose]();
const pause = await runner.pause();
pause[Symbol.dispose]();
const nextRun = sinon.stub().resolves();
const nextHandler = new ToolHandler(
{...tool, name: 'next_tool', handler: nextRun},
config,
async () => context,
abandonBrowser,
);
assert.strictEqual(
(await nextHandler.handle(args)).isError,
undefined,
);
sinon.assert.calledOnceWithExactly(
nextRun,
mode === 'browserless' ? {params: args} : {params: args, page},
responseHandle.firstCall.thisValue,
context,
);
});
}
}
for (const concurrency of [
'exclusive',
'page',
] satisfies ToolConcurrency[]) {
it(`cancels a queued ${concurrency} tool`, async () => {
const config = parseConfig();
const run = sinon.stub().resolves();
const tool = definePageTool(() => ({
name: 'queued_tool',
description: 'A queued tool',
annotations: {category: ToolCategory.INPUT, readOnlyHint: true},
schema: {},
blockedByDialog: false,
concurrency,
verifyFilesSchema: {},
handler: run,
}))(config.resolved);
const context = createMockMcpContext();
const queue =
concurrency === 'page' ? context.pageTaskQueue(1) : context.taskQueue;
const holder = await queue.scheduleTask();
const controller = new AbortController();
const handler = new ToolHandler(
tool,
config,
async () => context,
sinon.spy(),
);
const pending = handler.handle(
{pageId: 1},
{signal: controller.signal},
);
await settle();
controller.abort();
await assert.rejects(pending, {name: 'AbortError'});
holder[Symbol.dispose]();
using probe = await queue.scheduleTask();
sinon.assert.notCalled(context.ensureBrowser);
sinon.assert.notCalled(run);
assert.deepStrictEqual(
getEventListeners(controller.signal, 'abort'),
[],
);
});
}
it('releases a guard acquired just before cancellation', async () => {
const config = parseConfig();
const context = createMockMcpContext();
const controller = new AbortController();
const scheduleTask = context.taskQueue.scheduleTask.bind(
context.taskQueue,
);
sinon.stub(context.taskQueue, 'scheduleTask').callsFake(async signal => {
const guard = await scheduleTask(signal);
controller.abort();
return guard;
});
const handler = new ToolHandler(
evaluateScript(config.resolved),
config,
async () => context,
sinon.spy(),
);
await assert.rejects(handler.handle({}, {signal: controller.signal}), {
name: 'AbortError',
});
using probe = await scheduleTask();
sinon.assert.notCalled(context.ensureBrowser);
assert.deepStrictEqual(getEventListeners(controller.signal, 'abort'), []);
});
for (const stage of ['context', 'browser', 'page', 'files', 'telemetry']) {
it(`skips work after ${stage} cancellation`, async () => {
const started = Promise.withResolvers<void>();
const initialization = Promise.withResolvers<void>();
const config = parseConfig(['--no-page-id-routing']);
const run = sinon.stub().resolves();
const tool = definePageTool(() => ({
name: 'page_tool',
description: 'A page tool',
annotations: {category: ToolCategory.INPUT, readOnlyHint: true},
schema: {file: zod.string()},
blockedByDialog: false,
concurrency: 'page',
verifyFilesSchema: {file: true},
handler: run,
}))(config.resolved);
const page = createMockMcpPage();
const context = createMockMcpContext({selectedPage: page});
const browser = getMockBrowser();
context.ensureBrowser.resolves(browser);
context.validatePath.resolves('/tmp/file');
const waitForInitialization = async () => {
started.resolve();
await initialization.promise;
};
const getContext = async () => {
if (stage === 'context') {
await waitForInitialization();
}
return context;
};
if (stage === 'browser') {
context.ensureBrowser.callsFake(async () => {
await waitForInitialization();
return browser;
});
} else if (stage === 'page') {
page.init.callsFake(waitForInitialization);
} else if (stage === 'files') {
context.validatePath.callsFake(async () => {
await waitForInitialization();
return '/tmp/file';
});
} else if (stage === 'telemetry') {
context.getDevToolsData.callsFake(async () => {
await waitForInitialization();
return {};
});
}
const responseHandle = sinon.stub(McpResponse.prototype, 'handle');
const setPage = sinon.spy(McpResponse.prototype, 'setPage');
const telemetry = sinon.createStubInstance(ClearcutLogger);
sinon.stub(ClearcutLogger, 'get').returns(telemetry);
sinon.stub(Date, 'now').returns(1_000);
const controller = new AbortController();
const abandonBrowser = sinon.spy();
const handler = new ToolHandler(
tool,
config,
getContext,
abandonBrowser,
);
const pending = handler.handle(
{file: '/tmp/file'},
{signal: controller.signal},
);
await started.promise;
controller.abort();
await assert.rejects(pending, {name: 'AbortError'});
const invocation = {
toolName: tool.name,
params: {file: '/tmp/file'},
schema: tool.schema,
success: false,
latencyMs: 0,
devToolsData: undefined,
pageUrl: undefined,
};
if (stage === 'context') {
sinon.assert.notCalled(telemetry.logToolInvocation);
} else {
sinon.assert.calledOnceWithExactly(
telemetry.logToolInvocation,
invocation,
);
}
const acquired = sinon.spy();
const probe = context.taskQueue.scheduleTask().then(guard => {
acquired();
return guard;
});
await settle();
if (stage === 'context' || stage === 'browser') {
sinon.assert.calledOnceWithExactly(acquired);
} else {
sinon.assert.notCalled(acquired);
}
initialization.resolve();
(await probe)[Symbol.dispose]();
await settle();
if (stage === 'context') {
sinon.assert.notCalled(context.ensureBrowser);
} else if (stage === 'browser') {
sinon.assert.notCalled(context.consumeReconnectNotice);
} else if (stage === 'files') {
sinon.assert.notCalled(context.getSelectedMcpPage);
} else if (stage === 'page') {
sinon.assert.notCalled(setPage);
} else {
sinon.assert.notCalled(context.getSelectedMcpPageUrl);
}
sinon.assert.notCalled(responseHandle);
if (stage === 'context') {
sinon.assert.notCalled(telemetry.logToolInvocation);
} else {
sinon.assert.calledOnceWithExactly(
telemetry.logToolInvocation,
invocation,
);
}
sinon.assert.notCalled(abandonBrowser);
assert.deepStrictEqual(
getEventListeners(controller.signal, 'abort'),
[],
);
});
}
it('serializes select_page after a cancelled selection finishes', async () => {
const config = parseConfig();
const context = createMockMcpContext();
context.ensureBrowser.resolves(getMockBrowser());
const oldPage = createMockMcpPage();
const nextPage = createMockMcpPage();
context.getPageById.withArgs(1).returns(oldPage);
context.getPageById.withArgs(2).returns(nextPage);
const initialization = Promise.withResolvers<void>();
oldPage.init.returns(initialization.promise);
sinon
.stub(McpResponse.prototype, 'handle')
.resolves({content: [], structuredContent: {}});
const handler = new ToolHandler(
selectPage(config.resolved),
config,
async () => context,
sinon.spy(),
);
const controller = new AbortController();
const pending = handler.handle({pageId: 1}, {signal: controller.signal});
await settle();
sinon.assert.calledOnceWithExactly(oldPage.init, {emulateFocus: true});
controller.abort();
await assert.rejects(pending, {name: 'AbortError'});
const next = handler.handle({pageId: 2});
await settle();
sinon.assert.notCalled(nextPage.init);
sinon.assert.notCalled(context.selectPage);
initialization.resolve();
assert.strictEqual((await next).isError, undefined);
sinon.assert.calledTwice(context.selectPage);
sinon.assert.calledWithExactly(context.selectPage.firstCall, oldPage);
sinon.assert.calledWithExactly(context.selectPage.secondCall, nextPage);
});
it('retains the queue while cancelled response processing settles', async () => {
const config = parseConfig();
const runner = new TaskRunner();
const context = createMockMcpContext({taskRunner: runner});
context.ensureBrowser.resolves(getMockBrowser());
const page = createMockMcpPage();
context.getPageById.returns(page);
const processing =
Promise.withResolvers<Awaited<ReturnType<McpResponse['handle']>>>();
const responseHandle = sinon
.stub(McpResponse.prototype, 'handle')
.returns(processing.promise);
const handler = new ToolHandler(
selectPage(config.resolved),
config,
async () => context,
sinon.spy(),
);
const controller = new AbortController();
const pending = handler.handle({pageId: 1}, {signal: controller.signal});
await settle();
sinon.assert.calledOnceWithExactly(responseHandle, context, 'default');
controller.abort();
await assert.rejects(pending, {name: 'AbortError'});
const paused = sinon.spy();
const pause = runner.pause().then(guard => {
paused();
return guard;
});
await settle();
sinon.assert.notCalled(paused);
processing.resolve({content: [], structuredContent: {}});
(await pause)[Symbol.dispose]();
sinon.assert.calledOnceWithExactly(paused);
});
it('skips context for an already cancelled request', async () => {
const getContext = sinon.stub().resolves(createMockMcpContext());
const config = parseConfig();
const handler = new ToolHandler(
evaluateScript(config.resolved),
config,
getContext,
sinon.spy(),
);
const controller = new AbortController();
controller.abort();
await assert.rejects(handler.handle({}, {signal: controller.signal}), {
name: 'AbortError',
});
sinon.assert.notCalled(getContext);
});
});
it('calls getSelectedMcpPage for page scoped tools when pageIdRouting is disabled', async () => {
let handlerCalled = false;
const config = parseConfig(['--no-page-id-routing']);
const tool = definePageTool(() => ({
name: 'page_tool',
description: 'A page scoped tool',
annotations: {
category: ToolCategory.INPUT,
readOnlyHint: false,
},
schema: {},
blockedByDialog: false,
concurrency: 'exclusive',
verifyFilesSchema: {},
handler: async () => {
handlerCalled = true;
},
}))(config.resolved);
const mockContext = createMockMcpContext();
const mockProcess = sinon.createStubInstance(ChildProcess);
mockContext.ensureBrowser.resolves(getMockBrowser({process: mockProcess}));
const mockPage = sinon.createStubInstance(McpPage);
mockContext.getSelectedMcpPage.returns(mockPage);
const toolHandler = new ToolHandler(
tool,
config,
async () => mockContext,
sinon.spy(),
);
assert.strictEqual(toolHandler.disabled, false);
await toolHandler.handle({});
sinon.assert.calledOnceWithExactly(mockContext.getSelectedMcpPage);
sinon.assert.calledOnceWithExactly(mockPage.init, {emulateFocus: true});
assert.strictEqual(handlerCalled, true);
});
it('does not pass page to handler for non-page scoped tools', async () => {
let handlerCalled = false;
const tool: ToolDefinition = {
name: 'global_tool',
description: 'A global tool',
annotations: {
category: ToolCategory.NAVIGATION,
readOnlyHint: true,
},
schema: {},
blockedByDialog: false,
concurrency: 'exclusive',
verifyFilesSchema: {},
handler: async () => {
handlerCalled = true;
},
};
const mockContext = createMockMcpContext();
const mockProcess = sinon.createStubInstance(ChildProcess);
mockContext.ensureBrowser.resolves(getMockBrowser({process: mockProcess}));
const config = parseConfig();
const toolHandler = new ToolHandler(
tool,
config,
async () => mockContext,
sinon.spy(),
);
assert.strictEqual(toolHandler.disabled, false);
const result = await toolHandler.handle({});
assert.strictEqual(mockContext.getDevToolsData.calledOnce, true);
assert.strictEqual(mockContext.getSelectedMcpPageUrl.calledOnce, true);
assert.strictEqual(mockContext.getPageById.called, false);
assert.strictEqual(handlerCalled, true);
assert.strictEqual(result.isError, undefined);
});
describe("concurrency: 'exclusive'", () => {
function createGlobalTool(
handler: ToolDefinition['handler'],
options: {
name?: string;
concurrency?: ToolDefinition['concurrency'];
} = {},
): ToolDefinition {
return {
name: options.name ?? 'global_tool',
description: 'A global tool',
annotations: {
category: ToolCategory.NAVIGATION,
readOnlyHint: true,
},
schema: {},
blockedByDialog: false,
concurrency: options.concurrency ?? 'exclusive',
verifyFilesSchema: {},
handler,
};
}
function createContext() {
const mockContext = createMockMcpContext();
const mockProcess = sinon.createStubInstance(ChildProcess);
mockContext.ensureBrowser.resolves(
getMockBrowser({process: mockProcess}),
);
return mockContext;
}
function createHandler(tool: AnyToolDefinition, mockContext: McpContext) {
return new ToolHandler(
tool,
parseConfig(),
async () => mockContext,
sinon.spy(),
);
}
it('serializes exclusive tools', async () => {
const mockContext = createContext();
const events: string[] = [];
const {promise: release, resolve: finishWait} =
Promise.withResolvers<void>();
const blockingTool = createGlobalTool(
async () => {
events.push('blocking:start');
await release;
events.push('blocking:end');
},
{name: 'blocking_tool'},
);
const otherTool = createGlobalTool(
async () => {
events.push('other:run');
},
{name: 'other_tool'},
);
const blockingHandler = createHandler(blockingTool, mockContext);
const otherHandler = createHandler(otherTool, mockContext);
const blockingResult = blockingHandler.handle({});
await settle();
const otherResult = otherHandler.handle({});
await settle();
finishWait();
await Promise.all([blockingResult, otherResult]);
assert.deepStrictEqual(events, [
'blocking:start',
'blocking:end',
'other:run',
]);
});
it('runs a none page tool while an exclusive tool holds the context queue', async () => {
sinon
.stub(McpResponse.prototype, 'handle')
.resolves({content: [], structuredContent: {}});
const mockContext = createContext();
mockContext.getPageById.returns(createMockMcpPage());
const events: string[] = [];
const {promise: release, resolve: finishBlocking} =
Promise.withResolvers<void>();
const blockingTool = createGlobalTool(
async () => {
events.push('blocking:start');
await release;
events.push('blocking:end');
},
{name: 'blocking_tool'},
);
const waitingTool = definePageTool(() => ({
name: 'waiting_tool',
description: 'A page tool that waits for events',
annotations: {
category: ToolCategory.DEBUGGING,
readOnlyHint: true,
},
schema: {},
blockedByDialog: false,
concurrency: 'none',
verifyFilesSchema: {},
handler: async () => {
events.push('waiting:run');
},
}))(parseConfig().resolved);
const blockingResult = createHandler(blockingTool, mockContext).handle(
{},
);
await settle();
const waitingResult = await createHandler(
waitingTool,
mockContext,
).handle({pageId: 1});
finishBlocking();
await blockingResult;
assert.strictEqual(waitingResult.isError, undefined);
assert.deepStrictEqual(events, [
'blocking:start',
'waiting:run',
'blocking:end',
]);
});
});
describe("concurrency: 'page'", () => {
function createPageTool(
name: string,
handler: () => Promise<void>,
options: {
concurrency?: DefinedPageTool['concurrency'];
argv?: string[];
} = {},
): DefinedPageTool {
return definePageTool(() => ({
name,
description: 'A page tool',
annotations: {
category: ToolCategory.INPUT,
readOnlyHint: false,
},
schema: {},
blockedByDialog: false,
concurrency: options.concurrency ?? 'page',
verifyFilesSchema: {},
handler,
}))(parseConfig(options.argv).resolved);
}
function createExclusiveTool(
name: string,
handler: () => Promise<void>,
): ToolDefinition {
return {
name,
description: 'A global tool',
annotations: {
category: ToolCategory.NAVIGATION,
readOnlyHint: true,
},
schema: {},
blockedByDialog: false,
concurrency: 'exclusive',
verifyFilesSchema: {},
handler,
};
}
function createPages(ids: number[]) {
const mockContext = createMockMcpContext();
const mockProcess = sinon.createStubInstance(ChildProcess);
mockContext.ensureBrowser.resolves(
getMockBrowser({process: mockProcess}),
);
const pages = new Map(ids.map(id => [id, createMockMcpPage({id})]));
mockContext.getPageById.callsFake(id => {
const page = pages.get(id);
assert.ok(page);
return page;
});
return mockContext;
}
function createHandler(tool: AnyToolDefinition, mockContext: McpContext) {
return new ToolHandler(
tool,
parseConfig(),
async () => mockContext,
sinon.spy(),
);
}
it('runs page tools on different pages at the same time', async () => {
sinon
.stub(McpResponse.prototype, 'handle')
.resolves({content: [], structuredContent: {}});
const mockContext = createPages([1, 2]);
const events: string[] = [];
const {promise: release, resolve: finishFirst} =
Promise.withResolvers<void>();
const first = createHandler(
createPageTool('first', async () => {
events.push('first:start');
await release;
events.push('first:end');
}),
mockContext,
);
const second = createHandler(
createPageTool('second', async () => {
events.push('second:run');
}),
mockContext,
);
const firstResult = first.handle({pageId: 1});
await settle();
await second.handle({pageId: 2});
finishFirst();
await firstResult;
assert.deepStrictEqual(events, [
'first:start',
'second:run',
'first:end',
]);
});
it('serializes page tools on the same page', async () => {
sinon
.stub(McpResponse.prototype, 'handle')
.resolves({content: [], structuredContent: {}});
const mockContext = createPages([1]);
const events: string[] = [];
const {promise: release, resolve: finishFirst} =
Promise.withResolvers<void>();
const first = createHandler(
createPageTool('first', async () => {
events.push('first:start');
await release;
events.push('first:end');
}),
mockContext,
);
const second = createHandler(
createPageTool('second', async () => {
events.push('second:run');
}),
mockContext,
);
const firstResult = first.handle({pageId: 1});
await settle();
const secondResult = second.handle({pageId: 1});
await settle();
assert.deepStrictEqual(events, ['first:start']);
finishFirst();
await Promise.all([firstResult, secondResult]);
assert.deepStrictEqual(events, [
'first:start',
'first:end',
'second:run',
]);
});
it('queues an exclusive tool behind running page tools in FIFO order', async () => {
sinon
.stub(McpResponse.prototype, 'handle')
.resolves({content: [], structuredContent: {}});
const mockContext = createPages([1, 2]);
const events: string[] = [];
const {promise: release, resolve: finishFirst} =
Promise.withResolvers<void>();
const pageTool = createHandler(
createPageTool('page_tool', async () => {
events.push('page:start');
await release;
events.push('page:end');
}),
mockContext,
);
const exclusiveTool = createHandler(
createExclusiveTool('exclusive_tool', async () => {
events.push('exclusive:run');
}),
mockContext,
);
const latePageTool = createHandler(
createPageTool('late_page_tool', async () => {
events.push('late:run');
}),
mockContext,
);
const pageResult = pageTool.handle({pageId: 1});
await settle();
const exclusiveResult = exclusiveTool.handle({});
await settle();
// Targets another page, but waits behind the queued exclusive tool.
const lateResult = latePageTool.handle({pageId: 2});
await settle();
assert.deepStrictEqual(events, ['page:start']);
finishFirst();
await Promise.all([pageResult, exclusiveResult, lateResult]);
assert.deepStrictEqual(events, [
'page:start',
'page:end',
'exclusive:run',
'late:run',
]);
});
it('holds the page queue until the response is built', async () => {
const {promise: responseReady, resolve: finishResponse} =
Promise.withResolvers<void>();
const handleStub = sinon.stub(McpResponse.prototype, 'handle');
handleStub.onFirstCall().callsFake(async () => {
await responseReady;
return {content: [], structuredContent: {}};
});
handleStub.resolves({content: [], structuredContent: {}});
const mockContext = createPages([1]);
const events: string[] = [];
const first = createHandler(
createPageTool('first', async () => {
events.push('first:run');
}),
mockContext,
);
const second = createHandler(
createPageTool('second', async () => {
events.push('second:run');
}),
mockContext,
);
const firstResult = first.handle({pageId: 1});
await settle();
const secondResult = second.handle({pageId: 1});
await settle();
assert.deepStrictEqual(events, ['first:run']);
finishResponse();
await Promise.all([firstResult, secondResult]);
assert.deepStrictEqual(events, ['first:run', 'second:run']);
});
it('runs the call on the page queue', async () => {
sinon
.stub(McpResponse.prototype, 'handle')
.resolves({content: [], structuredContent: {}});
const mockContext = createPages([7]);
const events: string[] = [];
const {promise: release, resolve: finishHandler} =
Promise.withResolvers<void>();
const result = createHandler(
createPageTool('page_tool', async () => {
events.push('handler:start');
await release;
events.push('handler:end');
}),
mockContext,
).handle({pageId: 7});
await settle();
const pageTask = runOn(mockContext.pageTaskQueue(7), async () => {
events.push('page-task');
});
const contextTask = runOn(mockContext.taskQueue, async () => {
events.push('context-task');
});
await settle();
assert.deepStrictEqual(events, ['handler:start']);
finishHandler();
await Promise.all([result, pageTask, contextTask]);
assert.deepStrictEqual(events, [
'handler:start',
'handler:end',
'page-task',
'context-task',
]);
});
it('runs a page tool without pageId on the context queue', async () => {
sinon
.stub(McpResponse.prototype, 'handle')
.resolves({content: [], structuredContent: {}});
const argv = ['--no-page-id-routing'];
const mockContext = createPages([]);
const {promise: release, resolve: finishHandler} =
Promise.withResolvers<void>();
const result = new ToolHandler(
createPageTool(
'page_tool',
async () => {
await release;
},
{argv},
),
parseConfig(argv),
async () => mockContext,
sinon.spy(),
).handle({});
await settle();
let contextTaskRan = false;
const contextTask = runOn(mockContext.taskQueue, async () => {
contextTaskRan = true;
});
await settle();
assert.strictEqual(contextTaskRan, false);
sinon.assert.notCalled(mockContext.pageTaskQueue);
finishHandler();
await Promise.all([result, contextTask]);
assert.strictEqual(contextTaskRan, true);
});
it('releases the page queue when the handler throws', async () => {
sinon
.stub(McpResponse.prototype, 'handle')
.resolves({content: [], structuredContent: {}});
const mockContext = createPages([1]);
const result = await createHandler(
createPageTool('failing', async () => {
throw new Error('handler failed');
}),
mockContext,
).handle({pageId: 1});
assert.strictEqual(result.isError, true);
await runOn(mockContext.pageTaskQueue(1), async () => {});
});
it('fails a waiting page tool when the page queue is disposed', async () => {
sinon
.stub(McpResponse.prototype, 'handle')
.resolves({content: [], structuredContent: {}});
const mockContext = createPages([1]);
const handler = sinon.stub<[], Promise<void>>().resolves();
const {promise: release, resolve: finishFirst} =
Promise.withResolvers<void>();
const first = createHandler(
createPageTool('first', async () => {
await release;
}),
mockContext,
).handle({pageId: 1});
await settle();
const second = createHandler(
createPageTool('second', handler),
mockContext,
).handle({pageId: 1});
await settle();
mockContext.pageTaskQueue(1).dispose(new Error('Page 1 is closed.'));
finishFirst();
const [, result] = await Promise.all([first, second]);
assert.strictEqual(result.isError, true);
assert.ok(result.content[0].type === 'text');
assert.match(result.content[0].text, /Page 1 is closed\./);
sinon.assert.notCalled(handler);
});
});
const dataFormatCases: Array<{argv: string[]; expected: DataFormat}> = [
{argv: [], expected: 'default'},
{argv: ['--experimentalToonFormat'], expected: 'toon'},
{argv: ['--experimentalDataFormat=gcf'], expected: 'gcf'},
{
argv: ['--experimentalToonFormat', '--experimentalDataFormat=default'],
expected: 'default',
},
{
argv: ['--experimentalToonFormat', '--experimentalDataFormat=gcf'],
expected: 'gcf',
},
];
for (const {argv, expected} of dataFormatCases) {
it(`resolves data format ${expected} from [${argv.join(' ')}]`, async () => {
const tool: ToolDefinition = {
name: 'global_tool',
description: 'A global tool',
annotations: {
category: ToolCategory.NAVIGATION,
readOnlyHint: true,
},
schema: {},
blockedByDialog: false,
concurrency: 'exclusive',
verifyFilesSchema: {},
handler: async () => undefined,
};
const mockContext = createMockMcpContext();
mockContext.ensureBrowser.resolves(
getMockBrowser({
process: sinon.createStubInstance(ChildProcess),
}),
);
const handleStub = sinon
.stub(McpResponse.prototype, 'handle')
.resolves({content: [], structuredContent: {}});
const config = parseConfig(argv);
await new ToolHandler(
tool,
config,
async () => mockContext,
sinon.spy(),
).handle({});
sinon.assert.calledOnceWithExactly(handleStub, mockContext, expected);
});
}
it('passes devToolsData and pageUrl to logger', async () => {
const baseTool: ToolDefinition = {
name: 'test_tool',
description: 'A test tool',
annotations: {
category: ToolCategory.NAVIGATION,
readOnlyHint: true,
},
schema: {},
blockedByDialog: false,
concurrency: 'exclusive',
verifyFilesSchema: {},
handler: async () => {
return;
},
};
const config = parseConfig(['--no-page-id-routing']);
const testCases: Array<{
tool: ToolDefinition | DefinedPageTool;
devToolsData: DevToolsData;
pageUrl?: string;
}> = [
{
tool: definePageTool(() => ({
...baseTool,
name: 'page_tool',
}))(config.resolved),
devToolsData: {cdpBackendNodeId: 1},
pageUrl: 'http://localhost:9222/',
},
{
tool: {
...baseTool,
name: 'global_tool',
},
devToolsData: {},
pageUrl: undefined,
},
];
for (const testCase of testCases) {
let handlerCalled = false;
testCase.tool.handler = async () => {
handlerCalled = true;
};
const mockContext = createMockMcpContext();
const mockProcess = sinon.createStubInstance(ChildProcess);
mockContext.ensureBrowser.resolves(
getMockBrowser({process: mockProcess}),
);
mockContext.getDevToolsData.resolves(testCase.devToolsData);
if (testCase.pageUrl) {
mockContext.getSelectedMcpPageUrl.returns(testCase.pageUrl);
}
const logSpy = sinon.spy();
const getLoggerStub = sinon.stub(ClearcutLogger, 'get').returns({
logToolInvocation: logSpy,
} as unknown as ClearcutLogger);
const toolHandler = new ToolHandler(
testCase.tool,
config,
async () => mockContext,
sinon.spy(),
);
await toolHandler.handle({});
assert.strictEqual(logSpy.calledOnce, true);
assert.deepStrictEqual(
logSpy.firstCall.args[0].devToolsData,
testCase.devToolsData,
);
assert.strictEqual(logSpy.firstCall.args[0].pageUrl, testCase.pageUrl);
assert.strictEqual(handlerCalled, true);
getLoggerStub.restore();
ClearcutLogger.resetForTesting();
}
});
it('sanitizes raw validated args for tools with transformed schemas', async () => {
sinon.stub(Date, 'now').returns(1000);
sinon
.stub(McpResponse.prototype, 'handle')
.resolves({content: [], structuredContent: {}});
const config = parseConfig(['--no-page-id-routing']);
const mockContext = createMockMcpContext();
mockContext.ensureBrowser.resolves(
getMockBrowser({process: sinon.createStubInstance(ChildProcess)}),
);
mockContext.getSelectedMcpPage.returns(sinon.createStubInstance(McpPage));
mockContext.getDevToolsData.resolves({});
const mockPersistence = sinon.createStubInstance(FilePersistence, {
loadState: Promise.resolve({lastToolCall: new Date().toISOString()}),
});
const mockWatchdogClient = sinon.createStubInstance(WatchdogClient);
ClearcutLogger.initialize({
persistence: mockPersistence,
appVersion: '1.0.0',
watchdogClient: mockWatchdogClient,
});
await Promise.resolve();
const testCases: Array<{
tool: DefinedPageTool;
rawArgs: Record<string, unknown>;
expectedParams: Record<string, unknown>;
}> = [
{
tool: pressKey(config.resolved),
rawArgs: {key: 'Control+Shift+C'},
expectedParams: {
press_key_params: {
key_length: 20,
},
},
},
{
tool: typeText(config.resolved),
rawArgs: {text: 'hello', submitKey: ''},
expectedParams: {
type_text_params: {
text_length: 5,
submit_key_length: 0,
},
},
},
{
tool: emulate(config.resolved),
rawArgs: {
viewport: '400x400x1',
geolocation: '37.7749,-122.4194',
extraHttpHeaders: '{"X-Custom":"1"}',
},
expectedParams: {
emulate_params: {
viewport_length: 10,
geolocation_length: 20,
extra_http_headers_length: 20,
},
},
},
];
for (const {tool, rawArgs, expectedParams} of testCases) {
mockWatchdogClient.send.resetHistory();
const toolHandler = new ToolHandler(
tool,
config,
async () => mockContext,
sinon.spy(),
);
const result = await toolHandler.handle(rawArgs);
assert.strictEqual(result.isError, undefined);
sinon.assert.calledOnceWithExactly(mockWatchdogClient.send, {
type: WatchdogMessageType.LOG_EVENT,
payload: {
mcp_client: McpClient.MCP_CLIENT_UNSPECIFIED,
tool_invocation: {
tool_name: tool.name,
success: true,
latency_ms: 50,
context: {
is_devtools_open: false,
},
tool_params: expectedParams,
},
},
});
}
});
it('rejects unknown registered tool arguments and sets additionalProperties to false', () => {
const tool: ToolDefinition = {
name: 'strict_tool',
description: 'A tool with a required argument',
annotations: {
category: ToolCategory.NAVIGATION,
readOnlyHint: true,
},
schema: {
url: zod.string(),
},
blockedByDialog: false,
concurrency: 'exclusive',
verifyFilesSchema: {},
handler: async () => {
return;
},
};
const mockContext = createMockMcpContext();
const config = parseConfig();
const toolHandler = new ToolHandler(
tool,
config,
async () => mockContext,
sinon.spy(),
);
const params = {
url: 123,
description: 'open the page',
extra: true,
};
const parseResult = toolHandler.registeredInputSchema.safeParse(params);
assert.strictEqual(parseResult.success, false);
assert.strictEqual(parseResult.error.issues.length, 2);
assert.deepStrictEqual(
parseResult.error.issues.map(issue => issue.message),
[
'Invalid input: expected string, received number',
'Unrecognized keys: "description", "extra"',
],
);
const jsonSchema = zod.toJSONSchema(toolHandler.registeredInputSchema, {
io: 'input',
});
assert.strictEqual(jsonSchema.additionalProperties, false);
});
it('sets disabled to true and returns disabled reason when category is disabled', async () => {
let handlerCalled = false;
const tool: ToolDefinition = {
name: 'disabled_tool',
description: 'A disabled tool',
annotations: {
category: ToolCategory.EMULATION,
readOnlyHint: true,
},
schema: {},
blockedByDialog: false,
concurrency: 'exclusive',
verifyFilesSchema: {},
handler: async () => {
handlerCalled = true;
},
};
const mockContext = createMockMcpContext();
const config = parseConfig(['--categoryEmulation=false']);
const toolHandler = new ToolHandler(
tool,
config,
async () => mockContext,
sinon.spy(),
);
assert.strictEqual(toolHandler.disabled, true);
const result = await toolHandler.handle({});
assert.strictEqual(result.isError, true);
assert.match(
result.content[0].type === 'text' ? result.content[0].text : '',
/is currently disabled/,
);
assert.strictEqual(handlerCalled, false);
});
it('registers evaluate_script by default and disables it when javascriptEvaluation is false', async () => {
const mockContext = createMockMcpContext();
const defaultConfig = parseConfig();
const defaultTool = createTools(defaultConfig.resolved).find(
t => t.name === 'evaluate_script',
);
if (!defaultTool) {
assert.fail('evaluate_script not found');
}
const defaultHandler = new ToolHandler(
defaultTool,
defaultConfig,
async () => mockContext,
sinon.spy(),
);
assert.strictEqual(defaultHandler.disabled, false);
const disabledConfig = parseConfig(['--no-javascript-evaluation']);
const disabledTool = createTools(disabledConfig.resolved).find(
t => t.name === 'evaluate_script',
);
if (!disabledTool) {
assert.fail('evaluate_script not found');
}
const disabledHandler = new ToolHandler(
disabledTool,
disabledConfig,
async () => mockContext,
sinon.spy(),
);
assert.strictEqual(disabledHandler.disabled, true);
const disabledResult = await disabledHandler.handle({function: '() => 1'});
assert.strictEqual(disabledResult.isError, true);
assert.match(
disabledResult.content[0].type === 'text'
? disabledResult.content[0].text
: '',
/Tool evaluate_script requires flag --javascriptEvaluation and is currently disabled/,
);
const cliConfig = parseConfig(['--no-javascript-evaluation', '--viaCli']);
const cliTool = createTools(cliConfig.resolved).find(
t => t.name === 'evaluate_script',
);
if (!cliTool) {
assert.fail('evaluate_script not found');
}
const cliHandler = new ToolHandler(
cliTool,
cliConfig,
async () => mockContext,
sinon.spy(),
);
assert.strictEqual(cliHandler.disabled, false);
const cliResult = await cliHandler.handle({function: '() => 1'});
assert.strictEqual(cliResult.isError, true);
assert.match(
cliResult.content[0].type === 'text' ? cliResult.content[0].text : '',
/Tool evaluate_script requires flag --javascriptEvaluation and is currently disabled/,
);
});
it('disables slim evaluate tool when javascriptEvaluation is false', async () => {
const mockContext = createMockMcpContext();
const defaultConfig = parseConfig(['--slim']);
const defaultTool = createTools(defaultConfig.resolved).find(
t => t.name === 'evaluate',
);
if (!defaultTool) {
assert.fail('evaluate not found');
}
const defaultHandler = new ToolHandler(
defaultTool,
defaultConfig,
async () => mockContext,
sinon.spy(),
);
assert.strictEqual(defaultHandler.disabled, false);
const disabledConfig = parseConfig([
'--slim',
'--javascriptEvaluation=false',
]);
const disabledTool = createTools(disabledConfig.resolved).find(
t => t.name === 'evaluate',
);
if (!disabledTool) {
assert.fail('evaluate not found');
}
const disabledHandler = new ToolHandler(
disabledTool,
disabledConfig,
async () => mockContext,
sinon.spy(),
);
assert.strictEqual(disabledHandler.disabled, true);
});
it('disables set_logpoints when javascriptEvaluation is false', async () => {
const mockContext = createMockMcpContext();
const defaultConfig = parseConfig();
const defaultTool = createTools(defaultConfig.resolved).find(
t => t.name === 'set_logpoints',
);
if (!defaultTool) {
assert.fail('set_logpoints not found');
}
const defaultHandler = new ToolHandler(
defaultTool,
defaultConfig,
async () => mockContext,
sinon.spy(),
);
assert.strictEqual(defaultHandler.disabled, false);
const disabledConfig = parseConfig(['--no-javascript-evaluation']);
const disabledTool = createTools(disabledConfig.resolved).find(
t => t.name === 'set_logpoints',
);
if (!disabledTool) {
assert.fail('set_logpoints not found');
}
const disabledHandler = new ToolHandler(
disabledTool,
disabledConfig,
async () => mockContext,
sinon.spy(),
);
assert.strictEqual(disabledHandler.disabled, true);
const disabledResult = await disabledHandler.handle({logpoints: []});
assert.strictEqual(disabledResult.isError, true);
assert.match(
disabledResult.content[0].type === 'text'
? disabledResult.content[0].text
: '',
/Tool set_logpoints requires flag --javascriptEvaluation and is currently disabled/,
);
});
describe('slim mode', () => {
function createHandler(toolName: string, argv: string[]) {
const config = parseConfig(argv);
const tool = createTools(config.resolved).find(t => t.name === toolName);
if (!tool) {
assert.fail(`${toolName} not found`);
}
return new ToolHandler(
tool,
config,
async () => createMockMcpContext(),
sinon.spy(),
);
}
it('disables slim tools without --slim', async () => {
const handler = createHandler('navigate', []);
assert.strictEqual(handler.disabled, true);
const result = await handler.handle({url: 'https://example.com'});
assert.strictEqual(result.isError, true);
assert.deepStrictEqual(result.content, [
{type: 'text', text: 'Tool navigate is only available with --slim.'},
]);
});
it('disables non-slim tools with --slim', async () => {
const handler = createHandler('navigate_page', ['--slim']);
assert.strictEqual(handler.disabled, true);
const result = await handler.handle({url: 'https://example.com'});
assert.strictEqual(result.isError, true);
assert.deepStrictEqual(result.content, [
{
type: 'text',
text: 'Tool navigate_page is not available with --slim.',
},
]);
});
it('enables slim tools with --slim', () => {
assert.strictEqual(createHandler('navigate', ['--slim']).disabled, false);
});
it('disables tools from the other mode even via CLI', () => {
assert.strictEqual(
createHandler('navigate', ['--viaCli']).disabled,
true,
);
});
});
it('validates files specified in verifyFilesSchema and rewrites input with validated paths/URLs', async () => {
let handlerCalled = false;
let receivedParams: Record<string, unknown> | undefined;
const tool: ToolDefinition = {
name: 'file_tool',
description: 'A tool requiring file validation',
annotations: {
category: ToolCategory.PERFORMANCE,
readOnlyHint: true,
},
schema: {
filePath: zod.string(),
fileList: zod.array(zod.string()),
},
blockedByDialog: false,
concurrency: 'exclusive',
verifyFilesSchema: {
filePath: true,
// allowUrl lets a remote URL pass through unchanged (file/plain paths
// are still validated); this is what source-map/PWA-style params use.
fileList: {local: true, remote: true, allowUrl: true},
},
handler: async request => {
handlerCalled = true;
receivedParams = request.params;
},
};
const mockContext = createMockMcpContext();
const mockProcess = sinon.createStubInstance(ChildProcess);
mockContext.ensureBrowser.resolves(getMockBrowser({process: mockProcess}));
mockContext.validatePath.callsFake(async p => {
if (!p) {
return undefined;
}
return path.resolve(
'/canonical',
path.relative(path.resolve('/workspace'), p),
);
});
const config = parseConfig();
const toolHandler = new ToolHandler(
tool,
config,
async () => mockContext,
sinon.spy(),
);
const testFile = path.resolve('/workspace/url-file.txt');
const testFileUrl = pathToFileURL(testFile).href;
const testListFile1 = path.resolve('/workspace/list1.txt');
const testListFile2 = path.resolve('/workspace/list2.txt');
const result = await toolHandler.handle({
filePath: testFileUrl,
fileList: [
testListFile1,
testListFile2,
'https://example.com/remote.txt',
],
});
assert.strictEqual(result.isError, undefined);
assert.strictEqual(handlerCalled, true);
sinon.assert.callCount(mockContext.validatePath, 3);
assert.strictEqual(mockContext.validatePath.calledWith(testFile), true);
assert.strictEqual(
mockContext.validatePath.calledWith(testListFile1),
true,
);
assert.strictEqual(
mockContext.validatePath.calledWith(testListFile2),
true,
);
assert.deepStrictEqual(receivedParams, {
filePath: pathToFileURL(path.resolve('/canonical/url-file.txt')).href,
fileList: [
path.resolve('/canonical/list1.txt'),
path.resolve('/canonical/list2.txt'),
'https://example.com/remote.txt',
],
});
});
it('returns error when file validation fails for verifyFilesSchema', async () => {
let handlerCalled = false;
const tool: ToolDefinition = {
name: 'file_tool',
description: 'A tool requiring file validation',
annotations: {
category: ToolCategory.PERFORMANCE,
readOnlyHint: true,
},
schema: {
filePath: zod.string(),
},
blockedByDialog: false,
concurrency: 'exclusive',
verifyFilesSchema: {
filePath: true,
},
handler: async () => {
handlerCalled = true;
},
};
const mockContext = createMockMcpContext();
const mockProcess = sinon.createStubInstance(ChildProcess);
mockContext.ensureBrowser.resolves(getMockBrowser({process: mockProcess}));
mockContext.validatePath.rejects(
new Error('Access denied: path is outside roots'),
);
const config = parseConfig();
const toolHandler = new ToolHandler(
tool,
config,
async () => mockContext,
sinon.spy(),
);
const result = await toolHandler.handle({
filePath: '/outside/workspace/file.txt',
});
assert.strictEqual(result.isError, true);
assert.match(
result.content[0].type === 'text' ? result.content[0].text : '',
/Access denied/,
);
assert.strictEqual(handlerCalled, false);
});
for (const body of ['/outside/script.js', 'https://example.com/script.js']) {
it(
'validates mock_network body files before resolving the page: ' + body,
async () => {
const config = parseConfig(['--categoryNetworkMocks']);
const context = createMockMcpContext();
context.ensureBrowser.resolves(getMockBrowser());
context.validatePath.rejects(new Error('Access denied'));
const handler = new ToolHandler(
mockNetwork(config.resolved),
config,
async () => context,
sinon.spy(),
);
const result = await handler.handle({pageId: 1, body});
assert.strictEqual(result.isError, true);
assert.match(
result.content[0].type === 'text' ? result.content[0].text : '',
/Access denied|expects a file path, not a URL/,
);
sinon.assert.notCalled(context.getPageById);
},
);
}
for (const thrown of ['str-thrown', 0]) {
it(`reports non-Error values thrown by a handler: ${thrown}`, async () => {
const tool: ToolDefinition = {
name: 'throwing_tool',
description: 'A tool that throws a non-Error value',
annotations: {
category: ToolCategory.INPUT,
readOnlyHint: true,
},
schema: {},
blockedByDialog: false,
concurrency: 'exclusive',
verifyFilesSchema: {},
handler: async () => {
// eslint-disable-next-line @typescript-eslint/only-throw-error
throw thrown;
},
};
const mockContext = createMockMcpContext();
mockContext.ensureBrowser.resolves(
getMockBrowser({process: sinon.createStubInstance(ChildProcess)}),
);
const toolHandler = new ToolHandler(
tool,
parseConfig(),
async () => mockContext,
sinon.spy(),
);
const result = await toolHandler.handle({});
assert.strictEqual(result.isError, true);
assert.deepStrictEqual(result.content, [
{type: 'text', text: `Error: ${thrown}`},
]);
});
}
it('validates evaluate_script sourcePath before reading the file', async () => {
const config = parseConfig();
const tool = evaluateScript(config.resolved);
const mockContext = createMockMcpContext();
const mockProcess = sinon.createStubInstance(ChildProcess);
mockContext.ensureBrowser.resolves(getMockBrowser({process: mockProcess}));
mockContext.validatePath.rejects(
new Error('Access denied: path is outside roots'),
);
const toolHandler = new ToolHandler(
tool,
config,
async () => mockContext,
sinon.spy(),
);
const sourcePath = path.resolve('/outside/workspace/script.js');
const result = await toolHandler.handle({sourcePath, pageId: 1});
assert.strictEqual(result.isError, true);
assert.match(
result.content[0].type === 'text' ? result.content[0].text : '',
/Access denied/,
);
sinon.assert.calledOnceWithExactly(mockContext.validatePath, sourcePath);
sinon.assert.notCalled(mockContext.loadResource);
});
it('validates verifyFilesSchema when local: true and browser is running locally via process', async () => {
let handlerCalled = false;
let receivedParams: Record<string, unknown> | undefined;
const tool: ToolDefinition = {
name: 'upload_tool',
description: 'A tool with local-only file verification',
annotations: {
category: ToolCategory.INPUT,
readOnlyHint: false,
},
schema: {
filePaths: zod.array(zod.string()),
},
blockedByDialog: false,
concurrency: 'exclusive',
verifyFilesSchema: {
filePaths: {
local: true,
remote: false,
},
},
handler: async request => {
handlerCalled = true;
receivedParams = request.params;
},
};
const mockContext = createMockMcpContext();
const mockProcess = sinon.createStubInstance(ChildProcess);
mockContext.ensureBrowser.resolves(getMockBrowser({process: mockProcess}));
const canonicalPath = path.resolve('/canonical/workspace/upload.png');
mockContext.validatePath.resolves(canonicalPath);
const config = parseConfig();
const toolHandler = new ToolHandler(
tool,
config,
async () => mockContext,
sinon.spy(),
);
const testPath = path.resolve('/workspace/upload.png');
const result = await toolHandler.handle({
filePaths: [testPath],
});
assert.strictEqual(result.isError, undefined);
assert.strictEqual(handlerCalled, true);
assert.strictEqual(mockContext.validatePath.calledOnceWith(testPath), true);
assert.deepStrictEqual(receivedParams, {
filePaths: [canonicalPath],
});
});
it('validates verifyFilesSchema when local: true and browser is connected to localhost wsEndpoint', async () => {
let handlerCalled = false;
let receivedParams: Record<string, unknown> | undefined;
const tool: ToolDefinition = {
name: 'install_pwa_tool',
description: 'PWA tool with local-only file verification',
annotations: {
category: ToolCategory.INPUT,
readOnlyHint: false,
},
schema: {
installUrlOrBundleUrl: zod.string(),
},
blockedByDialog: false,
concurrency: 'exclusive',
verifyFilesSchema: {
installUrlOrBundleUrl: {
local: true,
},
},
handler: async request => {
handlerCalled = true;
receivedParams = request.params;
},
};
const mockContext = createMockMcpContext();
mockContext.ensureBrowser.resolves(
getMockBrowser({
wsEndpoint: 'ws://127.0.0.1:9222/devtools/browser/test',
}),
);
const canonicalBundlePath = path.resolve('/canonical/workspace/app.swbn');
mockContext.validatePath.resolves(canonicalBundlePath);
const config = parseConfig();
const toolHandler = new ToolHandler(
tool,
config,
async () => mockContext,
sinon.spy(),
);
const bundlePath = path.resolve('/workspace/app.swbn');
const fileUrl = pathToFileURL(bundlePath).href;
const result = await toolHandler.handle({
installUrlOrBundleUrl: fileUrl,
});
assert.strictEqual(result.isError, undefined);
assert.strictEqual(handlerCalled, true);
assert.strictEqual(
mockContext.validatePath.calledOnceWith(bundlePath),
true,
);
assert.deepStrictEqual(receivedParams, {
installUrlOrBundleUrl: pathToFileURL(canonicalBundlePath).href,
});
});
it('validates local-only verifyFilesSchema when browser is connected to a 0.0.0.0 wsEndpoint', async () => {
const handler = sinon.stub().resolves();
const tool: ToolDefinition = {
name: 'upload_tool',
description: 'A tool with local-only file verification',
annotations: {
category: ToolCategory.INPUT,
readOnlyHint: false,
},
schema: {
filePaths: zod.array(zod.string()),
},
blockedByDialog: false,
concurrency: 'exclusive',
verifyFilesSchema: {
filePaths: {
local: true,
remote: false,
},
},
handler,
};
const mockContext = createMockMcpContext();
mockContext.ensureBrowser.resolves(
getMockBrowser({
wsEndpoint: 'ws://0.0.0.0:9222/devtools/browser/test',
}),
);
mockContext.validatePath.rejects(new Error('Access denied'));
const toolHandler = new ToolHandler(
tool,
parseConfig(),
async () => mockContext,
sinon.spy(),
);
const result = await toolHandler.handle({
filePaths: ['/etc/passwd'],
});
assert.strictEqual(result.isError, true);
sinon.assert.calledOnceWithExactly(mockContext.validatePath, '/etc/passwd');
sinon.assert.notCalled(handler);
});
it('skips local-only verifyFilesSchema when browser is remote', async () => {
let handlerCalled = false;
let receivedParams: Record<string, unknown> | undefined;
const tool: ToolDefinition = {
name: 'upload_tool',
description: 'A tool with local-only file verification',
annotations: {
category: ToolCategory.INPUT,
readOnlyHint: false,
},
schema: {
filePaths: zod.array(zod.string()),
},
blockedByDialog: false,
concurrency: 'exclusive',
verifyFilesSchema: {
filePaths: {
local: true,
remote: false,
},
},
handler: async request => {
handlerCalled = true;
receivedParams = request.params;
},
};
const mockContext = createMockMcpContext();
mockContext.ensureBrowser.resolves(
getMockBrowser({
wsEndpoint: 'ws://remote-host.com:9222/devtools/browser/test',
}),
);
const config = parseConfig();
const toolHandler = new ToolHandler(
tool,
config,
async () => mockContext,
sinon.spy(),
);
const result = await toolHandler.handle({
filePaths: ['/remote/server/path.txt'],
});
assert.strictEqual(result.isError, undefined);
assert.strictEqual(handlerCalled, true);
assert.strictEqual(mockContext.validatePath.called, false);
assert.deepStrictEqual(receivedParams, {
filePaths: ['/remote/server/path.txt'],
});
});
it('skips local-only verifyFilesSchema when browser has no process', async () => {
let handlerCalled = false;
const tool: ToolDefinition = {
name: 'upload_tool',
description: 'A tool with local-only file verification',
annotations: {
category: ToolCategory.INPUT,
readOnlyHint: false,
},
schema: {
filePaths: zod.array(zod.string()),
},
blockedByDialog: false,
concurrency: 'exclusive',
verifyFilesSchema: {
filePaths: {
local: true,
},
},
handler: async () => {
handlerCalled = true;
},
};
const mockContext = createMockMcpContext();
mockContext.ensureBrowser.resolves(getMockBrowser());
const config = parseConfig();
const toolHandler = new ToolHandler(
tool,
config,
async () => mockContext,
sinon.spy(),
);
const result = await toolHandler.handle({
filePaths: ['/path/to/upload.txt'],
});
assert.strictEqual(result.isError, undefined);
assert.strictEqual(handlerCalled, true);
assert.strictEqual(mockContext.validatePath.called, false);
});
it('skips non-file URLs for local-only verifyFilesSchema even on local browser', async () => {
let handlerCalled = false;
const tool: ToolDefinition = {
name: 'install_pwa_tool',
description: 'PWA tool with local-only file verification',
annotations: {
category: ToolCategory.INPUT,
readOnlyHint: false,
},
schema: {
installUrlOrBundleUrl: zod.string(),
},
blockedByDialog: false,
concurrency: 'exclusive',
verifyFilesSchema: {
installUrlOrBundleUrl: {
local: true,
allowUrl: true,
},
},
handler: async () => {
handlerCalled = true;
},
};
const mockContext = createMockMcpContext();
const mockProcess = sinon.createStubInstance(ChildProcess);
mockContext.ensureBrowser.resolves(getMockBrowser({process: mockProcess}));
const config = parseConfig();
const toolHandler = new ToolHandler(
tool,
config,
async () => mockContext,
sinon.spy(),
);
const result = await toolHandler.handle({
installUrlOrBundleUrl: 'https://example.com/app',
});
assert.strictEqual(result.isError, undefined);
assert.strictEqual(handlerCalled, true);
assert.strictEqual(mockContext.validatePath.called, false);
});
it('rejects an http/ws URL for a filesystem-path parameter when allowUrl is not set, even on a local browser', async () => {
// Regression test for the allowUrl TSDoc in ToolDefinition.ts: a filesystem-path parameter must reject a value that merely parses as an http/ws URL instead of passing it through.
let handlerCalled = false;
const tool: ToolDefinition = {
name: 'upload_tool',
description: 'A local-only file sink without allowUrl',
annotations: {
category: ToolCategory.INPUT,
readOnlyHint: false,
},
schema: {
filePaths: zod.array(zod.string()),
},
blockedByDialog: false,
concurrency: 'exclusive',
verifyFilesSchema: {
filePaths: {
local: true,
remote: false,
},
},
handler: async () => {
handlerCalled = true;
},
};
const mockContext = createMockMcpContext();
const mockProcess = sinon.createStubInstance(ChildProcess);
mockContext.ensureBrowser.resolves(getMockBrowser({process: mockProcess}));
const config = parseConfig();
const toolHandler = new ToolHandler(
tool,
config,
async () => mockContext,
sinon.spy(),
);
const traversalUrl = 'http://x/' + '../'.repeat(12) + 'etc/passwd';
const result = await toolHandler.handle({filePaths: [traversalUrl]});
assert.strictEqual(result.isError, true);
assert.strictEqual(handlerCalled, false);
sinon.assert.notCalled(mockContext.validatePath);
assert.strictEqual(
result.content[0].type === 'text' ? result.content[0].text : '',
'Error: This parameter expects a file path, not a URL.',
);
});
it('validates verifyFilesSchema with true but skips local: true on remote browser', async () => {
let handlerCalled = false;
let receivedParams: Record<string, unknown> | undefined;
const tool: ToolDefinition = {
name: 'hybrid_tool',
description: 'A tool with both schema file verifications',
annotations: {
category: ToolCategory.PERFORMANCE,
readOnlyHint: false,
},
schema: {
outputFile: zod.string(),
inputFile: zod.string(),
},
blockedByDialog: false,
concurrency: 'exclusive',
verifyFilesSchema: {
outputFile: true,
inputFile: {
local: true,
remote: false,
},
},
handler: async request => {
handlerCalled = true;
receivedParams = request.params;
},
};
const mockContext = createMockMcpContext();
mockContext.ensureBrowser.resolves(
getMockBrowser({
wsEndpoint: 'ws://remote-host.com:9222/devtools/browser/test',
}),
);
const canonicalOutputPath = path.resolve('/canonical/output.json');
mockContext.validatePath.resolves(canonicalOutputPath);
const config = parseConfig();
const toolHandler = new ToolHandler(
tool,
config,
async () => mockContext,
sinon.spy(),
);
const outputPath = path.resolve('/local/output.json');
const result = await toolHandler.handle({
outputFile: outputPath,
inputFile: '/remote/input.json',
});
assert.strictEqual(result.isError, undefined);
assert.strictEqual(handlerCalled, true);
assert.strictEqual(
mockContext.validatePath.calledOnceWith(outputPath),
true,
);
assert.deepStrictEqual(receivedParams, {
outputFile: canonicalOutputPath,
inputFile: '/remote/input.json',
});
});
it('returns error when file validation fails for local: true on local browser', async () => {
let handlerCalled = false;
const tool: ToolDefinition = {
name: 'upload_tool',
description: 'A tool with local-only file verification',
annotations: {
category: ToolCategory.INPUT,
readOnlyHint: false,
},
schema: {
filePaths: zod.array(zod.string()),
},
blockedByDialog: false,
concurrency: 'exclusive',
verifyFilesSchema: {
filePaths: {
local: true,
remote: false,
},
},
handler: async () => {
handlerCalled = true;
},
};
const mockContext = createMockMcpContext();
const mockProcess = sinon.createStubInstance(ChildProcess);
mockContext.ensureBrowser.resolves(getMockBrowser({process: mockProcess}));
mockContext.validatePath.rejects(
new Error('Path is outside configured roots'),
);
const config = parseConfig();
const toolHandler = new ToolHandler(
tool,
config,
async () => mockContext,
sinon.spy(),
);
const result = await toolHandler.handle({
filePaths: ['/forbidden/path.txt'],
});
assert.strictEqual(result.isError, true);
assert.match(
result.content[0].type === 'text' ? result.content[0].text : '',
/Path is outside configured roots/,
);
assert.strictEqual(handlerCalled, false);
});
it('validates remote: true on remote browser and skips on local browser', async () => {
const tool: ToolDefinition = {
name: 'remote_file_tool',
description: 'A tool with remote-only file verification',
annotations: {
category: ToolCategory.PERFORMANCE,
readOnlyHint: false,
},
schema: {
remoteFile: zod.string(),
},
blockedByDialog: false,
concurrency: 'exclusive',
verifyFilesSchema: {
remoteFile: {
local: false,
remote: true,
},
},
handler: async () => {
// no-op
},
};
const config = parseConfig();
// Remote browser: should validate
const mockRemoteContext = createMockMcpContext();
mockRemoteContext.ensureBrowser.resolves(
getMockBrowser({
wsEndpoint: 'ws://remote-host.com:9222/devtools/browser/test',
}),
);
mockRemoteContext.validatePath.resolves();
const remoteToolHandler = new ToolHandler(
tool,
config,
async () => mockRemoteContext,
sinon.spy(),
);
const remotePath = path.resolve('/remote/file.txt');
await remoteToolHandler.handle({remoteFile: remotePath});
assert.strictEqual(
mockRemoteContext.validatePath.calledOnceWith(remotePath),
true,
);
// Local browser: should skip
const mockLocalContext = createMockMcpContext();
const mockProcess = sinon.createStubInstance(ChildProcess);
mockLocalContext.ensureBrowser.resolves(
getMockBrowser({process: mockProcess}),
);
const localToolHandler = new ToolHandler(
tool,
config,
async () => mockLocalContext,
sinon.spy(),
);
await localToolHandler.handle({remoteFile: remotePath});
assert.strictEqual(mockLocalContext.validatePath.called, false);
});
it('rewrites file paths in params for page scoped tools', async () => {
let receivedParams: Record<string, unknown> | undefined;
const config = parseConfig(['--no-page-id-routing']);
const tool = definePageTool(() => ({
name: 'page_file_tool',
description: 'A page scoped tool with file verification',
annotations: {
category: ToolCategory.DEBUGGING,
readOnlyHint: false,
},
schema: {
filePath: zod.string(),
},
blockedByDialog: false,
concurrency: 'exclusive',
verifyFilesSchema: {
filePath: true,
},
handler: async request => {
receivedParams = request.params;
},
}))(config.resolved);
const mockContext = createMockMcpContext();
const mockProcess = sinon.createStubInstance(ChildProcess);
mockContext.ensureBrowser.resolves(getMockBrowser({process: mockProcess}));
mockContext.getDevToolsData.resolves({});
const mockPage = sinon.createStubInstance(McpPage);
mockPage.getDialog.returns(undefined);
mockPage.getConsoleDataAfter.returns([]);
sinon.stub(mockPage, 'networkConditions').get(() => undefined);
sinon.stub(mockPage, 'geolocation').get(() => undefined);
sinon.stub(mockPage, 'viewport').get(() => undefined);
sinon.stub(mockPage, 'userAgent').get(() => undefined);
sinon.stub(mockPage, 'colorScheme').get(() => undefined);
sinon.stub(mockPage, 'forcedColors').get(() => undefined);
sinon.stub(mockPage, 'prefersContrast').get(() => undefined);
sinon.stub(mockPage, 'prefersReducedMotion').get(() => undefined);
sinon.stub(mockPage, 'cpuThrottlingRate').get(() => 1);
mockContext.getSelectedMcpPage.returns(mockPage);
const canonicalFilePath = path.resolve('/canonical/output.png');
mockContext.validatePath.resolves(canonicalFilePath);
const toolHandler = new ToolHandler(
tool,
config,
async () => mockContext,
sinon.spy(),
);
const inputPath = path.resolve('/workspace/output.png');
const result = await toolHandler.handle({
filePath: inputPath,
});
assert.strictEqual(result.isError, undefined);
assert.strictEqual(
mockContext.validatePath.calledOnceWith(inputPath),
true,
);
assert.deepStrictEqual(receivedParams, {
filePath: canonicalFilePath,
});
});
it('skips validation and clears empty or whitespace-only file paths in params', async () => {
let receivedParams: Record<string, unknown> | undefined;
const tool: ToolDefinition = {
name: 'file_tool',
description: 'A tool with file verification',
annotations: {
category: ToolCategory.DEBUGGING,
readOnlyHint: false,
},
schema: {
filePath: zod.string().optional(),
filePaths: zod.array(zod.string()).optional(),
},
blockedByDialog: false,
concurrency: 'exclusive',
verifyFilesSchema: {
filePath: true,
filePaths: true,
},
handler: async request => {
receivedParams = request.params;
},
};
const mockContext = createMockMcpContext();
mockContext.ensureBrowser.resolves(getMockBrowser());
const config = parseConfig();
const toolHandler = new ToolHandler(
tool,
config,
async () => mockContext,
sinon.spy(),
);
const result = await toolHandler.handle({
filePath: ' ',
filePaths: [' ', ''],
});
assert.strictEqual(result.isError, undefined);
sinon.assert.notCalled(mockContext.validatePath);
assert.deepStrictEqual(receivedParams, {
filePath: undefined,
filePaths: [],
});
});
it('does not cut off a slow tool handler on a healthy browser', async () => {
const tool: ToolDefinition = {
name: 'slow_tool',
description: 'A tool whose handler legitimately outlasts the timeout',
annotations: {
category: ToolCategory.NAVIGATION,
readOnlyHint: true,
},
schema: {},
blockedByDialog: false,
concurrency: 'exclusive',
verifyFilesSchema: {},
handler: async (_request, response) => {
// Simulates valid slow work, e.g. wait_for with a long timeout or
// evaluate_script awaiting a slow promise.
await new Promise<void>(resolve => {
setTimeout(resolve, TOOL_CALL_TIMEOUT_MS * 2);
});
response.appendResponseLine('done');
},
};
const mockContext = createMockMcpContext();
const mockProcess = sinon.createStubInstance(ChildProcess);
mockContext.ensureBrowser.resolves(getMockBrowser({process: mockProcess}));
const config = parseConfig();
const toolHandler = new ToolHandler(
tool,
config,
async () => mockContext,
sinon.spy(),
);
// Keep the test runner's clocks real while advancing the tool timeout.
const clock = sinon.useFakeTimers({toFake: ['setTimeout', 'clearTimeout']});
try {
const resultPromise = toolHandler.handle({});
await clock.tickAsync(TOOL_CALL_TIMEOUT_MS * 2);
const result = await resultPromise;
assert.strictEqual(result.isError, undefined);
assert.strictEqual(
result.content[0].type === 'text' ? result.content[0].text : '',
'done',
);
} finally {
clock.restore();
}
});
it('times out when ensureBrowser() hangs, and abandons the pending connect', async () => {
const tool: ToolDefinition = {
name: 'hanging_context_tool',
description: 'A tool whose browser connection never resolves',
annotations: {
category: ToolCategory.NAVIGATION,
readOnlyHint: true,
},
schema: {},
blockedByDialog: false,
concurrency: 'exclusive',
verifyFilesSchema: {},
handler: async () => {
// Never reached: the timeout fires while still awaiting ensureBrowser().
},
};
const mockContext = createMockMcpContext();
mockContext.ensureBrowser.returns(
new Promise(() => {
// Simulates BrowserManager#ensureBrowser() hanging on a half-open
// socket: it never resolves or rejects on its own.
}),
);
const abandonPendingBrowserAttemptSpy = sinon.spy();
const config = parseConfig();
const toolHandler = new ToolHandler(
tool,
config,
async () => mockContext,
abandonPendingBrowserAttemptSpy,
);
const clock = sinon.useFakeTimers({toFake: ['setTimeout', 'clearTimeout']});
try {
const resultPromise = toolHandler.handle({});
await clock.tickAsync(TOOL_CALL_TIMEOUT_MS);
const result = await resultPromise;
assert.strictEqual(result.isError, true);
assert.match(
result.content[0].type === 'text' ? result.content[0].text : '',
/timed out/,
);
sinon.assert.calledOnce(abandonPendingBrowserAttemptSpy);
} finally {
clock.restore();
}
});
it('emulates focus before a page tool acts on an untouched background page', async () => {
const focusStates: boolean[] = [];
const config = parseConfig();
await withMcpContext(async (_response, context) => {
const page = context.getSelectedMcpPage();
const foregroundPage = await context.browser.newPage();
await foregroundPage.bringToFront();
focusStates.push(await page.pptrPage.evaluate(() => document.hasFocus()));
const tool = definePageTool(() => ({
name: 'page_tool',
description: 'A page scoped tool',
annotations: {category: ToolCategory.INPUT, readOnlyHint: true},
schema: {},
blockedByDialog: false,
concurrency: 'exclusive',
verifyFilesSchema: {},
handler: async ({page}) => {
focusStates.push(
await page.pptrPage.evaluate(() => document.hasFocus()),
);
},
}))(config.resolved);
const handler = new ToolHandler(
tool,
config,
async () => context,
sinon.spy(),
);
const result = await handler.handle({pageId: page.id});
assert.notStrictEqual(result.isError, true);
});
assert.deepStrictEqual(focusStates, [false, true]);
});
async function handlePageToolCall(
concurrency: DefinedPageTool['concurrency'],
) {
sinon
.stub(McpResponse.prototype, 'handle')
.resolves({content: [], structuredContent: {}});
const includeConsoleErrorsFrom = sinon.spy(
McpResponse.prototype,
'includeConsoleErrorsFrom',
);
const config = parseConfig();
const mockContext = createMockMcpContext();
mockContext.ensureBrowser.resolves(
getMockBrowser({process: sinon.createStubInstance(ChildProcess)}),
);
const mockPage = createMockMcpPage();
mockContext.getPageById.returns(mockPage);
const tool = definePageTool(() => ({
name: 'page_tool',
description: 'A page scoped tool',
annotations: {category: ToolCategory.INPUT, readOnlyHint: false},
schema: {},
blockedByDialog: false,
concurrency,
verifyFilesSchema: {},
handler: async () => {},
}))(config.resolved);
await new ToolHandler(
tool,
config,
async () => mockContext,
sinon.spy(),
).handle({pageId: 1});
return {includeConsoleErrorsFrom, mockPage};
}
it("hands the page of a page tool with concurrency 'exclusive' to the response", async () => {
const {includeConsoleErrorsFrom, mockPage} =
await handlePageToolCall('exclusive');
sinon.assert.calledOnceWithExactly(includeConsoleErrorsFrom, mockPage);
});
it("does not hand the page of a page tool with concurrency 'none' to the response", async () => {
const {includeConsoleErrorsFrom} = await handlePageToolCall('none');
sinon.assert.notCalled(includeConsoleErrorsFrom);
});
describe('browserless tools', () => {
function createBrowserlessTool(
handler: BrowserlessToolDefinition['handler'],
) {
return defineBrowserlessTool(() => ({
name: 'browserless_tool',
description: 'A tool that does not need a browser',
annotations: {
category: ToolCategory.MEMORY,
readOnlyHint: true,
},
schema: {
filePath: zod.string(),
},
blockedByDialog: false,
verifyFilesSchema: {filePath: true},
handler,
}))(parseConfig().resolved);
}
it('runs without establishing a browser connection', async () => {
const handler = sinon.stub().resolves();
const mockContext = createMockMcpContext();
mockContext.validatePath.resolves('/canonical/file.heapsnapshot');
const handleStub = sinon
.stub(McpResponse.prototype, 'handle')
.resolves({content: [], structuredContent: {}});
const result = await new ToolHandler(
createBrowserlessTool(handler),
parseConfig(),
async () => mockContext,
sinon.spy(),
).handle({filePath: 'file.heapsnapshot'});
assert.strictEqual(result.isError, undefined);
sinon.assert.notCalled(mockContext.ensureBrowser);
sinon.assert.notCalled(mockContext.consumeReconnectNotice);
sinon.assert.notCalled(mockContext.getDevToolsData);
sinon.assert.calledOnceWithExactly(
mockContext.validatePath,
'file.heapsnapshot',
);
sinon.assert.calledOnceWithExactly(
handler,
{params: {filePath: '/canonical/file.heapsnapshot'}},
sinon.match.instanceOf(McpResponse),
mockContext,
);
sinon.assert.calledOnceWithExactly(handleStub, mockContext, 'default');
});
it('defaults to concurrency none', () => {
const tool = createBrowserlessTool(sinon.stub().resolves());
assert.strictEqual(tool.concurrency, 'none');
});
it('does not enter the context queue', async () => {
const mockContext = createMockMcpContext();
mockContext.validatePath.resolves('/canonical/file.heapsnapshot');
sinon
.stub(McpResponse.prototype, 'handle')
.resolves({content: [], structuredContent: {}});
const scheduleTask = sinon.stub(mockContext.taskQueue, 'scheduleTask');
const result = await new ToolHandler(
createBrowserlessTool(sinon.stub().resolves()),
parseConfig(),
async () => mockContext,
sinon.spy(),
).handle({filePath: 'file.heapsnapshot'});
assert.strictEqual(result.isError, undefined);
sinon.assert.notCalled(scheduleTask);
});
it('runs while another tool holds the context queue', async () => {
const mockContext = createMockMcpContext();
mockContext.validatePath.resolves('/canonical/file.heapsnapshot');
sinon
.stub(McpResponse.prototype, 'handle')
.resolves({content: [], structuredContent: {}});
const handler = sinon.stub().resolves();
const {promise: release, resolve: finishExclusive} =
Promise.withResolvers<void>();
const exclusive = runOn(mockContext.taskQueue, async () => {
await release;
});
const result = await new ToolHandler(
createBrowserlessTool(handler),
parseConfig(),
async () => mockContext,
sinon.spy(),
).handle({filePath: 'file.heapsnapshot'});
finishExclusive();
await exclusive;
assert.strictEqual(result.isError, undefined);
sinon.assert.calledOnce(handler);
});
});
describe('update', () => {
function createGlobalTool(
schema: ToolDefinition['schema'],
handler: ToolDefinition['handler'],
options: {
description?: string;
annotations?: ToolDefinition['annotations'];
} = {},
): ToolDefinition {
return {
name: 'global_tool',
description: options.description ?? 'A global tool',
annotations: options.annotations ?? {
category: ToolCategory.NAVIGATION,
readOnlyHint: true,
},
schema,
blockedByDialog: false,
concurrency: 'exclusive',
verifyFilesSchema: {},
handler,
};
}
it('applies to calls that wait for the queue', async () => {
const config = parseConfig();
const handler = sinon.stub().resolves();
const tool = createGlobalTool({}, handler);
const taskRunner = new TaskRunner();
const mockContext = createMockMcpContext({taskRunner});
const toolHandler = new ToolHandler(
tool,
config,
async () => mockContext,
sinon.spy(),
);
const guard = await taskRunner.pause();
const call = toolHandler.handle({});
config.commit(parseConfig(['--no-category-navigation']));
toolHandler.update(tool);
guard[Symbol.dispose]();
const result = await call;
assert.strictEqual(result.isError, true);
assert.match(
result.content[0]?.type === 'text' ? result.content[0].text : '',
/is currently disabled/,
);
sinon.assert.notCalled(handler);
});
it('validates waiting calls against the updated schema', async () => {
const config = parseConfig();
const handler = sinon.stub().resolves();
const taskRunner = new TaskRunner();
const mockContext = createMockMcpContext({taskRunner});
const toolHandler = new ToolHandler(
createGlobalTool({a: zod.string().optional()}, handler),
config,
async () => mockContext,
sinon.spy(),
);
const guard = await taskRunner.pause();
const call = toolHandler.handle({a: 'value'});
const listingChanged = toolHandler.update(
createGlobalTool(
{a: zod.string().optional(), b: zod.string()},
handler,
),
);
guard[Symbol.dispose]();
const result = await call;
assert.strictEqual(listingChanged, true);
assert.strictEqual(result.isError, true);
assert.match(
result.content[0]?.type === 'text' ? result.content[0].text : '',
/^Input validation error: Invalid arguments for tool global_tool: b:/,
);
sinon.assert.notCalled(handler);
});
it('runs waiting calls with the updated tool handler and schema', async () => {
const config = parseConfig();
const initialHandler = sinon.stub().resolves();
const updatedHandler = sinon.stub().resolves();
const taskRunner = new TaskRunner();
const mockContext = createMockMcpContext({taskRunner});
mockContext.ensureBrowser.resolves(getMockBrowser());
const toolHandler = new ToolHandler(
createGlobalTool({a: zod.string()}, initialHandler),
config,
async () => mockContext,
sinon.spy(),
);
const guard = await taskRunner.pause();
const call = toolHandler.handle({a: 'value', b: 'extra'});
const listingChanged = toolHandler.update(
createGlobalTool({a: zod.string(), b: zod.string()}, updatedHandler),
);
guard[Symbol.dispose]();
const result = await call;
assert.strictEqual(listingChanged, true);
assert.strictEqual(result.isError, undefined);
sinon.assert.notCalled(initialHandler);
sinon.assert.calledOnceWithExactly(
updatedHandler,
{params: {a: 'value', b: 'extra'}},
sinon.match.instanceOf(McpResponse),
mockContext,
);
});
it('throws ProtocolError when a waiting MCP call becomes disabled', async () => {
const config = parseConfig();
const handler = sinon.stub().resolves();
const tool = createGlobalTool({}, handler);
const taskRunner = new TaskRunner();
const mockContext = createMockMcpContext({taskRunner});
const toolHandler = new ToolHandler(
tool,
config,
async () => mockContext,
sinon.spy(),
);
const guard = await taskRunner.pause();
const call = toolHandler.handle({}, {viaMcp: true});
config.commit(parseConfig(['--no-category-navigation']));
toolHandler.update(tool);
guard[Symbol.dispose]();
await assert.rejects(call, (error: unknown) => {
assert.ok(error instanceof ProtocolError);
assert.strictEqual(error.code, ProtocolErrorCode.InvalidParams);
assert.strictEqual(error.message, 'Tool global_tool disabled');
return true;
});
sinon.assert.notCalled(handler);
});
it('runs waiting calls when the schema is unchanged', async () => {
const config = parseConfig();
const initialHandler = sinon.stub().resolves();
const updatedHandler = sinon.stub().resolves();
const taskRunner = new TaskRunner();
const mockContext = createMockMcpContext({taskRunner});
mockContext.ensureBrowser.resolves(getMockBrowser());
const toolHandler = new ToolHandler(
createGlobalTool({a: zod.string().optional()}, initialHandler),
config,
async () => mockContext,
sinon.spy(),
);
const guard = await taskRunner.pause();
const call = toolHandler.handle({a: 'value'});
config.commit(parseConfig(['--redact-network-headers']));
const listingChanged = toolHandler.update(
createGlobalTool({a: zod.string().optional()}, updatedHandler),
);
guard[Symbol.dispose]();
await call;
assert.strictEqual(listingChanged, false);
sinon.assert.notCalled(initialHandler);
sinon.assert.calledOnceWithExactly(
updatedHandler,
{params: {a: 'value'}},
sinon.match.instanceOf(McpResponse),
mockContext,
);
});
it('updates the disabled state and reports listing change', () => {
const config = parseConfig();
const tool = createGlobalTool({}, sinon.stub().resolves());
const toolHandler = new ToolHandler(
tool,
config,
async () => createMockMcpContext(),
sinon.spy(),
);
config.commit(parseConfig(['--no-category-navigation']));
const listingChanged = toolHandler.update(tool);
assert.strictEqual(listingChanged, true);
assert.strictEqual(toolHandler.disabled, true);
});
it('reports listing change when description or annotations change', () => {
const config = parseConfig();
const handler = sinon.stub().resolves();
const toolHandler = new ToolHandler(
createGlobalTool({}, handler),
config,
async () => createMockMcpContext(),
sinon.spy(),
);
assert.strictEqual(
toolHandler.update(
createGlobalTool({}, handler, {description: 'Updated description'}),
),
true,
);
assert.strictEqual(
toolHandler.update(
createGlobalTool({}, handler, {
description: 'Updated description',
annotations: {
category: ToolCategory.NAVIGATION,
readOnlyHint: false,
},
}),
),
true,
);
});
it('does not report listing change when a disabled tool remains disabled', () => {
const config = parseConfig(['--no-category-navigation']);
const handler = sinon.stub().resolves();
const toolHandler = new ToolHandler(
createGlobalTool({a: zod.string().optional()}, handler),
config,
async () => createMockMcpContext(),
sinon.spy(),
);
const listingChanged = toolHandler.update(
createGlobalTool({a: zod.string(), b: zod.number()}, handler, {
description: 'Updated description',
}),
);
assert.strictEqual(listingChanged, false);
assert.strictEqual(toolHandler.disabled, true);
});
it('uses reloaded config options when building response for an unqueued tool', async () => {
const config = parseConfig();
const {promise: unblockTool, resolve: finishTool} =
Promise.withResolvers<void>();
const {promise: started, resolve: markStarted} =
Promise.withResolvers<void>();
const unqueuedTool: BrowserlessToolDefinition = defineBrowserlessTool(
() => ({
name: 'unqueued_tool',
description: 'Runs outside the task runner',
annotations: {
category: ToolCategory.NAVIGATION,
readOnlyHint: true,
},
schema: {},
blockedByDialog: false,
verifyFilesSchema: {},
concurrency: 'none',
handler: async (_request, response) => {
markStarted();
await unblockTool;
response.appendResponseLine('done');
},
}),
)(config.resolved);
const toolHandler = new ToolHandler(
unqueuedTool,
config,
async () => createMockMcpContext(),
sinon.spy(),
);
const callPromise = toolHandler.handle({});
await started;
config.commit(parseConfig(['--experimental-structured-content']));
finishTool();
const result = await callPromise;
assert.deepStrictEqual(result.structuredContent, {message: 'done'});
});
});
it('includes nested error causes in error output', async () => {
const config = parseConfig();
const tool: ToolDefinition = {
name: 'failing_connect_tool',
description: 'A tool whose ensureBrowser() fails with nested causes',
annotations: {
category: ToolCategory.NAVIGATION,
readOnlyHint: true,
},
schema: {},
blockedByDialog: false,
concurrency: 'exclusive',
verifyFilesSchema: {},
handler: async () => undefined,
};
const rootCause = Object.assign(
new Error(
"EPERM: operation not permitted, open '/Users/test/Library/Application Support/Google/Chrome/DevToolsActivePort'",
),
{code: 'EPERM'},
);
const puppeteerError = new Error(
'Could not find DevToolsActivePort for chrome at /Users/test/Library/Application Support/Google/Chrome/DevToolsActivePort',
{cause: rootCause},
);
const connectError = new Error(
'Could not connect to Chrome. Check if Chrome is running and remote debugging is enabled by going to chrome://inspect/#remote-debugging.',
{cause: puppeteerError},
);
const mockContext = createMockMcpContext();
mockContext.ensureBrowser.rejects(connectError);
const toolHandler = new ToolHandler(
tool,
config,
async () => mockContext,
sinon.spy(),
);
const result = await toolHandler.handle({});
assert.strictEqual(result.isError, true);
const text =
result.content[0].type === 'text' ? result.content[0].text : '';
assert.strictEqual(
text,
[
'Could not connect to Chrome. Check if Chrome is running and remote debugging is enabled by going to chrome://inspect/#remote-debugging.',
'Cause: Could not find DevToolsActivePort for chrome at /Users/test/Library/Application Support/Google/Chrome/DevToolsActivePort',
"Cause: EPERM: operation not permitted, open '/Users/test/Library/Application Support/Google/Chrome/DevToolsActivePort'",
].join('\n'),
);
});
});