craftdriver 0.1.0 → 0.2.0

package/skills/craftdriver/cheatsheet.md

@@ -0,0 +1,194 @@
+# craftdriver — cheatsheet
+
+Compact reference for writing tests. Pair with
+[docs/api-reference.md](../../docs/api-reference.md) for the full export
+list.
+
+## Launch & teardown
+
+```ts
+import { Browser } from 'craftdriver';
+
+const browser = await Browser.launch({
+  browserName: 'chrome',   // 'chrome' | 'chromium' | 'firefox'
+  headless: true,
+  enableBiDi: true,        // required for network / logs / tracing / init scripts
+});
+try {
+  await browser.navigateTo('https://example.com');
+  // ...
+} finally {
+  await browser.quit();    // never wrap in try/catch in tests
+}
+```
+
+## Navigation
+
+```ts
+await browser.navigateTo(url, { waitUntil: 'load' | 'domcontentloaded' | 'networkidle' });
+await browser.goBack();
+await browser.goForward();
+await browser.reload();
+await browser.waitForLoadState('load');
+```
+
+## Selectors
+
+```ts
+import { By } from 'craftdriver';
+
+By.testId('submit')                  // [data-testid="submit"]  ← preferred
+By.role('button', { name: /save/i }) // ARIA role + accessible name
+By.labelText('Email')                // form label
+By.text('Sign in', { exact: true })  // visible text
+By.css('button.primary')             // last resort
+By.xpath('//button')                 // never if anything else works
+```
+
+## Locators (Playwright-style)
+
+```ts
+const submit = browser.locator(By.role('button', { name: 'Submit' }));
+
+await submit.click();                     // auto-waits visible
+await submit.fill('hello');               // click + clear + type
+await submit.hover();
+await submit.expect().toBeVisible();
+await submit.expect().toHaveText('Submit');
+await submit.expect().toBeEnabled();
+
+// composition
+const row = browser.locator('.row').filter({ hasText: 'Acme' }).first();
+const cells = await row.locator('td').all();
+const count = await row.locator('td').count();   // 0-wait probe
+```
+
+## Element handles
+
+```ts
+const el = await browser.find(By.css('#submit'));
+await el.click();
+await el.sendKeys('hello');
+await el.clear();
+const text = await el.getText();
+const value = await el.getValue();
+const tag = await el.tagName();
+const isVisible = await el.isDisplayed();
+```
+
+## Assertions (`expect`)
+
+```ts
+await browser.locator('h1').expect().toHaveText(/welcome/i);
+await browser.locator('input').expect().toHaveValue('jane@example.com');
+await browser.locator('button').expect().toBeEnabled();
+await browser.locator('.spinner').expect().not.toBeVisible();
+```
+
+Every `expect(...).to…()` auto-waits up to the default timeout. Bump
+per-call with `{ timeout: 10_000 }`.
+
+## Errors
+
+```ts
+import { CraftdriverError, ErrorCode } from 'craftdriver';
+
+try {
+  await browser.locator('#missing').click();
+} catch (err) {
+  if (CraftdriverError.is(err, ErrorCode.NO_MATCH)) {
+    // selector is wrong — see err.detail.selector / err.hint
+  }
+}
+```
+
+Codes: `NO_MATCH`, `TIMEOUT_WAITING_VISIBLE`, `TIMEOUT_WAITING_STATE`,
+`TIMEOUT_WAITING_LOAD`, `TIMEOUT_WAITING_NETWORK`,
+`TIMEOUT_WAITING_DIALOG`, `TIMEOUT`, `EXPECT_MISMATCH`,
+`A11Y_VIOLATIONS`, `EVAL_THREW`, `EVAL_BAD_ARG`, `INVALID_ARGUMENT`,
+`UNSUPPORTED`, `STATE_INVALID`, `DRIVER_ERROR`. Full table:
+[docs/error-codes.md](../../docs/error-codes.md).
+
+## Pages and contexts
+
+```ts
+const ctx = await browser.newContext();    // isolated profile (BiDi)
+const page = await ctx.newPage();
+await page.navigateTo(url);
+
+const pages = browser.pages();
+const fresh = await browser.waitForPage(() => browser.click('a[target=_blank]'));
+```
+
+## Network (BiDi)
+
+```ts
+await browser.network.intercept({ url: '**/api/users', response: { status: 200, body: '[]' } });
+const req = await browser.waitForRequest((r) => r.url.includes('/api/login'));
+const res = await browser.waitForResponse((r) => r.url.includes('/api/me'));
+await browser.network.waitForNetworkIdle();
+```
+
+## Logs (BiDi)
+
+```ts
+const logs = browser.logs.consoleMessages();
+const errors = browser.logs.javaScriptErrors();
+```
+
+## Input
+
+```ts
+await browser.keyboard.press('Enter');
+await browser.keyboard.type('hello');
+await browser.mouse.move({ x: 100, y: 100 });
+await browser.mouse.click({ x: 100, y: 100 });
+await browser.actions().keyDown('Shift').click(el).keyUp('Shift').perform();
+```
+
+## Files
+
+```ts
+await element.setInputFiles('./fixtures/sample.txt');
+const download = await browser.waitForDownload(() => browser.click('#download'));
+```
+
+## Screenshots & tracing
+
+```ts
+await browser.screenshot({ path: 'out.png', fullPage: true });
+
+await browser.startTrace({ outDir: './artefacts/run' });
+try { /* ... */ } finally { await browser.stopTrace(); }
+```
+
+## Accessibility
+
+```ts
+const result = await browser.a11y.audit();       // returns violations
+await browser.a11y.check();                       // throws A11yError if any
+```
+
+## Virtual clock
+
+```ts
+await browser.clock.install({ time: '2026-01-01T00:00:00Z' });
+await browser.clock.tick(1000);
+await browser.clock.fastForward('05:00');         // 5 minutes
+await browser.clock.uninstall();
+```
+
+## Emulation
+
+```ts
+await browser.emulate({
+  colorScheme: 'dark',
+  reducedMotion: 'reduce',
+  locale: 'fr-FR',
+  timezoneId: 'Europe/Paris',
+  offline: true,
+});
+await browser.setViewportSize({ width: 1280, height: 720 });
+await browser.setGeolocation({ latitude: 48.85, longitude: 2.35 });
+await browser.grantPermissions(['geolocation']);
+```

