craftdriver 0.0.3 → 0.2.0

package/docs/assertions.md

@@ -0,0 +1,182 @@
+# Assertions
+
+CraftDriver provides a fluent assertion API via `browser.expect()` for testing element states.
+
+> For accessibility assertions, see [docs/accessibility.md](./accessibility.md) — `browser.a11y.check()` is the assertion form of the axe-core wrapper.
+
+## Basic Usage
+
+```typescript
+// Assert on element state
+await browser.expect('#message').toHaveText('Success!');
+await browser.expect('#email').toHaveValue('test@example.com');
+await browser.expect('#modal').toBeVisible();
+```
+
+## Assertion Methods
+
+### toHaveText(expected)
+
+Assert that the element's text content matches exactly.
+
+```typescript
+await browser.expect('#heading').toHaveText('Welcome');
+await browser.expect('.alert').toHaveText('Form submitted successfully');
+```
+
+### toContainText(expected)
+
+Assert that the element's text content contains the expected substring.
+
+```typescript
+await browser.expect('#paragraph').toContainText('important');
+await browser.expect('.notification').toContainText('saved');
+```
+
+### toHaveValue(expected)
+
+Assert that an input element has the expected value.
+
+```typescript
+await browser.expect('#username').toHaveValue('testuser');
+await browser.expect('#quantity').toHaveValue('5');
+```
+
+### toBeVisible()
+
+Assert that the element is visible on the page.
+
+```typescript
+await browser.expect('#success-modal').toBeVisible();
+await browser.expect('.tooltip').toBeVisible();
+```
+
+### toHaveAttribute(name, value)
+
+Assert that the element has an attribute with the expected value.
+
+```typescript
+await browser.expect('#link').toHaveAttribute('href', '/dashboard');
+await browser.expect('#input').toHaveAttribute('disabled', 'true');
+await browser.expect('#image').toHaveAttribute('alt', 'Product photo');
+```
+
+## Negation
+
+Use `.not` to negate any assertion:
+
+```typescript
+await browser.expect('#error').not.toBeVisible();
+await browser.expect('#input').not.toHaveValue('');
+await browser.expect('#button').not.toHaveAttribute('disabled', 'true');
+```
+
+## Element-Scoped Assertions
+
+You can also get an assertion API scoped to an ElementHandle:
+
+```typescript
+const message = browser.find('#message');
+await message.expect().toHaveText('Success');
+await message.expect().toBeVisible();
+```
+
+This is useful when you're already working with an element reference:
+
+```typescript
+const form = browser.find('#login-form');
+
+// Fill the form
+await browser.find('#username').fill('testuser');
+await browser.find('#password').fill('secret');
+await browser.find('#submit').click();
+
+// Assert on result
+await browser.find('#result').expect().toHaveText('Login successful');
+```
+
+## Waiting Behavior
+
+All assertions automatically wait for the condition to be true, up to a configurable timeout.
+
+```typescript
+// Uses the browser-level default (5000 ms unless changed)
+await browser.expect('#loading').not.toBeVisible();
+
+// Per-call timeout override
+await browser.expect('#data').toHaveText('Loaded', { timeout: 10000 });
+await browser.expect('#modal').toBeVisible({ timeout: 2000 });
+await browser.expect('#result').toContainText('success', { timeout: 8000 });
+```
+
+### Changing the default timeout
+
+Use `browser.setDefaultTimeout()` to raise or lower the default for **all**
+subsequent assertions (and actions) on that browser instance:
+
+```typescript
+browser.setDefaultTimeout(10000); // all assertions now wait up to 10 s by default
+
+await browser.expect('#slow-widget').toBeVisible(); // uses 10 s
+await browser.expect('#fast-check').toHaveText('ok', { timeout: 500 }); // per-call wins
+```
+
+See [Browser API — Configuring timeouts](./browser-api.md#configuring-timeouts) for full details.
+
+## Examples
+
+### Form Validation
+
+```typescript
+await browser.find('#email').fill('invalid-email');
+await browser.find('#submit').click();
+
+await browser.expect('#email-error').toBeVisible();
+await browser.expect('#email-error').toHaveText('Please enter a valid email');
+```
+
+### Navigation Confirmation
+
+```typescript
+await browser.find('#logout').click();
+
+await browser.expect('#login-form').toBeVisible();
+await browser.expect('.welcome-message').not.toBeVisible();
+```
+
+### Successful Form Submission
+
+```typescript
+await browser.find('#name').fill('John Doe');
+await browser.find('#email').fill('john@example.com');
+await browser.find('#submit').click();
+
+await browser.expect('#success-message').toBeVisible();
+await browser.expect('#success-message').toContainText('Thank you');
+await browser.expect('#form').not.toBeVisible();
+```
+
+### Attribute Verification
+
+```typescript
+// Check link destination
+await browser.expect('#dashboard-link').toHaveAttribute('href', '/dashboard');
+
+// Check disabled state
+await browser.expect('#submit').not.toHaveAttribute('disabled', 'true');
+
+// After disabling
+await browser.find('#submit').click();
+await browser.expect('#submit').toHaveAttribute('disabled', 'true');
+```
+
+### Page Title and URL
+
+```typescript
+// Use browser methods directly for page-level checks
+const title = await browser.title();
+expect(title).toBe('Dashboard'); // Using Vitest/Jest expect
+
+const url = await browser.url();
+expect(url).toContain('/dashboard');
+```

package/docs/bidi-features.md

@@ -0,0 +1,462 @@
+# BiDi Features
+
+CraftDriver is built on the WebDriver BiDi protocol, giving you network interception, browser log capture, and precise load-state detection out of the box.
+
+> **Browser support in craftdriver:** Chrome, Chromium, and Firefox.
+
+---
+
+## Feature matrix
+
+Most of craftdriver works against both BiDi and Classic WebDriver. The
+features below are **BiDi-only** — they require `enableBiDi: true`
+(the default) and a browser that successfully negotiates a BiDi
+WebSocket. Calling them after BiDi negotiation failed throws a clear
+error; gate them with `browser.isBiDiEnabled()` if your code may run
+in Classic mode.
+
+| Capability | API | BiDi-only? |
+|---|---|---|
+| Network mocking / interception | [`browser.network.*`](#network-mocking) | yes |
+| Console & error log capture | [`browser.logs.*`](#console--error-logs) | yes |
+| `waitForLoadState('load' \| 'domcontentloaded' \| 'networkidle')` | `browser.waitForLoadState()` | yes |
+| `navigateTo(..., { waitUntil })` real load events | `browser.navigateTo()` | yes |
+| `waitForRequest()` / `waitForResponse()` | `browser.waitForRequest()` / `waitForResponse()` | yes |
+| Init scripts (run before any page script) | `browser.addInitScript()` | yes |
+| Open new tab / popup | `browser.openPage()` | yes |
+| Capture popup opened by an action | `browser.waitForPage()` | yes |
+| Isolated user contexts (incognito profiles) | `browser.newContext()` / `browser.contexts()` | yes |
+| Downloads | `browser.waitForDownload()` | yes |
+| Tracing | `browser.startTrace()` / `browser.stopTrace()` | yes |
+| Storage state (cookies + localStorage) | `browser.storage.*`, `saveState()`, `loadState()` | no — works in Classic too |
+| Element actions, locators, assertions, frames, dialogs, screenshots, keyboard/mouse, mobile emulation | rest of the API | no — works in Classic too |
+
+---
+
+## Network Mocking
+
+Intercept and mock network requests using `browser.network`.
+
+### mock(pattern, response)
+
+Return a mocked response for matching requests. Response can be an object or a function for dynamic mocking.
+
+```typescript
+// Static mock
+await browser.network.mock('**/api/users', {
+  status: 200,
+  body: { users: [{ id: 1, name: 'Test User' }] },
+});
+
+// Dynamic mock - response based on request
+await browser.network.mock('**/api/items/*', (request) => {
+  const id = request.url.split('/').pop();
+  return {
+    status: 200,
+    body: { id, name: `Item ${id}`, price: 9.99 },
+  };
+});
+
+// Navigate - API calls will return mocked data
+await browser.navigateTo('https://example.com/dashboard');
+```
+
+### block(pattern)
+
+Block all requests matching the pattern.
+
+```typescript
+// Block analytics and tracking
+await browser.network.block('**/analytics/**');
+await browser.network.block('**/tracking/**');
+```
+
+### setExtraHeaders(headers)
+
+Add extra headers to all requests.
+
+```typescript
+await browser.network.setExtraHeaders({
+  'X-Test-Mode': 'true',
+  Authorization: 'Bearer test-token',
+});
+```
+
+### setCacheBehavior(behavior)
+
+Control browser caching behavior.
+
+```typescript
+// Bypass cache - always fetch fresh
+await browser.network.setCacheBehavior('bypass');
+
+// Use default caching
+await browser.network.setCacheBehavior('default');
+```
+
+### intercept(pattern, handler)
+
+Intercept requests and provide custom responses. The handler receives request details and can return a mock response.
+
+```typescript
+let capturedRequests: string[] = [];
+
+const interceptId = await browser.network.intercept('**/api/**', async (request) => {
+  // Log request details
+  capturedRequests.push(`${request.method} ${request.url}`);
+
+  // Return a mock response
+  return {
+    status: 200,
+    body: { intercepted: true, originalUrl: request.url },
+  };
+});
+```
+
+### removeIntercept(interceptId)
+
+Remove a previously registered intercept using the ID returned from `intercept()` or `mock()`.
+
+```typescript
+const interceptId = await browser.network.mock('**/api/users', { status: 200, body: {} });
+// ... later
+await browser.network.removeIntercept(interceptId);
+```
+
+### Examples
+
+#### Mock API Error
+
+```typescript
+await browser.network.mock('**/api/login', {
+  status: 401,
+  body: { error: 'Invalid credentials' },
+});
+
+await browser.find('#username').fill('baduser');
+await browser.find('#password').fill('wrongpass');
+await browser.find('#submit').click();
+
+await browser.expect('#error').toHaveText('Invalid credentials');
+```
+
+#### Test Slow Network
+
+```typescript
+await browser.network.intercept('**/api/**', async (request) => {
+  // Simulate slow network
+  await new Promise((resolve) => setTimeout(resolve, 3000));
+  // Return mock response after delay
+  return { status: 200, body: { data: 'delayed response' } };
+});
+
+// Test loading state appears
+await browser.find('#load-data').click();
+await browser.expect('#loading-spinner').toBeVisible();
+```
+
+---
+
+## Waiting for Network
+
+`browser.waitForRequest` and `browser.waitForResponse` let you observe real network
+traffic without intercepting it. Register them **before** the action that triggers
+the request — the canonical pattern is `Promise.all`:
+
+```typescript
+const [response] = await Promise.all([
+  browser.waitForResponse('**/api/users'),
+  browser.click('#load-users'),
+]);
+expect(response.status).toBe(200);
+```
+
+Both accept a URL **glob** (same `**` syntax as `network.mock`) or a **predicate**:
+
+```typescript
+// Glob — matches by pathname
+const [res] = await Promise.all([
+  browser.waitForResponse('**/api/users'),
+  browser.click('#load-users'),
+]);
+
+// Predicate — full control over matching
+const [res2] = await Promise.all([
+  browser.waitForResponse(r => r.url.includes('/api/users') && r.status === 200),
+  browser.click('#load-users'),
+]);
+```
+
+### waitForResponse(pattern, opts?)
+
+Resolves with an `InterceptedResponse` once a matching completed response arrives.
+
+| Property    | Type                       | Description                           |
+| ----------- | -------------------------- | ------------------------------------- |
+| `url`       | `string`                   | Full request URL                      |
+| `status`    | `number`                   | HTTP status code                      |
+| `statusText`| `string`                   | E.g. `"OK"`                           |
+| `headers`   | `Record<string, string>`   | Response headers                      |
+| `mimeType`  | `string`                   | E.g. `"application/json"`             |
+| `fromCache` | `boolean`                  | Whether served from browser cache     |
+| `request`   | `{ id, url, method, headers }` | Matching request info             |
+
+### waitForRequest(pattern, opts?)
+
+Resolves with an `InterceptedRequest` as soon as the browser sends the request
+(before a response arrives). Useful for asserting that a request was made with
+the right method/headers without waiting for the response.
+
+| Property  | Type                     | Description            |
+| --------- | ------------------------ | ---------------------- |
+| `id`      | `string`                 | BiDi request id        |
+| `url`     | `string`                 | Full URL               |
+| `method`  | `string`                 | `"GET"`, `"POST"`, …   |
+| `headers` | `Record<string, string>` | Request headers        |
+
+### Timeout
+
+Both methods accept `{ timeout?: number }` (defaults to the browser navigation
+timeout, 30 s). On timeout a clear error is thrown:
+
+```
+waitForResponse("**/api/users") timed out after 30000ms
+```
+
+---
+
+## Console & Error Logs
+
+Access browser console output and JavaScript errors via `browser.logs`.
+
+### getMessages()
+
+Get all console messages.
+
+```typescript
+const messages = browser.logs.getMessages();
+
+for (const msg of messages) {
+  console.log(`[${msg.level}] ${msg.text}`);
+}
+```
+
+Each message has:
+
+- `type`: Always `'console'`
+- `level`: `'debug'`, `'info'`, `'warn'`, or `'error'`
+- `text`: The message content
+- `method`: Console method used (`'log'`, `'warn'`, `'error'`, `'info'`, `'debug'`)
+- `args`: Array of arguments passed to console
+- `timestamp`: When the message was logged (Date object)
+- `stackTrace`: Array of stack frames (optional)
+
+### getLogsByLevel(level)
+
+Get logs filtered by level.
+
+```typescript
+// Only warnings
+const warnings = browser.logs.getLogsByLevel('warn');
+
+// Only errors
+const errors = browser.logs.getLogsByLevel('error');
+```
+
+### getErrors()
+
+Get JavaScript errors that occurred on the page.
+
+```typescript
+const errors = browser.logs.getErrors();
+
+for (const error of errors) {
+  console.log(`Error: ${error.text}`);
+  if (error.stackTrace) {
+    for (const frame of error.stackTrace) {
+      console.log(`  at ${frame.functionName} (${frame.url}:${frame.lineNumber})`);
+    }
+  }
+}
+```
+
+Each error has:
+
+- `type`: Always `'javascript'`
+- `level`: Always `'error'`
+- `text`: The error message
+- `timestamp`: When the error occurred (Date object)
+- `stackTrace`: Array of stack frames (optional), each with:
+  - `functionName`: Name of the function
+  - `url`: Source file URL
+  - `lineNumber`: Line number
+  - `columnNumber`: Column number
+
+### clearLogs()
+
+Clear all collected logs (both console messages and errors).
+
+```typescript
+browser.logs.clearLogs();
+```
+
+### onError(handler)
+
+Subscribe to JavaScript errors in real-time.
+
+```typescript
+const unsubscribe = browser.logs.onError((error) => {
+  console.log('JS Error detected:', error.text);
+  // Take screenshot, log to file, etc.
+});
+
+// Later: stop listening
+unsubscribe();
+```
+
+### onConsole(handler)
+
+Subscribe to console messages in real-time.
+
+```typescript
+const unsubscribe = browser.logs.onConsole((msg) => {
+  if (msg.level === 'error') {
+    console.log('Console error:', msg.text);
+  }
+});
+```
+
+### Examples
+
+#### Verify No Console Errors
+
+```typescript
+await browser.navigateTo('https://example.com');
+
+// Interact with the page
+await browser.find('#button').click();
+await browser.pause(1000);
+
+// Verify no errors occurred
+const errors = browser.logs.getErrors();
+expect(errors).toHaveLength(0);
+```
+
+#### Check for Expected Log
+
+```typescript
+await browser.find('#track-event').click();
+
+const messages = browser.logs.getMessages();
+const trackingLogs = messages.filter((m) => m.text.includes('Analytics event:'));
+
+expect(trackingLogs.length).toBeGreaterThan(0);
+```
+
+#### Debug Test Failures
+
+```typescript
+test('form submission', async () => {
+  const browser = await Browser.launch({ browserName: 'chrome' });
+
+  try {
+    await browser.navigateTo('https://example.com/form');
+    await browser.find('#submit').click();
+    await browser.expect('#success').toBeVisible();
+  } catch (error) {
+    // On failure, log browser console output
+    console.log('Console messages:', browser.logs.getMessages());
+    console.log('JS errors:', browser.logs.getErrors());
+    throw error;
+  } finally {
+    await browser.quit();
+  }
+});
+```
+
+---
+
+## Session Storage
+
+Manage cookies and browser storage via `browser.storage`.
+
+### addCookie(cookie)
+
+Add a cookie.
+
+```typescript
+await browser.storage.addCookie({
+  name: 'session_id',
+  value: 'abc123',
+  domain: 'example.com',
+  path: '/',
+  secure: true,
+  httpOnly: true,
+  sameSite: 'Lax',
+  expiry: new Date('2027-01-01'),
+});
+```
+
+### getCookies(filter?)
+
+Get cookies, optionally filtered.
+
+```typescript
+// All cookies
+const cookies = await browser.storage.getCookies();
+
+// Filter by domain
+const sessionCookies = await browser.storage.getCookies({ domain: 'example.com' });
+
+// Cookie value is a plain string
+for (const cookie of cookies) {
+  console.log(`${cookie.name}=${cookie.value}`);
+}
+```
+
+### clearCookies(filter?)
+
+Clear cookies, optionally filtered.
+
+```typescript
+// Clear all cookies
+await browser.storage.clearCookies();
+
+// Clear specific domain
+await browser.storage.clearCookies({ domain: 'example.com' });
+```
+
+### saveState(path, options?) / loadState(path)
+
+Save and restore session state (cookies + localStorage) - Playwright-style persistence.
+
+```typescript
+// Save login session
+await browser.navigateTo('https://example.com/login');
+await browser.find('#username').fill('user');
+await browser.find('#password').fill('pass');
+await browser.find('#submit').click();
+await browser.saveState('./auth.json');
+
+// Later: restore session in new browser
+const browser2 = await Browser.launch({
+  browserName: 'chrome',
+  storageState: './auth.json',
+});
+// Or manually:
+await browser2.loadState('./auth.json');
+```
+
+### saveState options
+
+```typescript
+await browser.saveState('./state.json', {
+  includeCookies: true, // default: true
+  includeLocalStorage: true, // default: true
+  includeSessionStorage: false, // default: false
+  origins: ['https://example.com'], // specific origins only
+});
+```
+
+---
+