browser-commander 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.10.0
+
+### Minor Changes
+
+- fe688ac: Add `channel` and `executablePath` launch options for reusing an installed Chrome-family browser.
+
+## 0.9.1
+
+### Patch Changes
+
+- cbd4fe1: Remove CI warning noise from workflow actions, release logging, and lint output.
+
 ## 0.9.0
 
 ### Minor Changes

package/README.md

@@ -87,6 +87,19 @@ await commander.destroy();
 await browser.close();
 ```
 
+To reuse an installed Chrome-family browser instead of downloading the
+engine's bundled Chromium, select a browser channel or provide its executable
+path. Both options are passed directly to Playwright or Puppeteer:
+
+```javascript
+const { browser, page } = await launchBrowser({
+  engine: 'playwright',
+  channel: 'chrome',
+  // Or: executablePath: '/usr/bin/google-chrome',
+  headless: true,
+});
+```
+
 ## Browser Commander Tests
 
 `browser-commander/tests` adds browser fixtures and scheduling helpers on top of

package/eslint.config.js

@@ -88,13 +88,13 @@ export default [
       // Comments and documentation
       'spaced-comment': ['error', 'always', { markers: ['/'] }],
 
-      // Complexity rules - reasonable thresholds for maintainability
-      complexity: ['warn', 15], // Cyclomatic complexity - allow more complex logic than strict 8
+      // Complexity rules - tuned for browser-automation orchestration code
+      complexity: ['warn', 30], // Cyclomatic complexity guardrail for unusually branchy functions
       'max-depth': ['warn', 5], // Maximum nesting depth - slightly more lenient than strict 4
       'max-lines-per-function': [
         'warn',
         {
-          max: 150, // More reasonable than strict 50 lines per function
+          max: 300, // Allows orchestration functions while still catching very large functions
           skipBlankLines: true,
           skipComments: true,
         },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "browser-commander",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Universal browser automation library that supports both Playwright and Puppeteer with a unified API",
   "main": "src/index.js",
   "type": "module",
@@ -9,12 +9,12 @@
     "./tests": "./src/tests/index.js"
   },
   "scripts": {
-    "test": "node --test --test-reporter spec tests/unit/",
-    "test:unit": "node --test --test-reporter spec tests/unit/",
-    "test:coverage": "node --test --experimental-test-coverage tests/unit/",
-    "test:e2e": "RUN_E2E=true node --test tests/e2e/",
-    "test:e2e:playwright": "RUN_E2E=true node --test tests/e2e/playwright.e2e.test.js",
-    "test:e2e:puppeteer": "RUN_E2E=true node --test tests/e2e/puppeteer.e2e.test.js",
+    "test": "node scripts/run-tests.mjs --reporter spec tests/unit",
+    "test:unit": "node scripts/run-tests.mjs --reporter spec tests/unit",
+    "test:coverage": "node scripts/run-tests.mjs --coverage tests/unit",
+    "test:e2e": "node scripts/run-tests.mjs --env RUN_E2E=true tests/e2e",
+    "test:e2e:playwright": "node scripts/run-tests.mjs --env RUN_E2E=true tests/e2e/playwright.e2e.test.js",
+    "test:e2e:puppeteer": "node scripts/run-tests.mjs --env RUN_E2E=true tests/e2e/puppeteer.e2e.test.js",
     "test:all": "npm run test:unit && npm run test:e2e",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",

package/scripts/clean-npm-config.mjs

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { pathToFileURL } from 'node:url';
+
+export function removeDeprecatedAlwaysAuth(configPath) {
+  if (!configPath || !existsSync(configPath)) {
+    return false;
+  }
+
+  const config = readFileSync(configPath, 'utf8');
+  const lines = config.split(/\r?\n/);
+  const filteredLines = lines.filter(
+    (line) => !/^\s*always-auth\s*=/.test(line)
+  );
+
+  if (filteredLines.length === lines.length) {
+    return false;
+  }
+
+  writeFileSync(configPath, filteredLines.join('\n'));
+  return true;
+}
+
+function main() {
+  const removed = removeDeprecatedAlwaysAuth(process.env.NPM_CONFIG_USERCONFIG);
+  if (removed) {
+    console.log('Removed deprecated always-auth from npm user config.');
+  } else {
+    console.log('No deprecated npm always-auth config found.');
+  }
+}
+
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(process.argv[1]).href
+) {
+  main();
+}

package/scripts/npm-registry.mjs

@@ -0,0 +1,31 @@
+export function formatRegistryPackagePath(packageName) {
+  return encodeURIComponent(packageName);
+}
+
+export async function isVersionPublished(
+  packageName,
+  version,
+  fetchFn = fetch
+) {
+  const packagePath = formatRegistryPackagePath(packageName);
+  const versionPath = encodeURIComponent(version);
+  const response = await fetchFn(
+    `https://registry.npmjs.org/${packagePath}/${versionPath}`,
+    {
+      headers: { accept: 'application/json' },
+    }
+  );
+
+  if (response.status === 404) {
+    return false;
+  }
+
+  if (!response.ok) {
+    throw new Error(
+      `Failed to check npm registry for ${packageName}@${version}: ${response.status} ${response.statusText}`
+    );
+  }
+
+  const metadata = await response.json();
+  return metadata?.version === version;
+}

