craftdriver 1.0.3 → 1.1.0

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)

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();
 ```