A universal browser automation library with a unified API across multiple browser engines and programming languages. The key focus is on stoppable page triggers - ensuring automation logic is properly mounted/unmounted during page navigation.
| Language | Package | Status |
|---|---|---|
| JavaScript/TypeScript | browser-commander |  |
| Rust | browser-commander |  |
| Python | browser-commander |  |
| Language | Primary engines | Notes |
|---|---|---|
| JavaScript/TypeScript | Playwright, Puppeteer | Uses the official Node.js packages directly. |
| Rust | Chromiumoxide, Playwright, Puppeteer | Chromiumoxide is native Rust/CDP. Playwright and Puppeteer run through a Node.js bridge to the official packages. Fantoccini remains available as an engine type for compatibility, but managed launch is not implemented yet. |
| Python | Playwright, Selenium | Uses the official Python integrations and supports attaching to an existing Chrome-family browser over CDP. |
See docs/feature-parity.md for the cross-language feature matrix and docs/case-studies/issue-51/README.md for the implementation notes.
All three implementations can attach to a running Chrome-family browser over
CDP or find and start an installed Chrome, Edge, Brave, or Chromium with a
safe, dedicated automation profile before attaching. Use
launchRealBrowser() in JavaScript and launch_real_browser() in Python or
Rust.
Browser Commander manages the browser as a state machine with two states:
+------------------+ +------------------+
| | navigation start | |
| WORKING STATE | -------------------> | LOADING STATE |
| (action runs) | | (wait only) |
| | <----------------- | |
+------------------+ page ready +------------------+
LOADING STATE: Page is loading. Only waiting/tracking operations are allowed. No automation logic runs.
WORKING STATE: Page is fully loaded (30 seconds of network idle). Page triggers can safely interact with DOM.
The library provides a guarantee when navigation is detected:
- Action is signaled to stop (AbortController.abort())
- Wait for action to finish (up to 10 seconds for graceful cleanup)
- Only then start waiting for page load
This ensures:
- No DOM operations on stale/loading pages
- Actions can do proper cleanup (clear intervals, save state)
- No race conditions between action and navigation
For installation and usage instructions, see the documentation for your preferred language:
- JavaScript/TypeScript: See js/README.md
- Rust: See rust/README.md
- Python: See python/README.md
The JavaScript package now exposes browser-commander/tests, a
test-anywhere-based browser test layer with Playwright/Puppeteer engine
matrices, fixture cleanup, retries, failure artifacts, historical duration
tracking, longest-first ordering, and balanced shard planning. See
js/README.md#browser-commander-tests and
js/examples/browser-commander-tests.example.js.
See js/src/ARCHITECTURE.md for detailed architecture documentation.
The Documentation workflow builds JavaScript JSDoc output and Rust cargo doc output into one artifact. On main, the same artifact is published with GitHub Pages when Pages is enabled for the repository.
Local commands:
cd js && npm run docs:api
cd rust && cargo doc --no-deps --all-features