craftdriver 1.0.2 → 1.0.4

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)

package/docs/recipes/trace-failing-test.md

@@ -0,0 +1,64 @@
+# Capture Failure Evidence With Tracing
+
+Use this pattern when a flaky or complex test needs evidence: actions,
+navigation, console output, JavaScript errors, network events, and screenshots.
+
+```ts
+import { afterAll, beforeAll, describe, it } from 'vitest';
+import { Browser } from 'craftdriver';
+
+describe('checkout', () => {
+  let browser: Browser;
+
+  beforeAll(async () => {
+    browser = await Browser.launch({ browserName: 'chrome' });
+  });
+
+  afterAll(async () => {
+    await browser.quit();
+  });
+
+  async function withTrace(name: string, run: () => Promise<void>) {
+    const outDir = `./traces/${name}-${Date.now()}`;
+    await browser.startTrace({ outDir });
+
+    try {
+      await run();
+    } catch (error) {
+      console.error(`Trace kept at ${outDir}`);
+      throw error;
+    } finally {
+      await browser.stopTrace().catch(() => undefined);
+    }
+  }
+
+  it('places an order', async () => {
+    await withTrace('checkout-order', async () => {
+      await browser.navigateTo('http://localhost:3000/cart');
+      await browser.getByRole('button', { name: 'Checkout' }).click();
+      await browser.getByLabel('Card number').fill('4242424242424242');
+      await browser.getByRole('button', { name: 'Pay' }).click();
+      await browser.expect('#order-status').toContainText('Confirmed');
+    });
+  });
+});
+```
+
+## Notes
+
+- The trace file is NDJSON, so it remains useful even if the test throws before cleanup.
+- Screenshots are stored under the trace directory.
+- For high-volume suites, turn screenshots off unless the test is under investigation.
+
+```ts
+await browser.startTrace({
+  outDir: './traces/smoke',
+  screenshots: 'off',
+});
+```
+
+## Learn More
+
+- [Tracing](../tracing.md)
+- [Screenshots](../screenshots.md)
+- [Console Logs And JavaScript Errors](../browser-logs.md)

package/docs/recipes/virtual-clock-time-sensitive-ui.md

@@ -0,0 +1,60 @@
+# Test Time-Sensitive UI With The Virtual Clock
+
+Use this pattern for debounced search, trial banners, idle logout, countdowns,
+and other UI that normally makes tests sleep.
+
+```ts
+import { afterAll, afterEach, beforeAll, beforeEach, describe, it } from 'vitest';
+import { Browser } from 'craftdriver';
+
+describe('debounced search', () => {
+  let browser: Browser;
+
+  beforeAll(async () => {
+    browser = await Browser.launch({ browserName: 'chrome' });
+  });
+
+  beforeEach(async () => {
+    await browser.clock.install({ time: '2030-01-01T00:00:00Z' });
+    await browser.navigateTo('http://localhost:3000/search');
+  });
+
+  afterEach(async () => {
+    await browser.clock.uninstall();
+  });
+
+  afterAll(async () => {
+    await browser.quit();
+  });
+
+  it('fires search only after the debounce window', async () => {
+    await browser.network.mock('**/api/search?q=lap', {
+      status: 200,
+      body: { results: ['Laptop stand'] },
+    });
+
+    await browser.getByLabel('Search').fill('lap');
+
+    await browser.clock.tick(299);
+    await browser.expect('#results').toHaveText('');
+
+    await browser.clock.tick(1);
+    await browser.expect('#results').toContainText('Laptop stand');
+  });
+});
+```
+
+## Fixed Dates
+
+For date-dependent UI, freeze the wall clock before navigation:
+
+```ts
+await browser.clock.setFixedTime('2026-06-15T23:59:00Z');
+await browser.navigateTo('http://localhost:3000/billing');
+await browser.expect('#trial-banner').toContainText('expires today');
+```
+
+## Learn More
+
+- [Virtual Clock](../clock.md)
+- [Network Mocking And Request Waiting](../network.md)

package/docs/recipes/vitest-browser-lifecycle.md

