browser-commander 0.4.0 → 0.5.3

package/CHANGELOG.md

@@ -1,5 +1,58 @@
 # Changelog
 
+## 0.5.3
+
+### Patch Changes
+
+- 8b86dd7: Include README.md in npm package
+
+  Added language-specific README.md files for each implementation:
+  - js/README.md: JavaScript/npm-specific documentation with installation and API usage
+  - rust/README.md: Rust/Cargo-specific documentation
+  - Root README.md: Common overview linking to both implementations
+
+  The npm package now includes the JavaScript-specific README.md directly from the js/ directory.
+
+## 0.5.2
+
+### Patch Changes
+
+- 87224ee: Fix package.json path in version-and-commit.mjs for monorepo structure
+
+  The git show command uses repository root paths, not the workflow's working directory. Since this is a monorepo with js/ and rust/ folders, the path must be js/package.json instead of just package.json.
+
+  This was causing "Unexpected end of JSON input" errors when the script tried to read package.json from the repository root (which doesn't exist) instead of js/package.json.
+
+## 0.5.1
+
+### Patch Changes
+
+- 2b22f43: Fix PlaywrightAdapter.evaluateOnPage() to spread multiple arguments correctly
+
+  When using `evaluateOnPage()` with multiple arguments, the arguments are now properly spread to the function in the browser context, matching Puppeteer's behavior.
+
+  Previously, the function would receive the entire array as its first parameter instead of spread arguments, causing issues like invalid selectors when passing selector + array combinations.
+
+## 0.5.0
+
+### Minor Changes
+
+- adfccde: Add Rust implementation with parallel JavaScript codebase reorganization
+
+  This introduces a complete Rust translation of the browser-commander library alongside the existing JavaScript implementation. The codebase is now organized into two parallel structures:
+  - `js/` - JavaScript implementation (all existing functionality preserved)
+  - `rust/` - New Rust implementation with the same modular architecture
+
+  Key features of the Rust implementation:
+  - Unified API across multiple browser engines (chromiumoxide, fantoccini)
+  - Core types and traits (constants, engine adapter, logger)
+  - Element operations (selectors, visibility, content)
+  - User interactions (click, scroll, fill)
+  - Browser management (launcher, navigation)
+  - General utilities (URL handling, wait operations)
+  - High-level DRY utilities
+  - Comprehensive test coverage with 106 tests
+
 ## 0.4.0
 
 ### Minor Changes

package/README.md

@@ -1,6 +1,6 @@
 # Browser Commander
 
-A universal browser automation library that supports both Playwright and Puppeteer with a unified API. The key focus is on **stoppable page triggers** - ensuring automation logic is properly mounted/unmounted during page navigation.
+A universal browser automation library for JavaScript/TypeScript that supports both Playwright and Puppeteer with a unified API. The key focus is on **stoppable page triggers** - ensuring automation logic is properly mounted/unmounted during page navigation.
 
 ## Installation
 
@@ -332,4 +332,4 @@ See [src/ARCHITECTURE.md](src/ARCHITECTURE.md) for detailed architecture documen
 
 ## License
 
-[UNLICENSE](LICENSE)
+[UNLICENSE](../LICENSE)

package/package.json

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

package/scripts/validate-changeset.mjs

@@ -15,7 +15,10 @@ import { readFileSync, readdirSync, existsSync } from 'fs';
 import { join } from 'path';
 
 const PACKAGE_NAME = 'browser-commander';
+// When running from js/ directory, the changeset dir is local
 const CHANGESET_DIR = '.changeset';
+// But git diff output uses repository-root relative paths
+const GIT_CHANGESET_PATH = 'js/.changeset';
 
 /**
  * Ensure a git commit is available locally, fetching if necessary
@@ -46,13 +49,19 @@ function parseAddedChangesets(diffOutput) {
       continue;
     }
     const [status, filePath] = line.split('\t');
+    // Check both local (.changeset/) and repo-root (js/.changeset/) paths
+    const isChangeset =
+      filePath.startsWith(`${CHANGESET_DIR}/`) ||
+      filePath.startsWith(`${GIT_CHANGESET_PATH}/`);
     if (
       status === 'A' &&
-      filePath.startsWith(`${CHANGESET_DIR}/`) &&
+      isChangeset &&
       filePath.endsWith('.md') &&
       !filePath.endsWith('README.md')
     ) {
-      addedChangesets.push(filePath.replace(`${CHANGESET_DIR}/`, ''));
+      // Extract just the filename
+      const fileName = filePath.split('/').pop();
+      addedChangesets.push(fileName);
     }
   }
   return addedChangesets;

package/scripts/version-and-commit.mjs

@@ -126,7 +126,9 @@ function countChangesets() {
  */
 async function getVersion(source = 'local') {
   if (source === 'remote') {
-    const result = await $`git show origin/main:package.json`.run({
+    // Use js/package.json for monorepo structure
+    // The workflow runs with working-directory: js, but git show uses repo root paths
+    const result = await $`git show origin/main:js/package.json`.run({
       capture: true,
     });
     return JSON.parse(result.stdout).version;

package/src/core/engine-adapter.js

@@ -304,13 +304,25 @@ export class PlaywrightAdapter extends EngineAdapter {
 
   async evaluateOnPage(fn, args = []) {
     // Playwright only accepts a single argument (can be array/object)
+    // To match Puppeteer's behavior where args are spread, we wrap the function
+    // and pass all args as a single array, then apply them in the browser context
     if (args.length === 0) {
       return await this.page.evaluate(fn);
     } else if (args.length === 1) {
       return await this.page.evaluate(fn, args[0]);
     } else {
-      // Multiple args - pass as array
-      return await this.page.evaluate(fn, args);
+      // Multiple args - wrap function to accept array and spread them
+      // This makes Playwright behave like Puppeteer's spread behavior
+      // We pass the function string and args array, then reconstruct and call in browser
+      const fnString = fn.toString();
+      return await this.page.evaluate(
+        ({ fnStr, argsArray }) => {
+          // Reconstruct the function in browser context and call with spread args
+          const reconstructedFn = new Function(`return (${fnStr})`)();
+          return reconstructedFn(...argsArray);
+        },
+        { fnStr: fnString, argsArray: args }
+      );
     }
   }
 

package/tests/helpers/mocks.js

@@ -105,28 +105,15 @@ export function createMockPlaywrightPage(options = {}) {
       return locs.map((l) => l.evaluate(fn, ...args));
     },
     locator: locatorMock,
-    evaluate: async (fn, ...args) => {
+    // Playwright's page.evaluate() only accepts a single argument (not spread)
+    // This is the key difference from Puppeteer
+    evaluate: async (fn, arg) => {
       if (evaluateResult !== null) {
         return evaluateResult;
       }
-      // Create mock window/document context
-      const mockContext = {
-        innerHeight: 800,
-        innerWidth: 1200,
-        sessionStorage: {
-          _data: {},
-          getItem: (key) => mockContext.sessionStorage._data[key] || null,
-          setItem: (key, val) => {
-            mockContext.sessionStorage._data[key] = val;
-          },
-          removeItem: (key) => {
-            delete mockContext.sessionStorage._data[key];
-          },
-        },
-        querySelectorAll: () => [],
-      };
       try {
-        return fn(...args);
+        // Playwright passes exactly one argument (can be object/array)
+        return fn(arg);
       } catch {
         return fn;
       }

package/tests/unit/core/engine-adapter.test.js

@@ -78,6 +78,53 @@ describe('engine-adapter', () => {
       const count = await adapter.count('button');
       assert.strictEqual(count, 5);
     });
+
+    describe('evaluateOnPage', () => {
+      it('should handle zero arguments', async () => {
+        page = createMockPlaywrightPage();
+        adapter = new PlaywrightAdapter(page);
+        const result = await adapter.evaluateOnPage(() => 42);
+        assert.strictEqual(result, 42);
+      });
+
+      it('should handle single argument', async () => {
+        page = createMockPlaywrightPage();
+        adapter = new PlaywrightAdapter(page);
+        const result = await adapter.evaluateOnPage((x) => x * 2, [5]);
+        assert.strictEqual(result, 10);
+      });
+
+      it('should handle multiple arguments by spreading them', async () => {
+        page = createMockPlaywrightPage();
+        adapter = new PlaywrightAdapter(page);
+        // This is the bug case - multiple args should be spread, not passed as array
+        const result = await adapter.evaluateOnPage((a, b) => a + b, [3, 7]);
+        assert.strictEqual(result, 10);
+      });
+
+      it('should handle selector + array arguments (real-world bug case)', async () => {
+        page = createMockPlaywrightPage();
+        adapter = new PlaywrightAdapter(page);
+        // This reproduces the original bug: selector and processedIds
+        const result = await adapter.evaluateOnPage(
+          (selector, processedIds) =>
+            `Selector: ${selector}, Count: ${processedIds.length}`,
+          ['[data-qa="test"]', ['id1', 'id2']]
+        );
+        assert.ok(result.includes('Selector: [data-qa="test"]'));
+        assert.ok(result.includes('Count: 2'));
+      });
+
+      it('should handle multiple arguments of different types', async () => {
+        page = createMockPlaywrightPage();
+        adapter = new PlaywrightAdapter(page);
+        const result = await adapter.evaluateOnPage(
+          (str, num, obj) => `${str}-${num}-${obj.key}`,
+          ['hello', 42, { key: 'world' }]
+        );
+        assert.strictEqual(result, 'hello-42-world');
+      });
+    });
   });
 
   describe('PuppeteerAdapter', () => {
@@ -130,6 +177,42 @@ describe('engine-adapter', () => {
       const count = await adapter.count('button');
       assert.strictEqual(count, 5);
     });
+
+    describe('evaluateOnPage', () => {
+      it('should handle zero arguments', async () => {
+        page = createMockPuppeteerPage();
+        adapter = new PuppeteerAdapter(page);
+        const result = await adapter.evaluateOnPage(() => 42);
+        assert.strictEqual(result, 42);
+      });
+
+      it('should handle single argument', async () => {
+        page = createMockPuppeteerPage();
+        adapter = new PuppeteerAdapter(page);
+        const result = await adapter.evaluateOnPage((x) => x * 2, [5]);
+        assert.strictEqual(result, 10);
+      });
+
+      it('should handle multiple arguments by spreading them', async () => {
+        page = createMockPuppeteerPage();
+        adapter = new PuppeteerAdapter(page);
+        // Puppeteer natively spreads args - ensure same behavior as Playwright fix
+        const result = await adapter.evaluateOnPage((a, b) => a + b, [3, 7]);
+        assert.strictEqual(result, 10);
+      });
+
+      it('should handle selector + array arguments (parity with PlaywrightAdapter)', async () => {
+        page = createMockPuppeteerPage();
+        adapter = new PuppeteerAdapter(page);
+        const result = await adapter.evaluateOnPage(
+          (selector, processedIds) =>
+            `Selector: ${selector}, Count: ${processedIds.length}`,
+          ['[data-qa="test"]', ['id1', 'id2']]
+        );
+        assert.ok(result.includes('Selector: [data-qa="test"]'));
+        assert.ok(result.includes('Count: 2'));
+      });
+    });
   });
 
   describe('createEngineAdapter', () => {

package/.github/workflows/release.yml

@@ -1,296 +0,0 @@
-name: Checks and release
-
-on:
-  push:
-    branches:
-      - main
-  pull_request:
-    types: [opened, synchronize, reopened]
-  # Manual release support - consolidated here to work with npm trusted publishing
-  # npm only allows ONE workflow file as trusted publisher, so all publishing
-  # must go through this workflow (release.yml)
-  workflow_dispatch:
-    inputs:
-      release_mode:
-        description: 'Manual release mode'
-        required: true
-        type: choice
-        default: 'instant'
-        options:
-          - instant
-          - changeset-pr
-      bump_type:
-        description: 'Manual release type'
-        required: true
-        type: choice
-        options:
-          - patch
-          - minor
-          - major
-      description:
-        description: 'Manual release description (optional)'
-        required: false
-        type: string
-
-concurrency: ${{ github.workflow }}-${{ github.ref }}
-
-jobs:
-  # Changeset check - only runs on PRs
-  changeset-check:
-    name: Check for Changesets
-    runs-on: ubuntu-latest
-    if: github.event_name == 'pull_request'
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: '20.x'
-
-      - name: Install dependencies
-        run: npm install
-
-      - name: Check for changesets
-        env:
-          # Pass PR context to the validation script
-          GITHUB_BASE_REF: ${{ github.base_ref }}
-          GITHUB_BASE_SHA: ${{ github.event.pull_request.base.sha }}
-          GITHUB_HEAD_SHA: ${{ github.event.pull_request.head.sha }}
-        run: |
-          # Skip changeset check for automated version PRs
-          if [[ "${{ github.head_ref }}" == "changeset-release/"* ]]; then
-            echo "Skipping changeset check for automated release PR"
-            exit 0
-          fi
-
-          # Run changeset validation script
-          # This validates that exactly ONE changeset was ADDED by this PR
-          # Pre-existing changesets from other merged PRs are ignored
-          node scripts/validate-changeset.mjs
-
-  # Linting and formatting - runs after changeset check on PRs, immediately on main
-  lint:
-    name: Lint and Format Check
-    runs-on: ubuntu-latest
-    needs: [changeset-check]
-    if: always() && (github.event_name == 'push' || needs.changeset-check.result == 'success')
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: '20.x'
-
-      - name: Install dependencies
-        run: npm install
-
-      - name: Run ESLint
-        run: npm run lint
-
-      - name: Check formatting
-        run: npm run format:check
-
-      - name: Check code duplication
-        run: npm run check:duplication
-
-  # Test job - runs on Node.js only (browser automation requires specific setup)
-  test:
-    name: Test (Node.js on ${{ matrix.os }})
-    runs-on: ${{ matrix.os }}
-    needs: [changeset-check]
-    if: always() && (github.event_name == 'push' || needs.changeset-check.result == 'success')
-    strategy:
-      fail-fast: false
-      matrix:
-        os: [ubuntu-latest, macos-latest, windows-latest]
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: '20.x'
-
-      - name: Install dependencies
-        run: npm install
-
-      - name: Run unit tests
-        run: npm test
-
-  # Release - only runs on main after tests pass (for push events)
-  release:
-    name: Release
-    needs: [lint, test]
-    # Use always() to ensure this job runs even if changeset-check was skipped
-    # This is needed because lint/test jobs have a transitive dependency on changeset-check
-    if: always() && github.ref == 'refs/heads/main' && github.event_name == 'push' && needs.lint.result == 'success' && needs.test.result == 'success'
-    runs-on: ubuntu-latest
-    # Permissions required for npm OIDC trusted publishing
-    permissions:
-      contents: write
-      pull-requests: write
-      id-token: write
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: '20.x'
-          registry-url: 'https://registry.npmjs.org'
-
-      - name: Install dependencies
-        run: npm install
-
-      - name: Update npm for OIDC trusted publishing
-        run: node scripts/setup-npm.mjs
-
-      - name: Check for changesets
-        id: check_changesets
-        run: |
-          # Count changeset files (excluding README.md and config.json)
-          CHANGESET_COUNT=$(find .changeset -name "*.md" ! -name "README.md" | wc -l)
-          echo "Found $CHANGESET_COUNT changeset file(s)"
-          echo "has_changesets=$([[ $CHANGESET_COUNT -gt 0 ]] && echo 'true' || echo 'false')" >> $GITHUB_OUTPUT
-          echo "changeset_count=$CHANGESET_COUNT" >> $GITHUB_OUTPUT
-
-      - name: Merge multiple changesets
-        if: steps.check_changesets.outputs.has_changesets == 'true' && steps.check_changesets.outputs.changeset_count > 1
-        run: |
-          echo "Multiple changesets detected, merging..."
-          node scripts/merge-changesets.mjs
-
-      - name: Version packages and commit to main
-        if: steps.check_changesets.outputs.has_changesets == 'true'
-        id: version
-        run: node scripts/version-and-commit.mjs --mode changeset
-
-      - name: Publish to npm
-        # Run if version was committed OR if a previous attempt already committed (for re-runs)
-        if: steps.version.outputs.version_committed == 'true' || steps.version.outputs.already_released == 'true'
-        id: publish
-        run: node scripts/publish-to-npm.mjs --should-pull
-
-      - name: Create GitHub Release
-        if: steps.publish.outputs.published == 'true'
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: node scripts/create-github-release.mjs --release-version "${{ steps.publish.outputs.published_version }}" --repository "${{ github.repository }}"
-
-      - name: Format GitHub release notes
-        if: steps.publish.outputs.published == 'true'
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: node scripts/format-github-release.mjs --release-version "${{ steps.publish.outputs.published_version }}" --repository "${{ github.repository }}" --commit-sha "${{ github.sha }}"
-
-  # Manual Instant Release - triggered via workflow_dispatch with instant mode
-  # This job is in release.yml because npm trusted publishing
-  # only allows one workflow file to be registered as a trusted publisher
-  instant-release:
-    name: Instant Release
-    if: github.event_name == 'workflow_dispatch' && github.event.inputs.release_mode == 'instant'
-    runs-on: ubuntu-latest
-    # Permissions required for npm OIDC trusted publishing
-    permissions:
-      contents: write
-      pull-requests: write
-      id-token: write
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: '20.x'
-          registry-url: 'https://registry.npmjs.org'
-
-      - name: Install dependencies
-        run: npm install
-
-      - name: Update npm for OIDC trusted publishing
-        run: node scripts/setup-npm.mjs
-
-      - name: Version packages and commit to main
-        id: version
-        run: node scripts/version-and-commit.mjs --mode instant --bump-type "${{ github.event.inputs.bump_type }}" --description "${{ github.event.inputs.description }}"
-
-      - name: Publish to npm
-        # Run if version was committed OR if a previous attempt already committed (for re-runs)
-        if: steps.version.outputs.version_committed == 'true' || steps.version.outputs.already_released == 'true'
-        id: publish
-        run: node scripts/publish-to-npm.mjs
-
-      - name: Create GitHub Release
-        if: steps.publish.outputs.published == 'true'
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: node scripts/create-github-release.mjs --release-version "${{ steps.publish.outputs.published_version }}" --repository "${{ github.repository }}"
-
-      - name: Format GitHub release notes
-        if: steps.publish.outputs.published == 'true'
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: node scripts/format-github-release.mjs --release-version "${{ steps.publish.outputs.published_version }}" --repository "${{ github.repository }}" --commit-sha "${{ github.sha }}"
-
-  # Manual Changeset PR - creates a pull request with the changeset for review
-  changeset-pr:
-    name: Create Changeset PR
-    if: github.event_name == 'workflow_dispatch' && github.event.inputs.release_mode == 'changeset-pr'
-    runs-on: ubuntu-latest
-    permissions:
-      contents: write
-      pull-requests: write
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: '20.x'
-
-      - name: Install dependencies
-        run: npm install
-
-      - name: Create changeset file
-        run: node scripts/create-manual-changeset.mjs --bump-type "${{ github.event.inputs.bump_type }}" --description "${{ github.event.inputs.description }}"
-
-      - name: Format changeset with Prettier
-        run: |
-          # Run Prettier on the changeset file to ensure it matches project style
-          npx prettier --write ".changeset/*.md" || true
-
-          echo "Formatted changeset files"
-
-      - name: Create Pull Request
-        uses: peter-evans/create-pull-request@v7
-        with:
-          token: ${{ secrets.GITHUB_TOKEN }}
-          commit-message: 'chore: add changeset for manual ${{ github.event.inputs.bump_type }} release'
-          branch: changeset-manual-release-${{ github.run_id }}
-          delete-branch: true
-          title: 'chore: manual ${{ github.event.inputs.bump_type }} release'
-          body: |
-            ## Manual Release Request
-
-            This PR was created by a manual workflow trigger to prepare a **${{ github.event.inputs.bump_type }}** release.
-
-            ### Release Details
-            - **Type:** ${{ github.event.inputs.bump_type }}
-            - **Description:** ${{ github.event.inputs.description || 'Manual release' }}
-            - **Triggered by:** @${{ github.actor }}
-
-            ### Next Steps
-            1. Review the changeset in this PR
-            2. Merge this PR to main
-            3. The automated release workflow will create a version PR
-            4. Merge the version PR to publish to npm and create a GitHub release

package/LICENSE

@@ -1,24 +0,0 @@
-This is free and unencumbered software released into the public domain.
-
-Anyone is free to copy, modify, publish, use, compile, sell, or
-distribute this software, either in source code form or as a compiled
-binary, for any purpose, commercial or non-commercial, and by any
-means.
-
-In jurisdictions that recognize copyright laws, the author or authors
-of this software dedicate any and all copyright interest in the
-software to the public domain. We make this dedication for the benefit
-of the public at large and to the detriment of our heirs and
-successors. We intend this dedication to be an overt act of
-relinquishment in perpetuity of all present and future rights to this
-software under copyright law.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
-EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
-IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
-OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
-ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
-OTHER DEALINGS IN THE SOFTWARE.
-
-For more information, please refer to <https://unlicense.org>