craftdriver 1.0.2 → 1.0.4

package/docs/index.md

@@ -0,0 +1,64 @@
+---
+layout: home
+title: CraftDriver
+titleTemplate: false
+hero:
+  name: CraftDriver
+  text: Crafted browser automation for Node.js.
+  tagline: Playwright-style ergonomics. WebDriver standards. AI friendly.
+  image:
+    src: /craftdriver-mark.svg
+    alt: CraftDriver
+  actions:
+    - theme: brand
+      text: Get Started
+      link: /getting-started
+    - theme: alt
+      text: API Reference
+      link: /api-reference
+    - theme: alt
+      text: AI Agent Guide
+      link: /agents
+features:
+  - title: Control network traffic
+    details: Mock APIs, block noisy requests, intercept calls, and wait for real requests or responses.
+  - title: Reuse browser state
+    details: Save cookies and localStorage, launch already signed in, and isolate users with browser contexts.
+  - title: Test time and quality
+    details: Use virtual time, axe-core accessibility checks, traces, screenshots, console logs, and JS error capture.
+  - title: Agent-friendly
+    details: CLI, MCP server, and assistant rules are there when you want coding agents to drive the browser too.
+---
+
+## One Install
+
+```bash
+npm install craftdriver --save-dev
+```
+
+```ts
+import { Browser } from 'craftdriver';
+
+const browser = await Browser.launch({ browserName: 'chrome' });
+
+await browser.navigateTo('https://example.com/login');
+await browser.getByLabel('Username').fill('alice');
+await browser.getByLabel('Password').fill('hunter2');
+await browser.getByRole('button', { name: 'Sign in' }).click();
+await browser.expect('#result').toHaveText('Welcome alice');
+
+await browser.quit();
+```
+
+## Choose Your Path
+
+| You want to...                    | Start                                   |
+| --------------------------------- | --------------------------------------- |
+| Write browser automation          | [Getting Started](./getting-started.md) |
+| Give an AI coding agent a browser | [AI Agent Guide](./agents.md)           |
+
+## Good Stuff To Read Next
+
+- [Zero-Config Drivers](./zero-config-drivers.md) explains driver resolution and caching.
+- [WebDriver Standards](./standards.md) explains how Classic and BiDi work together.
+- [Recipes](./recipes.md) collects KB-style patterns for common real-world workflows.

package/docs/keyboard-mouse.md

@@ -48,6 +48,15 @@ Release a held key.
 await browser.keyboard.up('Shift');
 ```
 
+### chord(...keys)
+
+Press a key combination.
+
+```typescript
+await browser.keyboard.chord('Control', 'a');
+await browser.keyboard.chord('Shift', 'Tab');
+```
+
 ### Key Combinations
 
 Combine `down()` and `up()` for modifier key combinations:
@@ -129,23 +138,25 @@ await browser.mouse.move({ x: 150, y: 300 });
 await browser.mouse.move('#target');
 ```
 
-### down()
+### down(button?)
 
 Press the mouse button.
 
 ```typescript
 await browser.mouse.down();
+await browser.mouse.down('right');
 ```
 
-### up()
+### up(button?)
 
 Release the mouse button.
 
 ```typescript
 await browser.mouse.up();
+await browser.mouse.up('right');
 ```
 
-### wheel(deltaX, deltaY)
+### wheel(deltaX, deltaY, target?)
 
 Scroll the page.
 
@@ -158,6 +169,9 @@ await browser.mouse.wheel(0, -100);
 
 // Scroll right
 await browser.mouse.wheel(100, 0);
+
+// Scroll while targeting an element
+await browser.mouse.wheel(0, 300, '#scroll-panel');
 ```
 
 ### dragAndDrop(from, to)
@@ -194,14 +208,14 @@ await browser.mouse.dragAndDrop({ x: startX, y: startY }, { x: endX, y: endY });
 
 ```typescript
 // Move to start position
-await browser.mouse.move(100, 100);
+await browser.mouse.move({ x: 100, y: 100 });
 await browser.mouse.down();
 
 // Draw a line