@@ -0,0 +1,56 @@
+# Use CraftDriver With Vitest Hooks
+
+Use this pattern when a test file should launch one browser, navigate to a clean
+page before each test, and fail if the page reports unexpected JavaScript errors.
+
+This keeps tests fast without sharing dirty page state.
+
+```ts
+import { afterAll, afterEach, beforeAll, beforeEach, describe, it } from 'vitest';
+import { Browser } from 'craftdriver';
+
+describe('settings page', () => {
+  let browser: Browser;
+  const baseUrl = 'http://localhost:3000';
+
+  beforeAll(async () => {
+    browser = await Browser.launch({
+      browserName: 'chrome',
+      captureLogs: true,
+    });
+  });
+
+  beforeEach(async () => {
+    browser.logs.clearLogs();
+    await browser.network.removeAllIntercepts();
+    await browser.navigateTo(`${baseUrl}/settings`);
+  });
+
+  afterEach(() => {
+    browser.logs.assertNoErrors();
+  });
+
+  afterAll(async () => {
+    await browser.quit();
+  });
+
+  it('updates the display name', async () => {
+    await browser.getByLabel('Display name').fill('Alice');
+    await browser.getByRole('button', { name: 'Save' }).click();
+    await browser.expect('#toast').toContainText('Saved');
+  });
+});
+```
+
+## Notes
+
+- Launch in `beforeAll()` when tests in the file can share one browser process.
+- Navigate in `beforeEach()` so each test starts from a known URL.
+- Clear network mocks and logs before each test so one test cannot influence the next.
+- Use `afterAll()` for `browser.quit()` so local driver and browser processes are cleaned up.
+
+## Learn More
+
+- [Browser API](../browser-api.md)
+- [Console Logs And JavaScript Errors](../browser-logs.md)
+- [Network Mocking And Request Waiting](../network.md)

package/docs/recipes.md

@@ -0,0 +1,33 @@
+# Recipes
+
+Recipes are short, real-world patterns that combine CraftDriver features into
+common testing workflows. Use this page as the index; each recipe has its own
+page so the list can grow without turning into a wall of code.
+
+For exact signatures, use the linked feature docs and the
+[API reference](./api-reference.md).
+
+## Test Structure
+
+| Scenario                  | Use when                                                                   | Recipe                                                                     |
+| ------------------------- | -------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
+| Vitest browser lifecycle  | You want one browser per test file and a fresh page per test.              | [Use CraftDriver With Vitest Hooks](./recipes/vitest-browser-lifecycle.md) |
+| Login once, reuse session | Login UI is slow or noisy and most tests start signed in.                  | [Log In Once And Reuse The Session](./recipes/login-once-reuse-session.md) |
+| Multi-user flows          | You need Alice and Bob signed in at the same time without leaking cookies. | [Test Multi-User Workflows](./recipes/multi-user-contexts.md)              |
+
+## App Behavior
+
+| Scenario                     | Use when                                                                  | Recipe                                                                                        |
+| ---------------------------- | ------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
+| Mock APIs and assert traffic | A UI flow depends on backend responses or request payloads.               | [Mock APIs And Assert Network Traffic](./recipes/mock-api-and-assert-network.md)              |
+| Time-sensitive UI            | Debounces, trial banners, idle logout, or scheduled jobs make tests slow. | [Test Time-Sensitive UI With The Virtual Clock](./recipes/virtual-clock-time-sensitive-ui.md) |
+| Mobile-specific behavior     | Mobile layout depends on viewport, device headers, API config, or logs.   | [Test A Mobile Flow With API Mocks And Logs](./recipes/mobile-flow-with-network-and-logs.md)  |
+| File upload and download     | A flow uploads a file, exports a report, or verifies downloaded content.  | [Test File Uploads And Downloads](./recipes/file-upload-download.md)                          |
+
+## Quality Gates And Debugging
+
+| Scenario                      | Use when                                                                        | Recipe                                                                   |
+| ----------------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
+| Accessibility regression gate | CI should fail on serious page or component accessibility issues.               | [Run Accessibility Gates](./recipes/accessibility-gate.md)               |
+| Console and JavaScript errors | Tests should fail if the browser reports unexpected client-side errors.         | [Fail On Console And JavaScript Errors](./recipes/console-error-gate.md) |
+| Evidence on failure           | You want a replayable trail of actions, network, logs, errors, and screenshots. | [Capture Failure Evidence With Tracing](./recipes/trace-failing-test.md) |

package/docs/selectors.md

@@ -343,6 +343,28 @@ const texts = await Promise.all(handles.map(h => h.text()));
 const allButtons = await browser.findAll('.buy-btn');
 ```
 
+### Locator actions and state
+
+| Method | Description |
+| ------ | ----------- |
+| `click(options?)` | Click the first matching visible element |
+| `fill(text, options?)` | Fill the first matching visible element |
+| `text(options?)` | Get visible text |
+| `textContent(options?)` | Alias for `text()` |
+| `isVisible(options?)` | Return `true` if a matching element is visible |
+| `count()` | Count current matches without auto-wait |
+| `all()` | Return snapshot `ElementHandle`s for current matches |
+| `waitFor({ state, timeout? })` | Wait for `attached`, `detached`, `visible`, or `hidden` |
+| `expect()` | Element assertions scoped to this locator |
+| `a11y` | Accessibility audit scoped to this locator |
+
+```typescript
+await browser.locator('.toast').waitFor({ state: 'visible' });
+const shown = await browser.locator('.toast').isVisible();
+const text = await browser.locator('.toast').textContent();
+const audit = await browser.locator('#checkout').a11y.audit();
+```
+
 ### Assertions on locators
 
 ```typescript
