browser-commander 0.8.0 → 0.9.0

package/.prettierignore

@@ -1,6 +1,7 @@
 node_modules
 coverage
 dist
+docs-api
 *.min.js
 package-lock.json
 .eslintcache

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 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
+
+- ffc59e6: Add generated JSDoc API documentation support for the JavaScript package.
+
 ## 0.8.0
 
 ### Minor Changes

package/README.md

@@ -18,6 +18,16 @@ npm install playwright
 npm install puppeteer
 ```
 
+## Documentation
+
+Generate the JavaScript API reference locally with:
+
+```bash
+npm run docs:api
+```
+
+The repository Documentation workflow also combines this JSDoc output with Rust `cargo doc` output for GitHub Pages publishing from `main`.
+
 ## Core Concept: Page State Machine
 
 Browser Commander manages the browser as a state machine with two states:
@@ -77,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:
@@ -290,6 +347,24 @@ await commander.fillTextArea({
 });
 ```
 
+### Keyboard Interactions
+
+```javascript
+import { pressKey, typeText, keyDown, keyUp } from 'browser-commander';
+
+// Press a single key
+await pressKey({ page, engine: 'playwright', key: 'Escape' });
+await pressKey({ page, engine: 'playwright', key: 'Enter' });
+await pressKey({ page, engine: 'playwright', key: 'Tab' });
+
+// Type text
+await typeText({ page, engine: 'playwright', text: 'Hello World' });
+
+// Hold and release modifier keys
+await keyDown({ page, engine: 'playwright', key: 'Control' });
+await keyUp({ page, engine: 'playwright', key: 'Control' });
+```
+
 ### commander.destroy()
 
 ```javascript

package/eslint.config.js

@@ -118,6 +118,7 @@ export default [
       'node_modules/**',
       'coverage/**',
       'dist/**',
+      'docs-api/**',
       '*.min.js',
       '.eslintcache',
     ],

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/jsdoc.json

@@ -0,0 +1,11 @@
+{
+  "source": {
+    "include": ["src"],
+    "includePattern": ".+\\.js$"
+  },
+  "opts": {
+    "destination": "docs-api",
+    "readme": "README.md",
+    "recurse": true
+  }
+}

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "browser-commander",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "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/",
@@ -19,6 +20,7 @@
     "lint:fix": "eslint . --fix",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
+    "docs:api": "jsdoc -c jsdoc.json",
     "check:duplication": "jscpd .",
     "check": "npm run lint && npm run format:check && npm run check:duplication",
     "prepare": "husky || true",
@@ -61,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",
@@ -69,6 +72,7 @@
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-prettier": "^5.5.4",
     "husky": "^9.1.7",
+    "jsdoc": "^4.0.4",
     "jscpd": "^4.0.5",
     "lint-staged": "^16.2.6",
     "playwright": "^1.56.1",

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

@@ -220,7 +220,7 @@ export async function waitForUrlStabilization(options = {}) {
  * @param {boolean} options.verify - Whether to verify the navigation (default: true)
  * @param {Function} options.verifyFn - Custom verification function (optional)
  * @param {number} options.verificationTimeout - Verification timeout in ms (default: TIMING.VERIFICATION_TIMEOUT)
- * @returns {Promise<{navigated: boolean, verified: boolean, actualUrl?: string, reason?: string}>}
+ * @returns {Promise<Object>} Navigation result.
  */
 export async function goto(options = {}) {
   const {

package/src/index.js

@@ -11,7 +11,10 @@
  */
 
 // Export the factory function
-export { makeBrowserCommander } from './factory.js';
+export {
+  makeBrowserCommander,
+  makeBrowserCommander as createCommander,
+} from './factory.js';
 
 // Re-export all public APIs from exports module
 export * from './exports.js';

package/src/interactions/click.js

@@ -173,7 +173,7 @@ export async function verifyClick(options = {}) {
  * @param {boolean} options.verify - Whether to verify the click operation (default: true)
  * @param {Function} options.verifyFn - Custom verification function (optional)
  * @param {Object} options.adapter - Engine adapter (optional, will be created if not provided)
- * @returns {Promise<{clicked: boolean, verified: boolean, reason?: string}>}
+ * @returns {Promise<Object>} Click result.
  */
 export async function clickElement(options = {}) {
   const {
@@ -352,7 +352,7 @@ async function prepareElement(options = {}) {
  * @param {boolean} options.noAutoScroll - Prevent Playwright's automatic scrolling
  * @param {boolean} options.verify - Whether to verify the click operation
  * @param {Function} options.verifyFn - Custom verification function (optional)
- * @returns {Promise<{clicked: boolean, verified: boolean, reason?: string, navigated: boolean}>}
+ * @returns {Promise<Object>} Click result.
  */
 async function executeClick(options = {}) {
   const {
@@ -567,7 +567,7 @@ async function handleNavigationAfterClick(options = {}) {
  * @param {number} options.timeout - Timeout in ms (default: TIMING.DEFAULT_TIMEOUT)
  * @param {boolean} options.verify - Whether to verify the click operation (default: true)
  * @param {Function} options.verifyFn - Custom verification function (optional)
- * @returns {Promise<{clicked: boolean, navigated: boolean, verified: boolean, reason?: string}>}
+ * @returns {Promise<Object>} Click result.
  *   - clicked: true if click was performed
  *   - navigated: true if click caused navigation
  *   - verified: true if click was verified (navigation counts as verification)

package/src/interactions/fill.js

@@ -146,7 +146,7 @@ export async function checkIfElementEmpty(options = {}) {
  * @param {number} options.verificationTimeout - Verification timeout in ms (default: TIMING.VERIFICATION_TIMEOUT)
  * @param {Function} options.log - Logger instance (optional)
  * @param {Object} options.adapter - Engine adapter (optional, will be created if not provided)
- * @returns {Promise<{filled: boolean, verified: boolean, actualValue?: string}>}
+ * @returns {Promise<Object>} Fill result.
  */
 export async function performFill(options = {}) {
   const {
@@ -240,7 +240,7 @@ export async function performFill(options = {}) {
  * @param {boolean} options.verify - Whether to verify the fill operation (default: true)
  * @param {Function} options.verifyFn - Custom verification function (optional, uses defaultFillVerification if not provided)
  * @param {number} options.verificationTimeout - Verification timeout in ms (default: TIMING.VERIFICATION_TIMEOUT)
- * @returns {Promise<{filled: boolean, verified: boolean, skipped: boolean, actualValue?: string}>}
+ * @returns {Promise<Object>} Fill result.
  *   - filled: true if fill operation was attempted
  *   - verified: true if fill was verified successfully (only meaningful if filled is true)
  *   - skipped: true if element already had content and checkEmpty was true