-await browser.mouse.move(200, 100);
-await browser.mouse.move(200, 200);
-await browser.mouse.move(100, 200);
-await browser.mouse.move(100, 100);
+await browser.mouse.move({ x: 200, y: 100 });
+await browser.mouse.move({ x: 200, y: 200 });
+await browser.mouse.move({ x: 100, y: 200 });
+await browser.mouse.move({ x: 100, y: 100 });
 
 await browser.mouse.up();
 ```
@@ -227,10 +241,14 @@ For element-scoped key presses, use the `press()` method on ElementHandle:
 
 ```typescript
 // Press Enter in a specific input
-await browser.find('#search').fill('query').press('Enter');
+const search = browser.find('#search');
+await search.fill('query');
+await search.press('Enter');
 
 // Tab out of a field
-await browser.find('#username').fill('user').press('Tab');
+const username = browser.find('#username');
+await username.fill('user');
+await username.press('Tab');
 ```
 
 This is often more convenient than using the global keyboard API.

package/docs/mobile-emulation.md

@@ -163,9 +163,9 @@ await browser.click('#mobile-menu-button');
 await browser.expect('#mobile-menu').toBeVisible();
 ```
 
-### Combine with BiDi Features
+### Combine With Network Mocking And Logs
 
-Mobile emulation works alongside BiDi features:
+Mobile emulation works alongside network mocking and browser log capture:
 
 ```typescript
 const browser = await Browser.launch({
@@ -186,6 +186,9 @@ const errors = browser.logs.getErrors();
 expect(errors).toHaveLength(0);
 ```
 
+Learn more in [Network Mocking And Request Waiting](./network.md) and
+[Console Logs And JavaScript Errors](./browser-logs.md).
+
 ## Limitations
 
 - **Chrome/Chromium only**: Mobile emulation uses Chrome-specific capabilities

package/docs/network.md