@@ -378,5 +400,4 @@ await browser.find('nav a[href="/about"]').click();
 ```typescript
 await browser.getByRole('button', { name: 'Submit' }).click();
 await browser.getByText('Cancel').click();
-await browser.find('button:contains("Save")').click();
 ```

package/docs/session-management.md

@@ -1,11 +1,14 @@
 # Session Management
 
-Craftdriver supports Playwright-style session persistence, allowing you to save and restore browser state including cookies and localStorage. This is perfect for:
+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
 
+Session management is the user-facing feature. Under the hood, CraftDriver uses
+the best available WebDriver transport for the browser you launched.
+
 ## Saving Session State
 
 ```typescript
@@ -51,6 +54,15 @@ The saved file contains:
 await browser.loadState('./session.json');
 ```
 
+## Working With State Objects
+
+Use the state object directly when you do not want to write a file:
+
+```typescript
+const state = await browser.storage.getState();
+await browser.storage.setState(state);
+```
+
 ## Launching with Pre-loaded State
 
 The most common pattern - launch a browser with existing session:
@@ -89,6 +101,11 @@ const cookies = await browser.storage.getCookies();
 // Get cookies for specific domain
 const domainCookies = await browser.storage.getCookies({ domain: 'example.com' });
 
+// Set multiple cookies
+await browser.storage.setCookies([
+  { name: 'theme', value: 'dark', domain: 'example.com', path: '/' },
+]);
+
 // Clear all cookies
 await browser.storage.clearCookies();
 

package/docs/standards.md

@@ -0,0 +1,40 @@
+# WebDriver Standards
+
+CraftDriver is built on W3C WebDriver protocols:
+
+- **WebDriver Classic** for broadly supported browser automation commands
+- **WebDriver BiDi** for modern bidirectional browser capabilities
+
+That protocol choice is the center of the project. CraftDriver tries to provide a modern developer experience without making browser-private protocols the foundation of user code.
+
+## Classic And BiDi Together
+
+| Protocol          | Used for                                                                                                                                              |
+| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| WebDriver Classic | Stable navigation, element actions, browser sessions, window operations, and widely supported commands.                                               |
+| WebDriver BiDi    | Network interception, console and page errors, screenshots, storage, contexts, init scripts, downloads, tracing, and other event-driven capabilities. |
+
+CraftDriver picks the practical protocol path behind a single public API. You call `browser.click()`, `browser.navigateTo()`, `browser.network.mock()`, or `browser.startTrace()`; the library handles the transport details.
+
+## Why It Matters
+
+Standards-based automation gives projects a few useful properties:
+
+- browser behavior can converge across engines instead of depending on a single vendor protocol
+- Firefox support is a first-class target, not an afterthought
+- protocol errors can be mapped into stable CraftDriver error codes
+- browser control can be exposed safely to CLIs and MCP tools
+
+## Honest Limits
+
+WebDriver BiDi is still evolving. Some capabilities are browser-specific today, especially around emulation and mobile behavior. CraftDriver documents those limits instead of silently pretending every browser supports every feature.
+
+Use these pages when you need exact capability details:
+
+- [Network Mocking And Request Waiting](./network.md)
+- [Console Logs And JavaScript Errors](./browser-logs.md)
+- [Session Management](./session-management.md)
+- [Browser Contexts](./browser-context.md)
+- [Emulation](./emulation.md)
+- [Mobile Emulation](./mobile-emulation.md)
+- [Error Codes](./error-codes.md)

package/docs/why-craftdriver.md

@@ -0,0 +1,28 @@
+# Why CraftDriver?
+
+CraftDriver is for writing boringly reliable automation against real browsers, with code that reads nicely.
+
+## What It Cares About
+
+- 🍺 **Focused Node.js API** - browser automation without a giant framework around it.
+- 🧭 **Real browsers** - drives installed Chrome, Chromium, and Firefox instead of patched browser engine builds.
+- 🌐 **Standards that age well** - W3C WebDriver standards stay stable while browser-private protocols change.
+- 🚦 **Readable, auto-waited flows** - role, label, text, test id, CSS, XPath, click, fill, and expect.
+- 📡 **Network control** - mock, block, intercept, and wait for browser requests and responses.
+- 🔐 **Reusable sessions** - save cookies and localStorage, then launch already signed in.
+- ⏱️ **Virtual clock** - freeze or fast-forward `Date`, timers, and time-sensitive UI.
+- ♿ **Accessibility audits** - run axe-core checks on pages, elements, and locators.
+- 🧾 **Trace evidence** - capture actions, console output, errors, network events, and screenshots.
+- 🤖 **Agent-friendly** - CLI, MCP, and assistant rules when coding agents need the browser.
+
+## Good Fits
+
+- End-to-end tests in Node.js.
+- Browser scripts and diagnostics.
+- Projects that want installed Chrome, Chromium, and Firefox through WebDriver.
+- Tests that need network mocks, saved auth state, virtual time, or accessibility gates.
+- Coding agents that should use the same browser automation primitives as humans.
+
+## Not The Goal
+
+CraftDriver is not trying to be a giant testing universe. It is the browser control layer: launch, navigate, click, fill, assert, inspect, debug, and get on with your day.

