craftdriver 0.0.3 → 0.2.0

package/docs/element-api.md

@@ -0,0 +1,219 @@
+# Element API
+
+The `ElementHandle` provides methods for interacting with individual DOM elements.
+
+## Getting an ElementHandle
+
+```typescript
+// Via browser.find()
+const element = browser.find('#my-element');
+const button = browser.find(By.text('Submit'));
+
+// Chained operations
+await browser.find('#input').fill('text').press('Enter');
+```
+
+> **Tip:** Use `browser.locator(selector)` instead of `find()` when you need
+> composition, filtering, or indexed access (`.nth()`, `.filter()`, `.all()`).
+> See [Selectors & Locators](./selectors.md#locators-lazy--chainable).
+
+## Methods
+
+### click()
+
+Click on the element.
+
+```typescript
+await browser.find('#button').click();
+```
+
+### fill(text, options?)
+
+Fill a text input with the given value.
+
+```typescript
+await browser.find('#username').fill('testuser');
+
+// With options
+await browser.find('#email').fill('test@example.com', { timeout: 5000 });
+```
+
+### clear(options?)
+
+Clear the input value.
+
+```typescript
+await browser.find('#search').clear();
+```
+
+### press(key)
+
+Press a keyboard key while focused on the element.
+
+```typescript
+await browser.find('#input').press('Enter');
+await browser.find('#textarea').press('Tab');
+await browser.find('#field').press('Backspace');
+```
+
+Available keys: `'Enter'`, `'Tab'`, `'Escape'`, `'Backspace'`, `'ArrowUp'`, `'ArrowDown'`, `'ArrowLeft'`, `'ArrowRight'`, etc.
+
+### hover(options?)
+
+Move the mouse to hover over the element.
+
+```typescript
+// Reveal a tooltip
+await browser.find('#info-icon').hover();
+
+// Open a dropdown menu on hover
+await browser.find('.menu-trigger').hover();
+await browser.find('.menu-item').click();
+```
+
+### select(value, options?)
+
+Select an option from a `<select>` dropdown by value.
+
+```typescript
+await browser.find('#country').select('us');
+await browser.find('#language').select('en');
+```
+
+> ⚠️ **Note:** This method only works on `<select>` elements. It will throw an error if used on other element types.
+
+### text()
+
+Get the visible text content of the element.
+
+```typescript
+const message = await browser.find('#result').text();
+console.log(message); // "Success!"
+```
+
+### value()
+
+Get the current value of an input element.
+
+```typescript
+const inputValue = await browser.find('#email').value();
+```
+
+### getAttribute(name)
+
+Get an attribute value from the element.
+
+```typescript
+const href = await browser.find('a.link').getAttribute('href');
+const disabled = await browser.find('#btn').getAttribute('disabled');
+```
+
+### isVisible()
+
+Check if the element is visible on the page.
+
+```typescript
+const visible = await browser.find('#modal').isVisible();
+if (visible) {
+  await browser.find('#modal .close').click();
+}
+```
+
+### isEnabled()
+
+Check if the element is enabled (not disabled).
+
+```typescript
+const enabled = await browser.find('#submit').isEnabled();
+```
+
+### isChecked()
+
+Check if a checkbox or radio button is checked.
+
+```typescript
+const checked = await browser.find('#agree-terms').isChecked();
+```
+
+### boundingBox()
+
+Get the element's position and size.
+
+```typescript
+const box = await browser.find('#target').boundingBox();
+// { x: 100, y: 200, width: 300, height: 50 }
+```
+
+### screenshot(opts?)
+
+Take a screenshot of just this element. Returns the PNG bytes as a
+`Buffer`; pass `path` to also write the file in one step.
+
+```typescript
+// Get as buffer
+const buffer = await browser.find('#chart').screenshot();
+
+// Save to file
+await browser.find('#logo').screenshot({ path: 'logo.png' });
+```
+
+### expect()
+
+Get an ExpectApi scoped to this element for assertions.
+
+```typescript
+await browser.find('#message').expect().toHaveText('Success');
+await browser.find('#input').expect().toHaveValue('test@example.com');
+```
+
+## Method Chaining
+
+ElementHandle methods that don't return values can be chained:
+
+```typescript
+await browser.find('#username').fill('testuser').press('Tab');
+
+await browser.find('#password').fill('secret123').press('Enter');
+```
+
+## Examples
+
+### Form Filling
+
+```typescript
+await browser.find('#first-name').fill('John');
+await browser.find('#last-name').fill('Doe');
+await browser.find('#email').fill('john@example.com');
+await browser.find('#country').select('us');
+await browser.find('#agree-terms').click();
+await browser.find('#submit').click();
+```
+
+### Hover Interactions
+
+```typescript
+// Reveal dropdown menu
+await browser.find('#user-menu').hover();
+await browser.find('#logout-link').click();
+```
+
+### Conditional Actions
+
+```typescript
+const modal = browser.find('#cookie-banner');
+if (await modal.isVisible()) {
+  await browser.find('#accept-cookies').click();
+}
+```
+
+### Getting Element State
+
+```typescript
+const button = browser.find('#submit');
+
+const text = await button.text();
+const enabled = await button.isEnabled();
+const visible = await button.isVisible();
+
+console.log({ text, enabled, visible });
+```

package/docs/emulation.md

@@ -0,0 +1,155 @@
+# Emulation
+
+`browser.emulate(options)` overrides what a page sees from `matchMedia`,
+`navigator.language`, `Intl.*`, and the network stack. One ergonomic method,
+six independent knobs.
+
+```typescript
+import { Browser } from 'craftdriver';
+
+const browser = await Browser.launch({ browserName: 'chrome' });
+
+await browser.emulate({
+  colorScheme: 'dark',
+  locale: 'de-DE',
+  timezoneId: 'Europe/Berlin',
+});
+```
+
+> **BiDi required.** All emulation overrides use BiDi commands
+> (`enableBiDi: true`, the default). Calling `emulate()` with BiDi
+> disabled throws. CSS media features and `offline` additionally require
+> Chromium (see the cross-browser column below).
+
+## Options
+
+| Option | What the page sees | Transport | Cross-browser |
+|---|---|---|---|
+| `colorScheme` | `prefers-color-scheme` media query | BiDi + CDP `Emulation.setEmulatedMedia` | Chromium only |
+| `reducedMotion` | `prefers-reduced-motion` media query | BiDi + CDP `Emulation.setEmulatedMedia` | Chromium only |
+| `forcedColors` | `forced-colors` media query | BiDi + CDP `Emulation.setEmulatedMedia` | Chromium only |
+| `locale` | `navigator.language`, `Intl.*` formatting | BiDi `emulation.setLocaleOverride` | yes |
+| `timezoneId` | `Intl.DateTimeFormat`, `Date` offsets | BiDi `emulation.setTimezoneOverride` | yes |
+| `offline` | `navigator.onLine`, network stack | BiDi + CDP `Network.emulateNetworkConditions` | Chromium only |
+
+- Pass `null` for any field to clear that override.
+- Calling `emulate({})` is a no-op.
+- Settings persist across navigations in the same session.
+
+### Type
+
+```typescript
+interface EmulateOptions {
+  colorScheme?: 'light' | 'dark' | 'no-preference' | null;
+  reducedMotion?: 'reduce' | 'no-preference' | null;
+  forcedColors?: 'active' | 'none' | null;
+  locale?: string | null;        // BCP-47, e.g. 'de-DE'
+  timezoneId?: string | null;    // IANA, e.g. 'Europe/Berlin'
+  offline?: boolean;
+}
+```
+
+## Use cases
+
+### Dark mode rendering
+
+Verify your theme renders correctly without flipping the OS preference.
+Real CSS `@media (prefers-color-scheme: dark)` rules apply — this is not a
+JavaScript-only patch.
+
+```typescript
+await browser.emulate({ colorScheme: 'dark' });
+await browser.navigateTo('https://app.example.com');
+
+const bg = await browser.find('body').getCssValue('background-color');
+expect(bg).toBe('rgb(17, 17, 17)');
+```
+
+### Offline PWA / service-worker fallback
+
+Confirm your offline banner appears and cached pages still load when the
+network drops.
+
+```typescript
+await browser.navigateTo('https://pwa.example.com');
+await browser.emulate({ offline: true });
+
+await browser.click('#refresh');
+await browser.expect('#offline-banner').toBeVisible();
+
+await browser.emulate({ offline: false });
+```
+
+### Locale + timezone formatting bugs
+
+Catch number/date/currency rendering issues without spinning up a fresh
+browser for each locale.
+
+```typescript
+await browser.emulate({ locale: 'de-DE', timezoneId: 'Europe/Berlin' });
+await browser.navigateTo('https://shop.example.com/cart');
+
+// "12,50 €" instead of "$12.50"
+await browser.expect('#total').toHaveText('12,50 €');
+
+// "Liefertermin" in German, Berlin-local cutoff time
+await browser.expect('#delivery-cutoff').toContainText('18:00');
+```
+
+### Reduced motion (a11y regression)
+
+Confirm animations are actually suppressed for users who request it.
+
+```typescript
+await browser.emulate({ reducedMotion: 'reduce' });
+await browser.navigateTo('https://app.example.com');
+
+const anim = await browser.find('.hero').getCssValue('animation-name');
+expect(anim).toBe('none');
+```
+
+### Forced colors (Windows high-contrast)
+
+Catch buttons that lose their outline or icons that disappear when the OS
+forces a high-contrast palette.
+
+```typescript
+await browser.emulate({ forcedColors: 'active' });
+await browser.navigateTo('https://app.example.com');
+
+await browser.expect('button.primary').toBeVisible();
+```
+
+## Clearing overrides
+
+Pass `null` (or `false` for `offline`) to revert a single field. Other
+fields stay as-is.
+
+```typescript
+await browser.emulate({ locale: 'de-DE', timezoneId: 'Europe/Berlin' });
+
+// Clear the timezone, keep the locale
+await browser.emulate({ timezoneId: null });
+
+// Clear everything you may have set
+await browser.emulate({
+  colorScheme: null,
+  reducedMotion: null,
+  forcedColors: null,
+  locale: null,
+  timezoneId: null,
+  offline: false,
+});
+```
+
+## Errors
+
+- **`emulate() requires BiDi`** — you launched with `enableBiDi: false`.
+  Re-enable BiDi.
+- **`emulate({ colorScheme }) is not supported on Firefox yet`** — the
+  CSS-media-feature and `offline` paths currently use the BiDi+CDP
+  bridge, which only Chromium exposes. Use `locale` / `timezoneId` on
+  Firefox, or run the test on Chrome/Chromium.
+- **`CDP command \`...\` failed`** — usually means the browser is not a
+  Chromium build with the BiDi+CDP bridge enabled. Confirm
+  `browserName: 'chrome'` or `'chromium'`.

package/docs/error-codes.md

@@ -0,0 +1,67 @@
+# Error codes
+
+Every error thrown from the public craftdriver API is a
+[`CraftdriverError`](../src/lib/errors.ts), carrying:
+
+- `code` — a stable, machine-readable identifier from the table below.
+- `message` — human-readable summary.
+- `detail` — JSON-serializable structured context (selector, timeout,
+  candidates, etc.). Safe to log or send to an LLM.
+- `hint` — one-line remediation when there is an obvious next step.
+
+`CraftdriverError extends Error`, so `instanceof Error` keeps working
+and stack traces are preserved.
+
+```ts
+import { CraftdriverError, ErrorCode } from 'craftdriver';
+
+try {
+  await browser.locator('#missing').click();
+} catch (err) {
+  if (CraftdriverError.is(err, ErrorCode.NO_MATCH)) {
+    // Selector matched zero elements — fix the selector.
+    console.error(err.detail);
+  }
+}
+```
+
+## Codes
+
+| Code | When it fires | Typical recovery |
+|---|---|---|
+| `NO_MATCH` | Selector matched zero elements within the timeout. | Fix the selector. Prefer `By.testId` / `By.role` / `By.labelText` over CSS for resilience. |
+| `TIMEOUT_WAITING_VISIBLE` | Selector matched an element, but it never became visible within the timeout. | Open the containing view first (modal, accordion, tab). The element is in the DOM but not displayed. |
+| `TIMEOUT_WAITING_STATE` | Element visible but never reached the requested state (`enabled`, `checked`, `attached`, `detached`, `hidden`). | Wait for the precondition that drives the state transition. |
+| `TIMEOUT_WAITING_LOAD` | Page never reached the requested load state (`load` / `domcontentloaded` / `networkidle`). | Bump the navigation timeout, or wait on a stable DOM signal instead. |
+| `TIMEOUT_WAITING_NETWORK` | A specific request / response / network-idle predicate did not resolve. | Verify the predicate matches the real traffic; widen with a regex. |
+| `TIMEOUT_WAITING_DIALOG` | `waitForDialog()` did not see a dialog of the expected type. | Confirm the action under test actually opens the dialog. |
+| `TIMEOUT` | Generic `WebDriverWait.until(...)` timeout with no more specific code. | Same as above — check the condition. |
+| `EXPECT_MISMATCH` | An `expect(locator).to…()` assertion failed after auto-waiting. | Inspect `error.detail` for the selector and observed value. |
+| `A11Y_VIOLATIONS` | `browser.a11y.check()` (or scoped variants) found axe-core violations. | Iterate over `error.violations` — each has an `id`, `impact`, and `helpUrl`. |
+| `EVAL_THREW` | The function passed to `evaluate()` threw inside the page. | The page-side exception text is in `error.detail.exception`. |
+| `EVAL_BAD_ARG` | `evaluate()` / `addInitScript()` received a non-JSON-serializable argument (function, Symbol, DOM node…). | Pass plain JSON values. |
+| `INVALID_ARGUMENT` | Caller passed an invalid value (bad enum, wrong shape, unparseable duration…). | Read the message; it lists the accepted forms. |
+| `UNSUPPORTED` | Feature exists but is unavailable on this browser/transport (e.g. Chromium-only over Firefox, or a BiDi-only feature with BiDi disabled). | Enable BiDi (`enableBiDi: true`) or switch browser. |
+| `STATE_INVALID` | Method called in the wrong state (e.g. `stopTrace()` without `startTrace()`, `clock.tick()` before `install()`). | Call the prerequisite first. |
+| `DRIVER_ERROR` | Driver-level / transport-level failure surfaced to the caller. | Inspect `error.cause`. |
+
+## Stability
+
+- Codes are **append-only**. New ones may be added; existing ones are
+  never renamed or repurposed.
+- `code` strings are case-sensitive and stable across patch releases.
+- `detail` keys are additive: new keys may appear; existing keys keep
+  their meaning.
+
+## Distinguishing the three common probe failures
+
+This is the highest-leverage distinction for agents:
+
+- **`NO_MATCH`** — your selector is wrong.
+- **`TIMEOUT_WAITING_VISIBLE`** — the element is there; you opened the
+  page too early or skipped a UI step that reveals it.
+- **`TIMEOUT_WAITING_STATE`** — the element is visible; you tried to
+  act on it before it was ready (still disabled, still loading…).
+
+Each one points at a different fix. Today's prose-only error collapses
+all three, which is exactly why naive recovery loops loop.

package/docs/getting-started.md

@@ -0,0 +1,168 @@
+# Getting Started
+
+## Installation
+
+```bash
+npm install craftdriver --save-dev
+```
+
+## Your First Test
+
+```typescript
+import { Browser } from 'craftdriver';
+
+async function main() {
+  // Launch browser
+  const browser = await Browser.launch({ browserName: 'chrome' });
+
+  try {
+    // Navigate to a page
+    await browser.navigateTo('https://example.com');
+
+    // Get page title
+    const title = await browser.title();
+    console.log('Page title:', title);
+
+    // Click a link
+    await browser.click('a');
+
+    // Fill a form
+    await browser.fill('#email', 'test@example.com');
+    await browser.click('#submit');
+
+    // Assert result
+    await browser.expect('#message').toHaveText('Success!');
+  } finally {
+    await browser.quit();
+  }
+}
+
+main();
+```
+
+## `browser.X()` vs `page.X()` — when to use which
+
+`browser.click()`, `browser.find()`, `browser.fill()`, `browser.evaluate()`
+and the other DOM-touching shortcuts on `Browser` are sugar for
+`(await browser.activePage()).X(...)`. They always target the focused
+page in `browser.defaultContext`. They never cross into a `Page` that
+lives inside a context returned by `browser.newContext()`.
+
+For single-tab tests this is exactly what you want — the shortcuts keep
+your code short:
+
+```typescript
+await browser.navigateTo('https://example.com');
+await browser.click('#submit');
+```
+
+For multi-tab or multi-user tests, get a `Page` explicitly:
+
+```typescript
+// Multi-tab
+const page = await browser.openPage({ url: '/help', type: 'tab' });
+await page.click('#close');           // unambiguous
+
+// Multi-user (isolated profiles)
+const alice = await browser.newContext();
+const aPage = await alice.newPage({ url: '/login' });
+await aPage.fill('#user', 'alice');   // browser.fill() would target the
+                                      // default context, NOT alice.
+```
+
+If you need to be explicit even in single-tab code, `browser.activePage()`
+returns the same `Page` the shortcuts would target.
+
+## Launch Options
+
+```typescript
+// Chrome (default)
+const browser = await Browser.launch({
+  browserName: 'chrome', // 'chrome' | 'chromium' | 'firefox'
+  storageState: './session.json', // optional: pre-load saved session state
+});
+
+// Firefox
+const browser = await Browser.launch({
+  browserName: 'firefox',
+});
+```
+
+### Running tests on Firefox
+
+Set `BROWSER_NAME=firefox` before running your test command:
+
+```bash
+BROWSER_NAME=firefox npx vitest run
+# or use the built-in script if your package.json has it:
+npm run test:firefox
+```
+
+### Custom WebDriver binary or port
+
+`Browser.launch()` resolves the driver binary automatically. To pin a
+specific binary, change the host/port, or pass extra command-line
+arguments to the driver, construct a `ChromeService` or `FirefoxService`
+and pass it via `chromeService` / `firefoxService`:
+
+```typescript
+import { Browser, ChromeService, FirefoxService } from 'craftdriver';
+
+// Pin a specific chromedriver binary on a fixed port
+const browser = await Browser.launch({
+  browserName: 'chrome',
+  chromeService: new ChromeService({
+    binaryPath: '/opt/chromedriver/chromedriver',
+    port: 9515,
+    hostname: '127.0.0.1',
+    args: ['--log-level=ALL'],
+  }),
+});
+
+// Custom geckodriver path for Firefox
+const ff = await Browser.launch({
+  browserName: 'firefox',
+  firefoxService: new FirefoxService({
+    binaryPath: '/usr/local/bin/geckodriver',
+  }),
+});
+```
+
+Without an explicit `binaryPath`, both services check (in order) the
+matching env var (`CHROMEDRIVER_PATH` / `GECKODRIVER_PATH`),
+`node_modules/.bin/`, then `$PATH`. If `port` is omitted, a free port
+is picked automatically.
+
+## With Vitest
+
+```typescript
+import { describe, it, beforeEach, afterEach } from 'vitest';
+import { Browser } from 'craftdriver';
+
+describe('My App', () => {
+  let browser: Browser;
+
+  beforeEach(async () => {
+    browser = await Browser.launch({ browserName: 'chrome' });
+  });
+
+  afterEach(async () => {
+    await browser.quit();
+  });
+
+  it('shows welcome message after login', async () => {
+    await browser.navigateTo('http://localhost:3000/login');
+    await browser.fill('#username', 'testuser');
+    await browser.fill('#password', 'password123');
+    await browser.click('#login-btn');
+
+    await browser.expect('#welcome').toContainText('Hello, testuser');
+  });
+});
+```
+
+## Next Steps
+
+- [Browser API](./browser-api.md) - Full browser control reference
+- [Selectors](./selectors.md) - Finding elements with CSS, XPath, and semantic locators
+- [Session Management](./session-management.md) - Save/restore login sessions