craftdriver 1.1.0 → 1.1.1

package/docs/recipes/page-objects.md

@@ -0,0 +1,52 @@
+# Organize Flows With Page Objects
+
+As a suite grows, the same selectors and steps get copy-pasted across tests, and
+one markup change breaks them all. A page object puts the selectors and actions
+for a screen behind named methods, so tests read like intent (`loginAs(...)`) and
+a UI change is a one-line fix in a single class. This recipe wraps the live
+[login example](https://dtopuzov.github.io/craftdriver/examples/login.html) in a
+`LoginPage`.
+
+```ts
+import { Browser } from 'craftdriver';
+
+class LoginPage {
+  constructor(private readonly browser: Browser) {}
+
+  async open() {
+    await this.browser.navigateTo('https://dtopuzov.github.io/craftdriver/examples/login.html');
+  }
+
+  async loginAs(username: string, password: string) {
+    await this.browser.getByLabel('Username').fill(username);
+    await this.browser.getByLabel('Password').fill(password);
+    await this.browser.getByRole('button', { name: 'Sign in' }).click();
+  }
+
+  async expectWelcome(username: string) {
+    await this.browser.expect('#welcome').toContainText(`Welcome back, ${username}!`);
+  }
+}
+```
+
+A test then reads as a sequence of intentions, with no selectors in sight:
+
+```ts
+const loginPage = new LoginPage(browser);
+
+await loginPage.open();
+await loginPage.loginAs('alice', 'secret');
+await loginPage.expectWelcome('alice');
+```
+
+## Notes
+
+- Expose intent (`loginAs`) rather than mechanics (`fill`, `click`) so tests survive markup changes.
+- Keep assertions the test cares about in the test; put reusable expectations (like `expectWelcome`) on the page object.
+- Pass the `browser` in rather than launching inside the page object, so lifecycle stays in your Vitest hooks.
+
+## Learn More
+
+- [Use CraftDriver With Vitest Hooks](./vitest-browser-lifecycle.md)
+- [Selectors](../selectors.md)
+- [Assertions](../assertions.md)

package/docs/recipes/trace-failing-test.md

@@ -1,60 +1,47 @@
 # Capture Failure Evidence With Tracing
 
-Use this pattern when a flaky or complex test needs evidence: actions,
-navigation, console output, JavaScript errors, network events, and screenshots.
+When a complex or occasionally-flaky test fails, the message alone rarely tells
+you why. A trace records the actions, navigation, console output, JavaScript
+errors, network events, and screenshots so you can replay what happened. Wrap
+the flow in a helper that starts a trace, keeps it on failure, and always stops
+it. This recipe traces a sign-in against the live
+[login example](https://dtopuzov.github.io/craftdriver/examples/login.html).
 
-```ts
-import { afterAll, beforeAll, describe, it } from 'vitest';
-import { Browser } from 'craftdriver';
-
-describe('checkout', () => {
-  let browser: Browser;
-
-  beforeAll(async () => {
-    browser = await Browser.launch({ browserName: 'chrome' });
-  });
-
-  afterAll(async () => {
-    await browser.quit();
-  });
+The `try/catch` here is deliberate — it is what keeps the trace directory when
+the flow throws.
 
-  async function withTrace(name: string, run: () => Promise<void>) {
-    const outDir = `./traces/${name}-${Date.now()}`;
-    await browser.startTrace({ outDir });
-
-    try {
-      await run();
-    } catch (error) {
-      console.error(`Trace kept at ${outDir}`);
-      throw error;
-    } finally {
-      await browser.stopTrace().catch(() => undefined);
-    }
+```ts
+async function withTrace(name: string, run: () => Promise<void>) {
+  const outDir = `./traces/${name}-${Date.now()}`;
+  await browser.startTrace({ outDir });
+
+  try {
+    await run();
+  } catch (error) {
+    console.error(`Trace kept at ${outDir}`);
+    throw error;
+  } finally {
+    await browser.stopTrace().catch(() => undefined);
   }
-
-  it('places an order', async () => {
-    await withTrace('checkout-order', async () => {
-      await browser.navigateTo('http://localhost:3000/cart');
-      await browser.getByRole('button', { name: 'Checkout' }).click();
-      await browser.getByLabel('Card number').fill('4242424242424242');
-      await browser.getByRole('button', { name: 'Pay' }).click();
-      await browser.expect('#order-status').toContainText('Confirmed');
-    });
-  });
+}
+
+await withTrace('login', async () => {
+  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!');
 });
 ```
 
 ## Notes
 
-- The trace file is NDJSON, so it remains useful even if the test throws before cleanup.
+- The trace file is NDJSON, so it stays useful even if the test throws before `stopTrace()`.
 - Screenshots are stored under the trace directory.
-- For high-volume suites, turn screenshots off unless the test is under investigation.
+- For high-volume suites, turn screenshots off unless a test is under investigation:
 
 ```ts
-await browser.startTrace({
-  outDir: './traces/smoke',
-  screenshots: 'off',
-});
+await browser.startTrace({ outDir: './traces/smoke', screenshots: 'off' });
 ```
 
 ## Learn More

package/docs/recipes/virtual-clock-time-sensitive-ui.md

@@ -1,59 +1,43 @@
 # Test Time-Sensitive UI With The Virtual Clock
 
-Use this pattern for debounced search, trial banners, idle logout, countdowns,
-and other UI that normally makes tests sleep.
+Debounced search, trial banners, idle logout, and countdowns all force tests to
+either sleep (slow, flaky) or never test the timing at all. Install a virtual
+clock and you control time directly: advance it to the exact millisecond a timer
+should fire, or freeze it on a fixed date. This recipe drives the live
+[clock example](https://dtopuzov.github.io/craftdriver/examples/clock.html),
+whose search input debounces for 300 ms.
 
 ```ts
-import { afterAll, afterEach, beforeAll, beforeEach, describe, it } from 'vitest';
-import { Browser } from 'craftdriver';
+await browser.clock.install();
+await browser.navigateTo('https://dtopuzov.github.io/craftdriver/examples/clock.html');
 
-describe('debounced search', () => {
-  let browser: Browser;
+await browser.fill('#search-input', 'lap');
 
-  beforeAll(async () => {
-    browser = await Browser.launch({ browserName: 'chrome' });
-  });
+await browser.clock.tick(299); // just before the debounce threshold
+await browser.expect('#search-count').toHaveText('0');
 
-  beforeEach(async () => {
-    await browser.clock.install({ time: '2030-01-01T00:00:00Z' });
-    await browser.navigateTo('http://localhost:3000/search');
-  });
-
-  afterEach(async () => {
-    await browser.clock.uninstall();
-  });
-
-  afterAll(async () => {
-    await browser.quit();
-  });
-
-  it('fires search only after the debounce window', async () => {
-    await browser.network.mock('**/api/search?q=lap', {
-      status: 200,
-      body: { results: ['Laptop stand'] },
-    });
-
-    await browser.getByLabel('Search').fill('lap');
-
-    await browser.clock.tick(299);
-    await browser.expect('#results').toHaveText('');
-
-    await browser.clock.tick(1);
-    await browser.expect('#results').toContainText('Laptop stand');
-  });
-});
+await browser.clock.tick(2); // crosses 300ms — the search fires exactly once
+await browser.expect('#search-count').toHaveText('1');
 ```
 
 ## Fixed Dates
 
-For date-dependent UI, freeze the wall clock before navigation:
+For date-dependent UI, freeze the wall clock before navigation so the page
+renders as if it were that moment:
 
 ```ts
 await browser.clock.setFixedTime('2026-06-15T23:59:00Z');
-await browser.navigateTo('http://localhost:3000/billing');
-await browser.expect('#trial-banner').toContainText('expires today');
+await browser.navigateTo('https://dtopuzov.github.io/craftdriver/examples/clock.html');
+
+await browser.expect('#trial-banner').toContainText('Trial expires today');
 ```
 
+## Notes
+
+- `install()` fakes timers so `tick()` advances them deterministically; `uninstall()` restores the real clock.
+- `setFixedTime()` freezes `Date.now()` and `new Date()` without touching timers — ideal for date-keyed UI.
+- Install the clock before navigation so the page picks up the fake timers on load.
+
 ## Learn More
 
 - [Virtual Clock](../clock.md)

package/docs/recipes/vitest-browser-lifecycle.md

@@ -1,17 +1,19 @@
 # Use CraftDriver With Vitest Hooks
 
-Use this pattern when a test file should launch one browser, navigate to a clean
-page before each test, and fail if the page reports unexpected JavaScript errors.
+Most test files want the same shape: launch one browser, start each test from a
+known page, and fail loudly if the browser logged an error. This recipe is that
+skeleton — one browser per file, a fresh navigation per test, and an error gate
+in `afterEach`. The rest of the recipes on this site build on it, so they can
+show only the flow they are teaching and assume a launched `browser`.
 
-This keeps tests fast without sharing dirty page state.
+It drives the live [login example](https://dtopuzov.github.io/craftdriver/examples/login.html).
 
 ```ts
 import { afterAll, afterEach, beforeAll, beforeEach, describe, it } from 'vitest';
 import { Browser } from 'craftdriver';
 
-describe('settings page', () => {
+describe('login page', () => {
   let browser: Browser;
-  const baseUrl = 'http://localhost:3000';
 
   beforeAll(async () => {
     browser = await Browser.launch({
@@ -23,7 +25,7 @@ describe('settings page', () => {
   beforeEach(async () => {
     browser.logs.clearLogs();
     await browser.network.removeAllIntercepts();
-    await browser.navigateTo(`${baseUrl}/settings`);
+    await browser.navigateTo('https://dtopuzov.github.io/craftdriver/examples/login.html');
   });
 
   afterEach(() => {
@@ -34,10 +36,11 @@ describe('settings page', () => {
     await browser.quit();
   });
 
-  it('updates the display name', async () => {
-    await browser.getByLabel('Display name').fill('Alice');
-    await browser.getByRole('button', { name: 'Save' }).click();
-    await browser.expect('#toast').toContainText('Saved');
+  it('signs the user in', async () => {
+    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!');
   });
 });
 ```
@@ -47,7 +50,7 @@ describe('settings page', () => {
 - Launch in `beforeAll()` when tests in the file can share one browser process.
 - Navigate in `beforeEach()` so each test starts from a known URL.
 - Clear network mocks and logs before each test so one test cannot influence the next.
-- Use `afterAll()` for `browser.quit()` so local driver and browser processes are cleaned up.
+- Use `afterAll()` for `browser.quit()` so the local driver and browser processes are cleaned up.
 
 ## Learn More
 

package/docs/recipes.md

@@ -1,12 +1,30 @@
 # Recipes
 
+_Recipes for brewing great tests._ 🍺
+
 Recipes are short, real-world patterns that combine CraftDriver features into
 common testing workflows. Use this page as the index; each recipe has its own
-page so the list can grow without turning into a wall of code.
+page so the list can grow without turning into a wall of code. New here? Start
+with [Find Elements On The Page](./recipes/find-elements.md) — every other recipe
+builds on knowing how to point at the thing you want.
+
+Every snippet is verified in CI against a live example page you can open
+yourself, under
+[dtopuzov.github.io/craftdriver/examples](https://dtopuzov.github.io/craftdriver/examples/login.html).
+To stay readable, a snippet shows only the code it is teaching and assumes a
+launched `browser` — unless it shows a `Browser.launch(...)` call itself. See the
+[Vitest Hooks recipe](./recipes/vitest-browser-lifecycle.md) for the surrounding
+setup.
 
 For exact signatures, use the linked feature docs and the
 [API reference](./api-reference.md).
 
+## Start Here
+
+| Scenario           | Use when                                                          | Recipe                                                     |
+| ------------------ | ---------------------------------------------------------------- | --------------------------------------------------------- |
+| Find elements      | You're new and need to point CraftDriver at the element you want. | [Find Elements On The Page](./recipes/find-elements.md)   |
+
 ## Test Structure
 
 | Scenario                  | Use when                                                                   | Recipe                                                                     |
@@ -14,6 +32,7 @@ For exact signatures, use the linked feature docs and the
 | Vitest browser lifecycle  | You want one browser per test file and a fresh page per test.              | [Use CraftDriver With Vitest Hooks](./recipes/vitest-browser-lifecycle.md) |
 | Login once, reuse session | Login UI is slow or noisy and most tests start signed in.                  | [Log In Once And Reuse The Session](./recipes/login-once-reuse-session.md) |
 | Multi-user flows          | You need Alice and Bob signed in at the same time without leaking cookies. | [Test Multi-User Workflows](./recipes/multi-user-contexts.md)              |
+| Page objects              | Selectors and steps are copy-pasted across tests and break together.       | [Organize Flows With Page Objects](./recipes/page-objects.md)              |
 
 ## App Behavior