craftdriver 1.0.3 → 1.0.4

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)

package/docs/recipes/mobile-flow-with-network-and-logs.md

@@ -0,0 +1,57 @@
+# Test A Mobile Flow With API Mocks And Logs
+
+Use this pattern when mobile layout depends on a device preset and a backend
+configuration response. This combines mobile emulation, network mocking, and log
+capture in one test.
+
+```ts
+import { afterAll, beforeAll, describe, it } from 'vitest';
+import { Browser } from 'craftdriver';
+
+describe('mobile navigation', () => {
+  let browser: Browser;
+
+  beforeAll(async () => {
+    browser = await Browser.launch({
+      browserName: 'chrome',
+      mobileEmulation: 'Pixel 7',
+      captureLogs: true,
+    });
+  });
+
+  afterAll(async () => {
+    await browser.quit();
+  });
+
+  it('shows the mobile menu from mocked config', async () => {
+    browser.logs.clearLogs();
+
+    await browser.network.mock('**/api/mobile-config', {
+      status: 200,
+      body: {
+        navigation: 'bottom-tabs',
+        showInstallPrompt: false,
+      },
+    });
+
+    await browser.navigateTo('http://localhost:3000');
+    await browser.getByRole('button', { name: 'Menu' }).click();
+
+    await browser.expect('#mobile-menu').toBeVisible();
+    await browser.expect('#desktop-nav').not.toBeVisible();
+    browser.logs.assertNoErrors();
+  });
+});
+```
+
+## Notes
+
+- Mobile emulation is currently Chrome/Chromium only.
+- Mock before navigation when the page reads mobile config during startup.
+- Keep `captureLogs: true` if startup logs matter.
+
+## Learn More
+
+- [Mobile Emulation](../mobile-emulation.md)
+- [Network Mocking And Request Waiting](../network.md)
+- [Console Logs And JavaScript Errors](../browser-logs.md)

package/docs/recipes/mock-api-and-assert-network.md

@@ -0,0 +1,60 @@
+# Mock APIs And Assert Network Traffic
+
+Use this pattern when the UI should be tested independently from unstable,
+slow, or expensive backend services. Mock the response the app needs, then wait
+for the request or response caused by the user action.
+
+```ts
+import { expect, it } from 'vitest';
+import { Browser } from 'craftdriver';
+
+it('loads mocked users and verifies the request', async () => {
+  const browser = await Browser.launch({ browserName: 'chrome' });
+
+  try {
+    await browser.navigateTo('http://localhost:3000/users');
+
+    await browser.network.mock('**/api/users', {
+      status: 200,
+      body: {
+        users: [{ id: 1, name: 'Alice', plan: 'Pro' }],
+      },
+    });
+
+    const [request, response] = await Promise.all([
+      browser.waitForRequest((req) => {
+        return req.url.includes('/api/users') && req.method === 'GET';
+      }),
+      browser.waitForResponse('**/api/users'),
+      browser.getByRole('button', { name: 'Load users' }).click(),
+    ]);
+
+    expect(request.method).toBe('GET');
+    expect(response.status).toBe(200);
+    await browser.expect('#user-list').toContainText('Alice');
+  } finally {
+    await browser.quit();
+  }
+});
+```
+
+## Keep Mocks Isolated
+
+If you share a browser across tests, clear intercepts in `afterEach()`:
+
+```ts
+afterEach(async () => {
+  await browser.network.removeAllIntercepts();
+});
+```
+
+## Notes
+
+- Register waits before the click that triggers the request.
+- Use a glob for simple URL matching and a predicate when method, status, or headers matter.
+- Mock before navigation if the page fetches data during initial load.
+
+## Learn More
+
+- [Network Mocking And Request Waiting](../network.md)
+- [Console Logs And JavaScript Errors](../browser-logs.md)

package/docs/recipes/multi-user-contexts.md

@@ -0,0 +1,58 @@
+# Test Multi-User Workflows
+
+Use this pattern for chat, permissions, approvals, collaboration, admin/customer
+flows, or any test where two signed-in users must exist at the same time.
+
+Browser contexts isolate cookies and storage while sharing one launched browser.
+
+```ts
+import { afterAll, beforeAll, describe, it } from 'vitest';
+import { Browser } from 'craftdriver';
+
+describe('team invitation', () => {
+  let browser: Browser;
+  const baseUrl = 'http://localhost:3000';
+
+  beforeAll(async () => {
+    browser = await Browser.launch({ browserName: 'chrome' });
+  });
+
+  afterAll(async () => {
+    await browser.quit();
+  });
+
+  it('admin invites a teammate who accepts in another context', async () => {
+    const admin = await browser.newContext({ storageState: '.auth/admin.json' });
+    const teammate = await browser.newContext({ storageState: '.auth/alice.json' });
+
+    try {
+      const adminPage = await admin.newPage({ url: `${baseUrl}/team` });
+      await adminPage.find('#invite-member').click();
+      await adminPage.find('#invite-email').fill('alice@example.com');
+      await adminPage.find('#send-invite').click();
+      await adminPage.expect('#invite-status').toContainText('Sent');
+
+      const alicePage = await teammate.newPage({ url: `${baseUrl}/invites` });
+      await alicePage.find('#accept-invite').click();
+      await alicePage.expect('#membership').toContainText('Member');
+
+      await adminPage.find('#refresh-members').click();
+      await adminPage.expect('#member-list').toContainText('alice@example.com');
+    } finally {
+      await admin.close();
+      await teammate.close();
+    }
+  });
+});
+```
+
+## Notes
+
+- Use one context per user or role.
+- Put context cleanup in `finally` so failed assertions do not leak sessions.
+- Combine with saved storage state when users should start already signed in.
+
+## Learn More
+
+- [Browser Contexts](../browser-context.md)
+- [Session Management](../session-management.md)