craftdriver 0.1.0 → 0.2.0

package/docs/session-management.md

@@ -0,0 +1,229 @@
+# Session Management
+
+Craftdriver supports Playwright-style session persistence, allowing you to save and restore browser state including cookies and localStorage. This is perfect for:
+
+- **Skipping login in tests** - Log in once, reuse session across test runs
+- **Sharing auth state** - Generate auth state in setup, use in parallel tests
+- **Debugging** - Capture session state at any point
+
+## Saving Session State
+
+```typescript
+// Save all cookies and localStorage to a file
+await browser.saveState('./session.json');
+
+// Save with options
+await browser.saveState('./session.json', {
+  includeCookies: true, // default: true
+  includeLocalStorage: true, // default: true
+  includeSessionStorage: false, // default: false
+});
+```
+
+The saved file contains:
+
+```json
+{
+  "cookies": [
+    {
+      "name": "session",
+      "value": "abc123",
+      "domain": "example.com",
+      "path": "/",
+      "secure": true,
+      "httpOnly": true,
+      "sameSite": "lax"
+    }
+  ],
+  "localStorage": {
+    "https://example.com": {
+      "theme": "dark",
+      "userId": "12345"
+    }
+  }
+}
+```
+
+## Loading Session State
+
+```typescript
+// Load state into current browser
+await browser.loadState('./session.json');
+```
+
+## Launching with Pre-loaded State
+
+The most common pattern - launch a browser with existing session:
+
+```typescript
+const browser = await Browser.launch({
+  browserName: 'chrome',
+  storageState: './session.json',
+});
+
+// Navigate directly to authenticated page
+await browser.navigateTo('https://example.com/dashboard');
+// Already logged in!
+```
+
+## Cookie Management API
+
+Direct cookie manipulation is also available:
+
+```typescript
+// Add a cookie
+await browser.storage.addCookie({
+  name: 'session',
+  value: 'abc123',
+  domain: 'localhost',
+  path: '/',
+  secure: false,
+  httpOnly: true,
+  sameSite: 'Lax',
+  expiry: new Date('2025-12-31'), // or Unix timestamp
+});
+
+// Get all cookies
+const cookies = await browser.storage.getCookies();
+
+// Get cookies for specific domain
+const domainCookies = await browser.storage.getCookies({ domain: 'example.com' });
+
+// Clear all cookies
+await browser.storage.clearCookies();
+
+// Clear cookies by filter
+await browser.storage.clearCookies({ name: 'session' });
+await browser.storage.clearCookies({ domain: 'example.com' });
+```
+
+## Example: Login Once, Reuse Session
+
+### Step 1: Generate Auth State (run once)
+
+```typescript
+// scripts/generate-auth.ts
+import { Browser } from 'craftdriver';
+
+async function generateAuth() {
+  const browser = await Browser.launch({ browserName: 'chrome' });
+
+  await browser.navigateTo('https://myapp.com/login');
+  await browser.fill('#username', process.env.TEST_USER!);
+  await browser.fill('#password', process.env.TEST_PASS!);
+  await browser.click('#login-btn');
+
+  // Wait for login to complete
+  await browser.expect('#dashboard').toBeVisible();
+
+  // Save the authenticated state
+  await browser.saveState('./auth.json');
+
+  await browser.quit();
+  console.log('Auth state saved to auth.json');
+}
+
+generateAuth();
+```
+
+### Step 2: Use Auth State in Tests
+
+```typescript
+// tests/dashboard.test.ts
+import { describe, it, beforeEach, afterEach } from 'vitest';
+import { Browser } from 'craftdriver';
+
+describe('Dashboard', () => {
+  let browser: Browser;
+
+  beforeEach(async () => {
+    // Launch with saved auth - already logged in!
+    browser = await Browser.launch({
+      browserName: 'chrome',
+      storageState: './auth.json',
+    });
+  });
+
+  afterEach(async () => {
+    await browser.quit();
+  });
+
+  it('shows user profile', async () => {
+    // Go directly to authenticated page
+    await browser.navigateTo('https://myapp.com/profile');
+
+    // No login needed - session cookie is already set
+    await browser.expect('#username').toHaveText('testuser');
+  });
+
+  it('can update settings', async () => {
+    await browser.navigateTo('https://myapp.com/settings');
+    await browser.click('#dark-mode-toggle');
+    await browser.expect('#theme').toHaveText('dark');
+  });
+});
+```
+
+## Complete E2E Example
+
+```typescript
+import { Browser } from 'craftdriver';
+
+async function testLoginPersistence() {
+  // First browser: Log in and save state
+  let browser = await Browser.launch({ browserName: 'chrome' });
+
+  await browser.navigateTo('http://localhost:3000/login');
+  await browser.fill('#username', 'testuser');
+  await browser.fill('#password', 'secret123');
+  await browser.click('#submit');
+  await browser.expect('#welcome').toBeVisible();
+
+  await browser.saveState('./session.json');
+  await browser.quit();
+
+  // Second browser: Load state and verify logged in
+  browser = await Browser.launch({
+    browserName: 'chrome',
+    storageState: './session.json',
+  });
+
+  await browser.navigateTo('http://localhost:3000/login');
+
+  // Should already be logged in!
+  await browser.expect('#welcome').toContainText('testuser');
+
+  await browser.quit();
+}
+```
+
+## API Reference
+
+### Browser Methods
+
+| Method                      | Description                        |
+| --------------------------- | ---------------------------------- |
+| `saveState(path, options?)` | Save cookies and storage to file   |
+| `loadState(path)`           | Load cookies and storage from file |
+
+### StorageStateOptions
+
+| Option                  | Type       | Default | Description                    |
+| ----------------------- | ---------- | ------- | ------------------------------ |
+| `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      |
+
+### SessionStateManager (browser.storage)
+
+| Method                      | Description                        |
+| --------------------------- | ---------------------------------- |
+| `addCookie(cookie)`         | Add a single cookie                |
+| `getCookies(filter?)`       | Get cookies, optionally filtered   |
+| `setCookies(cookies)`       | Set multiple cookies               |
+| `clearCookies(filter?)`     | Clear cookies, optionally filtered |
+| `getState(options?)`        | Get current state as object        |
+| `setState(state)`           | Set state from object              |
+| `saveState(path, options?)` | Save state to file                 |
+| `loadState(path)`           | Load state from file               |

package/docs/tracing.md

@@ -0,0 +1,282 @@
+# Tracing
+
+Capture an append-only recording of a browser session for **bug
+investigation**. Every event is written synchronously to a line-delimited
+JSON file as it happens, so a thrown `expect`, a failed locator, or a
+process crash cannot lose the evidence that led up to it.
+
+> **BiDi-only.** Tracing piggybacks on the same BiDi subscriptions used
+> by `browser.logs` and `browser.network`. Calling `startTrace()` without
+> `enableBiDi: true` throws.
+
+## Quick start
+
+```ts
+import { chromium } from 'craftdriver';
+
+const browser = await chromium.launch({ enableBiDi: true });
+
+await browser.startTrace({ outDir: './artefacts/login' });
+try {
+  await browser.navigateTo('http://127.0.0.1:8080/login.html');
+  await browser.fill('#user', 'alice');
+  await browser.click('#submit');
+} finally {
+  await browser.stopTrace();
+}
+```
+
+After the run you get:
+
+```
+artefacts/login/
+├── trace.ndjson                  ← one JSON event per line
+└── screenshots/
+    ├── 0001.png
+    └── 0002.png
+```
+
+`try/finally` is the recommended shape, but it's a courtesy — see the
+next section.
+
+## What happens when a test throws
+
+Every recorded event hits disk **before** the next line of your test
+runs (synchronous `writeSync` on an open file descriptor). So if your
+test throws halfway through — `expect.toBeVisible()` times out, a click
+misses, an a11y check fails — the partial `trace.ndjson` already
+contains every action, console message, network event, navigation, and
+screenshot reference that led up to the failure.
+
+NDJSON has no closing bracket and no header. Partial files are valid
+NDJSON: any reader simply ignores a truncated final line. The only
+thing missing when `stopTrace()` doesn't run is a trailing
+`{"type":"meta","endedAt":"…"}` line — readers infer the end time from
+the last event's `t` field.
+
+The same is true for screenshots: each PNG is a self-contained file
+written as the capture resolves, so the ones taken before the failure
+are intact on disk.
+
+You don't need `try/finally` for correctness — only to write the closing
+meta marker and close the file handle cleanly. `browser.quit()` will
+close the handle for you on its way out.
+
+## What gets recorded
+
+Each line in `trace.ndjson` is one event. All events carry `t` (ms
+since `startTrace`) and a `type`:
+
+| `type`         | Fields                                                      |
+| -------------- | ----------------------------------------------------------- |
+| `meta`         | `startedAt` / `endedAt`, `opts` on the start line           |
+| `action`       | `name`, `args?`, `selector?`                                |
+| `console`      | `level`, `text`                                             |
+| `error`        | `text` (uncaught page errors)                               |
+| `request`      | `url`, `method`, `requestId?`                               |
+| `response`     | `url`, `status`, `mimeType?`, `fromCache?`, `requestId?`    |
+| `navigation`   | `url`, `context?`                                           |
+| `screenshot`   | `file` (relative path), `reason` (`'action'` \| `'error'`), `actionIndex?` |
+
+Actions currently logged: `navigateTo`, `goBack`, `goForward`, `reload`,
+`setContent`, `click`, `fill`, `clear`, `acceptDialog`, `dismissDialog`.
+
+## Screenshots: evidence, not video
+
+Screenshots are tied to **meaningful moments**, not a timer:
+
+* Before every logged action — answers *"what did the page look like
+  when I clicked?"*
+* On every page error — answers *"what was on screen when it broke?"*
+
+A 30-second test with 5 clicks produces 5 PNGs, not 300. Turn it off
+when you only want the JSON log:
+
+```ts
+await browser.startTrace({ outDir: './t', screenshots: 'off' });
+```
+
+`screenshots: 'auto'` (default), `true`, and omitting the option all
+mean the same thing.
+
+## Selectively disable pillars
+
+Every pillar is on by default. Switch off what you don't need:
+
+```ts
+await browser.startTrace({
+  outDir: './t',
+  actions: true,
+  screenshots: 'auto',
+  network: false,   // skip request/response events
+  console: false,   // skip console + error events
+});
+```
+
+`actions: false` keeps the timeline but stops adding action events (and
+the screenshots that ride along with them).
+
+## Reading a trace
+
+NDJSON is trivial to grep, even mid-run:
+
+```sh
+# All errors and the action that preceded them
+jq -c 'select(.type=="error" or .type=="action")' trace.ndjson
+
+# Failed network responses
+jq -c 'select(.type=="response" and .status>=400)' trace.ndjson
+
+# Find the screenshot for action #7
+jq -c 'select(.actionIndex==7)' trace.ndjson
+```
+
+```ts
+// Programmatic:
+import { readFileSync } from 'node:fs';
+const events = readFileSync('trace.ndjson', 'utf8')
+  .split('\n').filter(Boolean).map((l) => JSON.parse(l));
+```
+
+## Using with Vitest
+
+Vitest doesn't have Playwright-style fixtures, but a small helper using
+its `beforeEach` / `afterEach` hooks gets you **automatic per-test
+tracing with keep-on-failure**. One line per `describe()`, no per-test
+boilerplate.
+
+Drop this into your test folder (e.g. `tests/auto-trace.ts`):
+
+```ts
+import { beforeEach, afterEach } from 'vitest';
+import { rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import type { Browser, TraceScreenshotMode } from 'craftdriver';
+
+const ROOT  = process.env.CRAFTDRIVER_TRACE_DIR ?? './traces';
+const MODE  = (process.env.CRAFTDRIVER_TRACE ?? 'on-failure') as
+  'always' | 'on-failure' | 'off';
+const SHOTS = (process.env.CRAFTDRIVER_TRACE_SCREENSHOTS ?? 'auto') as
+  TraceScreenshotMode;
+
+export function autoTrace(getBrowser: () => Browser): void {
+  if (MODE === 'off') return;
+  let currentDir = '';
+
+  beforeEach(async ({ task }) => {
+    currentDir = join(ROOT, safeName(task));
+    await getBrowser().startTrace({ outDir: currentDir, screenshots: SHOTS });
+  });
+
+  afterEach(async ({ task }) => {
+    const failed = task.result?.state === 'fail';
+    // Snap the page as it looked at the failed assertion (not just
+    // before the last click).
+    if (failed) {
+      try {
+        const buf = await getBrowser().screenshot();
+        writeFileSync(join(currentDir, 'final.png'), buf);
+      } catch { /* browser may already be dead */ }
+    }
+    try { await getBrowser().stopTrace(); } catch { return; }
+    if (MODE === 'on-failure' && !failed) {
+      rmSync(currentDir, { recursive: true, force: true });
+    } else if (failed) {
+      console.error(`  📁 trace: ${currentDir}`);
+    }
+  });
+}
+
+function safeName(t: { name: string; suite?: { name: string } | null }): string {
+  const parts: string[] = [];
+  let s: typeof t | null | undefined = t;
+  while (s && s.name) { parts.unshift(s.name); s = s.suite; }
+  return parts.join('/').replace(/[^a-z0-9/]+/gi, '-').toLowerCase();
+}
+```
+
+Use it inside any `describe()`:
+
+```ts
+import { autoTrace } from './auto-trace';
+
+describe('Login', () => {
+  let browser: Browser;
+  beforeAll(async () => { browser = await Browser.launch({ enableBiDi: true }); });
+  afterAll(async () => { await browser.quit(); });
+
+  autoTrace(() => browser);   // ← that's it
+
+  it('signs in', async () => {
+    await browser.navigateTo('http://127.0.0.1:8080/login.html');
+    await browser.fill('#user', 'alice');
+    await browser.click('#submit');
+    // If this expect throws, ./traces/login/signs-in/trace.ndjson is on disk.
+  });
+});
+```
+
+Knobs are all environment variables — switch behaviour without touching code:
+
+| Env var | Values | Default | Effect |
+| --- | --- | --- | --- |
+| `CRAFTDRIVER_TRACE` | `off` \| `on-failure` \| `always` | `on-failure` | What to keep. `on-failure` deletes traces for passing tests. |
+| `CRAFTDRIVER_TRACE_DIR` | path | `./traces` | Root output directory. |
+| `CRAFTDRIVER_TRACE_SCREENSHOTS` | `auto` \| `off` | `auto` | Per the `screenshots` option. `off` skips the BiDi capture per action — much faster when you only need the JSON timeline. |
+
+Typical workflows:
+
+```sh
+npm test                                  # green run leaves no clutter; failures keep their trace
+CRAFTDRIVER_TRACE_SCREENSHOTS=off npm test    # cheap mode for big suites
+CRAFTDRIVER_TRACE=always npm test         # debugging the tracer itself
+CRAFTDRIVER_TRACE=off npm test            # tracing disabled
+```
+
+Why a helper and not built-in? Vitest owns the test lifecycle, not
+craftdriver — and the runner-specific glue (pass/fail detection, hook
+order, output paths) belongs on your side. The helper is ~30 lines you
+can read, copy, and adjust to your team's conventions.
+
+## API
+
+### `browser.startTrace(opts)`
+
+```ts
+interface TraceStartOptions {
+  outDir: string;                               // required
+  actions?: boolean;                            // default true
+  network?: boolean;                            // default true
+  console?: boolean;                            // default true
+  screenshots?: boolean | 'auto' | 'off';       // default 'auto'
+}
+```
+
+Creates `outDir` if missing, opens `outDir/trace.ndjson` for writing,
+and emits the start `meta` line. Throws if a trace is already running
+or BiDi is not enabled.
+
+### `browser.stopTrace()`
+
+Drains in-flight screenshot captures, writes the closing `meta` line,
+and closes the file. Returns `Promise<void>`. Throws if no trace is
+running.
+
+### Cleanup on `browser.quit()`
+
+If a trace is still running when you quit the browser, the file is
+closed without a closing `meta` line — same shape as the test-throws
+case. No file is deleted.
+
+## What this is *not*
+
+By design, the tracer does not:
+
+* produce a self-contained `.zip` or hosted viewer,
+* record video / fixed-interval screencast,
+* emit HAR (the NDJSON already holds request/response events),
+* capture DOM snapshots or sourcemaps.
+
+Those features make sense at much larger scale (Playwright Trace
+Viewer). For a single failing test, a tail-able NDJSON log plus a
+handful of PNGs beats a zip you can't open.

package/package.json

@@ -1,22 +1,27 @@
 {
   "name": "craftdriver",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Modern WebDriver automation library for NodeJS",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "module",
+  "bin": {
+    "craftdriver": "bin/craftdriver.mjs"
+  },
   "scripts": {
     "prebuild": "rimraf dist",
     "build": "tsc -p tsconfig.json",
     "lint": "eslint . --ext .ts",
     "format": "prettier --write .",
-    "test": "vitest run",
-    "test:firefox": "BROWSER_NAME=firefox vitest run",
+    "test": "HEADLESS=true vitest run",
+    "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",
     "clean": "rimraf dist",
     "serve": "http-server ./examples -a 127.0.0.1 -p 8080 -c-1 --cors",
     "examples:start": "npm run serve",
+    "docs:api": "node scripts/gen-api-reference.mjs",
+    "docs:api:check": "node scripts/gen-api-reference.mjs --check",
     "prepublishOnly": "npm run build && npm run lint"
   },
   "keywords": [
@@ -28,7 +33,10 @@
     "automation",
     "browser-automation",
     "testing",
-    "selenium"
+    "selenium",
+    "cli",
+    "agent",
+    "ai"
   ],
   "author": "Dimitar Topuzov",
   "license": "MIT",
@@ -45,7 +53,11 @@
   },
   "files": [
     "dist",
+    "bin",
+    "docs",
+    "skills",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "sideEffects": false,
@@ -53,6 +65,7 @@
     "@semantic-release/changelog": "^6.0.3",
     "@semantic-release/git": "^10.0.1",
     "@types/node": "^20.0.0",
+    "@types/ws": "^8.18.1",
     "@typescript-eslint/eslint-plugin": "^8.1.0",
     "@typescript-eslint/parser": "^8.1.0",
     "eslint": "^9.8.0",
@@ -68,7 +81,11 @@
     "vitest": "^4.0.18"
   },
   "dependencies": {
-    "@types/ws": "^8.18.1",
-    "ws": "^8.19.0"
+    "axe-core": "^4.11.4",
+    "ws": "^8.21.0"
+  },
+  "overrides": {
+    "brace-expansion": "5.0.6",
+    "ip-address": "10.1.1"
   }
 }

package/skills/craftdriver/SKILL.md

@@ -0,0 +1,84 @@
+# craftdriver — SKILL
+
+Modern BiDi-first WebDriver library for Node.js. Playwright ergonomics,
+WebDriver standards-compliance, no AI in the hot path.
+
+## Core loop
+
+```
+navigate → find → action → assert
+```
+
+Every action and every `expect(locator).to…()` **auto-waits** up to the
+default timeout (30 s in-library, 5 s on agent surfaces). Never add
+`sleep()` / `setTimeout()` — it's a footgun.
+
+## Selector preference order
+
+```
+By.testId  >  By.role({name})  >  By.labelText  >
+By.text({exact:true})  >  By.css  >  By.xpath
+```
+
+`testId` and `role` are stable across DOM refactors; CSS and XPath
+break the moment markup shifts.
+
+## Five rules
+
+1. Use `expect(locator).to…()` for assertions. Never hand-roll
+   `while (...) { ... sleep(100) }` retry loops — they auto-wait.
+2. Read errors by `code`, not by prose. Every public throw is a
+   `CraftdriverError` with a stable `code`. See
+   [docs/error-codes.md](../../docs/error-codes.md).
+3. `instanceof CraftdriverError` is true on every public throw;
+   `instanceof Error` is also true.
+4. BiDi features (`network`, `logs`, tracing, init scripts, true load
+   events) require `Browser.launch({ enableBiDi: true })`. The error
+   code on the wrong transport is `UNSUPPORTED`.
+5. Tests fetch from the example server. Start it in a separate
+   terminal: `npm run examples:start` before `npm test`.
+
+## When you reach for more
+
+- **Writing tests, looking for a method** → read
+  [skills/craftdriver/cheatsheet.md](cheatsheet.md). Also see
+  [docs/api-reference.md](../../docs/api-reference.md) — every public
+  export, one row each.
+- **Login, upload, wait-for-network, etc.** → read
+  [skills/craftdriver/patterns.md](patterns.md).
+- **Driving the browser from a shell or agent loop** → read
+  [skills/craftdriver/cli.md](cli.md). Same Browser API, exposed as a
+  `craftdriver` binary with daemon + ephemeral modes.
+- **Driving from an MCP-aware AI host** (Claude Desktop / Code, Cursor,
+  Windsurf, Zed, Goose, Gemini CLI) → `craftdriver mcp` is a stdio
+  JSON-RPC server with 14 schema-typed tools. Mutating tools return a
+  compact a11y snapshot **diffed from the previous turn** — you see
+  what changed without a follow-up read. See
+  [docs/mcp.md](../../docs/mcp.md).
+- **An error code you don't recognise** → read
+  [docs/error-codes.md](../../docs/error-codes.md).
+
+## Probing rule
+
+When unsure a selector exists, check before acting. Today: call
+`await locator.count()` (zero-wait, returns the current match count).
+Acting on a hallucinated selector wastes the whole auto-wait budget.
+
+For the **CLI and MCP**, the cheapest way to drive a page is to take a
+snapshot first and use refs:
+
+```
+$ craftdriver snapshot
+e4: textbox "Username" #username
+e7: button "Sign in" #submit
+$ craftdriver fill ref=e4 alice
+$ craftdriver click ref=e7
+```
+
+`ref=eN` resolves to a CSS attribute selector, auto-waits like any
+other selector, and re-allocates on every snapshot. No hallucination.
+
+## Imports
+
+Always `import { ... } from 'craftdriver'`. Never reach into
+`craftdriver/src/lib/...` — internals are unstable.