craftdriver 1.1.0 → 1.2.0

package/docs/recipes/console-error-gate.md

@@ -1,56 +1,44 @@
 # 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.
+A flow can look correct in the DOM while quietly throwing in the console — a
+failed fetch, an undefined access, a rejected promise. Logs are captured
+automatically from launch, so you can run the flow and then assert no JavaScript
+errors were reported, breaking the test instead of reaching users. This recipe
+uses the live
+[console errors example](https://dtopuzov.github.io/craftdriver/examples/console-errors.html).
 
 ```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();
-  });
-});
+const browser = await Browser.launch();
+
+await browser.navigateTo('https://dtopuzov.github.io/craftdriver/examples/console-errors.html');
+browser.logs.clearLogs();
+
+await browser.click('#btn-console-log'); // your real user flow goes here
+
+// Fails the test if the page reported any JavaScript error during the flow.
+browser.logs.assertNoErrors();
 ```
 
 ## Wait For A Known Log
 
-When the log itself is part of the expected behavior, arm the wait before the
+When a log line is itself 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');
-});
+const logged = browser.logs.waitForConsole((message) =>
+  message.text.includes('Hello from console.log')
+);
 
-await browser.getByRole('button', { name: 'Save' }).click();
-await saved;
+await browser.click('#btn-console-log');
+await logged;
 ```
 
+## Notes
+
+- `assertNoErrors()` checks captured JavaScript errors — capture is automatic, nothing to enable.
+- Call `clearLogs()` before the flow so errors from earlier tests don't bleed in.
+- Use `waitForConsole()` / `waitForError()` when a specific message is the thing you're asserting.
+
 ## Learn More
 
 - [Console Logs And JavaScript Errors](../browser-logs.md)

package/docs/recipes/file-upload-download.md

@@ -1,56 +1,36 @@
 # Test File Uploads And Downloads
 
-Use this pattern when a workflow imports data, uploads an attachment, exports a
-report, or verifies a generated file.
+Import, attachment, and export flows are easy to break and awkward to test by
+hand. CraftDriver sets files on a real `<input type="file">` and captures
+downloads to a directory you choose, so you can assert on the bytes that land on
+disk. This recipe uploads a fixture to the live
+[upload example](https://dtopuzov.github.io/craftdriver/examples/upload.html),
+then downloads a report from the
+[download example](https://dtopuzov.github.io/craftdriver/examples/download.html).
+It sets `downloadsDir` at launch, so it shows the `launch` call.
 
 ```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');
