craftdriver 0.2.2 → 1.0.1

package/docs/driver-configuration.md

@@ -7,13 +7,25 @@ Craftdriver resolves the WebDriver binary through a chain — first match wins:
 | 1 | `driverPath` option in `Browser.launch()` |
 | 2 | `CRAFTDRIVER_CHROMEDRIVER_PATH` / `CRAFTDRIVER_GECKODRIVER_PATH` env var |
 | 3 | `CRAFTDRIVER_DRIVER_PATH` env var (generic fallback for either browser) |
-| 4 | `chromedriver` / `geckodriver` in `node_modules/.bin` |
-| 5 | `chromedriver` / `geckodriver` on `PATH` |
-| 6 | **Auto-download from Chrome for Testing / GitHub** ← the zero-config default |
+| 4 | Legacy/Selenium-compatible env vars: `CHROMEDRIVER_PATH`, `SE_CHROMEDRIVER` (chromedriver) or `GECKODRIVER_PATH`, `GECKODRIVER_FILEPATH`, `SE_GECKODRIVER` (geckodriver) |
+| 5 | **Cached auto-resolution** — the path a previous auto-resolve settled on, reused within the `CRAFTDRIVER_DRIVER_TTL` window |
+| 6 | `chromedriver` / `geckodriver` in `node_modules/.bin` |
+| 7 | `chromedriver` / `geckodriver` on `PATH` |
+| 8 | **Auto-download from Chrome for Testing / GitHub** ← the zero-config default |
 
