browser-commander 0.8.1 → 0.9.1

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.9.1
+
+### Patch Changes
+
+- cbd4fe1: Remove CI warning noise from workflow actions, release logging, and lint output.
+
+## 0.9.0
+
+### Minor Changes
+
+- 21c63ac: Add the `browser-commander/tests` export with `test-anywhere`-based browser
+  test helpers for Playwright and Puppeteer, duration-aware ordering, balanced
+  shard planning, retries, timeouts, and failure artifacts.
+
 ## 0.8.1
 
 ### Patch Changes

package/README.md

@@ -87,6 +87,53 @@ await commander.destroy();
 await browser.close();
 ```
 
+## Browser Commander Tests
+
+`browser-commander/tests` adds browser fixtures and scheduling helpers on top of
+[`test-anywhere`](https://github.com/link-foundation/test-anywhere). It keeps
+tests portable across Node.js, Bun, and Deno while running the same browser
+scenario against Playwright and Puppeteer.
+
+```javascript
+import { assert, browserTest } from 'browser-commander/tests';
+
+browserTest(
+  'loads example.com',
+  async ({ commander, engine }) => {
+    await commander.goto({
+      url: 'https://example.com',
+      waitForNetworkIdle: false,
+    });
+
+    const heading = await commander.textContent({ selector: 'h1' });
+    assert.ok(heading.includes('Example Domain'), `${engine} should work`);
+  },
+  {
+    engines: ['playwright', 'puppeteer'],
+    launchOptions: { headless: true },
+    retries: 1,
+    timeoutMs: 60000,
+  }
+);
+```
+
+The test helpers provide:
+
+- `browserTest()` and `defineBrowserTests()` for Playwright/Puppeteer matrices.
+- Automatic fixture cleanup with `commander.destroy()` and `browser.close()`.
+- `retries`, per-test `timeoutMs`, and failure artifacts under
+  `test-results/browser-commander` by default.
+- Historical duration tracking in `tests/.browser-commander-test-timings.json`
+  when a `tests` directory exists.
+- Longest-first ordering and balanced shard planning. Set
+  `BROWSER_COMMANDER_TEST_SHARD=1/3` to select a shard.
+- Re-exported `test-anywhere` APIs such as `test`, `describe`, `it`, `assert`,
+  `expect`, and lifecycle hooks.
+
+See
+[`examples/browser-commander-tests.example.js`](examples/browser-commander-tests.example.js)
+for a runnable example.
+
 ## URL Condition Helpers
 
 The `makeUrlCondition` helper makes it easy to create URL matching conditions:

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/examples/browser-commander-tests.example.js

@@ -0,0 +1,30 @@
+import { assert, browserTest } from '../src/tests/index.js';
+
+const engines = process.env.BROWSER_COMMANDER_TEST_ENGINE
+  ? process.env.BROWSER_COMMANDER_TEST_ENGINE.split(',')
+  : undefined;
+
+browserTest(
+  'loads example.com',
+  async ({ commander, engine, testInfo }) => {
+    await commander.goto({
+      url: process.env.TEST_URL || 'https://example.com',
+      waitForNetworkIdle: false,
+    });
+
+    const heading = await commander.textContent({ selector: 'h1' });
+    assert.ok(
+      heading.includes('Example Domain'),
+      `${testInfo.name} should read the heading with ${engine}`
+    );
+  },
+  {
+    engines,
+    launchOptions: {
+      headless: process.env.HEADLESS !== 'false',
+    },
+    retries: process.env.CI ? 1 : 0,
+    timeoutMs: 60000,
+    artifactsDir: 'test-results/browser-commander-example',
+  }
+);

package/package.json

@@ -1,19 +1,20 @@
 {
   "name": "browser-commander",
-  "version": "0.8.1",
+  "version": "0.9.1",
   "description": "Universal browser automation library that supports both Playwright and Puppeteer with a unified API",
   "main": "src/index.js",
   "type": "module",
   "exports": {
-    ".": "./src/index.js"
+    ".": "./src/index.js",
+    "./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",
@@ -62,7 +63,8 @@
     }
   },
   "dependencies": {
-    "log-lazy": "^1.0.4"
+    "log-lazy": "^1.0.4",
+    "test-anywhere": "^0.9.1"
   },
   "devDependencies": {
     "@changesets/cli": "^2.29.7",

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/bindings.js

@@ -283,7 +283,9 @@ export function createBoundFunctions(options = {}) {
     // Main API functions
     wait: waitBound,
     emulateMedia: emulateMediaBound,
+    fill: fillTextAreaWrapped,
     fillTextArea: fillTextAreaWrapped,
+    click: clickButtonWrapped,
     clickButton: clickButtonWrapped,
     evaluate: evaluateBound,
     safeEvaluate: safeEvaluateBound,

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');