Chrome DevTools for coding agents
/**
* @license
* Copyright 2026 Google LLC
* SPDX-License-Identifier: Apache-2.0
*/
import assert from 'node:assert';
import type {IncomingMessage, ServerResponse} from 'node:http';
import {describe, it} from 'node:test';
import ts from 'typescript';
import type {Logpoint, LogpointOptions} from '../src/LogpointManager.js';
import {
LogpointError,
parseLogpoint,
validateExpression,
} from '../src/LogpointManager.js';
import type {McpPage} from '../src/McpPage.js';
import {serverHooks} from './server.js';
import {html, waitExecutionFor, withMcpContext} from './utils.js';
const APP_SCRIPT = `function greet(name) {
const message = 'Hello, ' + name;
return message;
}
function withDebuggerStatement() {
debugger;
return 42;
}
`;
function serveAppScript(req: IncomingMessage, res: ServerResponse) {
res.setHeader('Content-Type', 'text/javascript; charset=utf-8');
res.statusCode = 200;
res.end(APP_SCRIPT);
}
// A "bundle" transpiled from TypeScript with a real source map, like a
// bundler would produce. Line 2 of the TypeScript source is the logpoint
// target used in tests.
const TS_SOURCE = [
`function tsGreet(name: string): string {`,
` const tsMessage: string = 'Hello, ' + name;`,
` return tsMessage;`,
`}`,
`(globalThis as {tsGreet?: unknown}).tsGreet = tsGreet;`,
].join('\n');
function transpileTsBundle(): {js: string; map: string} {
const result = ts.transpileModule(TS_SOURCE, {
fileName: 'app.ts',
compilerOptions: {
sourceMap: true,
module: ts.ModuleKind.None,
target: ts.ScriptTarget.ES2020,
},
});
assert.ok(result.sourceMapText, 'transpilation should produce a source map');
return {js: result.outputText, map: result.sourceMapText};
}
// Simulates a rebuilt bundle: the same code shifted down by extra leading
// statements. Prepending a semicolon per line to the mappings shifts all
// generated positions accordingly. The banner lines are executable so that
// a logpoint left at the old generated position no longer hits tsGreet.
function shiftBundle(
bundle: {js: string; map: string},
extraLines: number,
): {js: string; map: string} {
const banner =
Array.from(
{length: extraLines},
(_, i) => `globalThis.banner${i} = ${i};`,
).join('\n') + '\n';
const map = JSON.parse(bundle.map);
map.mappings = ';'.repeat(extraLines) + map.mappings;
return {js: banner + bundle.js, map: JSON.stringify(map)};
}
// A TypeScript file served the way a dev server like Vite does: transpiled
// in place at the URL of the original file, with an inline source map that
// points back at that same URL. The interface shifts the TypeScript lines
// against the generated ones: tsDevGreet's message is on line 5 of the
// TypeScript source and on line 3 of the served JavaScript.
const DEV_TS_SOURCE = [
`interface Greeting {`,
` text: string;`,
`}`,
`function tsDevGreet(name: string): string {`,
` const devMessage: string = 'Hello, ' + name;`,
` return devMessage;`,
`}`,
`(globalThis as {tsDevGreet?: unknown}).tsDevGreet = tsDevGreet;`,
].join('\n');
function transpileDevTs(): string {
const result = ts.transpileModule(DEV_TS_SOURCE, {
fileName: 'dev.ts',
compilerOptions: {
inlineSourceMap: true,
inlineSources: true,
module: ts.ModuleKind.None,
target: ts.ScriptTarget.ES2020,
},
});
return result.outputText;
}
// A "minified" script whose variable names differ from the original source,
// as a minifier produces them, with a hand-written source map (there is no
// minifier among the dev dependencies). Every identifier is mapped, which
// DevTools needs to substitute original names in logpoint expressions.
const MIN_TS_SOURCE = [
`function minGreet(name: string): string {`,
` const minMessage: string = 'Hello, ' + name;`,
` return minMessage;`,
`}`,
`(globalThis as {minGreet?: unknown}).minGreet = minGreet;`,
].join('\n');
const MIN_JS = [
`function minGreet(n){`,
`const m='Hello, '+n;`,
`return m;`,
`}`,
`globalThis.minGreet=minGreet;`,
`//# sourceMappingURL=min.js.map`,
].join('\n');
// Per generated line, the tokens of the generated text in order and the
// original token each one comes from (same line of the original source).
// Tokens are found in order, so repeated tokens map to their next occurrence.
const MIN_NAMES = ['minGreet', 'name', 'minMessage'];
const MIN_TOKENS: Array<Array<[string, string]>> = [
[
['function', 'function'],
['minGreet', 'minGreet'],
['(', '('],
['n', 'name'],
[')', ')'],
['{', '{'],
],
[
['const', 'const'],
['m', 'minMessage'],
['=', '='],
[`'Hello, '`, `'Hello, '`],
['+', '+'],
['n', 'name'],
[';', ';'],
],
[
['return', 'return'],
['m', 'minMessage'],
[';', ';'],
],
[['}', '}']],
[
['globalThis', 'globalThis'],
['minGreet', 'minGreet'],
['=', '='],
['minGreet', 'minGreet'],
[';', ';'],
],
];
// [generated column, original line, original column, name index] segments.
function minSegments(): Array<Array<[number, number, number, number?]>> {
const originalLines = MIN_TS_SOURCE.split('\n');
const generatedLines = MIN_JS.split('\n');
return MIN_TOKENS.map((tokens, line) => {
let generatedFrom = 0;
let originalFrom = 0;
return tokens.map(([generatedToken, originalToken]) => {
const generatedColumn = generatedLines[line].indexOf(
generatedToken,
generatedFrom,
);
const originalColumn = originalLines[line].indexOf(
originalToken,
originalFrom,
);
assert.ok(generatedColumn >= 0 && originalColumn >= 0, generatedToken);
generatedFrom = generatedColumn + generatedToken.length;
originalFrom = originalColumn + originalToken.length;
const name = MIN_NAMES.indexOf(originalToken);
return name >= 0
? [generatedColumn, line, originalColumn, name]
: [generatedColumn, line, originalColumn];
});
});
}
const BASE64 =
'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
function encodeVlq(value: number): string {
let vlq = value < 0 ? (-value << 1) | 1 : value << 1;
let encoded = '';
do {
let digit = vlq & 31;
vlq >>>= 5;
if (vlq > 0) {
digit |= 32;
}
encoded += BASE64[digit];
} while (vlq > 0);
return encoded;
}
function encodeMappings(): string {
let previousSourceLine = 0;
let previousSourceColumn = 0;
let previousName = 0;
return minSegments()
.map(line => {
let previousGeneratedColumn = 0;
return line
.map(([generatedColumn, sourceLine, sourceColumn, name]) => {
const fields = [
generatedColumn - previousGeneratedColumn,
0,
sourceLine - previousSourceLine,
sourceColumn - previousSourceColumn,
];
previousGeneratedColumn = generatedColumn;
previousSourceLine = sourceLine;
previousSourceColumn = sourceColumn;
if (name !== undefined) {
fields.push(name - previousName);
previousName = name;
}
return fields.map(encodeVlq).join('');
})
.join(',');
})
.join(';');
}
function minifiedSourceMap(): string {
return JSON.stringify({
version: 3,
file: 'min.js',
sources: ['min.ts'],
sourcesContent: [MIN_TS_SOURCE],
names: MIN_NAMES,
mappings: encodeMappings(),
});
}
/** Collects console messages of the page from now on. */
function collectConsole(page: McpPage): string[] {
const messages: string[] = [];
page.pptrPage.on('console', message => {
messages.push(message.text());
});
return messages;
}
async function waitForMessage(
messages: string[],
expected: string | RegExp,
): Promise<void> {
const matches = (message: string) =>
typeof expected === 'string'
? message === expected
: expected.test(message);
await waitExecutionFor(async () => {
if (!messages.some(matches)) {
throw new Error(
`Console messages do not include ${expected} yet: ${JSON.stringify(messages)}`,
);
}
}, 5000);
}
function evaluateWithTimeout(
page: McpPage,
expression: string,
): Promise<unknown> {
return Promise.race([
page.pptrPage.evaluate(expression),
new Promise((_resolve, reject) => {
setTimeout(() => {
reject(new Error('Evaluation timed out: the debugger paused the page'));
}, 10_000);
}),
]);
}
function assertLogpoint(
actual: Logpoint,
expected: Omit<Logpoint, 'generatedLocations'> & {
generatedUrl: string;
generatedLineNumber: number;
},
): void {
const {generatedUrl, generatedLineNumber, ...rest} = expected;
const {generatedLocations, ...actualRest} = actual;
assert.deepStrictEqual(actualRest, rest);
assert.strictEqual(generatedLocations.length, 1);
assert.strictEqual(generatedLocations[0].url, generatedUrl);
assert.strictEqual(generatedLocations[0].lineNumber, generatedLineNumber);
}
describe('parseLogpoint', () => {
it('parses locations with ports, columns and expressions', () => {
assert.deepStrictEqual(
parseLogpoint(`http://127.0.0.1:16552/app.js:2 'greeting for', name`),
{
url: 'http://127.0.0.1:16552/app.js',
lineNumber: 2,
expression: `'greeting for', name`,
},
);
assert.deepStrictEqual(parseLogpoint('src/app.ts:42:7 cart.total'), {
url: 'src/app.ts',
lineNumber: 42,
columnNumber: 7,
expression: 'cart.total',
});
});
it('rejects a missing location or 0-based numbers', () => {
assert.throws(() => parseLogpoint('src/app.ts cart.total'), /format/);
assert.throws(() => parseLogpoint('src/app.ts:0 x'), /1-based/);
assert.throws(() => parseLogpoint('src/app.ts:4:0 x'), /1-based/);
});
});
describe('validateExpression', () => {
it('accepts console.log style arguments and rejects syntax errors', () => {
assert.doesNotThrow(() => validateExpression(`'total:', cart.total`));
assert.throws(
() => validateExpression(`'unbalanced', (`),
/does not compile/,
);
});
});
describe('LogpointManager', () => {
const server = serverHooks();
function setupRoutes() {
server.addRoute('/app.js', serveAppScript);
server.addHtmlRoute('/', html`<script src="/app.js"></script>`);
}
// Serves an html page with a transpiled TypeScript "bundle" whose content
// can be swapped between navigations via the returned holder.
function setupBundleRoutes(): {current: {js: string; map: string}} {
const holder = {current: transpileTsBundle()};
server.addHtmlRoute('/sm', html`<script src="/bundle.js"></script>`);
server.addRoute('/bundle.js', (req, res) => {
res.setHeader('Content-Type', 'text/javascript; charset=utf-8');
res.setHeader('Cache-Control', 'no-store');
res.end(holder.current.js);
});
server.addRoute('/app.js.map', (req, res) => {
res.setHeader('Content-Type', 'application/json');
res.setHeader('Cache-Control', 'no-store');
res.end(holder.current.map);
});
return holder;
}
it('logs without pausing, matches path suffixes and survives reloads', async () => {
await withMcpContext(async (response, context) => {
setupRoutes();
const page = context.getSelectedMcpPage();
await page.pptrPage.goto(server.getRoute('/'));
const messages = collectConsole(page);
const url = server.getRoute('/app.js');
const logpoints = await page.setLogpoints([
{url: 'app.js', lineNumber: 2, expression: `'greeting for', name`},
]);
assert.strictEqual(logpoints.length, 1);
assertLogpoint(logpoints[0], {
url,
lineNumber: 2,
// DevTools normalizes a missing column to the first column.
columnNumber: 1,
expression: `'greeting for', name`,
sourceMapped: false,
generatedUrl: url,
generatedLineNumber: 2,
});
await page.pptrPage.evaluate(`greet('World')`);
await waitForMessage(messages, 'greeting for World');
// Breakpoint conditions must not turn `debugger;` into a pause.
assert.strictEqual(
await evaluateWithTimeout(page, `withDebuggerStatement()`),
42,
);
await page.pptrPage.reload();
await page.pptrPage.evaluate(`greet('Again')`);
await waitForMessage(messages, 'greeting for Again');
assert.strictEqual(
await evaluateWithTimeout(page, `withDebuggerStatement()`),
42,
);
});
});
it('replaces, removes and clears logpoints with the complete list', async () => {
await withMcpContext(async (response, context) => {
setupRoutes();
const page = context.getSelectedMcpPage();
await page.pptrPage.goto(server.getRoute('/'));
const messages = collectConsole(page);
const url = server.getRoute('/app.js');
const line2: LogpointOptions = {url, lineNumber: 2, expression: `'two'`};
const line3: LogpointOptions = {
url,
lineNumber: 3,
expression: `'three'`,
};
assert.strictEqual((await page.setLogpoints([line2, line3])).length, 2);
// Keep line 3 with a new expression; line 2 must stop logging.
const replaced = await page.setLogpoints([
{...line3, expression: `'three replaced'`},
]);
assert.strictEqual(replaced.length, 1);
assert.strictEqual(replaced[0].lineNumber, 3);
assert.strictEqual(replaced[0].expression, `'three replaced'`);
await page.pptrPage.evaluate(`greet('World')`);
await waitForMessage(messages, 'three replaced');
assert.ok(!messages.includes('two'), `Line 2 still logged: ${messages}`);
assert.ok(
!messages.includes('three'),
`Old expression logged: ${messages}`,
);
assert.deepStrictEqual(await page.setLogpoints([]), []);
await page.pptrPage.evaluate(`greet('World')`);
await page.pptrPage.evaluate(`console.log('sentinel')`);
await waitForMessage(messages, 'sentinel');
assert.strictEqual(
messages.filter(message => message === 'three replaced').length,
1,
);
});
});
it('resolves original sources and re-binds after a rebuilt bundle', async () => {
await withMcpContext(async (response, context) => {
const holder = setupBundleRoutes();
const page = context.getSelectedMcpPage();
await page.pptrPage.goto(server.getRoute('/sm'));
const messages = collectConsole(page);
const options: LogpointOptions = {
url: 'app.ts',
lineNumber: 2,
expression: `'ts greeting', name`,
};
const [logpoint] = await page.setLogpoints([options]);
assert.strictEqual(logpoint.sourceMapped, true);
assert.ok(
logpoint.url.endsWith('/app.ts'),
`Expected the source map URL, got ${logpoint.url}`,
);
assert.strictEqual(logpoint.generatedLocations.length, 1);
const generated = logpoint.generatedLocations[0];
assert.strictEqual(generated.url, server.getRoute('/bundle.js'));
await page.pptrPage.evaluate(`tsGreet('One')`);
await waitForMessage(messages, 'ts greeting One');
// "Rebuild" the bundle: same source, shifted generated locations.
const extraLines = 5;
holder.current = shiftBundle(holder.current, extraLines);
await page.pptrPage.reload();
// The breakpoint manager re-binds once the new source map attaches.
await waitExecutionFor(async () => {
const [current] = await page.setLogpoints([options]);
const location = current.generatedLocations[0];
if (location?.lineNumber !== generated.lineNumber + extraLines) {
throw new Error(
`Not rebound yet: ${JSON.stringify(current.generatedLocations)}`,
);
}
}, 5000);
await page.pptrPage.evaluate(`tsGreet('Two')`);
await waitForMessage(messages, 'ts greeting Two');
});
});
it('substitutes original variable names at minified locations', async () => {
await withMcpContext(async (response, context) => {
server.addHtmlRoute('/min', html`<script src="/min.js"></script>`);
server.addRoute('/min.js', (req, res) => {
res.setHeader('Content-Type', 'text/javascript; charset=utf-8');
res.end(MIN_JS);
});
server.addRoute('/min.js.map', (req, res) => {
res.setHeader('Content-Type', 'application/json');
res.end(minifiedSourceMap());
});
const page = context.getSelectedMcpPage();
await page.pptrPage.goto(server.getRoute('/min'));
const messages = collectConsole(page);
const logpoints = await page.setLogpoints([
{
url: 'min.ts',
lineNumber: 3,
expression: `'min greeting', name, minMessage`,
},
]);
// The original source is only served through the source map.
assertLogpoint(logpoints[0], {
url: server.getRoute('/min.js').replace(/min\.js$/, 'min.ts'),
lineNumber: 3,
columnNumber: 3,
expression: `'min greeting', name, minMessage`,
sourceMapped: true,
generatedUrl: server.getRoute('/min.js'),
generatedLineNumber: 3,
});
// `name` and `minMessage` only exist as `n` and `m` in the script.
await page.pptrPage.evaluate(`minGreet('World')`);
await waitForMessage(messages, 'min greeting World Hello, World');
});
});
it('prefers the original source over a script served at the same URL', async () => {
await withMcpContext(async (response, context) => {
server.addHtmlRoute('/dev', html`<script src="/src/dev.ts"></script>`);
server.addRoute('/src/dev.ts', (req, res) => {
res.setHeader('Content-Type', 'text/javascript; charset=utf-8');
res.end(transpileDevTs());
});
const page = context.getSelectedMcpPage();
await page.pptrPage.goto(server.getRoute('/dev'));
const messages = collectConsole(page);
const url = server.getRoute('/src/dev.ts');
const logpoints = await page.setLogpoints([
{url: 'src/dev.ts', lineNumber: 5, expression: `'dev greeting', name`},
]);
// Line 5 of the TypeScript file, not line 5 of the served JavaScript;
// the column is that of the indented statement.
assertLogpoint(logpoints[0], {
url,
lineNumber: 5,
columnNumber: 3,
expression: `'dev greeting', name`,
sourceMapped: true,
generatedUrl: url,
generatedLineNumber: 3,
});
await page.pptrPage.evaluate(`tsDevGreet('Dev')`);
await waitForMessage(messages, 'dev greeting Dev');
});
});
it('reports unknown, ambiguous and non-executable locations', async () => {
await withMcpContext(async (response, context) => {
setupBundleRoutes();
const page = context.getSelectedMcpPage();
await page.pptrPage.goto(server.getRoute('/sm'));
const bundleUrl = server.getRoute('/bundle.js');
await assert.rejects(
page.setLogpoints([
{url: 'nonexistent.js', lineNumber: 2, expression: `'never'`},
]),
new RegExp(
`^Error: No parsed script or original source file matches "nonexistent.js"`,
),
);
await assert.rejects(
page.setLogpoints([
{url: 'other/bundle.js', lineNumber: 2, expression: `'never'`},
]),
new RegExp(`Sources with the same file name: ${bundleUrl}\\.$`),
);
// A valid logpoint is applied even when another one has no code.
await assert.rejects(
page.setLogpoints([
{url: 'app.ts', lineNumber: 2, expression: `'ok'`},
{url: 'app.ts', lineNumber: 999, expression: `'never'`},
]),
(error: unknown) => {
assert.ok(error instanceof LogpointError);
assert.match(error.message, /No executable code at .*app\.ts:999 /);
assert.strictEqual(error.logpoints.length, 1);
assert.strictEqual(error.logpoints[0].lineNumber, 2);
return true;
},
);
assert.strictEqual(
(
await page.setLogpoints([
{url: 'app.ts', lineNumber: 2, expression: `'ok'`},
])
).length,
1,
);
});
});
it('merges locations that normalize to the same breakpoint', async () => {
await withMcpContext(async (response, context) => {
setupBundleRoutes();
const page = context.getSelectedMcpPage();
await page.pptrPage.goto(server.getRoute('/sm'));
const messages = collectConsole(page);
const authored: LogpointOptions = {
url: 'app.ts',
lineNumber: 2,
expression: `'authored', name`,
};
const [first] = await page.setLogpoints([authored]);
const [generated] = first.generatedLocations;
// The generated location normalizes to the authored one, so both
// requests end up as one breakpoint whose expression is the last one.
const merged = await page.setLogpoints([
authored,
{
url: generated.url,
lineNumber: generated.lineNumber,
columnNumber: generated.columnNumber,
expression: `'generated', name`,
},
]);
assert.strictEqual(merged.length, 1);
assert.strictEqual(merged[0].url, first.url);
assert.strictEqual(merged[0].sourceMapped, true);
assert.strictEqual(merged[0].expression, `'generated', name`);
await page.pptrPage.evaluate(`tsGreet('One')`);
await waitForMessage(messages, 'generated One');
assert.ok(
!messages.includes('authored One'),
`Logged twice: ${messages}`,
);
// Keeping only one of the two locations keeps the shared breakpoint.
const [kept] = await page.setLogpoints([authored]);
assert.strictEqual(kept.expression, `'authored', name`);
await page.pptrPage.evaluate(`tsGreet('Kept')`);
await waitForMessage(messages, 'authored Kept');
// Dropping the last key removes the shared breakpoint.
assert.deepStrictEqual(await page.setLogpoints([]), []);
await page.pptrPage.evaluate(`tsGreet('Two')`);
await page.pptrPage.evaluate(`console.log('sentinel')`);
await waitForMessage(messages, 'sentinel');
assert.ok(!messages.includes('generated Two'), `Still logs: ${messages}`);
});
});
});