package/scripts/publish-to-npm.mjs

@@ -13,6 +13,8 @@
 
 import { readFileSync, appendFileSync } from 'fs';
 
+import { isVersionPublished } from './npm-registry.mjs';
+
 const PACKAGE_NAME = 'browser-commander';
 
 // Load use-m dynamically
@@ -74,26 +76,23 @@ async function main() {
     console.log(
       `Checking if version ${currentVersion} is already published...`
     );
-    const checkResult =
-      await $`npm view "${PACKAGE_NAME}@${currentVersion}" version`.run({
-        capture: true,
-      });
-
-    // command-stream returns { code: 0 } on success, { code: 1 } on failure (e.g., E404)
-    // Exit code 0 means version exists, non-zero means version not found
-    if (checkResult.code === 0) {
+    const versionIsPublished = await isVersionPublished(
+      PACKAGE_NAME,
+      currentVersion
+    );
+
+    if (versionIsPublished) {
       console.log(`Version ${currentVersion} is already published to npm`);
       setOutput('published', 'true');
       setOutput('published_version', currentVersion);
       setOutput('already_published', 'true');
       return;
-    } else {
-      // Version not found on npm (E404), proceed with publish
-      console.log(
-        `Version ${currentVersion} not found on npm, proceeding with publish...`
-      );
     }
 
+    console.log(
+      `Version ${currentVersion} not found on npm, proceeding with publish...`
+    );
+
     // Publish to npm using OIDC trusted publishing with retry logic
     for (let i = 1; i <= MAX_RETRIES; i++) {
       console.log(`Publish attempt ${i} of ${MAX_RETRIES}...`);

package/scripts/run-tests.mjs

@@ -0,0 +1,192 @@
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { resolve, relative, sep } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { spawnSync } from 'node:child_process';
+
+const TEST_FILE_PATTERN = /\.test\.[cm]?js$/u;
+
+function readOptionValue(argv, index, optionName) {
+  const value = argv[index + 1];
+
+  if (!value || value.startsWith('--')) {
+    throw new Error(`${optionName} requires a value`);
+  }
+
+  return value;
+}
+
+function parseEnvAssignment(assignment) {
+  const separatorIndex = assignment.indexOf('=');
+
+  if (separatorIndex <= 0) {
+    throw new Error(`Invalid environment override: ${assignment}`);
+  }
+
+  return {
+    name: assignment.slice(0, separatorIndex),
+    value: assignment.slice(separatorIndex + 1),
+  };
+}
+
+export function parseTestRunnerArgs(argv) {
+  const options = {
+    coverage: false,
+    env: {},
+    reporter: null,
+    targets: [],
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+
+    if (arg === '--coverage') {
+      options.coverage = true;
+      continue;
+    }
+
+    if (arg === '--reporter') {
+      options.reporter = readOptionValue(argv, index, '--reporter');
+      index += 1;
+      continue;
+    }
+
+    if (arg === '--env') {
+      const { name, value } = parseEnvAssignment(
+        readOptionValue(argv, index, '--env')
+      );
+      options.env[name] = value;
+      index += 1;
+      continue;
+    }
+
+    if (arg.startsWith('--env=')) {
+      const { name, value } = parseEnvAssignment(arg.slice('--env='.length));
+      options.env[name] = value;
+      continue;
+    }
+
+    options.targets.push(arg);
+  }
+
+  if (options.targets.length === 0) {
+    throw new Error('At least one test file or directory is required');
+  }
+
+  return options;
+}
+
+function normalizeForSort(filePath) {
+  return filePath.split(sep).join('/');
+}
+
+function isTestFile(filePath) {
+  return TEST_FILE_PATTERN.test(filePath);
+}
+
+function listFilesRecursively(directory) {
+  const entries = readdirSync(directory, { withFileTypes: true });
+  const files = [];
+
+  for (const entry of entries) {
+    const entryPath = resolve(directory, entry.name);
+
+    if (entry.isDirectory()) {
+      files.push(...listFilesRecursively(entryPath));
+      continue;
+    }
+
+    if (entry.isFile() && isTestFile(entryPath)) {
+      files.push(entryPath);
+    }
+  }
+
+  return files;
+}
+
+export function resolveTestFiles(targets, cwd = process.cwd()) {
+  const files = [];
+
+  for (const target of targets) {
+    const absoluteTarget = resolve(cwd, target);
+
+    if (!existsSync(absoluteTarget)) {
+      throw new Error(`Test target does not exist: ${target}`);
+    }
+
+    const targetStats = statSync(absoluteTarget);
+
+    if (targetStats.isDirectory()) {
+      files.push(...listFilesRecursively(absoluteTarget));
+      continue;
+    }
+
+    if (targetStats.isFile() && isTestFile(absoluteTarget)) {
+      files.push(absoluteTarget);
+    }
+  }
+
+  const uniqueFiles = [...new Set(files)];
+  uniqueFiles.sort((left, right) =>
+    normalizeForSort(left).localeCompare(normalizeForSort(right))
+  );
+
+  if (uniqueFiles.length === 0) {
+    throw new Error(`No test files found in: ${targets.join(', ')}`);
+  }
+
+  return uniqueFiles.map((file) => relative(cwd, file));
+}
+
+export function buildNodeTestArgs(options, testFiles) {
+  const args = ['--test'];
+
+  if (options.coverage) {
+    args.push('--experimental-test-coverage');
+  }
+
+  if (options.reporter) {
+    args.push('--test-reporter', options.reporter);
+  }
+
+  args.push(...testFiles);
+  return args;
+}
+
+function runNodeTests(options, testFiles) {
+  const result = spawnSync(
+    process.execPath,
+    buildNodeTestArgs(options, testFiles),
+    {
+      env: { ...process.env, ...options.env },
+      stdio: 'inherit',
+    }
+  );
+
+  if (result.error) {
+    throw result.error;
+  }
+
+  if (result.signal) {
+    throw new Error(`Node test runner terminated by signal ${result.signal}`);
+  }
+
+  return result.status ?? 1;
+}
+
+export function main(argv = process.argv.slice(2)) {
+  const options = parseTestRunnerArgs(argv);
+  const testFiles = resolveTestFiles(options.targets);
+  return runNodeTests(options, testFiles);
+}
+
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(process.argv[1]).href
+) {
+  try {
+    process.exitCode = main();
+  } catch (error) {
+    console.error(error.message);
+    process.exitCode = 1;
+  }
+}

package/scripts/setup-npm.mjs

@@ -3,7 +3,7 @@
 /**
  * Update npm for OIDC trusted publishing
  * npm trusted publishing requires npm >= 11.5.1
- * Node.js 20.x ships with npm 10.x, so we need to update
+ * Keep the runner npm version current enough for OIDC publishing
  *
  * Uses link-foundation libraries:
  * - use-m: Dynamic package loading without package.json dependencies

package/src/browser/launch-options.js

@@ -0,0 +1,51 @@
+function setBrowserSelectionOptions(options, { channel, executablePath }) {
+  if (channel !== undefined) {
+    options.channel = channel;
+  }
+  if (executablePath !== undefined) {
+    options.executablePath = executablePath;
+  }
+  return options;
+}
+
+export function buildPlaywrightLaunchOptions({
+  headless,
+  slowMo,
+  chromeArgs,
+  colorScheme,
+  channel,
+  executablePath,
+}) {
+  const options = {
+    headless,
+    slowMo,
+    chromiumSandbox: true,
+    viewport: null,
+    args: chromeArgs,
+    ignoreDefaultArgs: ['--enable-automation'],
+  };
+
+  if (colorScheme !== undefined) {
+    options.colorScheme = colorScheme;
+  }
+
+  return setBrowserSelectionOptions(options, { channel, executablePath });
+}
+
+export function buildPuppeteerLaunchOptions({
+  headless,
+  chromeArgs,
+  userDataDir,
+  channel,
+  executablePath,
+}) {
+  return setBrowserSelectionOptions(
+    {
+      headless,
+      defaultViewport: null,
+      args: ['--start-maximized', ...chromeArgs],
+      userDataDir,
+    },
+    { channel, executablePath }
+  );
+}

package/src/browser/launcher.js

@@ -3,6 +3,10 @@ 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,
+} from './launch-options.js';
 
 /**
  * Launch browser with default configuration
@@ -14,6 +18,8 @@ import { emulateMedia } from './media.js';
  * @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|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
  * @returns {Promise<Object>} - Object with browser and page
  */
 export async function launchBrowser(options = {}) {
@@ -25,6 +31,8 @@ export async function launchBrowser(options = {}) {
     verbose = false,
     args = [],
     colorScheme,
+    channel,
+    executablePath,
   } = options;
 
   // Combine default CHROME_ARGS with custom args
@@ -53,18 +61,14 @@ export async function launchBrowser(options = {}) {
 
   if (engine === 'playwright') {
     const { chromium } = await import('playwright');
-    const contextOptions = {
+    const contextOptions = buildPlaywrightLaunchOptions({
       headless,
       slowMo,
-      chromiumSandbox: true,
-      viewport: null,
-      args: chromeArgs,
-      ignoreDefaultArgs: ['--enable-automation'],
-    };
-    // Playwright supports colorScheme as a context-level launch option
-    if (colorScheme !== undefined) {
-      contextOptions.colorScheme = colorScheme;
-    }
+      chromeArgs,
+      colorScheme,
+      channel,
+      executablePath,
+    });
     browser = await chromium.launchPersistentContext(
       userDataDir,
       contextOptions
@@ -72,12 +76,15 @@ export async function launchBrowser(options = {}) {
     page = browser.pages()[0];
   } else {
     const puppeteer = await import('puppeteer');
-    browser = await puppeteer.default.launch({
-      headless,
-      defaultViewport: null,
-      args: ['--start-maximized', ...chromeArgs],
-      userDataDir,
-    });
+    browser = await puppeteer.default.launch(
+      buildPuppeteerLaunchOptions({
+        headless,
+        chromeArgs,
+        userDataDir,
+        channel,
+        executablePath,
+      })
+    );
     const pages = await browser.pages();
     page = pages[0];
   }

package/src/browser/navigation.js

@@ -25,7 +25,7 @@ export async function defaultNavigationVerification(options = {}) {
   const { page, expectedUrl, startUrl } = options;
 
   try {
-    const actualUrl = page.url();
+    const actualUrl = await Promise.resolve(page.url());
 
     // If expected URL is provided, verify it matches
     if (expectedUrl) {
@@ -232,7 +232,7 @@ export async function goto(options = {}) {
     waitUntil = 'domcontentloaded',
     waitForStableUrlBefore = true,
     waitForStableUrlAfter = true,
-    waitForNetworkIdle = true,
+    waitForNetworkIdle: _waitForNetworkIdle = true,
     stableChecks = 3,
     checkInterval = 1000,
     timeout = 240000,
@@ -395,7 +395,6 @@ export async function waitForNavigation(options = {}) {
  */
 export async function waitForPageReady(options = {}) {
   const {
-    page,
     navigationManager,
     networkTracker,
     log,

package/src/core/dialog-manager.js

@@ -19,7 +19,7 @@
  * @returns {Object} - DialogManager API
  */
 export function createDialogManager(options = {}) {
-  const { page, engine, log } = options;
+  const { page, log } = options;
 
   if (!page) {
     throw new Error('page is required in options');

package/src/core/engine-adapter.js

@@ -13,6 +13,12 @@
 
 import { TIMING } from './constants.js';
 
+function notImplemented(methodName) {
+  return Promise.reject(
+    new Error(`${methodName}() must be implemented by subclass`)
+  );
+}
+
 /**
  * Base class defining the engine adapter interface
  * All engine-specific operations should be defined here
@@ -39,7 +45,7 @@ export class EngineAdapter {
    * @param {string} selector - CSS selector
    * @returns {Object} - Locator (Playwright) or ElementHandle (Puppeteer)
    */
-  createLocator(selector) {
+  createLocator(_selector) {
     throw new Error('createLocator() must be implemented by subclass');
   }
 
@@ -48,8 +54,8 @@ export class EngineAdapter {
    * @param {string} selector - CSS selector
    * @returns {Promise<Object|null>} - Locator/Element or null
    */
-  async querySelector(selector) {
-    throw new Error('querySelector() must be implemented by subclass');
+  querySelector(_selector) {
+    return notImplemented('querySelector');
   }
 
   /**
@@ -57,8 +63,8 @@ export class EngineAdapter {
    * @param {string} selector - CSS selector
    * @returns {Promise<Array>} - Array of locators/elements
    */
-  async querySelectorAll(selector) {
-    throw new Error('querySelectorAll() must be implemented by subclass');
+  querySelectorAll(_selector) {
+    return notImplemented('querySelectorAll');
   }
 
   /**
@@ -67,8 +73,8 @@ export class EngineAdapter {
    * @param {Object} options - Wait options {visible, timeout}
    * @returns {Promise<void>}
    */
-  async waitForSelector(selector, options = {}) {
-    throw new Error('waitForSelector() must be implemented by subclass');
+  waitForSelector(_selector, _options = {}) {
+    return notImplemented('waitForSelector');
   }
 
   /**
@@ -77,8 +83,8 @@ export class EngineAdapter {
    * @param {number} timeout - Timeout in ms
    * @returns {Promise<Object>} - The locator/element
    */
-  async waitForVisible(locatorOrElement, timeout = TIMING.DEFAULT_TIMEOUT) {
-    throw new Error('waitForVisible() must be implemented by subclass');
+  waitForVisible(_locatorOrElement, _timeout = TIMING.DEFAULT_TIMEOUT) {
+    return notImplemented('waitForVisible');
   }
 
   /**
@@ -86,8 +92,8 @@ export class EngineAdapter {
    * @param {string} selector - CSS selector
    * @returns {Promise<number>} - Number of matching elements
    */
-  async count(selector) {
-    throw new Error('count() must be implemented by subclass');
+  count(_selector) {
+    return notImplemented('count');
   }
 
   // ============================================================================
@@ -101,8 +107,8 @@ export class EngineAdapter {
    * @param {any} args - Arguments to pass (optional)
    * @returns {Promise<any>} - Result of evaluation
    */
-  async evaluateOnElement(locatorOrElement, fn, args) {
-    throw new Error('evaluateOnElement() must be implemented by subclass');
+  evaluateOnElement(_locatorOrElement, _fn, _args) {
+    return notImplemented('evaluateOnElement');
   }
 
   /**
@@ -110,8 +116,8 @@ export class EngineAdapter {
    * @param {Object} locatorOrElement - Locator or element
    * @returns {Promise<string|null>} - Text content
    */
-  async getTextContent(locatorOrElement) {
-    throw new Error('getTextContent() must be implemented by subclass');
+  getTextContent(_locatorOrElement) {
+    return notImplemented('getTextContent');
   }
 
   /**
@@ -119,8 +125,8 @@ export class EngineAdapter {
    * @param {Object} locatorOrElement - Locator or element
    * @returns {Promise<string>} - Input value
    */
-  async getInputValue(locatorOrElement) {
-    throw new Error('getInputValue() must be implemented by subclass');
+  getInputValue(_locatorOrElement) {
+    return notImplemented('getInputValue');
   }
 
   /**
@@ -129,8 +135,8 @@ export class EngineAdapter {
    * @param {string} attribute - Attribute name
    * @returns {Promise<string|null>} - Attribute value
    */
-  async getAttribute(locatorOrElement, attribute) {
-    throw new Error('getAttribute() must be implemented by subclass');
+  getAttribute(_locatorOrElement, _attribute) {
+    return notImplemented('getAttribute');
   }
 
   // ============================================================================
@@ -143,8 +149,8 @@ export class EngineAdapter {
    * @param {Object} options - Click options {force, etc.}
    * @returns {Promise<void>}
    */
-  async click(locatorOrElement, options = {}) {
-    throw new Error('click() must be implemented by subclass');
+  click(_locatorOrElement, _options = {}) {
+    return notImplemented('click');
   }
 
   /**
@@ -153,8 +159,8 @@ export class EngineAdapter {
    * @param {string} text - Text to type
    * @returns {Promise<void>}
    */
-  async type(locatorOrElement, text) {
-    throw new Error('type() must be implemented by subclass');
+  type(_locatorOrElement, _text) {
+    return notImplemented('type');
   }
 
   /**
@@ -163,8 +169,8 @@ export class EngineAdapter {
    * @param {string} text - Text to fill
    * @returns {Promise<void>}
    */
-  async fill(locatorOrElement, text) {
-    throw new Error('fill() must be implemented by subclass');
+  fill(_locatorOrElement, _text) {
+    return notImplemented('fill');
   }
 
   /**
@@ -172,8 +178,8 @@ export class EngineAdapter {
    * @param {Object} locatorOrElement - Locator or element
    * @returns {Promise<void>}
    */
-  async focus(locatorOrElement) {
-    throw new Error('focus() must be implemented by subclass');
+  focus(_locatorOrElement) {
+    return notImplemented('focus');
   }
 
   // ============================================================================
@@ -185,8 +191,8 @@ export class EngineAdapter {
    * @param {string} key - Key name (Playwright/Puppeteer key format)
    * @returns {Promise<void>}
    */
-  async keyboardPress(key) {
-    throw new Error('keyboardPress() must be implemented by subclass');
+  keyboardPress(_key) {
+    return notImplemented('keyboardPress');
   }
 
   /**
@@ -194,8 +200,8 @@ export class EngineAdapter {
    * @param {string} text - Text to type
    * @returns {Promise<void>}
    */
-  async keyboardType(text) {
-    throw new Error('keyboardType() must be implemented by subclass');
+  keyboardType(_text) {
+    return notImplemented('keyboardType');
   }
 
   /**
@@ -203,8 +209,8 @@ export class EngineAdapter {
    * @param {string} key - Key name
    * @returns {Promise<void>}
    */
-  async keyboardDown(key) {
-    throw new Error('keyboardDown() must be implemented by subclass');
+  keyboardDown(_key) {
+    return notImplemented('keyboardDown');
   }
 
   /**
@@ -212,8 +218,8 @@ export class EngineAdapter {
    * @param {string} key - Key name
    * @returns {Promise<void>}
    */
-  async keyboardUp(key) {
-    throw new Error('keyboardUp() must be implemented by subclass');
+  keyboardUp(_key) {
+    return notImplemented('keyboardUp');
   }
 
   // ============================================================================
@@ -226,8 +232,8 @@ export class EngineAdapter {
    * @param {Array} args - Arguments to pass
    * @returns {Promise<any>} - Result of evaluation
    */
-  async evaluateOnPage(fn, args = []) {
-    throw new Error('evaluateOnPage() must be implemented by subclass');
+  evaluateOnPage(_fn, _args = []) {
+    return notImplemented('evaluateOnPage');
   }
 
   /**
@@ -243,8 +249,8 @@ export class EngineAdapter {
    * @param {Object} options - PDF options (format, printBackground, margin, etc.)
    * @returns {Promise<Buffer>} - PDF buffer
    */
-  async pdf(options = {}) {
-    throw new Error('pdf() must be implemented by subclass');
+  pdf(_options = {}) {
+    return notImplemented('pdf');
   }
 }
 
@@ -435,7 +441,7 @@ export class PuppeteerAdapter extends EngineAdapter {
     await this.page.waitForSelector(selector, { visible, timeout });
   }
 
-  async waitForVisible(locatorOrElement, timeout = TIMING.DEFAULT_TIMEOUT) {
+  waitForVisible(locatorOrElement, _timeout = TIMING.DEFAULT_TIMEOUT) {
     // For Puppeteer, locatorOrElement is already an ElementHandle
     // We can't wait on it directly, so we just return it
     // The caller should have already used waitForSelector

package/src/core/navigation-manager.js

@@ -370,7 +370,7 @@ export function createNavigationManager(options = {}) {
       });
     }
 
-    return navigationPromise;
+    return await navigationPromise;
   }
 
   /**

package/src/core/network-tracker.js

@@ -209,7 +209,6 @@ export function createNetworkTracker(options = {}) {
   async function waitForNetworkIdle(opts = {}) {
     const { timeout = 30000, idleTime = idleTimeout } = opts;
 
-    const startTime = Date.now();
     const currentNavId = navigationId;
 
     // If already idle, wait for idle time
@@ -317,7 +316,7 @@ export function createNetworkTracker(options = {}) {
    */
   function getPendingUrls() {
     const urls = [];
-    for (const [key, req] of pendingRequests) {
+    for (const req of pendingRequests.values()) {
       const url = typeof req.url === 'function' ? req.url() : req.url;
       urls.push(url);
     }

package/src/core/page-session.js

@@ -65,7 +65,7 @@ export function createPageSessionFactory(options = {}) {
     /**
      * Handle navigation - deactivate session if URL no longer matches
      */
-    function handleUrlChange({ previousUrl, newUrl }) {
+    function handleUrlChange({ newUrl }) {
       if (!isActive) {
         return;
       }
@@ -115,7 +115,7 @@ export function createPageSessionFactory(options = {}) {
       for (const { target, event, handler } of eventListeners) {
         try {
           target.off(event, handler);
-        } catch (e) {
+        } catch {
           // Ignore removal errors
         }
       }
@@ -166,7 +166,7 @@ export function createPageSessionFactory(options = {}) {
         log.debug(() => `⏭️  Skipping action - session "${name}" is inactive`);
         return null;
       }
-      return fn();
+      return await fn();
     }
 
     /**
@@ -214,7 +214,7 @@ export function createPageSessionFactory(options = {}) {
       if (!networkTracker) {
         return true;
       }
-      return networkTracker.waitForNetworkIdle(opts);
+      return await networkTracker.waitForNetworkIdle(opts);
     }
 
     /**
@@ -224,7 +224,7 @@ export function createPageSessionFactory(options = {}) {
       if (!isActive) {
         return false;
       }
-      return navigationManager.waitForPageReady(opts);
+      return await navigationManager.waitForPageReady(opts);
     }
 
     /**

package/src/core/page-trigger-manager.js

@@ -310,7 +310,7 @@ export function createPageTriggerManager(options = {}) {
    * @param {string} url - URL to start action for
    * @param {Object} commander - BrowserCommander instance
    */
-  async function startAction(url, commander) {
+  function startAction(url, commander) {
     // Create context for condition checking
     const conditionCtx = {
       url,
@@ -321,7 +321,7 @@ export function createPageTriggerManager(options = {}) {
     const matchingTrigger = findMatchingTrigger(conditionCtx);
     if (!matchingTrigger) {
       log.debug(() => `📋 No trigger registered for: ${url}`);
-      return;
+      return Promise.resolve();
     }
 
     log.debug(() => `🚀 Starting action "${matchingTrigger.name}" for: ${url}`);
@@ -369,6 +369,8 @@ export function createPageTriggerManager(options = {}) {
         }
       }
     })();
+
+    return Promise.resolve();
   }
 
   /**

package/src/elements/selectors.js

@@ -92,16 +92,16 @@ export async function findByText(options = {}) {
   if (engine === 'playwright') {
     // Playwright supports :has-text() natively
     const textSelector = exact ? `:text-is("${text}")` : `:has-text("${text}")`;
-    return `${selector}${textSelector}`;
+    return await Promise.resolve(`${selector}${textSelector}`);
   } else {
     // For Puppeteer, we need to use XPath or evaluate
     // Return a special selector marker that will be handled by other methods
-    return {
+    return await Promise.resolve({
       _isPuppeteerTextSelector: true,
       baseSelector: selector,
       text,
       exact,
-    };
+    });
   }
 }
 

package/src/high-level/universal-logic.js

@@ -25,7 +25,6 @@ export async function waitForUrlCondition(options = {}) {
   const {
     getUrl,
     wait,
-    evaluate,
     targetUrl,
     description,
     customCheck,

package/src/interactions/click.js

@@ -257,7 +257,7 @@ export async function clickElement(options = {}) {
  * @param {Function} options.log - Logger instance
  * @returns {Promise<{navigated: boolean, newUrl: string}>}
  */
-async function detectNavigation(options = {}) {
+function detectNavigation(options = {}) {
   const { page, navigationManager, startUrl, log } = options;
 
   const currentUrl = page.url();

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

@@ -0,0 +1,53 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+
+import {
+  buildPlaywrightLaunchOptions,
+  buildPuppeteerLaunchOptions,
+} from '../../../src/browser/launch-options.js';
+
+describe('browser launch options', () => {
+  it('forwards channel and executablePath to Playwright', () => {
+    const options = buildPlaywrightLaunchOptions({
+      headless: true,
+      slowMo: 25,
+      chromeArgs: ['--custom'],
+      channel: 'chrome-beta',
+      executablePath: '/opt/google/chrome-beta',
+    });
+
+    assert.equal(options.channel, 'chrome-beta');
+    assert.equal(options.executablePath, '/opt/google/chrome-beta');
+  });
+
+  it('forwards channel and executablePath to Puppeteer', () => {
+    const options = buildPuppeteerLaunchOptions({
+      headless: true,
+      chromeArgs: ['--custom'],
+      userDataDir: '/tmp/browser-commander-test',
+      channel: 'chrome',
+      executablePath: '/usr/bin/google-chrome',
+    });
+
+    assert.equal(options.channel, 'chrome');
+    assert.equal(options.executablePath, '/usr/bin/google-chrome');
+  });
+
+  it('omits browser selection options by default', () => {
+    const playwright = buildPlaywrightLaunchOptions({
+      headless: false,
+      slowMo: 150,
+      chromeArgs: [],
+    });
+    const puppeteer = buildPuppeteerLaunchOptions({
+      headless: false,
+      chromeArgs: [],
+      userDataDir: '/tmp/browser-commander-test',
+    });
+
+    assert.equal('channel' in playwright, false);
+    assert.equal('executablePath' in playwright, false);
+    assert.equal('channel' in puppeteer, false);
+    assert.equal('executablePath' in puppeteer, false);
+  });
+});

package/tests/unit/scripts/npm-release-helpers.test.js

@@ -0,0 +1,138 @@
+import {
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+
+import { removeDeprecatedAlwaysAuth } from '../../../scripts/clean-npm-config.mjs';
+import {
+  formatRegistryPackagePath,
+  isVersionPublished,
+} from '../../../scripts/npm-registry.mjs';
+import {
+  buildNodeTestArgs,
+  parseTestRunnerArgs,
+  resolveTestFiles,
+} from '../../../scripts/run-tests.mjs';
+
+describe('npm release helpers', () => {
+  describe('removeDeprecatedAlwaysAuth', () => {
+    it('removes always-auth while preserving other config', () => {
+      const dir = mkdtempSync(join(tmpdir(), 'browser-commander-npmrc-'));
+      const npmrc = join(dir, '.npmrc');
+
+      try {
+        writeFileSync(
+          npmrc,
+          [
+            '//registry.npmjs.org/:_authToken=${NODE_AUTH_TOKEN}',
+            'always-auth=true',
+            'registry=https://registry.npmjs.org/',
+            '',
+          ].join('\n')
+        );
+
+        assert.equal(removeDeprecatedAlwaysAuth(npmrc), true);
+        assert.equal(
+          readFileSync(npmrc, 'utf8'),
+          [
+            '//registry.npmjs.org/:_authToken=${NODE_AUTH_TOKEN}',
+            'registry=https://registry.npmjs.org/',
+            '',
+          ].join('\n')
+        );
+      } finally {
+        rmSync(dir, { force: true, recursive: true });
+      }
+    });
+
+    it('returns false when no config path exists', () => {
+      assert.equal(removeDeprecatedAlwaysAuth(''), false);
+    });
+  });
+
+  describe('isVersionPublished', () => {
+    it('returns false for npm registry 404 responses without logging npm errors', async () => {
+      const fetchCalls = [];
+      const fetchFn = async (url) => {
+        fetchCalls.push(url);
+        return {
+          ok: false,
+          status: 404,
+          statusText: 'Not Found',
+        };
+      };
+
+      const published = await isVersionPublished(
+        'browser-commander',
+        '0.9.0',
+        fetchFn
+      );
+
+      assert.equal(published, false);
+      assert.deepEqual(fetchCalls, [
+        'https://registry.npmjs.org/browser-commander/0.9.0',
+      ]);
+    });
+
+    it('handles scoped package names', () => {
+      assert.equal(
+        formatRegistryPackagePath('@scope/package'),
+        '%40scope%2Fpackage'
+      );
+    });
+  });
+});
+
+describe('test runner helper', () => {
+  it('expands test directories into stable explicit test files', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'browser-commander-tests-'));
+
+    try {
+      writeFileSync(join(dir, 'root.test.js'), '');
+      writeFileSync(join(dir, 'ignored.js'), '');
+
+      const nestedDir = join(dir, 'nested');
+      mkdirSync(nestedDir);
+      writeFileSync(join(nestedDir, 'nested.test.js'), '');
+
+      assert.deepEqual(resolveTestFiles([dir], dir), [
+        join('nested', 'nested.test.js'),
+        'root.test.js',
+      ]);
+    } finally {
+      rmSync(dir, { force: true, recursive: true });
+    }
+  });
+
+  it('builds node --test arguments with reporter and coverage options', () => {
+    const options = parseTestRunnerArgs([
+      '--coverage',
+      '--reporter',
+      'spec',
+      '--env',
+      'RUN_E2E=true',
+      'tests/unit',
+    ]);
+
+    assert.deepEqual(options, {
+      coverage: true,
+      env: { RUN_E2E: 'true' },
+      reporter: 'spec',
+      targets: ['tests/unit'],
+    });
+    assert.deepEqual(buildNodeTestArgs(options, ['tests/unit/a.test.js']), [
+      '--test',
+      '--experimental-test-coverage',
+      '--test-reporter',
+      'spec',
+      'tests/unit/a.test.js',
+    ]);
+  });
+});