@@ -0,0 +1,203 @@
+# Network Mocking And Request Waiting
+
+Use CraftDriver network tools when a test needs to control or observe HTTP traffic:
+
+- mock an API response without changing the backend
+- block analytics, ads, or flaky third-party services
+- add headers such as auth tokens or test markers
+- wait for the request or response triggered by a click
+- assert that the app sent the right method, URL, or headers
+
+> **Requires the default browser event connection.** Network interception and
+> request/response waiting require `enableBiDi: true` (the default) and a
+> browser that supports WebDriver BiDi. If you launch with
+> `enableBiDi: false`, these methods throw a clear `requires BiDi` error.
+
+## Browser Support
+
+CraftDriver supports these network APIs on Chrome, Chromium, and Firefox.
+
+## Quick Mock
+
+```typescript
+await browser.network.mock('**/api/users', {
+  status: 200,
+  body: {
+    users: [{ id: 1, name: 'Test User' }],
+  },
+});
+
+await browser.navigateTo('https://example.com/dashboard');
+await browser.expect('#users').toContainText('Test User');
+```
+
+The pattern uses URL globs. `**/api/users` matches that path on any host.
+
+## Common Tasks
+
+| Goal | API |
+| ---- | --- |
+| Return a fake response | `browser.network.mock(pattern, response)` |
+| Block matching requests | `browser.network.block(pattern)` |
+| Dynamically inspect and respond | `browser.network.intercept(pattern, handler)` |
+| Remove one route | `browser.network.removeIntercept(id)` |
+| Remove every route | `browser.network.removeAllIntercepts()` |
+| Add headers to outgoing requests | `browser.network.setExtraHeaders(headers)` |
+| Bypass or restore browser cache | `browser.network.setCacheBehavior(behavior)` |
+| Wait until traffic settles | `browser.network.waitForNetworkIdle(opts?)` |
+| Wait for one request | `browser.waitForRequest(patternOrPredicate, opts?)` |
+| Wait for one response | `browser.waitForResponse(patternOrPredicate, opts?)` |
+
+## Mock Responses
+
+### Static response
+
+```typescript
+await browser.network.mock('**/api/login', {
+  status: 401,
+  body: { error: 'Invalid credentials' },
+});
+
+await browser.getByLabel('Username').fill('baduser');
+await browser.getByLabel('Password').fill('wrongpass');
+await browser.getByRole('button', { name: 'Sign in' }).click();
+
+await browser.expect('#error').toHaveText('Invalid credentials');
+```
+
+### Dynamic response
+
+```typescript
+await browser.network.mock('**/api/items/*', (request) => {
+  const id = request.url.split('/').pop();
+
+  return {
+    status: 200,
+    body: { id, name: `Item ${id}`, price: 9.99 },
+  };
+});
+```
+
+## Block Requests
+
+```typescript
+await browser.network.block('**/analytics/**');
+await browser.network.block('**/tracking/**');
+```
+
+This is useful when third-party services make tests slower or less predictable.
+
+## Add Headers
+
+```typescript
+await browser.network.setExtraHeaders({
+  'X-Test-Mode': 'true',
+  Authorization: 'Bearer test-token',
+});
+```
+
+Extra headers are applied to matching browser requests after they are configured.
+
+## Control Cache
+
+```typescript
+await browser.network.setCacheBehavior('bypass');
+
+// Later, restore normal browser caching.
+await browser.network.setCacheBehavior('default');
+```
+
+## Intercept Requests
+
+Use `intercept()` when the response depends on request details or asynchronous
+test setup.
+
+```typescript
+const seen: string[] = [];
+
+const interceptId = await browser.network.intercept('**/api/**', async (request) => {
+  seen.push(`${request.method} ${request.url}`);
+
+  return {
+    status: 200,
+    body: { intercepted: true, originalUrl: request.url },
+  };
+});
+
+// Later, remove only this intercept.
+await browser.network.removeIntercept(interceptId);
+```
+
+You can also delay a response to test loading UI:
+
+```typescript
+await browser.network.intercept('**/api/**', async () => {
+  await new Promise((resolve) => setTimeout(resolve, 3000));
+  return { status: 200, body: { data: 'delayed response' } };
+});
+
+await browser.getByRole('button', { name: 'Load data' }).click();
+await browser.expect('#loading-spinner').toBeVisible();
+```
+
+## Wait For Real Traffic
+
+`browser.waitForRequest()` and `browser.waitForResponse()` observe real network
+traffic without mocking it. Register the wait before the action that triggers the
+request. `Promise.all` is the safest pattern:
+
+```typescript
+const [response] = await Promise.all([
+  browser.waitForResponse('**/api/users'),
+  browser.getByRole('button', { name: 'Load users' }).click(),
+]);
+
+expect(response.status).toBe(200);
+```
+
+Both methods accept a URL glob or a predicate:
+
+```typescript
+const [response] = await Promise.all([
+  browser.waitForResponse((res) => {
+    return res.url.includes('/api/users') && res.status === 200;
+  }),
+  browser.getByRole('button', { name: 'Load users' }).click(),
+]);
+```
+
+### Response shape
+
+| Property | Type | Description |
+| -------- | ---- | ----------- |
+| `url` | `string` | Full request URL |
+| `status` | `number` | HTTP status code |
+| `statusText` | `string` | Status text such as `"OK"` |
+| `headers` | `Record<string, string>` | Response headers |
+| `mimeType` | `string` | Response MIME type |
+| `fromCache` | `boolean` | Whether the browser served it from cache |
+| `request` | `{ id, url, method, headers }` | Matching request info |
+
+### Request shape
+
+| Property | Type | Description |
+| -------- | ---- | ----------- |
+| `id` | `string` | Browser request id |
+| `url` | `string` | Full URL |
+| `method` | `string` | Request method, such as `"GET"` or `"POST"` |
+| `headers` | `Record<string, string>` | Request headers |
+
+## Timeouts
+
+Both wait methods accept `{ timeout?: number }`. The default is the browser
+navigation timeout, 30 seconds.
+
+```typescript
+await browser.waitForResponse('**/api/users', { timeout: 10_000 });
+```
+
+On timeout, CraftDriver throws a clear error:
+
+```text
+waitForResponse("**/api/users") timed out after 30000ms
+```

package/docs/public/craftdriver-mark.svg

