Chrome DevTools for coding agents
feat: resolve config defaults after merging CLI and config file (#2849)
Nikolay Vitkovbdeb70d2b893
diff --git a/src/config/browser-options.ts b/src/config/browser-options.tsindex 2b9af492..9a3bb748 100644--- a/src/config/browser-options.ts+++ b/src/config/browser-options.ts@@ -59,7 +59,6 @@ export const browserOptions = {type: 'string',description:'Custom headers for WebSocket connection in JSON format (e.g., \'{"Authorization":"Bearer token"}\'). Only works with --wsEndpoint.',- implies: 'wsEndpoint',coerce: (val: string | undefined) => {if (!val) {return;@@ -91,7 +90,7 @@ export const browserOptions = {type: 'boolean',description:'If specified, creates a temporary user-data-dir that is automatically cleaned up after the browser is closed. Defaults to false.',- defaultDescription: 'false',+ default: false,},userDataDir: {type: 'string',@@ -103,7 +102,7 @@ export const browserOptions = {description:'Specify a different Chrome channel that should be used. The default is the stable channel version.',choices: ['canary', 'dev', 'beta', 'stable'] as const,- defaultDescription: 'stable',+ default: 'stable' as const,},proxyServer: {type: 'string',diff --git a/src/config/mcp-options.ts b/src/config/mcp-options.tsindex 292bc7ad..671cbeba 100644--- a/src/config/mcp-options.ts+++ b/src/config/mcp-options.ts@@ -119,13 +119,11 @@ export const mcpOptions = {experimentalFfmpegPath: {type: 'string',describe: 'Path to ffmpeg executable for screencast recording.',- implies: 'experimentalScreencast',},experimentalScreencastFps: {type: 'number',describe:'Frames per second to use for screencast recording. Lower values can reduce memory pressure on pages that produce frames faster than ffmpeg can encode them.',- implies: 'experimentalScreencast',coerce: (value: number | undefined) => {if (value === undefined) {return;@@ -144,7 +142,7 @@ export const mcpOptions = {describe:"Restricts browser's network access by blocking specified URL patterns (uses https://urlpattern.spec.whatwg.org/). Silently detaches from targets with blocked URLs upon connection, and blocks runtime requests (including navigations and subresources). Accepts an array of patterns. A pattern that uses a regexp group in any component (for example `(127\\.\\d+\\.\\d+\\.\\d+)` in the hostname) is rejected, because it is not enforced on redirects or subresources; use an exact value or a `*`/`:name` wildcard instead.",coerce: (arg: string[] | undefined) => {- if (arg === undefined) {+ if (arg === undefined || arg.length === 0) {return undefined;}const pattern = findUnenforceablePattern(arg);@@ -165,6 +163,11 @@ export const mcpOptions = {if (arg === undefined) {return undefined;}+ if (arg.length === 0) {+ throw new Error(+ 'Invalid --allowedUrlPattern: at least one pattern is required.',+ );+ }const pattern = findUnenforceablePattern(arg);if (pattern) {throw new Error(@@ -319,9 +322,20 @@ export const mcpOptions = {},} satisfies Record<string, YargsOptions>;-export type ParsedArguments = ReturnType<typeof parseArguments>;+type RawParsedArguments = ReturnType<+ ReturnType<typeof buildCliParser<typeof mcpOptions>>['parseSync']+>;++export type ParsedArguments = {+ [+ K in keyof RawParsedArguments as K extends '_' | '$0' ? never : K+ ]: RawParsedArguments[K];+};-export function getMcpOptionsForViaCli(): typeof mcpOptions {+export function getMcpOptionsForViaCli(): Record<+ keyof typeof mcpOptions,+ YargsOptions+> {if (!('default' in mcpOptions.headless)) {throw new Error('headless cli option unexpectedly does not have a default');}@@ -363,9 +377,8 @@ export function getMcpOptionsForViaCli(): typeof mcpOptions {export function getCliOptions(): Partial<Record<keyof typeof mcpOptions, YargsOptions>> {- const options: Partial<Record<keyof typeof mcpOptions, YargsOptions>> = {- ...getMcpOptionsForViaCli(),- };+ const options: Partial<Record<keyof typeof mcpOptions, YargsOptions>> =+ withoutDefaults(getMcpOptionsForViaCli());// Missing CLI serialization.delete options.viewport;@@ -374,19 +387,6 @@ export function getCliOptions(): Partial<delete options.experimentalStructuredContent;delete options.experimentalInteropTools;- const recordOptions: Record<string, YargsOptions | undefined> = options;- for (const [key, option] of Object.entries(recordOptions)) {- if (option?.default !== undefined) {- const copy: YargsOptions = {- ...option,- defaultDescription:- option.defaultDescription ?? JSON.stringify(option.default),- };- delete copy.default;- recordOptions[key] = copy;- }- }-return options;}@@ -465,6 +465,13 @@ const CONFLICTING_ARGS: Array<Array<keyof typeof mcpOptions>> = [['categoryExtensions', 'browserUrl', 'wsEndpoint'],];+const IMPLICATIONS: Array<[keyof typeof mcpOptions, keyof typeof mcpOptions]> =+ [+ ['wsHeaders', 'wsEndpoint'],+ ['experimentalFfmpegPath', 'experimentalScreencast'],+ ['experimentalScreencastFps', 'experimentalScreencast'],+ ];+function isPlainObject(value: unknown): value is Record<string, unknown> {return typeof value === 'object' && value !== null && !Array.isArray(value);}@@ -473,18 +480,13 @@ function getErrorMessage(err: unknown): string {return err instanceof Error ? err.message : String(err);}-/**- * Exported only for testing to not trigger process exit.- */-export function parser(+export function buildCliParser<T extends Record<string, YargsOptions>>(version: string,- argv = process.argv,- env = process.env,+ argv: string[],+ options: T,) {- const isViaCli = argv.includes('--viaCli') || argv.includes('--via-cli');- const options = isViaCli ? getMcpOptionsForViaCli() : mcpOptions;-- const yargsInstance = yargs(hideBin(argv))+ const yargsInstance = yargs(hideBin(argv));+ return yargsInstance.scriptName('npx chrome-devtools-mcp@latest').parserConfiguration({'strip-aliased': true,@@ -492,126 +494,208 @@ export function parser(}).options(options).showHelpOnFail(false, 'Specify --help for available options')- .check(args => {- const activeArgs = new Set<string>();+ .example(CLI_EXAMPLES)+ .wrap(Math.min(120, yargsInstance.terminalWidth()))+ .help()+ .version(version);+}- for (const [key, val] of Object.entries(args)) {- if (val !== undefined && val !== false) {- activeArgs.add(key);- }- }+function withoutDefaults(+ options: Record<string, YargsOptions>,+): Record<string, YargsOptions> {+ const result: Record<string, YargsOptions> = {};+ for (const [key, option] of Object.entries(options)) {+ const copy: YargsOptions = {...option};+ if (copy.default !== undefined) {+ copy.defaultDescription ??= JSON.stringify(copy.default);+ delete copy.default;+ }+ result[key] = copy;+ }+ return result;+}- for (const group of CONFLICTING_ARGS) {- // Find all active arguments within this conflict group- const activeInGroup = group.filter(arg => activeArgs.has(arg));+function stripYargsPositionalArgs<T extends {_?: unknown; $0?: unknown}>(+ parsed: T,+): Omit<T, '_' | '$0'> {+ const {_: _positionals, $0: _scriptName, ...rest} = parsed;+ return rest;+}- if (activeInGroup.length > 1) {- const [arg1, arg2] = activeInGroup;- throw new Error(- `Arguments ${arg1} and ${arg2} are mutually exclusive`,- );- }- }+/**+ * Step 1: parses the CLI flags without applying defaults, so the result only+ * contains what the user passed. `--help` and `--version` print and exit the+ * process; parse errors throw.+ */+export function parseCliArgs(+ version: string,+ argv: string[],+): Partial<ParsedArguments> {+ const parsed = buildCliParser(version, argv, withoutDefaults(mcpOptions))+ .fail(false)+ .parseSync();+ return stripYargsPositionalArgs(parsed);+}- return true;- })- .middleware(args => {- if (isViaCli) {- if (args.filesystemRoot === DEFAULT_FILESYSTEM_ROOT) {- const cliFilesystemArgs: {- allowUnrestrictedPaths?: boolean;- filesystemRoot?: unknown;- } = args;- cliFilesystemArgs.allowUnrestrictedPaths = true;- cliFilesystemArgs.filesystemRoot = undefined;- }- // Defaults that cannot be set in options without affecting yargs conflict resolution.- const connectsToExistingBrowser =- args.autoConnect || args.browserUrl || args.wsEndpoint;- if (- args.isolated === undefined &&- args.userDataDir === undefined &&- !connectsToExistingBrowser- ) {- args.isolated = true;- }- if (- args.categoryExtensions === undefined &&- !connectsToExistingBrowser- ) {- args.categoryExtensions = true;- }- }- // Only fall back to stable when Chrome is launched by channel. Leaving it- // unset otherwise keeps it out of telemetry (computeFlagUsage) for- // browserUrl, wsEndpoint and executablePath.- if (- !args.channel &&- !args.browserUrl &&- !args.wsEndpoint &&- !args.executablePath- ) {- args.channel = 'stable';- }- if (env['CI'] || env['CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS']) {- console.error(- "turning off usage statistics. process.env['CI'] || process.env['CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS'] is set.",- );- args.usageStatistics = false;- }+/**+ * Step 2: reads the JSON config file and runs it through yargs to reject+ * unknown keys and apply coercions, without applying defaults.+ */+export function parseConfigFile(configPath: string): Partial<ParsedArguments> {+ try {+ const fileContent: unknown = JSON.parse(readFileSync(configPath, 'utf-8'));+ if (!isPlainObject(fileContent)) {+ throw new Error('Config must be a JSON object');+ }+ const parsed = yargs([])+ .parserConfiguration({+ 'strip-aliased': true,+ 'camel-case-expansion': false,+ })+ .options(withoutDefaults(mcpOptions))+ .config(fileContent)+ .strict()+ .fail(false)+ .exitProcess(false)+ .parseSync([]);+ return stripYargsPositionalArgs(parsed);+ } catch (err) {+ throw new Error(`Invalid JSON config file: ${getErrorMessage(err)}`);+ }+}- const cliOptionsAllowedArgs = [- ...Object.keys(options),- // Yargs populated with positional args- '_',- '$0',- ];+function warnUnknownArgs(cliArgs: Partial<ParsedArguments>): void {+ const allowedArgs = new Set(Object.keys(mcpOptions));+ const unknownArgs = Object.keys(cliArgs).filter(arg => !allowedArgs.has(arg));+ if (unknownArgs.length > 0) {+ console.error(`Unknown arguments: ${unknownArgs.map(arg => `--${arg}`)}`);+ }+}- const unknownArgs = Object.keys(args).filter(- arg => !cliOptionsAllowedArgs.includes(arg),- );+/**+ * Step 4: rejects mutually exclusive inputs. Only explicit inputs are checked,+ * so defaults never conflict.+ */+export function validateConflicts(+ explicitArgs: Partial<ParsedArguments>,+): void {+ const activeArgs = new Set<string>();+ for (const [key, val] of Object.entries(explicitArgs)) {+ if (val !== undefined && val !== false) {+ activeArgs.add(key);+ }+ }+ for (const group of CONFLICTING_ARGS) {+ const activeInGroup = group.filter(arg => activeArgs.has(arg));+ if (activeInGroup.length > 1) {+ const [arg1, arg2] = activeInGroup;+ throw new Error(`Arguments ${arg1} and ${arg2} are mutually exclusive`);+ }+ }+}- if (unknownArgs.length > 0) {- console.error(- `Unknown arguments: ${unknownArgs.map(arg => `--${arg}`)}`,- );- }- })- .example(CLI_EXAMPLES);+export function validateImplications(+ explicitArgs: Partial<ParsedArguments>,+): void {+ for (const [key, implied] of IMPLICATIONS) {+ const isKeySet =+ explicitArgs[key] !== undefined && explicitArgs[key] !== false;+ const isImpliedSet =+ explicitArgs[implied] !== undefined && explicitArgs[implied] !== false;+ if (isKeySet && !isImpliedSet) {+ throw new Error(`Implications failed:\n ${key} -> ${implied}`);+ }+ }+}- return yargsInstance- .config('config', 'Path to JSON configuration file', configPath => {- try {- const parsed: unknown = JSON.parse(readFileSync(configPath, 'utf-8'));- if (!isPlainObject(parsed)) {- throw new Error('Config must be a JSON object');- }-- yargs()- .parserConfiguration({- 'strip-aliased': true,- 'camel-case-expansion': false,- })- .options(options)- .config(parsed)- .strict()- .fail(false)- .exitProcess(false)- .parseSync([]);- return parsed;- } catch (err) {- throw new Error(`Invalid JSON config file: ${getErrorMessage(err)}`);- }- })- .wrap(Math.min(120, yargsInstance.terminalWidth()))- .help()- .version(version);+/**+ * Step 5: fills in defaults for everything that was not set explicitly.+ * `viaCli` is an explicit input like any other; it selects which defaults+ * apply.+ */+export function applyDefaults(+ explicitArgs: Partial<ParsedArguments>,+ env: NodeJS.ProcessEnv,+): Partial<ParsedArguments> {+ const isViaCli = explicitArgs.viaCli === true;+ const baseOptions = isViaCli ? getMcpOptionsForViaCli() : mcpOptions;+ const resolvedArgs = {...explicitArgs};+ // `channel` only applies when Chrome is launched by channel. Leaving it+ // unset otherwise keeps it out of telemetry (computeFlagUsage).+ const launchesByChannel =+ !explicitArgs.browserUrl &&+ !explicitArgs.wsEndpoint &&+ !explicitArgs.executablePath;++ for (const [key, option] of Object.entries(baseOptions)) {+ if (key === 'channel' && !launchesByChannel) {+ continue;+ }+ if (resolvedArgs[key] === undefined && 'default' in option) {+ resolvedArgs[key] = option.default;+ }+ }++ if (isViaCli) {+ if (resolvedArgs.filesystemRoot === DEFAULT_FILESYSTEM_ROOT) {+ resolvedArgs.allowUnrestrictedPaths = true;+ resolvedArgs.filesystemRoot = undefined;+ }+ const connectsToExistingBrowser =+ resolvedArgs.autoConnect ||+ resolvedArgs.browserUrl ||+ resolvedArgs.wsEndpoint;+ if (+ explicitArgs.isolated === undefined &&+ resolvedArgs.userDataDir === undefined &&+ !connectsToExistingBrowser+ ) {+ resolvedArgs.isolated = true;+ }+ if (+ resolvedArgs.categoryExtensions === undefined &&+ !connectsToExistingBrowser+ ) {+ resolvedArgs.categoryExtensions = true;+ }+ }++ if (env['CI'] || env['CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS']) {+ console.error(+ "turning off usage statistics. process.env['CI'] || process.env['CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS'] is set.",+ );+ resolvedArgs.usageStatistics = false;+ }++ return resolvedArgs;}export function parseArguments(version: string,argv = process.argv,env = process.env,-) {- return parser(version, argv, env).parseSync();+ exitProcess = true,+): ParsedArguments {+ try {+ const cliArgs = parseCliArgs(version, argv);+ const configFileArgs =+ typeof cliArgs.config === 'string' ? parseConfigFile(cliArgs.config) : {};+ // Step 3: merges the explicit inputs. The CLI wins over the config file.+ const explicitArgs = {...configFileArgs, ...cliArgs};+ warnUnknownArgs(cliArgs);+ validateConflicts(explicitArgs);+ validateImplications(explicitArgs);+ const resolvedArgs = applyDefaults(explicitArgs, env);++ // The merge and the default loop lose the static type that yargs infers from+ // `mcpOptions`. Every value was produced by the same option definitions (CLI+ // parser, strict config-file parser, option defaults), so the shape matches.+ return resolvedArgs as ParsedArguments;+ } catch (error) {+ if (exitProcess) {+ console.error(getErrorMessage(error));+ process.exit(1);+ }+ throw error;+ }}diff --git a/tests/cli.test.ts b/tests/cli.test.tsindex 7d63b7bf..41e96033 100644--- a/tests/cli.test.ts+++ b/tests/cli.test.ts@@ -11,19 +11,18 @@ import {describe, it} from 'node:test';import {buildCommand} from '../src/config/cli-commands.js';import {commands} from '../src/config/cli-options.js';import {+ buildCliParser,DEFAULT_FILESYSTEM_ROOT,getCliOptions,mcpOptions,- parser,+ parseArguments as parseArgumentsImpl,} from '../src/config/mcp-options.js';import {computeFlagUsage} from '../src/telemetry/flagUtils.js';import {createTempFile} from './utils.js';function parseArguments(argv: string[], env: NodeJS.ProcessEnv = {}) {- return parser('0.0.0', ['node', 'main.js', ...argv], env)- .exitProcess(false)- .parseSync();+ return parseArgumentsImpl('0.0.0', ['node', 'main.js', ...argv], env, false);}describe('cli args parsing', () => {@@ -37,6 +36,7 @@ describe('cli args parsing', () => {categoryMemory: true,autoConnect: false,headless: false,+ isolated: false,acceptInsecureCerts: false,performanceCrux: true,usageStatistics: true,@@ -65,8 +65,6 @@ describe('cli args parsing', () => {const args = parseArguments([]);assert.deepStrictEqual(args, {...defaultArgs,- _: [],- $0: 'npx chrome-devtools-mcp@latest',channel: 'stable',});});@@ -86,8 +84,6 @@ describe('cli args parsing', () => {const args = parseArguments(['--browserUrl', 'http://localhost:3000']);assert.deepStrictEqual(args, {...defaultArgs,- _: [],- $0: 'npx chrome-devtools-mcp@latest',browserUrl: 'http://localhost:3000',});});@@ -116,8 +112,6 @@ describe('cli args parsing', () => {const args = parseArguments(['--user-data-dir', '/tmp/chrome-profile']);assert.deepStrictEqual(args, {...defaultArgs,- _: [],- $0: 'npx chrome-devtools-mcp@latest',channel: 'stable',userDataDir: '/tmp/chrome-profile',});@@ -127,8 +121,6 @@ describe('cli args parsing', () => {const args = parseArguments(['--browserUrl', ''], {});assert.deepStrictEqual(args, {...defaultArgs,- _: [],- $0: 'npx chrome-devtools-mcp@latest',channel: 'stable',browserUrl: undefined,});@@ -138,8 +130,6 @@ describe('cli args parsing', () => {const args = parseArguments(['--executablePath', '/tmp/test 123/chrome']);assert.deepStrictEqual(args, {...defaultArgs,- _: [],- $0: 'npx chrome-devtools-mcp@latest',executablePath: '/tmp/test 123/chrome',});});@@ -148,8 +138,6 @@ describe('cli args parsing', () => {const args = parseArguments(['--viewport', '888x777']);assert.deepStrictEqual(args, {...defaultArgs,- _: [],- $0: 'npx chrome-devtools-mcp@latest',channel: 'stable',viewport: {width: 888,@@ -165,8 +153,6 @@ describe('cli args parsing', () => {]);assert.deepStrictEqual(args, {...defaultArgs,- _: [],- $0: 'npx chrome-devtools-mcp@latest',channel: 'stable',chromeArg: ['--no-sandbox', '--disable-setuid-sandbox'],});@@ -219,8 +205,6 @@ describe('cli args parsing', () => {]);assert.deepStrictEqual(args, {...defaultArgs,- _: [],- $0: 'npx chrome-devtools-mcp@latest',channel: 'stable',ignoreDefaultChromeArg: ['--disable-extensions',@@ -236,8 +220,6 @@ describe('cli args parsing', () => {]);assert.deepStrictEqual(args, {...defaultArgs,- _: [],- $0: 'npx chrome-devtools-mcp@latest',wsEndpoint: 'ws://127.0.0.1:9222/devtools/browser/abc123',});});@@ -249,8 +231,6 @@ describe('cli args parsing', () => {]);assert.deepStrictEqual(args, {...defaultArgs,- _: [],- $0: 'npx chrome-devtools-mcp@latest',wsEndpoint: 'wss://example.com:9222/devtools/browser/abc123',});});@@ -272,8 +252,6 @@ describe('cli args parsing', () => {const args = parseArguments(['--no-category-emulation']);assert.deepStrictEqual(args, {...defaultArgs,- _: [],- $0: 'npx chrome-devtools-mcp@latest',channel: 'stable',categoryEmulation: false,});@@ -282,8 +260,6 @@ describe('cli args parsing', () => {const args = parseArguments(['--auto-connect'], {});assert.deepStrictEqual(args, {...defaultArgs,- _: [],- $0: 'npx chrome-devtools-mcp@latest',channel: 'stable',autoConnect: true,});@@ -470,6 +446,44 @@ describe('cli args parsing', () => {);});+ it('strips an empty blocked-url-pattern', async () => {+ const args = parseArguments(['--blocked-url-pattern']);+ assert.strictEqual(args.blockedUrlPattern, undefined);+ });++ it('allows an empty config blockedUrlPattern with allowed-url-pattern', async () => {+ using testConfig = createTempFile(+ JSON.stringify({blockedUrlPattern: []}),+ 'cd4a.test.config.empty-blocked.json',+ );+ const args = parseArguments([+ '--config',+ testConfig.path,+ '--allowed-url-pattern',+ 'https://a.com/*',+ ]);+ assert.strictEqual(args.blockedUrlPattern, undefined);+ assert.deepStrictEqual(args.allowedUrlPattern, ['https://a.com/*']);+ });++ it('rejects an empty allowed-url-pattern', async () => {+ assert.throws(+ () => parseArguments(['--allowed-url-pattern']),+ /Invalid --allowedUrlPattern: at least one pattern is required/,+ );+ });++ it('rejects an empty config allowedUrlPattern', async () => {+ using testConfig = createTempFile(+ JSON.stringify({allowedUrlPattern: []}),+ 'cd4a.test.config.empty-allowed.json',+ );+ assert.throws(+ () => parseArguments(['--config', testConfig.path]),+ /Invalid JSON config file: Invalid --allowedUrlPattern: at least one pattern is required/,+ );+ });+it('parses source-maps flag', async () => {const defaultParsed = parseArguments(['main.js']);assert.strictEqual(defaultParsed.sourceMaps, true);@@ -561,7 +575,7 @@ describe('cli args parsing', () => {const args = parseArguments(['--viaCli', '--config', relativePath]);assert.strictEqual(args.config, testConfig.path);assert.strictEqual(args.userDataDir, '/tmp/custom-profile');- assert.strictEqual(args.isolated, undefined);+ assert.strictEqual(args.isolated, false);assert.strictEqual(args.headless, false);});@@ -604,11 +618,145 @@ describe('cli args parsing', () => {);});+ it('rejects a config file with malformed JSON', async () => {+ using testConfig = createTempFile(+ '{"headless": true,',+ 'cd4a.test.config.malformed.json',+ );+ assert.throws(+ () => parseArguments(['--config', testConfig.path]),+ /Invalid JSON config file:/,+ );+ });++ it('rejects a config file that is not a JSON object', async () => {+ using testConfig = createTempFile(+ JSON.stringify(['--headless']),+ 'cd4a.test.config.array.json',+ );+ assert.throws(+ () => parseArguments(['--config', testConfig.path]),+ /Invalid JSON config file: Config must be a JSON object/,+ );+ });++ it('rejects a missing config file', async () => {+ assert.throws(+ () => parseArguments(['--config', 'cd4a.test.config.missing.json']),+ /Invalid JSON config file: ENOENT/,+ );+ });++ it('replaces config arrays with cli arrays instead of merging', async () => {+ using testConfig = createTempFile(+ JSON.stringify({chromeArg: ['--a']}),+ 'cd4a.test.config.array-replace.json',+ );+ const args = parseArguments([+ '--config',+ testConfig.path,+ '--chrome-arg=--b',+ ]);+ assert.deepStrictEqual(args.chromeArg, ['--b']);+ });++ it('lets the CI env disable usage statistics enabled in config', async () => {+ using testConfig = createTempFile(+ JSON.stringify({usageStatistics: true}),+ 'cd4a.test.config.usage-statistics.json',+ );+ const args = parseArguments(['--config', testConfig.path], {CI: 'true'});+ assert.strictEqual(args.usageStatistics, false);+ });++ it('lets explicit cli flags override viaCli dynamic defaults', async () => {+ const args = parseArguments(['--viaCli', '--no-headless']);+ assert.strictEqual(args.headless, false);+ });++ describe('viaCli defaults', () => {+ for (const flag of ['--viaCli=true', '--via-cli=true']) {+ it(`applies viaCli defaults for ${flag}`, async () => {+ const args = parseArguments([flag]);+ assert.strictEqual(args.viaCli, true);+ assert.strictEqual(args.headless, true);+ assert.strictEqual(args.isolated, true);+ assert.strictEqual(args.memoryDebugging, true);+ });+ }++ it('does not apply viaCli defaults for --viaCli false', async () => {+ const args = parseArguments(['--viaCli', 'false']);+ assert.strictEqual(args.viaCli, false);+ assert.strictEqual(args.headless, false);+ assert.strictEqual(args.isolated, false);+ assert.strictEqual(args.memoryDebugging, false);+ });++ it('applies viaCli defaults when viaCli is set in the config file', async () => {+ using testConfig = createTempFile(+ JSON.stringify({viaCli: true}),+ 'cd4a.test.config.via-cli.json',+ );+ const args = parseArguments(['--config', testConfig.path]);+ assert.strictEqual(args.viaCli, true);+ assert.strictEqual(args.headless, true);+ assert.strictEqual(args.isolated, true);+ });++ it('lets cli viaCli=false override config viaCli', async () => {+ using testConfig = createTempFile(+ JSON.stringify({viaCli: true}),+ 'cd4a.test.config.via-cli-override.json',+ );+ const args = parseArguments([+ '--config',+ testConfig.path,+ '--viaCli=false',+ ]);+ assert.strictEqual(args.viaCli, false);+ assert.strictEqual(args.headless, false);+ assert.strictEqual(args.isolated, false);+ });++ for (const connectArgs of [+ ['--auto-connect'],+ ['--browserUrl', 'http://localhost:9222'],+ ['--wsEndpoint', 'ws://localhost:9222'],+ ['--user-data-dir', '/tmp/chrome-profile'],+ ]) {+ it(`does not default to isolated with ${connectArgs[0]}`, async () => {+ const args = parseArguments(['--viaCli', ...connectArgs]);+ assert.strictEqual(args.isolated, false);+ });+ }++ it('does not default to isolated with autoConnect from the config file', async () => {+ using testConfig = createTempFile(+ JSON.stringify({autoConnect: true}),+ 'cd4a.test.config.via-cli-auto-connect.json',+ );+ const args = parseArguments(['--viaCli', '--config', testConfig.path]);+ assert.strictEqual(args.autoConnect, true);+ assert.strictEqual(args.isolated, false);+ });+ });+it('parses with devtoolsComments enabled', async () => {const args = parseArguments(['--devtoolsComments']);assert.strictEqual(args.devtoolsComments, true);});+ it('includes usage examples in help output', async () => {+ const help = await buildCliParser(+ '0.0.0',+ ['node', 'main.js'],+ mcpOptions,+ ).getHelp();+ assert.match(help, /Examples:/);+ assert.match(help, /--browserUrl http:\/\/127\.0\.0\.1:9222/);+ });+it('clears default values and populates defaultDescription in getCliOptions', () => {const cliOptions = getCliOptions();@@ -832,6 +980,73 @@ describe('cli args parsing', () => {);});+ it('rejects cli channel with config-based browserUrl', async () => {+ using testConfig = createTempFile(+ JSON.stringify({browserUrl: 'http://localhost:9222'}),+ 'cd4a.test.config.browser-url.json',+ );+ assert.throws(+ () =>+ parseArguments(['--config', testConfig.path, '--channel', 'canary']),+ /Arguments channel and browserUrl are mutually exclusive/,+ );+ });++ it('rejects conflicting arguments within a config file', async () => {+ using testConfig = createTempFile(+ JSON.stringify({+ browserUrl: 'http://localhost:9222',+ wsEndpoint: 'ws://localhost:9222',+ }),+ 'cd4a.test.config.conflict.json',+ );+ assert.throws(+ () => parseArguments(['--config', testConfig.path]),+ /Arguments browserUrl and wsEndpoint are mutually exclusive/,+ );+ });++ it('allows explicitly disabled isolated with userDataDir', async () => {+ const args = parseArguments([+ '--isolated=false',+ '--user-data-dir',+ '/tmp/chrome-profile',+ ]);+ assert.strictEqual(args.isolated, false);+ assert.strictEqual(args.userDataDir, '/tmp/chrome-profile');+ });++ it('allows a config value set to false alongside a conflicting arg', async () => {+ using testConfig = createTempFile(+ JSON.stringify({autoConnect: false}),+ 'cd4a.test.config.false-no-conflict.json',+ );+ const args = parseArguments([+ '--config',+ testConfig.path,+ '--executablePath',+ '/bin/chrome',+ ]);+ assert.strictEqual(args.autoConnect, false);+ assert.strictEqual(args.executablePath, '/bin/chrome');+ });++ it('lets a cli false override a conflicting config value', async () => {+ using testConfig = createTempFile(+ JSON.stringify({autoConnect: true}),+ 'cd4a.test.config.false-override.json',+ );+ const args = parseArguments([+ '--config',+ testConfig.path,+ '--autoConnect=false',+ '--executablePath',+ '/bin/chrome',+ ]);+ assert.strictEqual(args.autoConnect, false);+ assert.strictEqual(args.executablePath, '/bin/chrome');+ });+it('rejects categoryExtensions with autoConnect', async () => {assert.throws(() => parseArguments(['--category-extensions', '--auto-connect']),@@ -882,7 +1097,7 @@ describe('cli args parsing', () => {it(`allows viaCli with ${connectArgs[0]} without enabling extensions`, async () => {const args = parseArguments(['--viaCli', ...connectArgs]);assert.strictEqual(args.categoryExtensions, undefined);- assert.strictEqual(args.isolated, undefined);+ assert.strictEqual(args.isolated, false);});}@@ -975,8 +1190,8 @@ describe('cli command strings', () => {describe('flag usage telemetry', () => {it('reports the stable channel for a default launch', async () => {const usage = computeFlagUsage(parseArguments([]), mcpOptions);- assert.strictEqual(usage.isolated_present, false);- assert.strictEqual(usage.channel_present, true);+ assert.strictEqual(usage.isolated_present, undefined);+ assert.strictEqual(usage.channel_present, undefined);assert.strictEqual(usage.channel, 'CHANNEL_STABLE');});@@ -987,7 +1202,7 @@ describe('flag usage telemetry', () => {]) {it(`does not report channel with ${connectArgs[0]}`, async () => {const usage = computeFlagUsage(parseArguments(connectArgs), mcpOptions);- assert.strictEqual(usage.isolated_present, false);+ assert.strictEqual(usage.isolated_present, undefined);assert.strictEqual(usage.channel_present, false);assert.strictEqual(usage.channel, undefined);});diff --git a/tests/config/mcp-options.test.ts b/tests/config/mcp-options.test.tsnew file mode 100644index 00000000..8b043edc--- /dev/null+++ b/tests/config/mcp-options.test.ts@@ -0,0 +1,174 @@+/**+ * @license+ * Copyright 2026 Google LLC+ * SPDX-License-Identifier: Apache-2.0+ */++import assert from 'node:assert';+import {afterEach, describe, it} from 'node:test';++import sinon from 'sinon';++import {+ applyDefaults,+ DEFAULT_FILESYSTEM_ROOT,+ parseCliArgs,+ parseConfigFile,+ validateConflicts,+ validateImplications,+} from '../../src/config/mcp-options.js';+import {createTempFile} from '../utils.js';++describe('mcp-options steps', () => {+ afterEach(() => sinon.restore());++ describe('parseCliArgs', () => {+ it('returns only explicitly passed flags', () => {+ const args = parseCliArgs('0.0.0', ['node', 'main.js', '--headless']);+ assert.deepStrictEqual(args, {+ headless: true,+ });+ });+ });++ describe('parseConfigFile', () => {+ it('returns only the keys from the file', () => {+ using configFile = createTempFile(+ JSON.stringify({+ headless: true,+ blockedUrlPattern: ['https://a.com/*'],+ }),+ 'cd4a.steps.config.json',+ );+ const args = parseConfigFile(configFile.path);+ assert.strictEqual(args.headless, true);+ assert.deepStrictEqual(args.blockedUrlPattern, ['https://a.com/*']);+ assert.strictEqual(args.isolated, undefined);+ assert.strictEqual(args.channel, undefined);+ });++ it('rejects unknown keys', () => {+ using configFile = createTempFile(+ JSON.stringify({notAnOption: true}),+ 'cd4a.steps.config.unknown.json',+ );+ assert.throws(+ () => parseConfigFile(configFile.path),+ /Invalid JSON config file: .*notAnOption/,+ );+ });++ it('rejects non-object JSON', () => {+ using configFile = createTempFile(+ JSON.stringify([]),+ 'cd4a.steps.config.array.json',+ );+ assert.throws(+ () => parseConfigFile(configFile.path),+ /Invalid JSON config file: Config must be a JSON object/,+ );+ });+ });++ describe('validateConflicts', () => {+ it('accepts a single argument from a conflict group', () => {+ validateConflicts({browserUrl: 'http://localhost:9222'});+ });++ it('ignores false and undefined values', () => {+ validateConflicts({+ browserUrl: 'http://localhost:9222',+ wsEndpoint: undefined,+ categoryExtensions: false,+ });+ });++ it('rejects two arguments from the same group', () => {+ assert.throws(+ () =>+ validateConflicts({+ browserUrl: 'http://localhost:9222',+ channel: 'canary',+ }),+ /Arguments channel and browserUrl are mutually exclusive/,+ );+ });++ describe('validateImplications', () => {+ it('accepts when implying key is not set', () => {+ validateImplications({wsEndpoint: 'ws://localhost:9222'});+ });++ it('accepts when both implying and implied keys are set', () => {+ validateImplications({+ wsHeaders: {Auth: 'token'},+ wsEndpoint: 'ws://localhost:9222',+ });+ });++ it('rejects when implying key is set but implied key is missing', () => {+ assert.throws(+ () => validateImplications({wsHeaders: {Auth: 'token'}}),+ /Implications failed:\n {2}wsHeaders -> wsEndpoint/,+ );+ });++ it('rejects when implying key is set but implied key is negated', () => {+ assert.throws(+ () =>+ validateImplications({+ experimentalFfmpegPath: '/bin/ffmpeg',+ experimentalScreencast: false,+ }),+ /Implications failed:\n {2}experimentalFfmpegPath -> experimentalScreencast/,+ );+ });+ });+ });+ describe('applyDefaults', () => {+ it('keeps explicit values and fills in defaults', () => {+ const args = applyDefaults({headless: true}, {});+ assert.strictEqual(args.headless, true);+ assert.strictEqual(args.isolated, false);+ assert.strictEqual(args.channel, 'stable');+ assert.strictEqual(args.categoryExtensions, undefined);+ });++ for (const explicitArgs of [+ {browserUrl: 'http://localhost:9222'},+ {wsEndpoint: 'ws://localhost:9222'},+ {executablePath: '/tmp/chrome'},+ ]) {+ it(`does not default channel with ${Object.keys(explicitArgs)[0]}`, () => {+ assert.strictEqual(applyDefaults(explicitArgs, {}).channel, undefined);+ });+ }++ it('applies viaCli defaults when launching a browser', () => {+ const args = applyDefaults(+ {viaCli: true, filesystemRoot: DEFAULT_FILESYSTEM_ROOT},+ {},+ );+ assert.strictEqual(args.headless, true);+ assert.strictEqual(args.isolated, true);+ assert.strictEqual(args.categoryExtensions, true);+ assert.strictEqual(args.allowUnrestrictedPaths, true);+ assert.strictEqual(args.filesystemRoot, undefined);+ });++ it('does not enable isolated or extensions for viaCli with browserUrl', () => {+ const args = applyDefaults(+ {viaCli: true, browserUrl: 'http://localhost:9222'},+ {},+ );+ assert.strictEqual(args.isolated, false);+ assert.strictEqual(args.categoryExtensions, undefined);+ });++ it('turns off usage statistics in CI', () => {+ sinon.stub(console, 'error');+ const args = applyDefaults({usageStatistics: true}, {CI: 'true'});+ assert.strictEqual(args.usageStatistics, false);+ });+ });+});diff --git a/tests/mocks.ts b/tests/mocks.tsindex 4c09435e..a009898d 100644--- a/tests/mocks.ts+++ b/tests/mocks.ts@@ -25,7 +25,10 @@import type {Frame} from 'puppeteer-core';import sinon from 'sinon';-import {type ParsedArguments, parser} from '../src/config/mcp-options.js';+import {+ type ParsedArguments,+ parseArguments,+} from '../src/config/mcp-options.js';import {McpContext} from '../src/McpContext.js';import {McpPage} from '../src/McpPage.js';import {McpResponse} from '../src/McpResponse.js';@@ -1064,7 +1067,12 @@ export function createMockContextAnalysisResult(): DevTools.HeapSnapshotModel.Heexport function createMockParsedArguments(options: Partial<ParsedArguments> = {},): ParsedArguments {- const defaultArgs = parser('0.0.0', ['node', 'main.js']).parseSync();+ const defaultArgs = parseArguments(+ '0.0.0',+ ['node', 'main.js'],+ process.env,+ false,+ );return {...defaultArgs, ...options};}