package/skills/craftdriver/cli.md

@@ -0,0 +1,104 @@
+# craftdriver CLI
+
+The `craftdriver` binary is what you reach for from a **shell**, not from
+TypeScript. Use it for probing, debugging, and agent-driven exploration.
+
+## Install once
+
+```bash
+npm install craftdriver
+npx craftdriver --help
+```
+
+## Daemon model (preferred)
+
+Long-lived browser; each command is a one-shot RPC. State (page,
+cookies, storage) survives between calls.
+
+```bash
+npx craftdriver daemon start
+npx craftdriver go http://127.0.0.1:8080/login.html
+npx craftdriver click 'button[type=submit]'
+npx craftdriver daemon stop
+```
+
+If no daemon is running, the first command auto-starts one. Use
+`daemon start` explicitly when you want a non-default browser
+(`--browser firefox`) or a specific timing.
+
+## Ephemeral mode (sandboxed agents)
+
+```bash
+printf 'go http://127.0.0.1:8080/login.html
+fill "#user" alice
+click "button[type=submit]"
+text "#result"
+' | npx craftdriver --ephemeral
+```
+
+One short-lived browser for the whole script. No daemon, no socket.
+
+## Commands you actually use
+
+```
+go <url>                navigate active page
+find <sel> [--all]      first match (or all); pretty-prints index + tag + text
+exists <sel>            0-wait probe; exit 0 = match, exit 1 = none
+click <sel>
+fill <sel> <value>
+press <key> [sel]
+hover <sel>
+text [sel]              page text or element text
+attr <sel> <name>
+value <sel>
+is visible|enabled|checked <sel>
+wait <sel> [--state visible|hidden|attached|detached] [--timeout ms]
+wait load [--state load|domcontentloaded|networkidle]
+pages
+screenshot [-o out.png] [--full-page] [--selector sel]
+eval <js>               last resort
+back | forward | reload | status | quit
+daemon start|status|stop
+```
+
+## Selector syntax
+
+CSS by default. Switch kind with `prefix=value`:
+
+```
+role=button[name=Submit]   text=Sign In            text*=Sign
+label=Email                placeholder=Search…     testid=login-btn
+alt=Logo                   title=Help              xpath=//div[1]
+id=submit                  name=email              tag=h1
+```
+
+Anything else (including CSS attribute selectors like
+`button[type=submit]`) is parsed as CSS.
+
+## Output
+
+- TTY → human-readable text.
+- Piped or redirected → `{"ok":true,"result":…}` per line.
+- Force with `--json` or `--pretty`.
+- Errors include a stable `code:` line (same codes as the library
+  — see `docs/error-codes.md`). Use the code, not the prose.
+
+## Exit codes
+
+- `0` success (or `exists` matched ≥ 1)
+- `1` assertion / timeout / `NO_MATCH` / `exists` matched zero
+- `2` usage error
+
+## Defaults
+
+- 5 s per-call timeout (override with `--timeout ms` or
+  `CRAFTDRIVER_AGENT_TIMEOUT`).
+- Probe with `exists` before `click`/`wait` when you're guessing.
+- Don't `sleep`. `wait <sel>` is auto-waiting; `wait load` waits on
+  document state.
+
+## When NOT to use the CLI
+
+Writing a test suite. Use the library (`import { Browser } from
+'craftdriver'`) — it has 30 s default timeouts, full TS types, and
+chainable `Locator` ergonomics.