@@ -0,0 +1,15 @@
+<svg width="160" height="160" viewBox="0 0 160 160" fill="none" xmlns="http://www.w3.org/2000/svg" role="img" aria-labelledby="title desc">
+  <title id="title">CraftDriver mark</title>
+  <desc id="desc">A browser window with a command prompt and connection nodes.</desc>
+  <rect x="12" y="24" width="136" height="112" rx="18" fill="#111827"/>
+  <rect x="24" y="42" width="112" height="78" rx="10" fill="#f8fafc"/>
+  <circle cx="34" cy="34" r="5" fill="#f97316"/>
+  <circle cx="50" cy="34" r="5" fill="#f59e0b"/>
+  <circle cx="66" cy="34" r="5" fill="#22c55e"/>
+  <path d="M44 78L60 64L44 50" stroke="#b45309" stroke-width="8" stroke-linecap="round" stroke-linejoin="round"/>
+  <path d="M70 82H104" stroke="#2563eb" stroke-width="8" stroke-linecap="round"/>
+  <path d="M91 60H112C121.941 60 130 68.0589 130 78V78C130 87.9411 121.941 96 112 96H91" stroke="#94a3b8" stroke-width="6" stroke-linecap="round"/>
+  <circle cx="88" cy="60" r="8" fill="#2563eb"/>
+  <circle cx="88" cy="96" r="8" fill="#f59e0b"/>
+  <circle cx="118" cy="78" r="8" fill="#22c55e"/>
+</svg>

package/docs/public/social-card.svg

@@ -0,0 +1,27 @@
+<svg width="1200" height="630" viewBox="0 0 1200 630" fill="none" xmlns="http://www.w3.org/2000/svg" role="img" aria-labelledby="title desc">
+  <title id="title">CraftDriver social card</title>
+  <desc id="desc">Standards-based browser automation for Node.js, tests, scripts, and AI agents.</desc>
+  <rect width="1200" height="630" fill="#0f172a"/>
+  <rect x="72" y="72" width="1056" height="486" rx="32" fill="#111827" stroke="#334155" stroke-width="2"/>
+  <rect x="116" y="122" width="396" height="276" rx="24" fill="#f8fafc"/>
+  <rect x="116" y="122" width="396" height="54" rx="24" fill="#1f2937"/>
+  <circle cx="154" cy="149" r="9" fill="#f97316"/>
+  <circle cx="184" cy="149" r="9" fill="#f59e0b"/>
+  <circle cx="214" cy="149" r="9" fill="#22c55e"/>
+  <path d="M184 274L230 232L184 190" stroke="#b45309" stroke-width="18" stroke-linecap="round" stroke-linejoin="round"/>
+  <path d="M264 286H382" stroke="#2563eb" stroke-width="18" stroke-linecap="round"/>
+  <path d="M349 210H414C446.585 210 473 236.415 473 269V269C473 301.585 446.585 328 414 328H349" stroke="#94a3b8" stroke-width="12" stroke-linecap="round"/>
+  <circle cx="346" cy="210" r="17" fill="#2563eb"/>
+  <circle cx="346" cy="328" r="17" fill="#f59e0b"/>
+  <circle cx="432" cy="269" r="17" fill="#22c55e"/>
+  <text x="574" y="212" fill="#f8fafc" font-family="Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, Segoe UI, sans-serif" font-size="82" font-weight="800">CraftDriver</text>
+  <text x="578" y="281" fill="#f59e0b" font-family="Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, Segoe UI, sans-serif" font-size="34" font-weight="700">WebDriver automation for humans and AI agents</text>
+  <text x="578" y="356" fill="#cbd5e1" font-family="Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, Segoe UI, sans-serif" font-size="30">Playwright-style ergonomics. WebDriver standards. AI friendly.</text>
+  <text x="578" y="408" fill="#cbd5e1" font-family="Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, Segoe UI, sans-serif" font-size="30">Library API, CLI, MCP server, and packaged agent skills.</text>
+  <rect x="578" y="462" width="156" height="48" rx="24" fill="#b45309"/>
+  <text x="614" y="495" fill="#fff7ed" font-family="Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, Segoe UI, sans-serif" font-size="22" font-weight="700">Node.js</text>
+  <rect x="754" y="462" width="178" height="48" rx="24" fill="#1d4ed8"/>
+  <text x="790" y="495" fill="#eff6ff" font-family="Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, Segoe UI, sans-serif" font-size="22" font-weight="700">WebDriver</text>
+  <rect x="952" y="462" width="102" height="48" rx="24" fill="#15803d"/>
+  <text x="984" y="495" fill="#f0fdf4" font-family="Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, Segoe UI, sans-serif" font-size="22" font-weight="700">MCP</text>
+</svg>

