craftdriver 0.1.0 → 0.2.0

package/docs/cli.md

@@ -0,0 +1,233 @@
+# Command-line interface
+
+`craftdriver` ships with a CLI binary that wraps the library for
+**shell scripts, ad-hoc exploration, and AI agents** (Copilot, Claude
+Code, Cursor, Codex, Gemini CLI, Goose, OpenCode, …).
+
+```bash
+npm install craftdriver
+npx craftdriver --help
+```
+
+The CLI uses the same Browser API as the library, so anything you can
+script in TypeScript you can also drive from `bash` — but the CLI tunes
+defaults for **fast, fail-fast probing** instead of stable test runs.
+
+## Quick start
+
+Two-terminal workflow:
+
+```bash
+# terminal 1 — keep a long-lived browser around
+npx craftdriver daemon start
+
+# terminal 2 — drive it
+npx craftdriver go http://127.0.0.1:8080/login.html
+npx craftdriver fill '#username' alice
+npx craftdriver fill '#password' hunter2
+npx craftdriver click 'button[type=submit]'
+npx craftdriver wait '#result' --state visible
+npx craftdriver text '#result'
+
+npx craftdriver daemon stop
+```
+
+Each call opens a fresh connection to the daemon and exits — but the
+**browser, page, and cookies all persist** between calls. That makes
+the CLI feel like a REPL for the browser.
+
+If you don't want a daemon (sandboxed cloud agents, one-shot scripts),
+pipe a script through `--ephemeral` and the CLI launches a short-lived
+browser for the whole script:
+
+```bash
+printf 'go http://127.0.0.1:8080/login.html
+fill "#username" alice
+fill "#password" hunter2
+click "button[type=submit]"
+text "#result"
+' | npx craftdriver --ephemeral
+```
+
+## Commands
+
+```
+craftdriver go <url>
+craftdriver find <selector> [--all] [--limit N] [--offset M]
+craftdriver click <selector>
+craftdriver fill <selector> <value>
+craftdriver press <key> [selector]
+craftdriver hover <selector>
+
+craftdriver text [selector] [--limit N]
+craftdriver attr <selector> <name>
+craftdriver value <selector>
+craftdriver is visible|enabled|checked <selector>
+
+craftdriver wait <selector> [--state visible|hidden|attached|detached] [--timeout ms]
+craftdriver wait load [--state load|domcontentloaded|networkidle]
+craftdriver exists <selector>          # 0-wait probe; exit 0 if any match
+
+craftdriver pages
+craftdriver snapshot                   # sanitized DOM summary with refs
+craftdriver screenshot [-o file.png] [--full-page] [--selector S]
+craftdriver eval <js>                  # last resort
+craftdriver back | forward | reload | status | quit
+
+craftdriver daemon start|status|stop
+```
+
+Run `craftdriver --help` for the full list.
+
+## Selector syntax
+
+CSS is the default. Switch kind with a `prefix=value` form:
+
+| Prefix          | Maps to                                  | Example                              |
+| --------------- | ---------------------------------------- | ------------------------------------ |
+| _none_, `css=`  | `By.css`                                 | `'.product-list li'`                 |
+| `xpath=`        | `By.xpath`                               | `'xpath=//button[1]'`                |
+| `role=`         | `By.role` (+ `[name=...]` for the name)  | `'role=button[name=Submit]'`         |
+| `text=`         | `By.text` (exact)                        | `'text=Sign In'`                     |
+| `text*=`        | `By.partialText`                         | `'text*=Sign'`                       |
+| `label=`        | `By.labelText`                           | `'label=Email'`                      |
+| `placeholder=`  | `By.placeholder`                         | `'placeholder=name@example.com'`     |
+| `alt=`          | `By.altText`                             | `'alt=Logo'`                         |
+| `title=`        | `By.title`                               | `'title=Help'`                       |
+| `testid=`       | `By.testId`                              | `'testid=login-btn'`                 |
+| `id=`           | `By.id`                                  | `'id=submit'`                        |
+| `name=`         | `By.name`                                | `'name=email'`                       |
+| `ref=`          | snapshot ref (`craftdriver snapshot`)    | `'ref=e5'`                           |
+
+Anything else is treated as a CSS selector, so attribute selectors with
+`=` inside (e.g. `'button[type=submit]'`) work as expected.
+
+## Snapshot — sanitized DOM with refs
+
+`craftdriver snapshot` returns one line per visible interactive element
+on the active page, with a stable ref (`e1`, `e2`, …) that you can
+use as a selector for the next command:
+
+```bash
+$ craftdriver snapshot
+page: Login — http://127.0.0.1:8080/login.html
+e1: heading "Login"
+e2: form "Username Password Sign in" #login-form
+e3: label "Username"
+e4: textbox "Username" #username
+e5: label "Password"
+e6: textbox "Password" #password
+e7: button "Sign in" #submit
+
+$ craftdriver fill ref=e4 alice
+$ craftdriver fill ref=e6 hunter2
+$ craftdriver click ref=e7
+```
+
+Refs are recomputed on every `snapshot` call and invalidated on
+navigation. A stale ref just returns `NO_MATCH` — take a fresh
+snapshot.
+
+Internally `ref=eN` resolves to a CSS attribute selector
+(`[data-craftdriver-ref="eN"]`); auto-waiting works unchanged.
+
+## Output: pretty on a TTY, JSON when piped
+
+- TTY: human-readable text, one line per result for `find` / `pages`.
+- Piped or redirected: `{ "ok": true, "result": … }` per line.
+- Force either with `--json` or `--pretty`.
+
+Errors carry the same machine-readable `code` field as the library, plus
+an optional one-line `hint:`. See [error-codes.md](./error-codes.md).
+
+```bash
+$ npx craftdriver find '#nope'
+error: find: no element matches css selector=#nope
+code:  NO_MATCH
+```
+
+## Exit codes
+
+| Code | Meaning                                                                 |
+| ---- | ----------------------------------------------------------------------- |
+| `0`  | success (or `exists` matched at least one element)                      |
+| `1`  | assertion / timeout / `NO_MATCH` / `exists` matched zero elements       |
+| `2`  | usage error (missing argument, unknown command)                         |
+
+## Fail-fast defaults
+
+The library auto-waits up to **30 s** because tests want stability. The
+CLI lowers that to **5 s** because agents probe with guesses and should
+learn from failures fast.
+
+- Override per call with `--timeout <ms>`.
+- Override globally with `CRAFTDRIVER_AGENT_TIMEOUT=2000`.
+- Use `exists` as a 0-wait probe before `click` / `wait` when you're not
+  sure a selector matches.
+
+## Daemon details
+
+- Socket: `~/.craftdriver/sock` (override with `CRAFTDRIVER_SOCKET`).
+- PID file: `~/.craftdriver/pid` (override with `CRAFTDRIVER_PID`).
+- Wire: line-delimited JSON, one request per connection.
+- First request after `daemon start` triggers the browser launch; later
+  requests reuse the same browser, page and cookies.
+- `craftdriver daemon status` reports PID + active page URL.
+- `craftdriver daemon stop` cleans up the socket and PID file.
+
+The CLI also auto-starts a daemon for you on the first command if none
+is running — `daemon start` is only required when you want to control
+the timing (or to choose a non-default browser):
+
+```bash
+npx craftdriver daemon start --browser firefox
+```
+
+## When to use the CLI vs. the library
+
+- **Library** — write a test suite. Stable, 30 s auto-waits, full TS
+  types, runs under vitest / jest / playwright-test.
+- **CLI** — exploration, debugging, agent-driven loops, REPL-style
+  poking at a real page from your shell.
+
+Both share the same underlying Browser API and the same error codes, so
+findings transfer directly between the two.
+
+## Teach your AI assistant (`craftdriver init`)
+
+For every supported assistant, the CLI can drop an opinionated rules
+file into the **current project** so the assistant picks up
+craftdriver conventions (selector preference, auto-waiting, error
+codes, CLI usage) on every turn:
+
+```bash
+npx craftdriver init copilot   # .github/copilot-instructions.md
+npx craftdriver init claude    # CLAUDE.md
+npx craftdriver init cursor    # .cursor/rules/craftdriver.mdc
+npx craftdriver init gemini    # GEMINI.md
+npx craftdriver init agents    # AGENTS.md (Codex, OpenCode, Aider, Amp, Cursor)
+npx craftdriver init all       # every file above
+```
+
+Files are per-project (commit them to git so the team's agents share
+the rules). Pre-existing files are skipped unless you pass `--force`;
+use `--dry-run` to see what would be written. The body is identical
+across flavors, only the file name and any tool-specific header
+(e.g. Cursor's `.mdc` frontmatter) differ.
+
+## Skill pack
+
+For agents that load skills explicitly (Claude Code's Skills system,
+Copilot agent customization, custom orchestrators), the npm tarball
+ships a tiered skill pack under `skills/craftdriver/`:
+
+| File                                                          | Purpose                                                                  |
+| ------------------------------------------------------------- | ------------------------------------------------------------------------ |
+| [`SKILL.md`](../skills/craftdriver/SKILL.md)                  | Always-on, ≤ 500 tokens. Selector order, error-code-first, auto-wait.   |
+| [`cheatsheet.md`](../skills/craftdriver/cheatsheet.md)        | Command-by-command reference for writing tests.                          |
+| [`patterns.md`](../skills/craftdriver/patterns.md)            | Worked recipes (login, upload, network-wait, a11y, tracing, clock).      |
+| [`cli.md`](../skills/craftdriver/cli.md)                      | Agent-facing CLI reference.                                              |
+
+Point your agent at `node_modules/craftdriver/skills/craftdriver/SKILL.md`
+or copy it into your project. The other files are referenced from
+`SKILL.md` and loaded on demand.

package/docs/clock.md

@@ -0,0 +1,245 @@
+# Virtual Clock
+
+Test idle timeouts, trial expirations, and debounced inputs without `sleep()`.
+
+## Why you need this
+
+Three tests that are impossible — or flaky at best — without clock control:
+
+1. **Auto-logout after 15 minutes idle.** Without clock control you either
+   wait 15 real minutes in CI, or stub `Date` inside the app code (the test no
+   longer reflects production). With it: jump 15 min, assert the login modal.
+
+2. **Trial banner that flips at midnight.** Assert both "expires today" before
+   midnight and "expired" right after, in the same CI run, deterministically.
+
+3. **Debounced search input.** Advance exactly 299 ms (no request), then 2 ms
+   more (exactly one request). No `setTimeout(400)` flake.
+
+---
+
+## Quick-start examples
+
+### 1 — Idle logout after 15 minutes
+
+```ts
+import { Browser } from 'craftdriver';
+
+const browser = await Browser.launch();
+await browser.clock.install({ time: '2026-01-01T09:00:00Z' });
+await browser.navigateTo('http://localhost:3000/dashboard');
+await browser.clock.fastForward('15:01');
+await browser.expect('#login-modal').toBeVisible();
+await browser.quit();
+```
+
+### 2 — Trial banner flipping at midnight
+
+```ts
+import { Browser } from 'craftdriver';
+
+const browser = await Browser.launch();
+
+// Before midnight — banner says "expires today"
+await browser.clock.setFixedTime('2026-06-15T23:59:00Z');
+await browser.navigateTo('http://localhost:3000/billing');
+await browser.expect('#trial-banner').toContainText('expires today');
+
+// After midnight — banner says "expired"
+await browser.clock.setFixedTime('2026-06-16T00:00:01Z');
+await browser.reload();
+await browser.expect('#trial-banner').toContainText('expired');
+
+await browser.quit();
+```
+
+### 3 — Debounced search input
+
+```ts
+import { Browser } from 'craftdriver';
+
+const browser = await Browser.launch();
+await browser.clock.install();
+await browser.navigateTo('http://localhost:3000/search');
+await browser.fill('#q', 'lap');
+
+await browser.clock.tick(299); // debounce hasn't fired yet
+// assert: no /search network request
+
+await browser.clock.tick(2);  // total 301 ms — debounce fires
+// assert: exactly one /search?q=lap request
+
+await browser.quit();
+```
+
+---
+
+## Method reference
+
+| Method | When to use |
+|--------|-------------|
+| `clock.install(opts?)` | Full fake-timer suite: `Date`, `performance.now`, `setTimeout`, `setInterval`, `rAF`. Use when you need `tick()`. |
+| `clock.uninstall()` | Restore real globals and remove the preload script. |
+| `clock.tick(ms)` | Advance virtual time by `ms` milliseconds and fire all due timers. |
+| `clock.fastForward(duration)` | Like `tick()` but also accepts `"MM:SS"` / `"HH:MM:SS"` strings. |
+| `clock.setFixedTime(time)` | Freeze `Date.now()` at a point in time. Does **not** fake timers. |
+| `clock.setSystemTime(time)` | Move the virtual clock to `time` without firing timers. Requires `install()`. |
+| `clock.runFor(ms)` | Like `tick()` but yields between frames so async/microtask callbacks resolve. |
+
+### `clock.install(options?)`
+
+```ts
+await browser.clock.install();
+await browser.clock.install({ time: '2026-01-01T09:00:00Z' });
+await browser.clock.install({ time: 1_735_689_600_000 });   // ms since epoch
+await browser.clock.install({ time: new Date('2026-01-01') });
+```
+
+Installs fake implementations of:
+- `Date` constructor and `Date.now()`
+- `performance.now()`
+- `setTimeout` / `clearTimeout`
+- `setInterval` / `clearInterval`
+- `requestAnimationFrame` / `cancelAnimationFrame`
+
+Timers only fire when you explicitly call `tick()`, `fastForward()`, or
+`runFor()`. Also registers a **preload script** so the fake clock is
+automatically re-installed on every subsequent navigation for the duration of
+the browser session.
+
+**`time`** defaults to the real current time (`Date.now()`) if omitted.
+
+### `clock.uninstall()`
+
+```ts
+await browser.clock.uninstall();
+```
+
+Restores `Date`, `setTimeout`, `setInterval`, and all other faked globals to
+their originals.  Removes the preload script so future navigations use the real
+clock again.
+
+### `clock.tick(ms)`
+
+```ts
+await browser.clock.tick(500);   // advance 500 ms
+await browser.clock.tick(0);     // flush zero-delay timers
+```
+
+Advances the virtual clock by `ms` milliseconds. Every timer whose deadline
+falls within the window is fired in order.  `setInterval` timers reschedule
+themselves automatically.
+
+Requires `install()`.
+
+### `clock.fastForward(duration)`
+
+```ts
+await browser.clock.fastForward(60_000);    // 60 seconds
+await browser.clock.fastForward('15:00');   // 15 minutes
+await browser.clock.fastForward('01:30:00'); // 1 hour 30 minutes
+```
+
+Same as `tick()` but accepts a human-readable duration string.
+
+- **`"MM:SS"`** — minutes and seconds (numbers can exceed 59: `"90:00"` = 90 min)
+- **`"HH:MM:SS"`** — hours, minutes, seconds
+
+Requires `install()`.
+
+### `clock.setFixedTime(time)`
+
+```ts
+await browser.clock.setFixedTime('2026-06-15T23:59:00Z');
+await browser.clock.setFixedTime(1_750_032_540_000);
+await browser.clock.setFixedTime(new Date('2026-06-15T23:59:00Z'));
+```
+
+Freezes `Date.now()` and `new Date()` at the given instant.  Does **not**
+install fake `setTimeout` or `setInterval` — real timers continue to fire.
+
+Use this for simple date-dependent rendering where you don't need to control
+timer execution.
+
+Also registers a preload script so the fixed date persists across navigations.
+
+### `clock.setSystemTime(time)`
+
+```ts
+await browser.clock.install({ time: 0 });
+await browser.clock.setSystemTime(Date.UTC(2026, 5, 16)); // jump to 2026-06-16
+await browser.clock.tick(1000); // continue from here
+```
+
+Moves the virtual clock to `time` without advancing the timer queue or firing
+any callbacks.  Subsequent `tick()` calls continue from the new position.
+
+Requires `install()`.
+
+### `clock.runFor(ms)`
+
+```ts
+await browser.clock.runFor(1000);
+```
+
+Like `tick()` but yields between each ~16 ms frame so that microtask callbacks
+(e.g. `Promise.then()` chained to a timer) resolve in the correct order before
+the next frame is processed.
+
+Requires `install()`.
+
+---
+
+## Accepted time formats
+
+All methods that take a `time` argument accept:
+
+| Type | Example | Notes |
+|------|---------|-------|
+| `number` | `1_750_032_540_000` | Milliseconds since Unix epoch |
+| `string` | `'2026-06-15T23:59:00Z'` | Anything `new Date(string)` accepts |
+| `Date` | `new Date('2026-01-01')` | Used as-is |
+
+`fastForward` additionally accepts a **duration** string (`"MM:SS"` or
+`"HH:MM:SS"`), not an absolute point in time.
+
+---
+
+## Gotchas
+
+### What is and isn't faked
+
+After `install()`:
+
+| Faked ✓ | Not faked ✗ |
+|---------|------------|
+| `Date.now()` | `Date.prototype.toLocaleString` formatting |
+| `new Date()` with no args | `Intl.DateTimeFormat` time zone offsets |
+| `performance.now()` | Real network request timing |
+| `setTimeout` / `clearTimeout` | `Worker` timers |
+| `setInterval` / `clearInterval` | `SharedWorker` / `ServiceWorker` timers |
+| `requestAnimationFrame` | CSS animation timing |
+
+After `setFixedTime()` only `Date.now()`, `new Date()`, and `performance.now()`
+are affected. All timers use real wall time.
+
+### Navigation
+
+Both `install()` and `setFixedTime()` register a BiDi preload script that
+re-applies the fake clock automatically on every navigation.  You don't need to
+call them again after `navigateTo()` or `reload()`.
+
+`uninstall()` removes the preload script.  After uninstalling, future
+navigations use the real clock.
+
+### Interaction with real network requests
+
+Clock control affects only in-page JavaScript.  Real HTTP requests still run at
+wall-clock speed.  If your test asserts on a network response, make sure the
+request is made (i.e. a timer fires and calls `fetch()`) before asserting on the
+response.
+
+### install() is idempotent
+
+Calling `install()` a second time resets the virtual time and the timer queue.
+Any timers registered before the second `install()` are discarded.

package/docs/dialogs.md

@@ -0,0 +1,143 @@
+# Dialogs
+
+JavaScript dialogs (`alert`, `confirm`, `prompt`, `beforeunload`)
+appear as native browser modals — they block the page until the user
+or the automation handles them.
+
+> **craftdriver's stance: dialogs block until handled.**
+> If a dialog opens and nothing handles it, the action that triggered
+> it will time out. This is intentional. Playwright silently
+> auto-dismisses unhandled dialogs; craftdriver promotes them to loud
+> failures so unexpected dialogs surface as broken tests rather than
+> passing tests against a stuck browser.
+
+You handle a dialog one of three ways, depending on the shape of the
+test:
+
+| API                       | When to use                                              |
+| ------------------------- | -------------------------------------------------------- |
+| `browser.waitForDialog()` | One-shot — you know exactly which action triggers it.    |
+| `browser.onDialog(...)`   | Persistent — multiple dialogs in a workflow, or "accept all". |
+| `browser.acceptDialog()` / `browser.dismissDialog()` | You already raced past the dialog and want to handle whatever is open. |
+
+## `waitForDialog(opts?)` — one-shot wait
+
+Returns a `Promise<Dialog>` that resolves the next time a dialog opens.
+Pair it with the triggering action in `Promise.all` so both run
+concurrently:
+
+```typescript
+// confirm()
+const [, dialog] = await Promise.all([
+  browser.click('#confirm-btn'),
+  browser.waitForDialog(),
+]);
+
+console.log(dialog.type());    // 'confirm'
+console.log(dialog.message()); // 'Are you sure?'
+await dialog.accept();         // continue
+
+// prompt() — pass text to fill the input first
+const [, prompt] = await Promise.all([
+  browser.click('#prompt-btn'),
+  browser.waitForDialog(),
+]);
+console.log(prompt.defaultValue()); // pre-filled default
+await prompt.accept('my answer');
+
+// alert()
+const [, alert] = await Promise.all([
+  browser.click('#alert-btn'),
+  browser.waitForDialog(),
+]);
+await alert.dismiss();
+```
+
+`waitForDialog` rejects with a timeout error if no dialog appears
+within `opts.timeout` (default: the browser's default timeout).
+
+## `onDialog(handler)` — persistent handler
+
+Register a handler that fires for **every** dialog until you call the
+returned `off()` function. Use it when a workflow triggers multiple
+dialogs, or when you want a blanket "accept everything" during a noisy
+sequence:
+
+```typescript
+const off = browser.onDialog(async (dialog) => {
+  await dialog.accept();
+});
+
+await runNoisyWorkflow();
+off(); // stop listening — subsequent dialogs are loud again
+```
+
+`onDialog` does not retroactively handle dialogs that opened before
+registration; pair it with `acceptDialog` / `dismissDialog` for those.
+
+## Imperative `acceptDialog` / `dismissDialog`
+
+When you cannot wrap the triggering action in `Promise.all` (e.g.
+multiple actions race the dialog, or you handle a dialog inside a
+catch block), use the imperative API to act on whichever dialog is
+currently open:
+
+```typescript
+await browser.acceptDialog();        // click OK
+await browser.acceptDialog('value'); // fill a prompt, then accept
+await browser.dismissDialog();       // click Cancel / close
+const text = await browser.getDialogMessage();
+```
+
+These map directly onto W3C Classic alert endpoints
+(`/alert/accept`, `/alert/dismiss`, `/alert/text`) and throw if no
+dialog is currently open.
+
+## `Dialog` interface
+
+| Member                       | Description                                                                |
+| ---------------------------- | -------------------------------------------------------------------------- |
+| `dialog.type()`              | `'alert'` \| `'confirm'` \| `'prompt'` \| `'beforeunload'`                 |
+| `dialog.message()`           | Text shown in the dialog.                                                  |
+| `dialog.defaultValue()`      | Pre-filled value for prompts; empty string for other types.                |
+| `await dialog.accept(text?)` | Click OK. For prompts, optionally provide the input text first.            |
+| `await dialog.dismiss()`     | Click Cancel / close.                                                      |
+
+## Recipes
+
+### Accept everything during a flow
+
+```typescript
+const off = browser.onDialog((d) => d.accept());
+try {
+  await runFlow();
+} finally {
+  off();
+}
+```
+
+### Assert on a dialog and dismiss
+
+```typescript
+const [, dialog] = await Promise.all([
+  browser.click('#delete'),
+  browser.waitForDialog(),
+]);
+expect(dialog.type()).toBe('confirm');
+expect(dialog.message()).toContain('cannot be undone');
+await dialog.dismiss();
+```
+
+### `beforeunload` confirmation
+
+`beforeunload` arrives like any other dialog. Accept it to allow the
+navigation, dismiss it to keep the page:
+
+```typescript
+const [, dialog] = await Promise.all([
+  browser.navigateTo('/somewhere-else'),
+  browser.waitForDialog(),
+]);
+expect(dialog.type()).toBe('beforeunload');
+await dialog.accept();
+```

package/docs/driver-configuration.md

@@ -0,0 +1,64 @@
+# Driver Configuration
+
+Craftdriver resolves the WebDriver binary through a chain — first match wins:
+
+| Step | Source |
+|---|---|
+| 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 |
+
+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.
+
+## Environment variables
+
+| Variable | Description | Default |
+|---|---|---|
+| `CRAFTDRIVER_CHROMEDRIVER_PATH` | Absolute path to a chromedriver binary | — |
+| `CRAFTDRIVER_GECKODRIVER_PATH` | Absolute path to a geckodriver binary | — |
+| `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) |
+
+## Examples
+
+```bash
+# Pin a specific chromedriver
+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)
+CRAFTDRIVER_OFFLINE=1 npm test
+
+# Change the cache location
+CRAFTDRIVER_CACHE_DIR=/tmp/my-driver-cache npm test
+
+# Re-check geckodriver more frequently (every hour instead of 24 h)
+CRAFTDRIVER_DRIVER_TTL=3600 npm test
+```
+
+## Pinning via code
+
+For tighter control (custom port, extra driver flags), pass a `ChromeService`
+or `FirefoxService` directly to `Browser.launch()`:
+
+```typescript
+import { Browser, ChromeService, FirefoxService } from 'craftdriver';
+
+const browser = await Browser.launch({
+  browserName: 'chrome',
+  chromeService: new ChromeService({
+    binaryPath: '/opt/chromedriver/chromedriver',
+    port: 9515,
+    args: ['--log-level=ALL'],
+  }),
+});
+```