package/docs/zero-config-drivers.md

@@ -0,0 +1,52 @@
+# Zero-Config Drivers
+
+CraftDriver is designed so a normal install is enough:
+
+```bash
+npm install craftdriver --save-dev
+```
+
+Then launch an installed browser:
+
+```ts
+import { Browser } from 'craftdriver';
+
+const browser = await Browser.launch({ browserName: 'chrome' });
+```
+
+You do not need to add `chromedriver`, `geckodriver`, or browser downloads to most projects. CraftDriver resolves the matching WebDriver binary, starts it on a free port, and caches resolution details so later launches are faster.
+
+## What Happens At Launch?
+
+CraftDriver checks for the driver in this order:
+
+| Step | Source                                                                  |
+| ---- | ----------------------------------------------------------------------- |
+| 1    | Explicit `ChromeService` / `FirefoxService` configuration               |
+| 2    | Environment variables such as `CHROMEDRIVER_PATH` or `GECKODRIVER_PATH` |
+| 3    | Project-local binaries in `node_modules/.bin`                           |
+| 4    | Binaries already available on `PATH`                                    |
+| 5    | Auto-resolved and cached driver matching the installed browser          |
+
+If a browser update leaves a cached driver stale, CraftDriver retries once with a refreshed driver instead of making you clear the cache manually.
+
+## CI Friendly
+
+The default setup works well on CI runners that already include Chrome or Firefox. For stricter environments, you can pin the driver path or run offline:
+
+```bash
+CRAFTDRIVER_CHROMEDRIVER_PATH=/usr/bin/chromedriver npm test
+CRAFTDRIVER_OFFLINE=1 npm test
+CRAFTDRIVER_CACHE_DIR=/tmp/craftdriver-cache npm test
+```
+
+## When To Configure Manually
+
+Manual configuration is useful when:
+
+- your CI image pins a specific browser and driver pair
+- network access is blocked
+- you need custom driver logging
+- you want to avoid any version detection during launch
+
+See [Driver Configuration](./driver-configuration.md) for the full reference.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "craftdriver",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "Modern WebDriver automation library for NodeJS",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -24,6 +24,10 @@
     "examples:start": "npm run serve",
     "docs:api": "node scripts/gen-api-reference.mjs",
     "docs:api:check": "node scripts/gen-api-reference.mjs --check",
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "docs:preview": "vitepress preview docs",
+    "docs:check": "npm run docs:api:check && npm run docs:build",
     "prepublishOnly": "npm run build && npm run lint"
   },
   "keywords": [
@@ -34,11 +38,16 @@
     "chromium",
     "automation",
     "browser-automation",
+    "e2e",
+    "e2e-testing",
     "testing",
     "selenium",
+    "mcp",
     "cli",
     "agent",
-    "ai"
+    "ai",
+    "ai-agents",
+    "web-testing"
   ],
   "author": "Dimitar Topuzov",
   "license": "MIT",
@@ -49,14 +58,15 @@
   "bugs": {
     "url": "https://github.com/dtopuzov/craftdriver/issues"
   },
-  "homepage": "https://github.com/dtopuzov/craftdriver#readme",
+  "homepage": "https://dtopuzov.github.io/craftdriver/",
   "engines": {
     "node": ">=18"
   },
   "files": [
     "dist",
     "bin",
-    "docs",
+    "docs/**/*.md",
+    "docs/public",
     "skills",
     "README.md",
     "CHANGELOG.md",
@@ -80,6 +90,7 @@
     "rimraf": "^6.1.3",
     "semantic-release": "^25.0.5",
     "typescript": "^5.0.0",
+    "vitepress": "^1.6.4",
     "vitest": "^4.0.18"
   },
   "dependencies": {
@@ -90,6 +101,9 @@
     "brace-expansion": "5.0.6",
     "ip-address": "10.1.1",
     "npm": "^11.18.0",
-    "undici": "7.28.0"
+    "undici": "7.28.0",
+    "vitepress": {
+      "vite": "6.4.3"
+    }
   }
 }