package/docs/recipes/accessibility-gate.md

@@ -0,0 +1,53 @@
+# Run Accessibility Gates
+
+Use this pattern when CI should reject serious accessibility regressions, while
+still allowing deliberate rule exceptions in one place.
+
+```ts
+import { afterAll, beforeAll, beforeEach, describe, it } from 'vitest';
+import { Browser } from 'craftdriver';
+
+const A11Y_OPTIONS = {
+  minImpact: 'serious' as const,
+  disableRules: [
+    // Example: keep temporary exceptions explicit and reviewed.
+    'color-contrast',
+  ],
+};
+
+describe('accessibility gate', () => {
+  let browser: Browser;
+
+  beforeAll(async () => {
+    browser = await Browser.launch({ browserName: 'chrome' });
+  });
+
+  beforeEach(async () => {
+    await browser.navigateTo('http://localhost:3000/settings');
+  });
+
+  afterAll(async () => {
+    await browser.quit();
+  });
+
+  it('passes page-level accessibility checks', async () => {
+    await browser.a11y.check(A11Y_OPTIONS);
+  });
+
+  it('passes modal accessibility checks', async () => {
+    await browser.getByRole('button', { name: 'Edit profile' }).click();
+    await browser.locator('#profile-modal').a11y.check(A11Y_OPTIONS);
+  });
+});
+```
+
+## Notes
+
+- Use `check()` when violations should fail the test.
+- Use `audit()` when you want to write a report or inspect violations manually.
+- Prefer scoped checks for dynamic UI such as dialogs, menus, and checkout panels.
+
+## Learn More
+
+- [Accessibility](../accessibility.md)
+- [Selectors](../selectors.md)

package/docs/recipes/console-error-gate.md

@@ -0,0 +1,57 @@
+# Fail On Console And JavaScript Errors
+
+Use this pattern when a flow can look correct in the DOM while still logging
+client-side errors. Start log capture early, run the flow, then fail on
+unexpected JavaScript errors.
+
+```ts
+import { afterAll, beforeAll, beforeEach, describe, it } from 'vitest';
+import { Browser } from 'craftdriver';
+
+describe('critical browser flows', () => {
+  let browser: Browser;
+
+  beforeAll(async () => {
+    browser = await Browser.launch({
+      browserName: 'chrome',
+      captureLogs: true,
+    });
+  });
+
+  beforeEach(async () => {
+    browser.logs.clearLogs();
+  });
+
+  afterAll(async () => {
+    await browser.quit();
+  });
+
+  it('saves settings without browser errors', async () => {
+    await browser.navigateTo('http://localhost:3000/settings');
+    await browser.getByLabel('Display name').fill('Alice');
+    await browser.getByRole('button', { name: 'Save' }).click();
+
+    await browser.expect('#toast').toContainText('Saved');
+    browser.logs.assertNoErrors();
+  });
+});
+```
+
+## Wait For A Known Log
+
+When the log itself is part of the expected behavior, arm the wait before the
+action that emits it:
+
+```ts
+const saved = browser.logs.waitForConsole((message) => {
+  return message.level === 'info' && message.text.includes('settings:saved');
+});
+
+await browser.getByRole('button', { name: 'Save' }).click();
+await saved;
+```
+
+## Learn More
+
+- [Console Logs And JavaScript Errors](../browser-logs.md)
+- [Tracing](../tracing.md)

package/docs/recipes/file-upload-download.md

