craftdriver 1.0.3 → 1.0.4

package/docs/browser-logs.md

@@ -0,0 +1,158 @@
+# Console Logs And JavaScript Errors
+
+Use `browser.logs` to capture what the page writes to the console and what
+JavaScript errors the browser reports. This is useful for failing tests on
+unexpected client-side errors, debugging flaky flows, or asserting that an app
+emitted a known log message.
+
+> **Requires the default browser event connection.** Console and JavaScript
+> error capture requires `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.
+
+## Capture Timing
+
+Capture is lazy by default. CraftDriver subscribes to log events the first time
+you touch `browser.logs.onLog()`, `.onConsole()`, `.onError()`, `.on()`,
+`.waitForConsole()`, or `.waitForError()`.
+
+Messages emitted before that first touch are not captured, so this can return an
+empty array:
+
+```typescript
+await browser.navigateTo('https://example.com');
+const messages = browser.logs.getMessages();
+```
+
+Start capture before the action that logs:
+
+```typescript
+const warning = browser.logs.waitForConsole((msg) => msg.level === 'warn');
+
+await browser.getByRole('button', { name: 'Show warning' }).click();
+expect((await warning).text).toContain('Heads up');
+```
+
+Or start capture immediately at launch:
+
+```typescript
+const browser = await Browser.launch({
+  browserName: 'chrome',
+  captureLogs: true,
+});
+```
+
+## Read Collected Messages
+
+```typescript
+const messages = browser.logs.getMessages();
+
+for (const msg of messages) {
+  console.log(`[${msg.level}] ${msg.text}`);
+}
+```
+
+Each console message has:
+
+| Property | Description |
+| -------- | ----------- |
+| `type` | Always `'console'` |
+| `level` | `'debug'`, `'info'`, `'warn'`, or `'error'` |
+| `text` | Message text |
+| `method` | Console method, such as `'log'`, `'warn'`, or `'error'` |
+| `args` | Arguments passed to `console.*` |
+| `timestamp` | When the message was logged |
+| `stackTrace` | Optional stack frames |
+
+Filter by level:
+
+```typescript
+const warnings = browser.logs.getLogsByLevel('warn');
+const errors = browser.logs.getLogsByLevel('error');
+```
+
+## Read JavaScript Errors
+
+```typescript
+const errors = browser.logs.getErrors();
+
+for (const error of errors) {
+  console.log(`Error: ${error.text}`);
+}
+```
+
+Each JavaScript error has:
+
+| Property | Description |
+| -------- | ----------- |
+| `type` | Always `'javascript'` |
+| `level` | Always `'error'` |
+| `text` | Error message |
+| `timestamp` | When the error occurred |
+| `stackTrace` | Optional stack frames with function, URL, line, and column |
+
+## Wait For A Log Or Error
+
+```typescript
+const consoleMessage = browser.logs.waitForConsole((msg) => {
+  return msg.level === 'info' && msg.text.includes('Saved');
+});
+
+await browser.getByRole('button', { name: 'Save' }).click();
+expect((await consoleMessage).text).toContain('Saved');
+```
+
+```typescript
+const pageError = browser.logs.waitForError((error) => {
+  return error.text.includes('Cannot read properties');
+});
+
+await browser.getByRole('button', { name: 'Trigger error' }).click();
+expect((await pageError).text).toContain('Cannot read properties');
+```
+
+## Subscribe In Real Time
+
+```typescript
+const unsubscribeConsole = browser.logs.onConsole((msg) => {
+  if (msg.level === 'error') {
+    console.log('Console error:', msg.text);
+  }
+});
+
+const unsubscribeErrors = browser.logs.onError((error) => {
+  console.log('JavaScript error:', error.text);
+});
+
+// Later:
+unsubscribeConsole();
+unsubscribeErrors();
+```
+
+## Fail On Unexpected Errors
+
+```typescript
+await browser.navigateTo('https://example.com');
+await browser.getByRole('button', { name: 'Run flow' }).click();
+
+browser.logs.assertNoErrors();
+```
+
+You can also inspect errors yourself:
+
+```typescript
+const errors = browser.logs.getErrors();
+expect(errors).toHaveLength(0);
+```
+
+## Other Helpers
+
+| Method | Description |
+| ------ | ----------- |
+| `onLog(handler)` | Subscribe to all log messages |
+| `on(level, handler)` | Subscribe to one level: `debug`, `info`, `warn`, or `error` |
+| `getLogs()` | Return all captured console and JavaScript error messages |
+| `clearLogs()` | Clear all collected console messages and errors |
+| `waitForConsole(predicate, timeout?)` | Wait for a matching console message |
+| `waitForError(predicate?, timeout?)` | Wait for a JavaScript error |
+| `assertNoErrors()` | Throw if any JavaScript errors were captured |

package/docs/cli.md

@@ -83,21 +83,21 @@ Run `craftdriver --help` for the full list.
 
 CSS is the default. Switch kind with a `prefix=value` form:
 
-| Prefix          | Maps to                                  | Example                              |
-| --------------- | ---------------------------------------- | ------------------------------------ |
-| _none_, `css=`  | `By.css`                                 | `'.product-list li'`                 |
-| `xpath=`        | `By.xpath`                               | `'xpath=//button[1]'`                |
-| `role=`         | `By.role` (+ `[name=...]` for the name)  | `'role=button[name=Submit]'`         |
-| `text=`         | `By.text` (exact)                        | `'text=Sign In'`                     |
-| `text*=`        | `By.partialText`                         | `'text*=Sign'`                       |
-| `label=`        | `By.labelText`                           | `'label=Email'`                      |
-| `placeholder=`  | `By.placeholder`                         | `'placeholder=name@example.com'`     |
-| `alt=`          | `By.altText`                             | `'alt=Logo'`                         |
-| `title=`        | `By.title`                               | `'title=Help'`                       |
-| `testid=`       | `By.testId`                              | `'testid=login-btn'`                 |
-| `id=`           | `By.id`                                  | `'id=submit'`                        |
-| `name=`         | `By.name`                                | `'name=email'`                       |
-| `ref=`          | snapshot ref (`craftdriver snapshot`)    | `'ref=e5'`                           |
+| Prefix         | Maps to                                 | Example                          |
+| -------------- | --------------------------------------- | -------------------------------- |
+| _none_, `css=` | `By.css`                                | `'.product-list li'`             |
+| `xpath=`       | `By.xpath`                              | `'xpath=//button[1]'`            |
+| `role=`        | `By.role` (+ `[name=...]` for the name) | `'role=button[name=Submit]'`     |
+| `text=`        | `By.text` (exact)                       | `'text=Sign In'`                 |
+| `text*=`       | `By.partialText`                        | `'text*=Sign'`                   |
+| `label=`       | `By.labelText`                          | `'label=Email'`                  |
+| `placeholder=` | `By.placeholder`                        | `'placeholder=name@example.com'` |
+| `alt=`         | `By.altText`                            | `'alt=Logo'`                     |
+| `title=`       | `By.title`                              | `'title=Help'`                   |
+| `testid=`      | `By.testId`                             | `'testid=login-btn'`             |
+| `id=`          | `By.id`                                 | `'id=submit'`                    |
+| `name=`        | `By.name`                               | `'name=email'`                   |
+| `ref=`         | snapshot ref (`craftdriver snapshot`)   | `'ref=e5'`                       |
 
 Anything else is treated as a CSS selector, so attribute selectors with
 `=` inside (e.g. `'button[type=submit]'`) work as expected.
@@ -148,11 +148,11 @@ code:  NO_MATCH
 
 ## Exit codes
 
-| Code | Meaning                                                                 |
-| ---- | ----------------------------------------------------------------------- |
-| `0`  | success (or `exists` matched at least one element)                      |
-| `1`  | assertion / timeout / `NO_MATCH` / `exists` matched zero elements       |
-| `2`  | usage error (missing argument, unknown command)                         |
+| Code | Meaning                                                           |
+| ---- | ----------------------------------------------------------------- |
+| `0`  | success (or `exists` matched at least one element)                |
+| `1`  | assertion / timeout / `NO_MATCH` / `exists` matched zero elements |
+| `2`  | usage error (missing argument, unknown command)                   |
 
 ## Fail-fast defaults
 
@@ -221,12 +221,12 @@ For agents that load skills explicitly (Claude Code's Skills system,
 Copilot agent customization, custom orchestrators), the npm tarball
 ships a tiered skill pack under `skills/craftdriver/`:
 
-| File                                                          | Purpose                                                                  |
-| ------------------------------------------------------------- | ------------------------------------------------------------------------ |
-| [`SKILL.md`](../skills/craftdriver/SKILL.md)                  | Always-on, ≤ 500 tokens. Selector order, error-code-first, auto-wait.   |
-| [`cheatsheet.md`](../skills/craftdriver/cheatsheet.md)        | Command-by-command reference for writing tests.                          |
-| [`patterns.md`](../skills/craftdriver/patterns.md)            | Worked recipes (login, upload, network-wait, a11y, tracing, clock).      |
-| [`cli.md`](../skills/craftdriver/cli.md)                      | Agent-facing CLI reference.                                              |
+| File                                                                                                  | Purpose                                                               |
+| ----------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
+| [`SKILL.md`](https://github.com/dtopuzov/craftdriver/blob/main/skills/craftdriver/SKILL.md)           | Always-on, ≤ 500 tokens. Selector order, error-code-first, auto-wait. |
+| [`cheatsheet.md`](https://github.com/dtopuzov/craftdriver/blob/main/skills/craftdriver/cheatsheet.md) | Command-by-command reference for writing tests.                       |
+| [`patterns.md`](https://github.com/dtopuzov/craftdriver/blob/main/skills/craftdriver/patterns.md)     | Worked recipes (login, upload, network-wait, a11y, tracing, clock).   |
+| [`cli.md`](https://github.com/dtopuzov/craftdriver/blob/main/skills/craftdriver/cli.md)               | Agent-facing CLI reference.                                           |
 
 Point your agent at `node_modules/craftdriver/skills/craftdriver/SKILL.md`
 or copy it into your project. The other files are referenced from

package/docs/element-api.md

@@ -9,8 +9,10 @@ The `ElementHandle` provides methods for interacting with individual DOM element
 const element = browser.find('#my-element');
 const button = browser.find(By.text('Submit'));
 
-// Chained operations
-await browser.find('#input').fill('text').press('Enter');
+// Element-scoped operations
+const input = browser.find('#input');
+await input.fill('text');
+await input.press('Enter');
 ```
 
 > **Tip:** Use `browser.locator(selector)` instead of `find()` when you need