package/skills/craftdriver/patterns.md

@@ -0,0 +1,139 @@
+# craftdriver — patterns
+
+Worked recipes. Each is ≤ ~200 tokens; load on demand from
+[SKILL.md](SKILL.md).
+
+## 1. Login, save storage state for reuse
+
+```ts
+const browser = await Browser.launch({ enableBiDi: true });
+await browser.navigateTo('https://app.example.com/login');
+await browser.locator(By.labelText('Email')).fill('jane@example.com');
+await browser.locator(By.labelText('Password')).fill(process.env.PW!);
+await browser.locator(By.role('button', { name: 'Sign in' })).click();
+await browser.locator(By.testId('dashboard')).expect().toBeVisible();
+
+// Persist for fast subsequent runs.
+const state = await browser.defaultContext.storageState();
+await fs.writeFile('.auth/state.json', JSON.stringify(state));
+await browser.quit();
+```
+
+## 2. Re-use saved login
+
+```ts
+const state = JSON.parse(await fs.readFile('.auth/state.json', 'utf8'));
+const browser = await Browser.launch({
+  enableBiDi: true,
+  storageState: state,
+});
+await browser.navigateTo('https://app.example.com/dashboard');
+await browser.locator(By.testId('dashboard')).expect().toBeVisible();
+```
+
+## 3. Wait for a network response after a click
+
+```ts
+const [response] = await Promise.all([
+  browser.waitForResponse((r) => r.url.includes('/api/checkout') && r.status === 200),
+  browser.locator(By.role('button', { name: 'Pay' })).click(),
+]);
+const body = await response.text();
+```
+
+## 4. Upload a file
+
+```ts
+const input = await browser.find(By.css('input[type=file]'));
+await input.setInputFiles('./fixtures/contract.pdf');
+await browser.locator(By.role('button', { name: 'Upload' })).click();
+await browser.locator(By.text('Upload complete')).expect().toBeVisible();
+```
+
+## 5. Scoped text reads (one row of a table)
+
+```ts
+const row = browser.locator('tr').filter({ hasText: 'Acme Inc.' }).first();
+const status = await row.locator('[data-col=status]').text();
+const due = await row.locator('[data-col=due]').text();
+```
+
+## 6. Capture a failure trace for an agent or bug report
+
+```ts
+await browser.startTrace({
+  outDir: './artefacts/checkout-fail',
+  screenshots: 'auto',
+  network: true,
+  console: true,
+});
+try {
+  await runFlow(browser);
+} catch (e) {
+  // Trace lands on disk regardless — thrown expects never lose data.
+  throw e;
+} finally {
+  await browser.stopTrace();
+}
+```
+
+## 7. Mock an API for deterministic tests
+
+```ts
+await browser.network.intercept({
+  url: '**/api/users',
+  response: { status: 200, body: JSON.stringify([{ id: 1, name: 'Jane' }]) },
+});
+await browser.navigateTo('/users');
+await browser.locator(By.text('Jane')).expect().toBeVisible();
+```
+
+## 8. Recovery loop on a flaky element
+
+Don't write retry loops by hand — `expect()` already retries. Only
+catch a `CraftdriverError` when you have a meaningful fallback:
+
+```ts
+import { CraftdriverError, ErrorCode } from 'craftdriver';
+
+try {
+  await browser.locator(By.testId('cookie-banner-accept')).click({ timeout: 2000 });
+} catch (e) {
+  if (!CraftdriverError.is(e, ErrorCode.NO_MATCH)) throw e;
+  // Banner not shown this session — proceed.
+}
+```
+
+## 9. Multi-page (popup or new tab)
+
+```ts
+const popup = await browser.waitForPage(() =>
+  browser.locator(By.text('Open in new tab')).click()
+);
+await popup.locator(By.role('heading', { name: 'Details' })).expect().toBeVisible();
+```
+
+## 10. iframe scoping
+
+```ts
+const frame = await browser.frame('iframe#checkout');
+await frame.locator(By.labelText('Card number')).fill('4242 4242 4242 4242');
+```
+
+## 11. Accessibility gate in CI
+
+```ts
+await browser.navigateTo('/checkout');
+const result = await browser.a11y.audit({ minImpact: 'serious' });
+expect(result.violations).toEqual([]);
+```
+
+## 12. Virtual clock — exercise a debounce
+
+```ts
+await browser.clock.install({ time: '2026-01-01T00:00:00Z' });
+await browser.locator(By.css('#search')).fill('jane');
+await browser.clock.tick(300);  // skip the 300 ms debounce
+await browser.locator(By.testId('results')).expect().toBeVisible();
+await browser.clock.uninstall();
+```