craftdriver 0.1.0 → 0.2.0

package/docs/browser-context.md

@@ -0,0 +1,522 @@
+# Browser Contexts (isolated profiles)
+
+A `BrowserContext` is a **WebDriver BiDi user context** — an isolated
+browser profile, equivalent to opening a new incognito window. Each
+context has its own cookies, localStorage, IndexedDB, and service
+workers, fully isolated from every other context including the default
+one.
+
+Use `BrowserContext` to run multi-user scenarios (log in as Alice in
+one context, as Bob in another) without cookie cross-talk, or to test
+cold-start behaviour without nuking the rest of your session.
+
+> **BiDi-only.** This API maps directly onto BiDi
+> `browser.createUserContext` / `browser.getUserContexts` /
+> `browser.removeUserContext`. WebDriver Classic has no equivalent and
+> these methods throw a clear error when `enableBiDi: false`.
+
+## The hierarchy
+
+```
+Browser           — the BiDi session (one launched browser process)
+└── BrowserContext  — an isolated user context (this page)
+    └── Page          — a top-level browsing context (tab or window)
+        └── Frame       — a nested browsing context (iframe)
+```
+
+The `Browser` always exposes a `defaultContext` (id `'default'`). Pages
+opened via `browser.openPage()` belong to it. Call `browser.newContext()`
+to create additional isolated contexts.
+
+## Quick reference
+
+```typescript
+import { Browser } from 'craftdriver';
+
+const browser = await Browser.launch();
+
+// The default context (always present, id === 'default').
+const defaultCtx = browser.defaultContext;
+
+// Create a fresh isolated context.
+const ctx = await browser.newContext();
+
+// List every open context (including 'default').
+const all = await browser.contexts();
+
+// Pages inside a context.
+const page = await ctx.newPage({ url: 'https://example.com' });
+const pages = await ctx.pages();
+
+// Capture a popup spawned from this context.
+const popup = await ctx.waitForPage(() => page.find('#open').click());
+
+// Tear it down — all of its pages close, the profile is wiped.
+await ctx.close();
+```
+
+> **Heads-up.** `browser.click()`, `browser.find()` and the other
+> `Browser`-level shortcuts always target a page in **`defaultContext`**.
+> They never reach a `Page` you got from `ctx.newPage()` on a
+> non-default context. Always call methods on the `Page` you got back —
+> e.g. `await aPage.fill('#user', 'alice')`, not `browser.fill(...)`.
+
+## The auth-fixture pattern (skip the login UI in every test)
+
+Most test suites log in dozens of times against the same app. Do it
+**once**, snapshot the session to disk, and reuse it from every later
+test. This is the canonical real-world use of `storageState`.
+
+```typescript
+// tests/setup/login.ts — runs once, before the suite.
+import { Browser } from 'craftdriver';
+
+const browser = await Browser.launch();
+const ctx = await browser.newContext();
+const page = await ctx.newPage({ url: 'https://app.example.com/login' });
+await page.find('#username').fill('alice');
+await page.find('#password').fill('secret');
+await page.find('#submit').click();
+await page.expect('#welcome').toBeVisible();
+
+// Cookies + localStorage for every origin the context has visited.
+await ctx.saveStorageState('auth/alice.json');
+await browser.quit();
+```
+
+```typescript
+// every other test:
+const ctx = await browser.newContext({ storageState: 'auth/alice.json' });
+const page = await ctx.newPage({ url: 'https://app.example.com/dashboard' });
+// Already logged in — no form, no waiting.
+```
+
+## Multi-user login in one browser
+
+Two contexts — two logged-in sessions — no cookie cross-talk. Useful for
+testing permission boundaries (admin vs. guest), real-time features
+(chat, collaboration), or any flow that needs two users live at once.
+
+```typescript
+const alice = await browser.newContext();
+const bob = await browser.newContext();
+
+const aPage = await alice.newPage({ url: 'https://app.example.com/login' });
+await loginAs(aPage, 'alice');
+
+const bPage = await bob.newPage({ url: 'https://app.example.com/login' });
+await loginAs(bPage, 'bob');
+// bPage cannot see alice's session cookie, and vice versa.
+
+await alice.close();
+await bob.close();
+```
+
+## API
+
+### `browser.newContext(opts?): Promise<BrowserContext>`
+
+Create a new isolated user context. Backed by BiDi
+`browser.createUserContext`. Throws in Classic mode.
+
+- `opts.storageState`: a `SessionState` object **or** a path to a JSON
+  file produced by `BrowserContext.saveStorageState()`. Cookies are
+  applied immediately; localStorage entries land on first navigation to
+  each captured origin via an internal preload script.
+- `opts.baseURL`: a base URL applied to every relative `url` passed to
+  `ctx.newPage()` or `page.navigateTo()` inside the context. Absolute
+  URLs pass through unchanged. Lets your tests say `'/login'` instead
+  of repeating `'https://staging.example.com/login'` everywhere.
+- `opts.extraHTTPHeaders`: headers attached to **every** outgoing request
+  from every page in this context. Useful for staging tokens, tenant
+  ids, feature-flag overrides, or correlating test traffic in server
+  logs. Replace later with `ctx.setExtraHTTPHeaders(…)`.
+
+```typescript
+const ctx = await browser.newContext({
+  baseURL: 'https://staging.example.com',
+  extraHTTPHeaders: { 'x-test-tenant': 'acme', 'x-staging-token': process.env.STAGING_TOKEN! },
+  storageState: 'auth/alice.json',
+});
+const page = await ctx.newPage({ url: '/dashboard' }); // resolves against baseURL
+```
+
+### `browser.contexts(): Promise<BrowserContext[]>`
+
+Return all open user contexts, including the default one. Backed by
+BiDi `browser.getUserContexts`. Throws in Classic mode.
+
+### `browser.defaultContext: BrowserContext`
+
+The implicit context the browser started in (id `'default'`). Pages
+opened via `browser.openPage()` / `browser.waitForPage()` live here.
+
+### `BrowserContext.id: string`
+
+The BiDi user-context id. The default context's id is the literal
+string `'default'`.
+
+### `BrowserContext.newPage(opts?): Promise<Page>`
+
+Open a tab/window inside this context. `opts.url` navigates the new
+page; `opts.type` is `'tab'` (default) or `'window'`.
+
+### `BrowserContext.pages(): Promise<Page[]>`
+
+All open top-level pages that belong to this context.
+
+### `BrowserContext.waitForPage(action, opts?): Promise<Page>`
+
+Run `action` and resolve to the next new page that opens **inside this
+context**. Useful for popup-from-click flows.
+
+### `BrowserContext.cookies(urls?): Promise<Cookie[]>`
+
+Return cookies scoped to this user context. Pass a single URL or an
+array to filter to cookies that would be sent on a request to that URL
+(RFC-6265 domain/path match).
+
+```typescript
+const session = await ctx.cookies('https://app.example.com');
+expect(session.find((c) => c.name === 'sid')).toBeDefined();
+```
+
+### `BrowserContext.addCookies(cookies): Promise<void>`
+
+Add cookies to this context. `domain` is required (BiDi rejects
+host-less cookies). Throws a clear error if you ask for
+`sameSite: 'none'` without `secure: true`.
+
+```typescript
+await ctx.addCookies([
+  {
+    name: 'sid',
+    value: 'eyJ…',
+    domain: 'app.example.com',
+    path: '/',
+    secure: true,
+    sameSite: 'lax',
+  },
+]);
+```
+
+### `BrowserContext.clearCookies(filter?): Promise<void>`
+
+Remove cookies. With no filter, wipes every cookie in the context. With
+a filter, removes cookies that match **all** provided fields (`name`,
+`domain`, `path`).
+
+```typescript
+await ctx.clearCookies({ name: 'sid' }); // sign the user out
+await ctx.clearCookies({ domain: 'tracker.io' }); // wipe a third party
+await ctx.clearCookies(); // full reset
+```
+
+### `BrowserContext.storageState(opts?): Promise<SessionState>`
+
+Snapshot cookies + localStorage for this context.
+
+- `opts.includeCookies` — default `true`.
+- `opts.includeLocalStorage` — default `true`. Only origins of **currently
+  open pages** are captured; BiDi has no API to read localStorage for
+  an origin no page is visiting. Open one page per origin you need
+  captured before snapshotting.
+
+### `BrowserContext.saveStorageState(path, opts?): Promise<SessionState>`
+
+Snapshot the context and write it to `path` as JSON. Returns the
+snapshot for inspection. See the auth-fixture example above.
+
+### `BrowserContext.loadStorageState(source): Promise<void>`
+
+Apply a previously-captured snapshot. `source` is a `SessionState`
+object or a path to JSON produced by `saveStorageState`. Cookies are
+applied immediately; localStorage entries are installed via a preload
+script that runs on first navigation to each captured origin. Calling
+`loadStorageState` again replaces the previous preload — it does not
+stack.
+
+### `BrowserContext.close(): Promise<void>`
+
+Remove the user context and close all its pages. Subsequent operations
+on this `BrowserContext` instance throw. The default context cannot be
+closed — quit the browser instead.
+
+### `BrowserContext.isClosed: boolean`
+
+`true` after `close()` has run.
+
+### `BrowserContext.on(event, listener): () => void`
+
+Subscribe to lifecycle events on this context. Returns an **unsubscribe
+function**; call it to remove the listener. Events fire **only** for
+this context.
+
+- `'page'` — fires for every new top-level page in this context,
+  including popups opened by `window.open` or `target="_blank"` clicks.
+  Listener receives the new `Page`.
+- `'close'` — fires once when the context is closed (via `ctx.close()`
+  or because the browser quit). Listener receives no arguments.
+
+`ctx.off(event, listener)` is also available if you'd rather hold on to
+the listener reference than the unsubscribe function.
+
+```typescript
+// Real-world: capture every console error across every tab a test opens,
+// including popups. No more "why did my test pass with a 500 in a popup".
+const errors: string[] = [];
+ctx.on('page', (page) => {
+  page.on('console', (msg) => {
+    if (msg.type() === 'error') errors.push(`${page.url()}: ${msg.text()}`);
+  });
+});
+
+const main = await ctx.newPage({ url: '/checkout' });
+const receipt = await ctx.waitForPage(() => main.find('#print').click());
+await receipt.waitForLoadState('load');
+expect(errors).toEqual([]);
+```
+
+### `BrowserContext.addInitScript(script): Promise<InitScriptHandle>`
+
+Register a script that runs in **every** page of this context _before_
+any page script, on every navigation — including popups and iframes
+that share the realm. Maps to BiDi `script.addPreloadScript` scoped to
+this user context.
+
+The handle exposes `.id` and `.remove()`. Removing only affects future
+navigations.
+
+```typescript
+// Real-world: pin Date.now() and Math.random() for visual-regression
+// stability; flip a feature flag before app code reads it.
+const handle = await ctx.addInitScript(`
+  const fixed = new Date('2025-01-15T12:00:00Z').getTime();
+  Date.now = () => fixed;
+  Math.random = () => 0.42;
+  window.__FEATURES__ = { newCheckout: true };
+`);
+
+// …run tests…
+
+await handle.remove(); // back to live time on the next navigation
+```
+
+Init scripts do **not** leak between contexts: a script added to
+`ctx.A` never runs in pages of `ctx.B`.
+
+### `BrowserContext.removeInitScript(id): Promise<void>`
+
+Remove a previously-registered init script by id. Equivalent to
+`handle.remove()`. Unknown ids are silently ignored.
+
+### `BrowserContext.setExtraHTTPHeaders(headers): Promise<void>`
+
+Replace the context's `extraHTTPHeaders` map at runtime. Applies to
+all **future** requests from existing and new pages in this context.
+Pass `{}` to clear.
+
+```typescript
+// Rotate a per-test correlation id partway through a flow.
+await ctx.setExtraHTTPHeaders({ 'x-trace-id': crypto.randomUUID() });
+```
+
+### `BrowserContext.route(pattern, handler): Promise<string>`
+
+Intercept matching requests from pages in **this context only**.
+Returns a route id you can pass to `unroute()`.
+
+Under the hood we register one BiDi `network.addIntercept` **per page**,
+scoped to that page's browsing-context id. Pages opened later inherit
+every route automatically; closed pages have their intercept removed.
+Requests from other contexts are not seen.
+
+- `pattern`: a URL substring, a `RegExp`, or a glob (`*` matches any
+  run of non-`/` characters; `**` matches any run of characters).
+- `handler({ request, fulfill, continue: cont, abort })`: called for
+  every matched request. Must call exactly one of:
+  - `fulfill({ status?, headers?, contentType?, body? })` — reply
+    immediately without hitting the network.
+  - `continue({ url?, method?, headers?, postData? })` — let the
+    request go through, optionally rewritten.
+  - `abort(reason?)` — fail the request.
+
+```typescript
+// Real-world: serve a fixture to one tenant, let the real API answer
+// the other — in the same test, side-by-side.
+const admin = await browser.newContext();
+const guest = await browser.newContext();
+
+await admin.route('**/api/users', async ({ fulfill }) => {
+  await fulfill({
+    status: 200,
+    contentType: 'application/json',
+    body: JSON.stringify([{ id: 1, role: 'admin', name: 'Alice' }]),
+  });
+});
+
+const aPage = await admin.newPage({ url: '/users' });
+const gPage = await guest.newPage({ url: '/users' });
+// aPage sees the mock; gPage hits the live backend.
+```
+
+Glob matching is `**`-aware: `'**/api/users'` matches
+`https://api.example.com/v1/api/users` but not
+`https://example.com/api/users/123`.
+
+### `BrowserContext.unroute(id?): Promise<void>`
+
+Remove a single route by id, or with no argument remove **every** route
+registered on this context.
+
+```typescript
+const id = await ctx.route('**/api/flags', flagHandler);
+// …
+await ctx.unroute(id);
+```
+
+### `Page.context(): BrowserContext`
+
+Return the `BrowserContext` a page belongs to. Useful when a listener
+or helper receives a `Page` and needs to reach back to the context
+(e.g. to read cookies, set headers, or close the context).
+
+```typescript
+ctx.on('page', (page) => {
+  // page.context() === ctx
+});
+```
+
+### `browser.newContext({ locale, timezoneId, geolocation })`
+
+Identity-and-device overrides. Each is a thin wrapper over a BiDi
+`emulation.*` command scoped to this user context, so **every** page in
+the context — current and future, including popups — sees the override
+without any per-page plumbing.
+
+- `locale` — reported by `navigator.language`, `Intl.*`, and the
+  `Accept-Language` header. BiDi `emulation.setLocaleOverride`.
+  Cross-browser: Chrome and Firefox.
+- `timezoneId` — IANA timezone applied to `Date` and
+  `Intl.DateTimeFormat`. BiDi `emulation.setTimezoneOverride`.
+  Cross-browser: Chrome and Firefox.
+- `geolocation` — `{ latitude, longitude, accuracy? }` returned by
+  `navigator.geolocation.getCurrentPosition()`. BiDi
+  `emulation.setGeolocationOverride`. Reliable on Chrome; Firefox BiDi
+  coverage is uneven and the setter wraps the underlying error with a
+  clear engine name when it fails. The `geolocation` permission still
+  has to be granted — see {@link BrowserContext.grantPermissions}.
+
+```typescript
+// Real-world: render the German checkout, log times in Berlin, pin the
+// user to a Berlin lat/lon for the geofence test — all in one context,
+// fully isolated from the Tokyo-locale context next to it.
+const de = await browser.newContext({
+  locale: 'de-DE',
+  timezoneId: 'Europe/Berlin',
+  geolocation: { latitude: 52.52, longitude: 13.4 },
+});
+await de.grantPermissions(['geolocation'], { origin: 'https://app.example.com' });
+const page = await de.newPage({ url: 'https://app.example.com/checkout' });
+```
+
+### `BrowserContext.setLocale(locale: string | null): Promise<void>`
+
+Change the per-context locale at runtime. Pass `null` to clear. Existing
+pages pick up the new locale on their next page-driven re-read (e.g.
+reload, navigation, or any code that re-evaluates `navigator.language`).
+Cross-browser: Chrome and Firefox.
+
+### `BrowserContext.setTimezone(timezoneId: string | null): Promise<void>`
+
+Change the per-context timezone at runtime. Pass `null` to clear.
+Cross-browser: Chrome and Firefox.
+
+### `BrowserContext.setGeolocation(coords | null): Promise<void>`
+
+Replace the geolocation override for this context. Pass `null` to clear.
+Validates that latitude ∈ [-90, 90] and longitude ∈ [-180, 180]. Wraps
+the underlying BiDi error with the engine name on failure so you can
+tell when a browser hasn't shipped this command yet.
+
+### `BrowserContext.grantPermissions(permissions, { origin, state? })`
+
+Grant, deny, or reset W3C permissions for an origin in **this context
+only**. `origin` is required — BiDi `permissions.setPermission` has no
+"all origins" wildcard. `state` defaults to `'granted'`; pass `'denied'`
+to pre-reject the prompt, or `'prompt'` to clear back to the browser
+default.
+
+Valid `permissions` names are the W3C Permissions catalogue:
+`'geolocation'`, `'notifications'`, `'clipboard-read'`,
+`'clipboard-write'`, `'camera'`, `'microphone'`, `'midi'`,
+`'background-sync'`, `'persistent-storage'`, …
+
+```typescript
+// Real-world: don't make the test click through the notification prompt.
+await ctx.grantPermissions(['notifications'], {
+  origin: 'https://app.example.com',
+  state: 'denied',
+});
+```
+
+### `BrowserContext.clearPermissions(permissions, { origin })`
+
+Reset the listed permissions for an origin back to `'prompt'`. Sugar for
+`grantPermissions(…, { state: 'prompt' })`.
+
+## Cross-browser support
+
+Most of the `BrowserContext` API — cookies, storage state,
+`on('page'|'close')`, `addInitScript`, `route`/`unroute`,
+`setExtraHTTPHeaders`, `baseURL`, `extraHTTPHeaders`, `page.context()`,
+`setLocale`, `setTimezone`, `grantPermissions`/`clearPermissions` — works
+on **Chrome** and **Firefox** via WebDriver BiDi. Every method throws a
+clear error in Classic mode.
+
+`setGeolocation` / `newContext({ geolocation })` is reliable on Chrome.
+Firefox BiDi `emulation.setGeolocationOverride` coverage is still
+uneven; the setter surfaces the engine error with a clear message when
+the browser hasn't shipped it.
+
+A default `browser.newContext()` (no options) is always cross-browser.
+
+## Scope and precedence (gotchas)
+
+A few things that aren't bugs but bite if you don't know them:
+
+- **`storageState` covers cookies + localStorage only.** Not
+  sessionStorage, not IndexedDB, not Cache Storage. Apps that put their
+  auth token in sessionStorage (some Auth0 / MSAL fallback configs) will
+  need a custom restore step.
+- **Browser-level vs context-level emulation race.** `browser.setGeolocation(...)`
+  is a session-wide override; `ctx.setGeolocation(...)` is a per-context
+  override. If both are set, the context-level one wins inside the
+  context (it carries a more specific `userContexts` scope at the BiDi
+  layer). To avoid surprises, pick one layer per concern.
+- **`ctx.route()` does not see service-worker requests.** Per-page
+  intercepts are bound to the page's browsing context; fetches initiated
+  by a service worker or a dedicated/shared worker bypass them. Mock
+  those endpoints at the application layer, or unregister the service
+  worker via an `addInitScript`.
+- **`grantPermissions(['a','b'], ...)` is not transactional.** Each
+  permission is a separate BiDi call; if the second one fails, the first
+  one stays granted. Re-grant idempotently or wrap in your own
+  try/finally if you need rollback.
+- **`page.context()` reflects the BiDi user context, not the window
+  group.** Popups opened from a page in `ctx` belong to `ctx`. Pages
+  opened via `browser.openPage()` / `waitForPage()` belong to
+  `browser.defaultContext`.
+
+## What's not (yet) supported
+
+These are documented gaps, not bugs — open an issue if you need them:
+
+- **Per-context viewport, `colorScheme`, `reducedMotion`, `forcedColors`,
+  `userAgent`.** These require either CDP (Chromium-only) or BiDi
+  primitives that aren't broadly shipped yet. Use
+  `browser.emulate({ … })` for the session-wide equivalents on Chromium.
+- **localStorage capture for origins with no open page.** BiDi has no
+  out-of-band storage read API; only currently-visiting origins are in
+  the snapshot.
+- **`httpCredentials` / `offline`.** Not modelled in BiDi yet.