-Downloaded drivers are cached in `~/.cache/craftdriver` and reused as long as
-your browser version doesn't change. Only the driver binary is downloaded,
-never the browser itself.
+Downloaded drivers are cached in `~/.cache/craftdriver`, and so is the
+*resolution itself* — which driver path to use. Within the
+`CRAFTDRIVER_DRIVER_TTL` window (default 24 h), craftdriver reuses the
+resolved path directly and skips the system-browser probes it would
+otherwise run on **every** launch: launching the browser binary just to read
+its version string, and a `PATH` lookup. Both are blocking calls, so caching
+the resolution measurably speeds up launch — most noticeably when several
+browsers start in parallel (see [Performance](#performance)). After the TTL
+expires, or if Chrome reports that the cached chromedriver is for the wrong
+major version after a browser upgrade, the driver is re-resolved and
+re-downloaded if needed. Only the driver binary is ever downloaded, never the
+browser itself. Explicit configuration (steps 1–4) always takes precedence over
+the cache.
 
 ## Environment variables
 
@@ -24,7 +36,7 @@ never the browser itself.
 | `CRAFTDRIVER_DRIVER_PATH` | Generic fallback path (either browser) | — |
 | `CRAFTDRIVER_CACHE_DIR` | Directory for cached driver downloads | `~/.cache/craftdriver` |
 | `CRAFTDRIVER_OFFLINE` | Set to `1` to disable all network calls | — |
-| `CRAFTDRIVER_DRIVER_TTL` | Geckodriver freshness check interval (seconds) | `86400` (24 h) |
+| `CRAFTDRIVER_DRIVER_TTL` | Driver-resolution cache lifetime, in seconds (both browsers). `0` disables the cache | `86400` (24 h) |
 
 ## Examples
 
@@ -35,7 +47,7 @@ CRAFTDRIVER_CHROMEDRIVER_PATH=/usr/bin/chromedriver npm test
 # Pin a specific geckodriver
 CRAFTDRIVER_GECKODRIVER_PATH=/usr/local/bin/geckodriver npm test
 
-# Never make a network call (requires a local driver to exist in steps 1–5)
+# Never make a network call (requires a local driver to exist in steps 1–7)
 CRAFTDRIVER_OFFLINE=1 npm test
 
 # Change the cache location
@@ -45,6 +57,112 @@ CRAFTDRIVER_CACHE_DIR=/tmp/my-driver-cache npm test
 CRAFTDRIVER_DRIVER_TTL=3600 npm test
 ```
 
+## Performance
+
+Most of the time `Browser.launch()` spends is the browser process starting up
+(that's the same for WebDriver Classic and BiDi and there's little a client
+library can do about it). The part craftdriver *does* control is resolving and
+starting the driver, and it's tuned to stay out of the way:
+
+- **Driver resolution is cached** (see above). Without a cache, resolving a
+  chromedriver means launching your Chrome binary just to read its version
+  string — a blocking call of a few hundred milliseconds on *every* launch.
+  The TTL cache skips that after the first launch.
+- **Point at a driver explicitly to skip resolution entirely.** If you set
+  `CRAFTDRIVER_CHROMEDRIVER_PATH` / `CRAFTDRIVER_GECKODRIVER_PATH` (or pass
+  `chromeService: new ChromeService({ binaryPath })`), craftdriver uses it
+  directly — no version detection, no `PATH` lookup, no cache read. This is
+  the fastest and most deterministic option and is recommended for CI:
+
+  ```bash
+  CRAFTDRIVER_CHROMEDRIVER_PATH=/opt/chromedriver/chromedriver npm test
+  ```
+
+- **Parallel runs benefit the most.** The resolution work that the cache (or an
+  explicit path) removes was synchronous and blocked the event loop, so it
+  serialized when several browsers were launched at once. Removing it lets
+  concurrent `Browser.launch()` calls overlap their startup (measured ~17–20%
+  faster wall time for a batch of concurrent launches).
+
+### Concurrency and oversubscription
+
+Once resolution is out of the way, the rest of launch time is the browser
+process starting — and that is **CPU-bound**. Starting many browsers at once
+on a machine with fewer CPU cores oversubscribes the CPU, and each browser's
+startup slows down roughly in proportion. On an 8-core machine, for example, a
+single launch is ~2s but 20 simultaneous launches take ~25s *each* (they still
+finish sooner in aggregate than launching serially, just with diminishing
+returns). This is not a craftdriver limitation — it's the browser competing for
+CPU — and no client-side change removes it.
+
+Practical guidance for parallel test suites (e.g. Vitest / Jest / Playwright
+Test): **cap worker concurrency at roughly the number of CPU cores.** More
+workers than cores mostly adds launch latency, and a launch that is merely slow
+under heavy load can trip a short per-test/hook timeout and look like a hang.
+With Vitest, set `maxWorkers` (or `poolOptions`) accordingly; a generous
+`hookTimeout` for the `beforeAll` that launches the browser also helps on
+loaded CI runners.
+
+Indicative numbers from the `tests/perf/launch-critical-path.perf.ts`
+benchmark (macOS, Chrome, headless — absolute values are machine-dependent,
+but the direction holds):
+
+| Scenario | Before | After |
+|---|---|---|
+| `Browser.launch()` (BiDi) | ~2760ms | ~2240ms |
+| `Browser.launch()` (Classic) | ~2400ms | ~1860ms |
+| 4 browsers launched concurrently | ~6450ms | ~5130ms |
+
+Run it yourself with `npm run bench -- launch-critical-path`.
+
+### Browser startup flags (advanced, opt-in)
+
+craftdriver launches the browser with **no performance flags of its own** — it
+stays unopinionated so it never silently changes browser behavior underneath
+you. If you want to experiment, you can pass extra browser command-line flags
+via the `args` launch option (appended to `goog:chromeOptions.args` for
+Chrome/Chromium, `moz:firefoxOptions.args` for Firefox):
+
+```typescript
+const browser = await Browser.launch({
+  browserName: 'chrome',
+  args: [
+    '--no-first-run',
+    '--no-default-browser-check',
+    '--disable-background-networking',
+    '--disable-component-update',
+    '--disable-default-apps',
+    '--disable-extensions',
+    '--disable-sync',
+    '--metrics-recording-only',
+    '--disable-background-timer-throttling',
+    '--disable-backgrounding-occluded-windows',
+    '--disable-renderer-backgrounding',
+    '--mute-audio',
+    '--no-service-autorun',
+    '--password-store=basic',
+    '--use-mock-keychain', // macOS: skip keychain access
+    '--disable-features=Translate,BackForwardCache,AcceptCHFrame,MediaRouter,OptimizationHints',
+  ],
+});
+```
+
+> `args` are **browser** flags. They are distinct from the **driver**
+> (chromedriver/geckodriver) args you'd pass via `chromeService` /
+> `firefoxService` below.
+
+**Set expectations honestly:** on a normal local machine this set moved
+`Browser.launch()` wall time by **~0.4% (≈8ms — noise)** in our measurements.
+Cold browser startup is dominated by unavoidable process/engine init; these
+flags mostly suppress *background* work (auto-updates, telemetry, background
+networking, sync) that happens after startup rather than on the launch critical
+path. So their real value is **determinism and avoiding intermittent stalls in
+CI / constrained environments** (no update popups, no background network
+calls), not raw local launch speed. If you adopt them, **measure on your own
+environment** — the payoff is environment-dependent, and some flags can change
+behavior (e.g. `--no-sandbox`, or `--disable-features=...` entries a page or
+fixture relies on).
+
 ## Pinning via code
 
 For tighter control (custom port, extra driver flags), pass a `ChromeService`

package/docs/emulation.md

@@ -25,12 +25,16 @@ await browser.emulate({
 
 | Option | What the page sees | Transport | Cross-browser |
 |---|---|---|---|
-| `colorScheme` | `prefers-color-scheme` media query | BiDi + CDP `Emulation.setEmulatedMedia` | Chromium only |
-| `reducedMotion` | `prefers-reduced-motion` media query | BiDi + CDP `Emulation.setEmulatedMedia` | Chromium only |
-| `forcedColors` | `forced-colors` media query | BiDi + CDP `Emulation.setEmulatedMedia` | Chromium only |
+| `colorScheme` | `prefers-color-scheme` media query | CDP `Emulation.setEmulatedMedia` (over the BiDi+CDP bridge) | Chromium only |
+| `reducedMotion` | `prefers-reduced-motion` media query | CDP `Emulation.setEmulatedMedia` (over the BiDi+CDP bridge) | Chromium only |
+| `forcedColors` | `forced-colors` media query | CDP `Emulation.setEmulatedMedia` (over the BiDi+CDP bridge) | Chromium only |
 | `locale` | `navigator.language`, `Intl.*` formatting | BiDi `emulation.setLocaleOverride` | yes |
 | `timezoneId` | `Intl.DateTimeFormat`, `Date` offsets | BiDi `emulation.setTimezoneOverride` | yes |
-| `offline` | `navigator.onLine`, network stack | BiDi + CDP `Network.emulateNetworkConditions` | Chromium only |
+| `offline` | `navigator.onLine`, network stack | CDP `Network.emulateNetworkConditions` (over the BiDi+CDP bridge) | Chromium only |
+
+All options still require an active BiDi session (`enableBiDi: true`, the
+default) — the four CDP-backed options ride over a CDP bridge that BiDi
+opens, they don't work with BiDi disabled.
 
 - Pass `null` for any field to clear that override.
 - Calling `emulate({})` is a no-op.

package/docs/error-codes.md

@@ -1,6 +1,6 @@
 # Error codes
 
-Every error thrown from the public craftdriver API is a
+Nearly every error thrown from the public craftdriver API is a
 [`CraftdriverError`](../src/lib/errors.ts), carrying:
 
 - `code` — a stable, machine-readable identifier from the table below.
@@ -12,6 +12,11 @@ Every error thrown from the public craftdriver API is a
 `CraftdriverError extends Error`, so `instanceof Error` keeps working
 and stack traces are preserved.
 
+> A few edge cases still throw a plain `Error` instead — e.g. calling
+> `startTrace()` again while a trace is already running, or without
+> `outDir`. Guard against these with normal usage (don't call `startTrace()`
+> twice without `stopTrace()`) rather than a `code` check.
+
 ```ts
 import { CraftdriverError, ErrorCode } from 'craftdriver';
 
@@ -38,12 +43,12 @@ try {
 | `TIMEOUT` | Generic `WebDriverWait.until(...)` timeout with no more specific code. | Same as above — check the condition. |
 | `EXPECT_MISMATCH` | An `expect(locator).to…()` assertion failed after auto-waiting. | Inspect `error.detail` for the selector and observed value. |
 | `A11Y_VIOLATIONS` | `browser.a11y.check()` (or scoped variants) found axe-core violations. | Iterate over `error.violations` — each has an `id`, `impact`, and `helpUrl`. |
-| `EVAL_THREW` | The function passed to `evaluate()` threw inside the page. | The page-side exception text is in `error.detail.exception`. |
+| `EVAL_THREW` | The function passed to `evaluate()` threw inside the page. Also fires for `browser.clock` methods (`tick()`, `setSystemTime()`, `runFor()`) called before `install()` — they run as in-page scripts under the hood. | The page-side exception text is in `error.detail.exception`. |
 | `EVAL_BAD_ARG` | `evaluate()` / `addInitScript()` received a non-JSON-serializable argument (function, Symbol, DOM node…). | Pass plain JSON values. |
 | `INVALID_ARGUMENT` | Caller passed an invalid value (bad enum, wrong shape, unparseable duration…). | Read the message; it lists the accepted forms. |
 | `UNSUPPORTED` | Feature exists but is unavailable on this browser/transport (e.g. Chromium-only over Firefox, or a BiDi-only feature with BiDi disabled). | Enable BiDi (`enableBiDi: true`) or switch browser. |
-| `STATE_INVALID` | Method called in the wrong state (e.g. `stopTrace()` without `startTrace()`, `clock.tick()` before `install()`). | Call the prerequisite first. |
-| `DRIVER_ERROR` | Driver-level / transport-level failure surfaced to the caller. | Inspect `error.cause`. |
+| `STATE_INVALID` | Method called in the wrong state (e.g. `stopTrace()` without `startTrace()`). | Call the prerequisite first. |
+| `DRIVER_ERROR` | A WebDriver command returned a protocol error (non-200 response) — e.g. `stale element reference`, `element click intercepted`, `invalid selector` — or a transport-level failure. | `error.detail.webDriverError` carries the W3C JSON error code and `error.detail.webDriverMessage` the driver's message; recovery loops match on `webDriverError`. Also inspect `error.cause`. |
 
 ## Stability
 

package/docs/keyboard-mouse.md

@@ -98,22 +98,35 @@ await browser.keyboard.press('Backspace');
 
 ## Mouse
 
-Access the mouse API via `browser.mouse`.
+Access the mouse API via `browser.mouse`. `click()`, `move()`, and
+`dragAndDrop()` all accept a `Target`: a CSS selector string, a `By`
+locator, or `{ x, y }` coordinates.
 
-### click(x, y)
+### click(target, options?)
 
-Click at specific coordinates.
+Click at coordinates or on an element.
 
 ```typescript
-await browser.mouse.click(100, 200);
+await browser.mouse.click({ x: 100, y: 200 });
+await browser.mouse.click('#submit');
+await browser.mouse.click('#submit', { button: 'right', clickCount: 2 });
 ```
 
-### move(x, y)
+### dblclick(target, options?)
 
-Move the mouse to coordinates.
+Double-click at coordinates or on an element (shorthand for `click(target, { clickCount: 2 })`).
 
 ```typescript
-await browser.mouse.move(150, 300);
+await browser.mouse.dblclick('#item');
+```
+
+### move(target, options?)
+
+Move the mouse to coordinates or over an element.
+
+```typescript
+await browser.mouse.move({ x: 150, y: 300 });
+await browser.mouse.move('#target');
 ```
 
 ### down()

package/docs/session-management.md

@@ -213,7 +213,7 @@ async function testLoginPersistence() {
 | `includeCookies`        | `boolean`  | `true`  | Include cookies in saved state |
 | `includeLocalStorage`   | `boolean`  | `true`  | Include localStorage           |
 | `includeSessionStorage` | `boolean`  | `false` | Include sessionStorage         |
-| `origins`               | `string[]` | all     | Limit to specific origins      |
+| `origins`               | `string[]` | all     | Filter localStorage/sessionStorage capture by origin. Capture is always scoped to the page's *current* origin — this only decides whether that one origin is included, it does not collect storage from other origins the page hasn't visited. Cookies are unaffected by this option. |
 
 ### SessionStateManager (browser.storage)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "craftdriver",
-  "version": "0.2.2",
+  "version": "1.0.1",
   "description": "Modern WebDriver automation library for NodeJS",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -17,6 +17,8 @@
     "test:firefox": "BROWSER_NAME=firefox HEADLESS=true vitest run --maxWorkers=2",
     "test:chrome": "BROWSER_NAME=chrome vitest run",
     "test:chromium": "BROWSER_NAME=chromium vitest run",
+    "bench": "HEADLESS=true vitest run --config vitest.perf.config.ts",
+    "bench:realapp": "HEADLESS=true vitest run --config vitest.perf.realapp.config.ts",
     "clean": "rimraf dist",
     "serve": "http-server ./examples -a 127.0.0.1 -p 8080 -c-1 --cors",
     "examples:start": "npm run serve",
@@ -87,6 +89,7 @@
   "overrides": {
     "brace-expansion": "5.0.6",
     "ip-address": "10.1.1",
+    "npm": "^11.18.0",
     "undici": "7.28.0"
   }
 }

package/skills/craftdriver/SKILL.md

@@ -1,7 +1,8 @@
 # craftdriver — SKILL
 
-Modern BiDi-first WebDriver library for Node.js. Playwright ergonomics,
-WebDriver standards-compliance, no AI in the hot path.
+Modern WebDriver library for Node.js — picks the fastest correct protocol
+(Classic or BiDi) per command. Playwright ergonomics, WebDriver
+standards-compliance, no AI in the hot path.
 
 ## Core loop