@@ -0,0 +1,58 @@
+# Test File Uploads And Downloads
+
+Use this pattern when a workflow imports data, uploads an attachment, exports a
+report, or verifies a generated file.
+
+```ts
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { existsSync, mkdirSync, readFileSync, rmSync } from 'node:fs';
+import { resolve, join } from 'node:path';
+import { Browser } from 'craftdriver';
+
+describe('reports', () => {
+  let browser: Browser;
+  const downloadsDir = resolve('.tmp/downloads');
+  const fixture = resolve('tests/fixtures/sample.txt');
+
+  beforeAll(async () => {
+    mkdirSync(downloadsDir, { recursive: true });
+    browser = await Browser.launch({
+      browserName: 'chrome',
+      downloadsDir,
+    });
+  });
+
+  afterAll(async () => {
+    await browser.quit();
+    rmSync(downloadsDir, { recursive: true, force: true });
+  });
+
+  it('uploads a source file and downloads a report', async () => {
+    await browser.navigateTo('http://localhost:3000/reports');
+
+    await browser.find('#source-file').setInputFiles(fixture);
+    await browser.expect('#upload-status').toContainText('sample.txt');
+
+    const download = await browser.waitForDownload(() => {
+      return browser.getByRole('button', { name: 'Export report' }).click();
+    });
+
+    const target = join(downloadsDir, download.suggestedFilename);
+    await download.saveAs(target);
+
+    expect(existsSync(target)).toBe(true);
+    expect(readFileSync(target, 'utf8')).toContain('Report');
+  });
+});
+```
+
+## Notes
+
+- Configure `downloadsDir` at launch so files land somewhere predictable.
+- Wrap the click that triggers the download in `waitForDownload()`.
+- Use `setInputFiles()` on the actual `<input type="file">` element.
+
+## Learn More
+
+- [Element API](../element-api.md)
+- [Browser API](../browser-api.md)

package/docs/recipes/login-once-reuse-session.md

@@ -0,0 +1,73 @@
+# Log In Once And Reuse The Session
+
+Use this pattern when login is slow, rate-limited, or not the thing most tests
+are trying to prove. Log in once, save cookies and localStorage, then launch
+future tests already signed in.
+
+## Generate Auth State
+
+Run this as a setup step before the tests that need an authenticated user.
+
+```ts
+import { mkdir } from 'node:fs/promises';
+import { Browser } from 'craftdriver';
+
+const authState = '.auth/alice.json';
+
+await mkdir('.auth', { recursive: true });
+
+const browser = await Browser.launch({ browserName: 'chrome' });
+
+try {
+  await browser.navigateTo('http://localhost:3000/login');
+  await browser.getByLabel('Email').fill('alice@example.com');
+  await browser.getByLabel('Password').fill(process.env.TEST_PASSWORD!);
+  await browser.getByRole('button', { name: 'Sign in' }).click();
+  await browser.expect('#account').toContainText('Alice');
+
+  await browser.saveState(authState);
+} finally {
+  await browser.quit();
+}
+```
+
+## Use Auth State In Tests
+
+```ts
+import { afterAll, beforeAll, beforeEach, describe, it } from 'vitest';
+import { Browser } from 'craftdriver';
+
+describe('authenticated dashboard', () => {
+  let browser: Browser;
+
+  beforeAll(async () => {
+    browser = await Browser.launch({
+      browserName: 'chrome',
+      storageState: '.auth/alice.json',
+    });
+  });
+
+  beforeEach(async () => {
+    await browser.navigateTo('http://localhost:3000/dashboard');
+  });
+
+  afterAll(async () => {
+    await browser.quit();
+  });
+
+  it('shows account data', async () => {
+    await browser.expect('#account').toContainText('Alice');
+  });
+});
+```
+
+## Notes
+
+- Keep generated auth files out of source control if they contain real secrets.
+- Regenerate auth state when the app changes login/session behavior.
+- Use separate files such as `.auth/admin.json` and `.auth/customer.json` for different roles.
+
+## Learn More
+
+- [Session Management](../session-management.md)
+- [Browser Contexts](../browser-context.md)