-  });
-});
+const browser = await Browser.launch({ downloadsDir: '.tmp/downloads' });
+
+await browser.navigateTo('https://dtopuzov.github.io/craftdriver/examples/upload.html');
+await browser.find('#file-input').setInputFiles('tests/fixtures/sample.txt');
+await browser.expect('#result').toHaveText('sample.txt');
+
+await browser.navigateTo('https://dtopuzov.github.io/craftdriver/examples/download.html');
+const download = await browser.waitForDownload(() => browser.click('#download-btn'));
+
+const target = `.tmp/downloads/${download.suggestedFilename}`;
+await download.saveAs(target);
+
+expect(existsSync(target)).toBe(true);
+expect(readFileSync(target, 'utf8')).toContain('craftdriver download test');
 ```
 
 ## 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.
+- Wrap the click that triggers the download in `waitForDownload()` so the wait is armed first.
+- Call `setInputFiles()` on the actual `<input type="file">` element, not a styled wrapper.
 
 ## Learn More
 

package/docs/recipes/find-elements.md

@@ -0,0 +1,142 @@
+# Find Elements On The Page
+
+Everything you do with CraftDriver — click, fill, assert — starts by pointing at
+an element. Before you can automate anything, you have to name the thing you
+want. It's the first skill to learn, and it pays to learn it in the right order:
+some ways of naming an element survive a redesign or a translation, and some
+don't. This recipe starts with the anchors that hold up almost everywhere, then
+the more expressive ones and where they earn their place.
+
+It drives the live
+[login example](https://dtopuzov.github.io/craftdriver/examples/login.html).
+
+## Inspect the page first
+
+Open the page in a real browser, right-click the element you care about, and
+choose **Inspect**. Then look for a handle, roughly in this order:
+
+1. **A stable attribute you can anchor to** — a form field's `name`, an input
+   `type`, a hand-written `id`, or a `data-testid`. None of these change when the
+   wording or the layout does.
+2. **What the element is to a user** — its *role* (button, link, heading,
+   checkbox) and its *accessible name* (its visible words, or an input's
+   `<label>`).
+3. **Its visible text**, when that's the thing that identifies it.
+
+The login form, inspected, has ids and `name`s on the fields and a typed submit
+button:
+
+```html
+<h1>Login</h1>
+<label for="username">Username</label>
+<input id="username" name="username" />
+<label for="password">Password</label>
+<input id="password" name="password" />
+<button id="submit" type="submit">Sign in</button>
+```
+
+## Start with anchors that don't move
+
+Some anchors don't change when the copy changes, because they aren't copy — a
+form field's `name` is a backend contract, an input `type` is semantic, a
+hand-written `id` is put there on purpose. Reach for these first: they read
+clearly, they survive redesigns, and they resolve the same whether the page ships
+in English or German.
+
+```ts
+// Fields by their `name` — a form contract, not UI text
+await browser.find(By.name('username')).fill('alice');
+await browser.find(By.name('password')).fill('secret');
+
+// The submit button by its semantic type
+await browser.find('button[type="submit"]').click();
+
+// The result by its stable id
+await browser.locator('#welcome').expect().toBeVisible();
+```
+
+Each has a boundary worth knowing: `name` and `type` live mostly on form
+controls, so they won't help you point at a heading or a menu item; and an `id`
+is only trustworthy when it's authored for meaning — framework-generated ids like
+`#mui-4213` churn between builds, so never anchor to those.
+
+A word on `data-testid`, since it comes up constantly. It's the most robust
+anchor there is *when it's in the page you test* — invisible to users, untouched
+by redesign or translation. But test ids aren't a browser or "dev mode" feature;
+they're attributes a team chooses to add, and some builds strip them to trim the
+payload. So don't assume they exist: open the real production DOM and look. If
+you own the app, add them and make sure the production build keeps them; if you
+don't, lean on `name`, `type`, and honest semantic HTML — those are always
+shipped.
+
+## Match the way a user sees the page
+
+The anchors above are *plumbing* — attributes wired into the markup. Sometimes
+you want the opposite: to find an element the way a person, or a screen reader,
+actually perceives it. That's what `getByRole`, `getByLabel`, and `getByText`
+are for, and they read almost like a spoken description:
+
+```ts
+// "the Login heading"
+await browser.getByRole('heading', { name: 'Login' }).expect().toBeVisible();
+
+// "the Username / Password fields", found through their <label>
+await browser.getByLabel('Username').fill('alice');
+await browser.getByLabel('Password').fill('secret');
+
+// "the Sign in button", by role + accessible name
+await browser.getByRole('button', { name: 'Sign in' }).click();
+
+// "the welcome message", by its visible text
+await browser.getByText('Welcome back, alice!').expect().toBeVisible();
+```
+
+The match is meaningful, not just readable: if your test can find the button by
+its role and name, the page is exposing the semantics users depend on. These
+locators also shrug off markup refactors, since they don't care how many `<div>`s
+wrap the element.
+
+Pitfalls worth knowing:
+
+- **They rely on correct semantic HTML.** `getByRole('button')` finds a real
+  `<button>`, not a `<div onclick>`. That's often a bug worth surfacing — but it
+  means these locators expose how honest your markup is.
+- **The name is usually user-facing text**, so it's tied to the current language
+  — see the next section.
+- **Name matching is an approximation.** CraftDriver handles the common cases
+  (`aria-label`, simple `aria-labelledby`, visible text, form labels, `alt`,
+  `title`), but if a role query is fussy, use `getByLabel`, `getByTestId`, or a
+  stable attribute instead of guessing.
+
+## Working across languages
+
+Here's the catch these accessibility locators carry: the *name* you match on is
+translated text. `getByLabel('Username')` finds nothing on a page that renders
+`Benutzername`. Two honest ways to handle it:
+
+- **Anchor on the language-neutral attributes from the top of this page** —
+  `name`, `type`, id, test id. The same test then runs in every locale unchanged.
+  It's the simplest thing that works, and where most localised suites end up.
+- **Feed the locator from the same translations the app uses** —
+  `getByRole('button', { name: t('auth.signIn') })`. You keep the accessibility
+  benefits *and* run per-locale. The cost is discipline: the test has to read the
+  exact key the UI renders, and you run it once per language — otherwise a
+  translation change quietly becomes a false failure.
+
+A rule that applies either way: **a bare string is always a CSS selector**. To
+match by text or role you must use a `getBy*` method or a `By.*` locator; there's
+no `text=` string shorthand.
+
+## Notes
+
+- Names match the **whole** text by default. Pass `{ exact: false }` to match a
+  substring, e.g. `getByText('Welcome back', { exact: false })`.
+- To search *inside* one card or row instead of the whole page, chain from a
+  [locator](../selectors.md#locators-lazy--chainable):
+  `card.getByRole('button', { name: 'Buy' })`.
+
+## Learn More
+
+- [Selectors & Locators](../selectors.md) — the full reference for every strategy
+- [Organize Flows With Page Objects](./page-objects.md)
+- [Assertions](../assertions.md)

package/docs/recipes/login-once-reuse-session.md

@@ -1,70 +1,47 @@
 # 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.
+Signing in through the UI in every test is slow, and for most tests logging in
+is not the thing being proven. Do it once, save the resulting cookies and
+localStorage, then launch later tests already authenticated with `storageState`.
+Both halves below run against the live
+[login example](https://dtopuzov.github.io/craftdriver/examples/login.html),
+which persists its session in a cookie.
 
 ## Generate Auth State
 
-Run this as a setup step before the tests that need an authenticated user.
+Run this once as a setup step. It is one of the few recipes that shows
+`launch`/`quit`, because saving state is a self-contained script, not a test.
 
 ```ts
-import { mkdir } from 'node:fs/promises';
 import { Browser } from 'craftdriver';
 
-const authState = '.auth/alice.json';
+const browser = await Browser.launch();
 
-await mkdir('.auth', { recursive: true });
+await browser.navigateTo('https://dtopuzov.github.io/craftdriver/examples/login.html');
+await browser.getByLabel('Username').fill('alice');
+await browser.getByLabel('Password').fill('secret');
+await browser.getByRole('button', { name: 'Sign in' }).click();
+await browser.expect('#welcome').toContainText('Welcome back, alice!');
 
-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();
-}
+await browser.saveState('.auth/alice.json');
+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',
-    });
-  });
+Launch with `storageState` and the browser starts already signed in.
 
-  beforeEach(async () => {
-    await browser.navigateTo('http://localhost:3000/dashboard');
-  });
-
-  afterAll(async () => {
-    await browser.quit();
-  });
+```ts
+const browser = await Browser.launch({ storageState: '.auth/alice.json' });
 
-  it('shows account data', async () => {
-    await browser.expect('#account').toContainText('Alice');
-  });
-});
+await browser.navigateTo('https://dtopuzov.github.io/craftdriver/examples/login.html');
+await browser.expect('#welcome').toContainText('Welcome back, 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.
+- Regenerate auth state when the app changes its login or session behavior.
 - Use separate files such as `.auth/admin.json` and `.auth/customer.json` for different roles.
 
 ## Learn More

package/docs/recipes/mobile-flow-with-network-and-logs.md

@@ -1,54 +1,35 @@
 # 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.
+Mobile bugs often need three things set up at once: a real device viewport, a
+predictable backend response, and a check that nothing errored in the console on
+the smaller layout. This recipe combines all three — it launches with a Pixel 7
+preset, mocks the API, and gates on browser errors — against the live
+[network example](https://dtopuzov.github.io/craftdriver/examples/network.html).
+Because mobile emulation is a launch-time capability, this recipe shows the
+`launch` call.
 
 ```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();
-  });
+const browser = await Browser.launch({ mobileEmulation: 'Pixel 7' });
+
+// ?bidi=true makes the demo page issue real requests for interception.
+await browser.navigateTo('https://dtopuzov.github.io/craftdriver/examples/network.html?bidi=true');
+
+await browser.network.mock('**/api/users', {
+  status: 200,
+  body: { users: [{ id: 1, name: 'Alice', plan: 'Pro' }] },
 });
+
+await browser.getByRole('button', { name: 'Fetch Users' }).click();
+await browser.expect('#users-result').toContainText('Alice');
+
+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.
+- Mock before the action if the page reads data during that step.
+- Console/error capture is automatic, so `assertNoErrors()` always has the full picture.
 
 ## Learn More
 

package/docs/recipes/mock-api-and-assert-network.md

@@ -1,46 +1,33 @@
 # 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.
+Testing the UI against a real backend makes tests slow and flaky and couples them
+to data you do not control. Mock the response the page needs, then wait for the
+request or response the user action triggers so you can assert both the UI and
+the traffic. This recipe drives the live
+[network example](https://dtopuzov.github.io/craftdriver/examples/network.html).
 
 ```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();
-  }
+// The ?bidi=true query just tells this demo page to make real network
+// requests instead of its built-in stub, so the mock below is what answers.
+await browser.navigateTo('https://dtopuzov.github.io/craftdriver/examples/network.html?bidi=true');
+
+await browser.network.mock('**/api/users', {
+  status: 200,
+  body: { users: [{ id: 1, name: 'Alice', plan: 'Pro' }] },
 });
+
+const [response] = await Promise.all([
+  browser.waitForResponse('**/api/users'),
+  browser.getByRole('button', { name: 'Fetch Users' }).click(),
+]);
+
+expect(response.status).toBe(200);
+await browser.expect('#users-result').toContainText('Alice');
 ```
 
 ## Keep Mocks Isolated
 
-If you share a browser across tests, clear intercepts in `afterEach()`:
+When a browser is shared across tests, clear intercepts between them:
 
 ```ts
 afterEach(async () => {
@@ -50,7 +37,7 @@ afterEach(async () => {
 
 ## Notes
 
-- Register waits before the click that triggers the request.
+- Register the wait before the click that triggers the request (the `Promise.all` above).
 - 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.
 

package/docs/recipes/multi-user-contexts.md

@@ -1,56 +1,45 @@
 # 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.
+Chat, approvals, permissions, and admin/customer flows need two signed-in users
+at the same time — but sharing one browser leaks cookies between them. A browser
+context is an isolated cookie and storage jar inside one launched browser, so two
+users can act independently without a second browser process. This recipe signs
+two users into the live
+[login example](https://dtopuzov.github.io/craftdriver/examples/login.html) and
+shows they stay isolated.
 
 ```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();
-    }
-  });
+const alice = await browser.newContext();
+const bob = await browser.newContext();
+
+const alicePage = await alice.newPage({
+  url: 'https://dtopuzov.github.io/craftdriver/examples/login.html',
+});
+await alicePage.find('#username').fill('alice');
+await alicePage.find('#password').fill('secret');
+await alicePage.find('#submit').click();
+await alicePage.expect('#welcome').toContainText('Welcome back, alice!');
+
+const bobPage = await bob.newPage({
+  url: 'https://dtopuzov.github.io/craftdriver/examples/login.html',
 });
+await bobPage.find('#username').fill('bob');
+await bobPage.find('#password').fill('secret');
+await bobPage.find('#submit').click();
+await bobPage.expect('#welcome').toContainText('Welcome back, bob!');
+
+// Alice is unaffected by Bob signing in — cookies are per-context.
+await alicePage.expect('#welcome').toContainText('Welcome back, alice!');
+
+await alice.close();
+await bob.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.
+- In a real suite, close contexts in `afterEach()` so a failed assertion cannot leak sessions.
+- Combine with saved `storageState` when users should start already signed in.
 
 ## Learn More