browser-commander 0.13.0 → 0.15.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.15.0
+
+### Minor Changes
+
+- b3560c8: Apply automation-friendly Chromium launch defaults, including `--password-store=basic`, and add append/opt-out launch argument controls.
+
+## 0.14.0
+
+### Minor Changes
+
+- d22b80e: Add the `launchRealBrowser()` API name for launching and attaching to a genuine installed Chrome-family browser.
+
 ## 0.13.0
 
 ### Minor Changes

package/README.md

@@ -103,9 +103,17 @@ const { browser, page } = await launchBrowser({
   channel: 'chrome',
   // Or: executablePath: '/usr/bin/google-chrome',
   headless: true,
+  extraArgs: ['--lang=en-US'],
+  // Per-flag escape hatch; `args` remains a compatible append-only alias.
+  ignoreDefaultArgs: ['--disable-infobars'],
 });
 ```
 
+Browser Commander applies the documented
+[automation-friendly launch defaults](../docs/feature-parity.md#automation-friendly-launch-defaults),
+including `--password-store=basic` to avoid an additional OS credential
+dialog. `ignoreDefaultArgs: true` omits every Browser Commander default.
+
 Attach to a Chrome-family browser that is already listening for CDP connections:
 
 ```javascript
@@ -118,19 +126,25 @@ const { browser, page } = await connectBrowser({
 const commander = makeBrowserCommander({ page });
 ```
 
-`launchAndConnectRealBrowser()` can find and start a genuine installed Chrome,
+Attachment cannot change the existing process's launch arguments. Start it
+with a loopback remote-debugging port, a dedicated `--user-data-dir`, and the
+automation-friendly defaults above, or use `launchRealBrowser()`.
+
+`launchRealBrowser()` can find and start a genuine installed Chrome,
 Edge, Brave, or Chromium with a loopback CDP endpoint and then attach to it. It
 always uses a dedicated profile; Chrome 136 and newer do not honor remote
 debugging switches for the default profile. See the
 [Chrome remote-debugging security change](https://developer.chrome.com/blog/remote-debugging-port).
 
 ```javascript
-import { launchAndConnectRealBrowser } from 'browser-commander';
+import { launchRealBrowser } from 'browser-commander';
 
-const connection = await launchAndConnectRealBrowser({
+const connection = await launchRealBrowser({
   engine: 'puppeteer',
   channel: 'chrome',
   userDataDir: '/tmp/my-automation-profile',
+  extraArgs: ['--lang=en-US'],
+  ignoreDefaultArgs: ['--disable-infobars'],
   seedCookies: [
     { name: 'session', value: 'saved', url: 'https://example.com' },
   ],
@@ -140,6 +154,9 @@ await connection.browser.close();
 
 Cookie seeding copies only cookies you explicitly provide; the helper does not
 read, decrypt, or expose cookies from a browser's default profile.
+`launchAndConnectRealBrowser()` remains available as a descriptive alias.
+Remote-debugging, loopback, and profile arguments remain managed even when all
+optional defaults are ignored; `headless: true` adds `--headless=new`.
 
 Reuse a saved authenticated session by passing Playwright-compatible storage
 state as a JSON file path or object. Cookies and localStorage are restored for
@@ -359,7 +376,7 @@ const { browser, page } = await connectBrowser({
 Playwright accepts `timeout` and Puppeteer accepts `protocolTimeout`.
 `storageState` can also seed Playwright-compatible cookies and localStorage.
 
-### launchAndConnectRealBrowser(options)
+### launchRealBrowser(options)
 
 Start an installed browser and connect through `connectBrowser()`. Use
 `channel` (`chrome`, `chrome-beta`, `chrome-dev`, `chrome-canary`, `msedge`,
@@ -369,6 +386,10 @@ a managed directory under `~/.browser-commander/real-browser/`, rejects known
 default browser-profile paths, protects its remote-debugging arguments, and
 returns the spawned `browserProcess`, resolved `cdpEndpoint`, executable path,
 and profile path alongside `{ browser, page }`.
+`launchAndConnectRealBrowser()` is an alias with identical behavior.
+`extraArgs` appends custom switches, while `ignoreDefaultArgs` accepts a list
+of defaults to omit (or `true` to omit all optional defaults). The older
+`args` append option remains supported.
 
 ### saveStorageState(page, filePath)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "browser-commander",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "description": "Universal browser automation library that supports both Playwright and Puppeteer with a unified API",
   "main": "src/index.js",
   "type": "module",

package/src/browser/launch-options.js

@@ -1,3 +1,47 @@
+import { CHROME_ARGS } from '../core/constants.js';
+
+function stringArray(value, name) {
+  if (!Array.isArray(value) || value.some((item) => typeof item !== 'string')) {
+    throw new TypeError(`${name} must be an array of strings`);
+  }
+  return value;
+}
+
+/** Resolve Browser Commander defaults, compatibility args, and extra args. */
+export function resolveChromeArgs({
+  args = [],
+  extraArgs = [],
+  ignoreDefaultArgs = [],
+} = {}) {
+  stringArray(args, 'args');
+  stringArray(extraArgs, 'extraArgs');
+  if (
+    typeof ignoreDefaultArgs !== 'boolean' &&
+    !Array.isArray(ignoreDefaultArgs)
+  ) {
+    throw new TypeError('ignoreDefaultArgs must be a boolean or string array');
+  }
+  if (Array.isArray(ignoreDefaultArgs)) {
+    stringArray(ignoreDefaultArgs, 'ignoreDefaultArgs');
+  }
+
+  const normalizedIgnoreDefaultArgs =
+    ignoreDefaultArgs === false ? [] : ignoreDefaultArgs;
+  const ignored = new Set(
+    normalizedIgnoreDefaultArgs === true
+      ? CHROME_ARGS
+      : normalizedIgnoreDefaultArgs
+  );
+  return {
+    args: [
+      ...CHROME_ARGS.filter((argument) => !ignored.has(argument)),
+      ...args,
+      ...extraArgs,
+    ],
+    ignoreDefaultArgs: normalizedIgnoreDefaultArgs,
+  };
+}
+
 function setBrowserSelectionOptions(options, { channel, executablePath }) {
   if (channel !== undefined) {
     options.channel = channel;
@@ -15,14 +59,21 @@ export function buildPlaywrightLaunchOptions({
   colorScheme,
   channel,
   executablePath,
+  ignoreDefaultArgs = [],
 }) {
+  const normalizedIgnoreDefaultArgs =
+    ignoreDefaultArgs === false ? [] : ignoreDefaultArgs;
+  const engineIgnoreDefaultArgs =
+    normalizedIgnoreDefaultArgs === true
+      ? true
+      : [...new Set(['--enable-automation', ...normalizedIgnoreDefaultArgs])];
   const options = {
     headless,
     slowMo,
     chromiumSandbox: true,
     viewport: null,
     args: chromeArgs,
-    ignoreDefaultArgs: ['--enable-automation'],
+    ignoreDefaultArgs: engineIgnoreDefaultArgs,
   };
 
   if (colorScheme !== undefined) {
@@ -38,14 +89,21 @@ export function buildPuppeteerLaunchOptions({
   userDataDir,
   channel,
   executablePath,
+  ignoreDefaultArgs = [],
 }) {
-  return setBrowserSelectionOptions(
-    {
-      headless,
-      defaultViewport: null,
-      args: ['--start-maximized', ...chromeArgs],
-      userDataDir,
-    },
-    { channel, executablePath }
-  );
+  const normalizedIgnoreDefaultArgs =
+    ignoreDefaultArgs === false ? [] : ignoreDefaultArgs;
+  const options = {
+    headless,
+    defaultViewport: null,
+    args: ['--start-maximized', ...chromeArgs],
+    userDataDir,
+  };
+  if (
+    normalizedIgnoreDefaultArgs === true ||
+    normalizedIgnoreDefaultArgs.length > 0
+  ) {
+    options.ignoreDefaultArgs = normalizedIgnoreDefaultArgs;
+  }
+  return setBrowserSelectionOptions(options, { channel, executablePath });
 }

package/src/browser/launcher.js

@@ -1,11 +1,11 @@
 import path from 'path';
 import os from 'os';
-import { CHROME_ARGS } from '../core/constants.js';
 import { disableTranslateInPreferences } from '../core/preferences.js';
 import { emulateMedia } from './media.js';
 import {
   buildPlaywrightLaunchOptions,
   buildPuppeteerLaunchOptions,
+  resolveChromeArgs,
 } from './launch-options.js';
 import {
   loadStorageState,
@@ -22,6 +22,8 @@ import {
  * @param {number} options.slowMo - Slow down operations by ms (default: 150 for Playwright, 0 for Puppeteer)
  * @param {boolean} options.verbose - Enable verbose logging (default: false)
  * @param {string[]} options.args - Custom Chrome arguments to append to the default CHROME_ARGS
+ * @param {string[]} [options.extraArgs] - Additional Chrome arguments appended after legacy args
+ * @param {boolean|string[]} [options.ignoreDefaultArgs] - Browser Commander defaults to omit, or true for all
  * @param {string|null} [options.colorScheme] - Emulate color scheme: 'light', 'dark', 'no-preference', or null to reset
  * @param {string} [options.channel] - Installed browser channel, such as 'chrome', 'chrome-beta', or 'msedge'
  * @param {string} [options.executablePath] - Explicit path to a Chrome or Chromium executable
@@ -36,14 +38,20 @@ export async function launchBrowser(options = {}) {
     slowMo = engine === 'playwright' ? 150 : 0,
     verbose = false,
     args = [],
+    extraArgs = [],
+    ignoreDefaultArgs = [],
     colorScheme,
     channel,
     executablePath,
     storageState,
   } = options;
 
-  // Combine default CHROME_ARGS with custom args
-  const chromeArgs = [...CHROME_ARGS, ...args];
+  const resolvedChromeArgs = resolveChromeArgs({
+    args,
+    extraArgs,
+    ignoreDefaultArgs,
+  });
+  const chromeArgs = resolvedChromeArgs.args;
 
   if (!['playwright', 'puppeteer'].includes(engine)) {
     throw new Error(
@@ -77,6 +85,7 @@ export async function launchBrowser(options = {}) {
       colorScheme,
       channel,
       executablePath,
+      ignoreDefaultArgs: resolvedChromeArgs.ignoreDefaultArgs,
     });
     browser = await chromium.launchPersistentContext(
       userDataDir,
@@ -96,6 +105,7 @@ export async function launchBrowser(options = {}) {
         userDataDir,
         channel,
         executablePath,
+        ignoreDefaultArgs: resolvedChromeArgs.ignoreDefaultArgs,
       })
     );
     const pages = await browser.pages();

package/src/browser/real-browser.js

@@ -5,6 +5,7 @@ import os from 'node:os';
 import path from 'node:path';
 
 import { connectBrowser } from './connector.js';
+import { resolveChromeArgs } from './launch-options.js';
 
 const MANAGED_ARGUMENTS = [
   '--remote-debugging-address',
@@ -240,6 +241,8 @@ export function buildRealBrowserArgs({
   remoteDebuggingPort = 0,
   headless = false,
   args = [],
+  extraArgs = [],
+  ignoreDefaultArgs = [],
 }) {
   if (
     !Number.isInteger(remoteDebuggingPort) ||
@@ -250,7 +253,8 @@ export function buildRealBrowserArgs({
       'remoteDebuggingPort must be an integer from 0 to 65535'
     );
   }
-  const conflictingArgument = args.find((argument) =>
+  const customArgs = [...args, ...extraArgs];
+  const conflictingArgument = customArgs.find((argument) =>
     MANAGED_ARGUMENTS.some(
       (managed) => argument === managed || argument.startsWith(`${managed}=`)
     )
@@ -261,14 +265,15 @@ export function buildRealBrowserArgs({
     );
   }
 
+  const defaultArgs = resolveChromeArgs({ ignoreDefaultArgs }).args;
+
   return [
     '--remote-debugging-address=127.0.0.1',
     `--remote-debugging-port=${remoteDebuggingPort}`,
     `--user-data-dir=${userDataDir}`,
-    '--no-first-run',
-    '--no-default-browser-check',
+    ...defaultArgs,
     ...(headless ? ['--headless=new'] : []),
-    ...args,
+    ...customArgs,
   ];
 }
 
@@ -353,6 +358,8 @@ export async function waitForCdpEndpoint({
  * @param {number} [options.remoteDebuggingPort=0] - Loopback CDP port; zero lets Chrome choose
  * @param {boolean} [options.headless=false] - Run the installed browser headlessly
  * @param {string[]} [options.args] - Additional browser arguments
+ * @param {string[]} [options.extraArgs] - Additional browser arguments appended after legacy args
+ * @param {boolean|string[]} [options.ignoreDefaultArgs] - Browser Commander defaults to omit, or true for all
  * @param {number} [options.startupTimeout=30000] - CDP readiness timeout in milliseconds
  * @param {Object[]} [options.seedCookies] - Cookies to seed after connecting
  * @param {boolean} [options.verbose=false] - Show browser and connection logs
@@ -362,6 +369,15 @@ export async function launchAndConnectRealBrowser(options = {}) {
   return await launchAndConnectRealBrowserWithDependencies(options);
 }
 
+/**
+ * Short Playwright-style name for {@link launchAndConnectRealBrowser}.
+ *
+ * Both names are the same function so existing callers can keep using the
+ * descriptive name while new code can use the API proposed for real-browser
+ * launch.
+ */
+export const launchRealBrowser = launchAndConnectRealBrowser;
+
 /** Dependency-injected implementation used by the public helper and tests. */
 export async function launchAndConnectRealBrowserWithDependencies(
   options = {},
@@ -375,6 +391,8 @@ export async function launchAndConnectRealBrowserWithDependencies(
     remoteDebuggingPort = 0,
     headless = false,
     args = [],
+    extraArgs = [],
+    ignoreDefaultArgs = [],
     startupTimeout = 30_000,
     verbose = false,
     cdpEndpoint,
@@ -400,6 +418,8 @@ export async function launchAndConnectRealBrowserWithDependencies(
     remoteDebuggingPort,
     headless,
     args,
+    extraArgs,
+    ignoreDefaultArgs,
   });
   const spawnBrowser = dependencies.spawnBrowser ?? spawn;
   const browserProcess = spawnBrowser(resolvedExecutablePath, browserArgs, {

package/src/core/constants.js

@@ -5,6 +5,7 @@ export const CHROME_ARGS = [
   '--disable-session-crashed-bubble',
   '--hide-crash-restore-bubble',
   '--disable-infobars',
+  '--password-store=basic',
   '--no-first-run',
   '--no-default-browser-check',
   '--disable-crash-restore',

package/src/exports.js

@@ -43,7 +43,10 @@ export {
 
 // Re-export browser management
 export { connectBrowser } from './browser/connector.js';
-export { launchAndConnectRealBrowser } from './browser/real-browser.js';
+export {
+  launchAndConnectRealBrowser,
+  launchRealBrowser,
+} from './browser/real-browser.js';
 export { launchBrowser } from './browser/launcher.js';
 export { saveStorageState } from './browser/storage-state.js';
 export { emulateMedia } from './browser/media.js';

package/tests/unit/browser/launch-options.test.js

@@ -4,9 +4,64 @@ import assert from 'node:assert';
 import {
   buildPlaywrightLaunchOptions,
   buildPuppeteerLaunchOptions,
+  resolveChromeArgs,
 } from '../../../src/browser/launch-options.js';
 
 describe('browser launch options', () => {
+  it('applies safe defaults, appends extra arguments, and supports per-flag opt-out', () => {
+    const options = resolveChromeArgs({
+      args: ['--legacy-arg'],
+      extraArgs: ['--lang=en-US'],
+      ignoreDefaultArgs: ['--no-default-browser-check'],
+    });
+
+    assert.ok(options.args.includes('--password-store=basic'));
+    assert.ok(options.args.includes('--no-first-run'));
+    assert.equal(options.args.includes('--no-default-browser-check'), false);
+    assert.deepEqual(options.args.slice(-2), ['--legacy-arg', '--lang=en-US']);
+    assert.deepEqual(options.ignoreDefaultArgs, ['--no-default-browser-check']);
+  });
+
+  it('can ignore every Browser Commander default', () => {
+    const options = resolveChromeArgs({
+      extraArgs: ['--lang=en-US'],
+      ignoreDefaultArgs: true,
+    });
+
+    assert.deepEqual(options.args, ['--lang=en-US']);
+    assert.equal(options.ignoreDefaultArgs, true);
+  });
+
+  it('can opt out of the password-store default specifically', () => {
+    const options = resolveChromeArgs({
+      ignoreDefaultArgs: ['--password-store=basic'],
+    });
+
+    assert.equal(options.args.includes('--password-store=basic'), false);
+    assert.ok(options.args.includes('--no-first-run'));
+  });
+
+  it('forwards ignored defaults to both browser engines', () => {
+    const playwright = buildPlaywrightLaunchOptions({
+      headless: false,
+      slowMo: 150,
+      chromeArgs: [],
+      ignoreDefaultArgs: ['--no-first-run'],
+    });
+    const puppeteer = buildPuppeteerLaunchOptions({
+      headless: false,
+      chromeArgs: [],
+      userDataDir: '/tmp/browser-commander-test',
+      ignoreDefaultArgs: ['--no-first-run'],
+    });
+
+    assert.deepEqual(playwright.ignoreDefaultArgs, [
+      '--enable-automation',
+      '--no-first-run',
+    ]);
+    assert.deepEqual(puppeteer.ignoreDefaultArgs, ['--no-first-run']);
+  });
+
   it('forwards channel and executablePath to Playwright', () => {
     const options = buildPlaywrightLaunchOptions({
       headless: true,

package/tests/unit/browser/real-browser.test.js

@@ -9,8 +9,12 @@ import {
   buildRealBrowserArgs,
   launchAndConnectRealBrowser,
   launchAndConnectRealBrowserWithDependencies,
+  launchRealBrowser,
 } from '../../../src/browser/real-browser.js';
-import { launchAndConnectRealBrowser as publicHelper } from '../../../src/index.js';
+import {
+  launchAndConnectRealBrowser as publicHelper,
+  launchRealBrowser as publicShortHelper,
+} from '../../../src/index.js';
 
 describe('launchAndConnectRealBrowser', () => {
   let temporaryDirectory;
@@ -24,6 +28,8 @@ describe('launchAndConnectRealBrowser', () => {
 
   it('is exported from the package API', () => {
     assert.equal(publicHelper, launchAndConnectRealBrowser);
+    assert.equal(launchRealBrowser, launchAndConnectRealBrowser);
+    assert.equal(publicShortHelper, launchRealBrowser);
   });
 
   it('builds a loopback-only CDP command with a dedicated profile', () => {
@@ -38,13 +44,32 @@ describe('launchAndConnectRealBrowser', () => {
       '--remote-debugging-address=127.0.0.1',
       '--remote-debugging-port=9333',
       '--user-data-dir=/tmp/browser-commander-dedicated',
+      '--disable-session-crashed-bubble',
+      '--hide-crash-restore-bubble',
+      '--disable-infobars',
+      '--password-store=basic',
       '--no-first-run',
       '--no-default-browser-check',
+      '--disable-crash-restore',
       '--headless=new',
       '--lang=en-US',
     ]);
   });
 
+  it('supports additive arguments and per-default opt-out', () => {
+    const args = buildRealBrowserArgs({
+      userDataDir: '/tmp/browser-commander-dedicated',
+      args: ['--legacy-arg'],
+      extraArgs: ['--lang=en-US'],
+      ignoreDefaultArgs: ['--no-first-run'],
+    });
+
+    assert.ok(args.includes('--password-store=basic'));
+    assert.equal(args.includes('--no-first-run'), false);
+    assert.ok(args.includes('--no-default-browser-check'));
+    assert.deepEqual(args.slice(-2), ['--legacy-arg', '--lang=en-US']);
+  });
+
   it('rejects custom arguments that could bypass protected CDP settings', () => {
     for (const argument of [
       '--remote-debugging-address=0.0.0.0',

package/tests/unit/core/constants.test.js

@@ -10,6 +10,7 @@ describe('constants', () => {
 
     it('should contain expected browser arguments', () => {
       assert.ok(CHROME_ARGS.includes('--disable-infobars'));
+      assert.ok(CHROME_ARGS.includes('--password-store=basic'));
       assert.ok(CHROME_ARGS.includes('--no-first-run'));
       assert.ok(CHROME_ARGS.includes('--no-default-browser-check'));
     });