@@ -99,6 +101,14 @@ Get the current value of an input element.
 const inputValue = await browser.find('#email').value();
 ```
 
+### tagName()
+
+Get the element tag name.
+
+```typescript
+const tag = await browser.find('#submit').tagName(); // "button"
+```
+
 ### getAttribute(name)
 
 Get an attribute value from the element.
@@ -166,14 +176,35 @@ await browser.find('#message').expect().toHaveText('Success');
 await browser.find('#input').expect().toHaveValue('test@example.com');
 ```
 
-## Method Chaining
+### setInputFiles(filePaths, options?)
+
+Set files on an `<input type="file">`.
+
+```typescript
+await browser.find('#avatar').setInputFiles('/absolute/path/avatar.png');
+await browser.find('#photos').setInputFiles([
+  '/absolute/path/one.jpg',
+  '/absolute/path/two.jpg',
+]);
+```
+
+### evaluate(fn, ...args)
 
-ElementHandle methods that don't return values can be chained:
+Run JavaScript with this element as the first argument.
 
 ```typescript
-await browser.find('#username').fill('testuser').press('Tab');
+const tag = await browser.find('#submit').evaluate(el => el.tagName.toLowerCase());
+const active = await browser
+  .find('#submit')
+  .evaluate((el, cls) => el.classList.contains(cls), 'active');
+```
 
-await browser.find('#password').fill('secret123').press('Enter');
+### a11y
+
+Run an accessibility audit scoped to this element and its descendants.
+
+```typescript
+const result = await browser.find('#checkout').a11y.audit();
 ```
 
 ## Examples

package/docs/emulation.md

@@ -65,7 +65,9 @@ JavaScript-only patch.
 await browser.emulate({ colorScheme: 'dark' });
 await browser.navigateTo('https://app.example.com');
 
-const bg = await browser.find('body').getCssValue('background-color');
+const bg = await browser.evaluate(() =>
+  getComputedStyle(document.body).backgroundColor
+);
 expect(bg).toBe('rgb(17, 17, 17)');
 ```
 
@@ -108,7 +110,9 @@ Confirm animations are actually suppressed for users who request it.
 await browser.emulate({ reducedMotion: 'reduce' });
 await browser.navigateTo('https://app.example.com');
 
-const anim = await browser.find('.hero').getCssValue('animation-name');
+const anim = await browser.evaluate(() =>
+  getComputedStyle(document.querySelector('.hero')!).animationName
+);
 expect(anim).toBe('none');
 ```
 

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