@e2edev/e2e 0.5.1 → 0.6.1

package/skills/e2e/references/running.md

@@ -0,0 +1,153 @@
+# Running tests
+
+## Commands
+
+```bash
+npx --no-install e2e run [files...] [options]   # run tests
+npx --no-install e2e list [files...] [options]  # print what run would select, without running
+npx --no-install e2e init [--yes]               # scaffold a project, refresh the agent skill
+npx --no-install e2e guide [topic]              # print this skill: setup, writing-tests, agent, running, debugging
+npx --no-install e2e cache ls|clear|stats       # read or empty the trace cache
+```
+
+`run` flags:
+
+| Flag | Effect |
+| --- | --- |
+| `[files...]` | Files, directories, or quoted globs relative to the project root. They narrow the config `tests` glob, never bypass it. |
+| `--config <path>` | Explicit config file. Default: `e2e.config.ts` or `.mts` found upward from the working directory. |
+| `--target <ids>` | Comma-separated target names. |
+| `--tag <tag>` | Repeatable tag filter; `--tag-mode all` requires every tag. |
+| `--headed` | Visible browser or simulator when the engine supports it. |
+| `--workers <n>`, `--retries <n>` | Override the resolved values. |
+| `--reporter <ids>` | `list`, `json`, `junit`, comma-separated. `json` cannot combine with `list`. |
+| `--artifacts <dir>` | Artifact root, default `.e2e/artifacts`. |
+| `--no-cache` | Run with the trace cache off. |
+| `--pass-with-no-tests` | Exit 0 when nothing matches instead of `NO_TESTS`. |
+| `--debug` | Phase timings and an agent step table on stderr; step transcripts saved as artifacts. |
+| `--ai-trace` | Record every model call to `.e2e/ai-trace.json`. |
+
+```bash
+npx --no-install e2e run tests/signup.e2e.ts
+npx --no-install e2e run tests/agent --tag smoke
+npx --no-install e2e run 'tests/**/*.smoke.e2e.ts' --target chromium --workers 1 --retries 0
+CI=1 npx --no-install e2e run   # reproduce the CI defaults locally
+```
+
+`list` takes the same files and the selection flags (`--config`, `--target`,
+`--tag`, `--tag-mode`, `--pass-with-no-tests`) and prints one line per
+test-target pair, `file › title [target]`, then exits without starting the
+app, an engine, or a worker. `--reporter json` prints `{ "pairs": [...] }`.
+Use it to check a filter before a run.
+
+```bash
+npx --no-install e2e list --tag smoke
+npx --no-install e2e list tests/signup.e2e.ts --reporter json
+```
+
+A `package.json` script keeps it short: `"test:e2e": "e2e run"`, then
+`pnpm test:e2e tests/signup.e2e.ts`.
+
+## The trace cache
+
+Entries live under `.e2e/cache/`, one file per key, named after the key
+digest. `cache` commands read the same config as `run`, so `--config` and
+`cache.dir` point them at the right store.
+
+| Command | Prints |
+| --- | --- |
+| `e2e cache ls` | One row per entry: test, target, instruction digest, age, action count. |
+| `e2e cache stats` | Directory, entry count, total size. |
+| `e2e cache clear` | Deletes the entries and the directory; files the runner never wrote stay. |
+
+Use `ls` to see what a committed cache would replay, and `clear` when a
+recorded flow is stale — `--no-cache` only skips the cache for one run.
+
+## Output
+
+- `list` (default): one line per file and target, a `Failed Tests` section
+  with each error, its code, the failing line and a code frame, then a
+  summary (`Test Files`, `Tests`, `AI`, `Duration`, `Report`).
+- `.e2e/report.json` is written on every run whatever the reporters:
+  `run.status`, `run.exitCode`, `run.errors[]` (run-level failures such as
+  `APP_UNREACHABLE`), and `run.results[]`, one per test and target, with
+  `titlePath`, `file`, `source`, `status`, and `attempts[]` holding `steps[]`,
+  `artifacts[]`, and `error`.
+- `junit`: `.e2e/junit.xml` beside the report, for CI test summaries.
+  Combine it with the terminal output: `--reporter list,junit`.
+- `json`: the report document on stdout.
+- Artifacts (screenshots, Playwright traces, `--debug` transcripts,
+  downloads) live under `.e2e/artifacts/`; every path is recorded in the
+  report.
+
+## Exit codes
+
+| Code | Meaning |
+| ---: | --- |
+| 0 | Every selected test passed, was flaky, or was skipped |
+| 1 | A test or setup test failed or timed out |
+| 2 | CLI, config, collection, credential, model-config, or policy error |
+| 3 | Engine, app process, model provider, artifact, or cleanup failure |
+| 4 | Internal runner error |
+| 130 | Interrupted |
+
+The highest code present wins for a mixed run (`130 > 4 > 3 > 2 > 1 > 0`).
+Do not retry a job on exit 2: it is deterministic. Exit 3 is the only one
+where a job-level retry makes sense.
+
+Ctrl-C once interrupts and still writes the report; twice forces teardown;
+three times exits at once.
+
+## Continuous integration
+
+CI mode is on when `CI` is set (and not `0` or `false`). It changes
+`retries` to 1, `workers` to 1, rejects `test.only` with `ONLY_IN_CI`, makes
+the trace cache `read-only`, and ignores `reuseExisting`.
+
+```yaml
+# .github/workflows/e2e.yml
+name: e2e
+on:
+  pull_request:
+  push:
+    branches: [main]
+permissions:
+  contents: read
+jobs:
+  e2e:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: pnpm/action-setup@9fd676a19091d4595eefd76e4bd31c97133911f1 # v4.2.0
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: 26
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - run: npx playwright install chromium --with-deps
+      - run: npx --no-install e2e run --reporter list,junit
+        env:
+          E2E_USER_ADMIN_USERNAME: ${{ secrets.E2E_USER_ADMIN_USERNAME }}
+          E2E_USER_ADMIN_PASSWORD: ${{ secrets.E2E_USER_ADMIN_PASSWORD }}
+      - if: ${{ !cancelled() }}
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: e2e-report
+          path: |
+            .e2e/report.json
+            .e2e/junit.xml
+      - if: failure()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: e2e-artifacts
+          path: .e2e/artifacts
+          retention-days: 7
+```
+
+- Install browsers as their own step so the download never counts against a
+  launch timeout.
+- Start the app through the engine's `command`; the runner tears it down on
+  every exit path.
+- Agentic suites: a separate config, run on `schedule` or
+  `workflow_dispatch`, `E2E_MODEL` as a CI variable and `E2E_MODEL_API_KEY`
+  as a secret, never a required check.

package/skills/e2e/references/setup.md

@@ -0,0 +1,239 @@
+# Setting up e2e
+
+## Requirements
+
+- Node.js 22.12 or newer.
+- ES modules. The `package.json` nearest to the config and the tests must set
+  `"type": "module"`. An `e2e.config.mts` is ESM on its own, but `.ts` tests
+  still follow their package. In a CommonJS package either run
+  `npm pkg set type=module` (this also changes how its `.js` files run) or put
+  the tests in their own ESM package directory.
+- For browser tests, `@e2edev/playwright`. Missing browsers download when the
+  engine first boots. In CI install them up front:
+  `npx playwright install chromium --with-deps`.
+
+## Scaffold
+
+```bash
+npx @e2edev/e2e@beta init       # npm
+pnpm dlx @e2edev/e2e@beta init  # pnpm
+```
+
+When `@e2edev/e2e` is already installed, run `npx --no-install e2e init`
+instead, so the installed version scaffolds.
+
+The wizard asks for the engine (Playwright by default; None and agent-device
+are the alternatives), whether to enable AI testing (adds `ai@^7.0.0` and
+`createAgent` to the config), which agent directories receive this skill
+(`.agents/skills/` and `.claude/skills/`), a confirmation of the files it
+will write, and whether to install. `--yes` skips every prompt (use it from
+scripts and from a shell without a TTY): Playwright, AI on, no installation,
+skill in both directories. The closing line prints the run command,
+`APP_URL=http://localhost:3000 npx --no-install e2e run` for Playwright, and
+suggests a `tsconfig.json` when the project has none.
+
+Init writes `package.json` (a private ESM package when missing; otherwise
+only the missing dev dependencies and the `test:e2e` script are added),
+`e2e.config.ts`, `tests/example.e2e.ts`, `.gitignore` entries for the `.e2e/`
+output, and the skill. Existing config and test files are never touched. Re-run it after an
+upgrade to refresh the skill; it changes nothing else in an initialized
+project.
+
+Without the wizard:
+
+```bash
+npm install --save-dev @e2edev/e2e@beta @e2edev/playwright@beta ai@^7
+```
+
+`ai` (the Vercel AI SDK, v7) is only needed for `agent.*` steps.
+
+## The config
+
+`e2e.config.ts` sits at the project root and default-exports an object
+literal ending in `satisfies E2EConfig`. The runner validates it at load:
+unknown keys are `INVALID_CONFIG`.
+
+```ts
+import type { E2EConfig } from '@e2edev/e2e';
+import { createAgent } from '@e2edev/e2e/agent';
+import { playwright } from '@e2edev/playwright';
+
+export default {
+  tests: 'tests/**/*.e2e.ts',
+  targets: [
+    {
+      name: 'web',
+      platform: 'web',
+      engine: playwright({
+        url: 'http://127.0.0.1:3000',
+        command: { executable: 'pnpm', args: ['dev'], log: '.e2e/logs/app.log' },
+      }),
+    },
+  ],
+  // Only for agent.* steps. The model comes from E2E_MODEL unless set here.
+  agent: createAgent({ system: 'You are a thorough QA agent. Verify every outcome on screen.' }),
+  credentials: {
+    admin: { username: 'admin@example.test', password: process.env.ADMIN_PASSWORD ?? '' },
+  },
+} satisfies E2EConfig;
+```
+
+| Key | Default | Notes |
+| --- | --- | --- |
+| `targets` | required | Non-empty. Each target: `name` (used by `--target` and in reports), `platform` (`web`, `ios`, `android`, or any label), `engine`. |
+| `tests` | `'tests/**/*.e2e.ts'` | A glob or an array of globs, `/` separators. |
+| `timeout` | `120000` | Per test attempt, in ms. Also the default `agent.act` deadline. |
+| `actionTimeout` | `30000` | Every locator action and engine operation, including each observation inside an agent step. Raise it for slow model providers. |
+| `assertionTimeout` | `5000` | `expect` polling window. |
+| `retries` | `0`, `1` in CI | 0 to 10. |
+| `workers` | half the cores, `1` in CI | Test files run in parallel across workers. Use `1` for device targets. |
+| `reporters` | `['list']` | `list`, `json`, `junit`. `json` excludes `list`. |
+| `cache` | `'read-write'`, `'read-only'` in CI | The trace cache for `agent.act`; `'off'` disables it. |
+| `agent` | unset | `createAgent(...)`, an options block `{ model, context, visionModel, maxSteps, maxModelCalls, vision, providerOptions }`, or a custom `StepExecutor`. Omitted, the built-in agent runs with `E2E_MODEL`. |
+| `credentials` | `{}` | Named `{ username, password, allowedOrigins? }` entries; `password` may be a function returning the value. |
+| `screen.testIdAttribute` | `'data-testid'` | Attribute read by `getByTestId`. |
+| `artifacts` | `['screenshot', 'trace']` | Kinds to keep, or `{ kinds, store }`. |
+| `projectId` | the package name | Report and cache identity. |
+
+## The app under test
+
+The engine declares the app; the runner owns navigation policy, the app
+process, and identity. `playwright()` accepts:
+
+| Option | Meaning |
+| --- | --- |
+| `url` | Base URL for `app.open()` and relative navigation. A missing scheme becomes `https://`, or `http://` for a loopback host. Required once a test navigates. |
+| `command` | The process that serves `url`. See below. |
+| `readyUrl` | Readiness probe when it differs from `url`. |
+| `services` | Dependency processes started before `command`, in order. |
+| `allowedOrigins` | Origins tests and the agent may navigate to. Default: the origin of `url`. |
+| `environment` | `'test'`, `'staging'`, `'production'`. Inferred from the host; a label for the report and the cache key. |
+| `identity` | Stable app identity for cache and session keys when the origin changes per deploy (preview URLs). |
+| `browser` | `'chromium'` (default), `'firefox'`, `'webkit'`. |
+| `viewport` | `{ width, height }`, default 1280x720. |
+| `connect` | `{ cdpEndpoint }` to attach to a remote Chromium over CDP instead of launching. |
+
+Two browsers are two targets sharing one app declaration:
+
+```ts
+const app = { url: 'http://127.0.0.1:3000' };
+export default {
+  targets: [
+    { name: 'chromium', platform: 'web', engine: playwright(app) },
+    { name: 'mobile-webkit', platform: 'web', engine: playwright({ ...app, browser: 'webkit', viewport: { width: 390, height: 844 } }) },
+  ],
+} satisfies E2EConfig;
+```
+
+### Let the runner start the app
+
+Prefer `command` over a hand-started dev server: the run is then
+self-contained locally and in CI.
+
+```ts
+engine: playwright({
+  url: 'http://127.0.0.1:3000',
+  services: [
+    {
+      name: 'postgres',
+      executable: 'docker',
+      args: ['compose', 'up', '--wait', 'postgres'],
+      waitForExit: true,
+      teardown: { executable: 'docker', args: ['compose', 'down'] },
+    },
+    { name: 'migrate', executable: 'pnpm', args: ['db:migrate'], waitForExit: true },
+  ],
+  command: {
+    executable: 'pnpm',
+    args: ['dev'],
+    env: { PORT: '3000', DATABASE_URL: process.env.DATABASE_URL ?? '' },
+    startupTimeout: 120_000,
+    log: '.e2e/logs/app.log',
+  },
+}),
+```
+
+How it behaves:
+
+- The runner spawns `command`, polls `readyUrl` (default `url`) until a
+  200 to 499 status arrives within `startupTimeout` (default 60 s), and stops
+  the process when the run ends, fails, or is interrupted. Never ready is
+  `APP_UNREACHABLE`; `.e2e/report.json` is still written.
+- The child inherits only `PATH`, `HOME`, and the temp-directory variables,
+  plus `command.env`. Anything the app needs (database URL, API keys) must be
+  passed through `env` explicitly. Model keys and `E2E_USER_*` values are
+  never inherited.
+- Output is discarded unless `log` names a file. Set it; a server that dies
+  on boot is otherwise invisible. Keep the file under an ignored directory
+  such as `.e2e/logs/`.
+- If `url` already answers before the spawn, the run fails with
+  `APP_ALREADY_RUNNING`. Set `reuseExisting: true` for local development to
+  attach to a dev server that is already up; CI ignores the flag.
+- `services` start one at a time in declaration order. Each declares
+  `readyUrl` (polled) or `waitForExit: true` (ready when it exits 0). On
+  every exit path the runner stops the app, stops the services in reverse,
+  then runs their `teardown` commands in reverse.
+- `executable` is resolved on `PATH` and never shell-interpreted. Point it at
+  the server itself rather than at a wrapper script.
+
+To test an app started elsewhere, point `url` at it and start it yourself,
+or read the address from the environment:
+`url: process.env.APP_URL ?? 'http://localhost:3000'`. The runner reads no
+`APP_URL` itself; the config does.
+
+## Environment variables the runner reads
+
+| Variable | Effect |
+| --- | --- |
+| `E2E_MODEL` | `provider/model-id` for `agent.*` steps when the config sets no model. Routed through the Vercel AI Gateway. |
+| `E2E_MODEL_API_KEY` | Credential for that model. `AI_GATEWAY_API_KEY` is the fallback. |
+| `E2E_MODEL_ENDPOINT` | Any OpenAI-compatible endpoint URL for that model; the gateway is the default. HTTPS unless loopback. `agent.model.endpoint` wins. |
+| `E2E_VISION_MODEL` | Model for calls with `vision`; falls back to the main model. |
+| `E2E_USER_<NAME>_USERNAME`, `E2E_USER_<NAME>_PASSWORD` | Override `credentials.<name>`. `<NAME>` is the credential name uppercased, other characters as `_`. |
+| `CI` | Turns on CI defaults: `retries: 1`, `workers: 1`, `test.only` rejected, cache read-only, `reuseExisting` ignored. |
+
+## Mobile targets
+
+`@e2edev/agent-device` drives iOS simulators and Android emulators through
+[agent-device](https://github.com/callstack/agent-device). It needs Xcode
+with a simulator runtime, or the Android SDK with an emulator; run
+`npx agent-device doctor` once.
+
+```ts
+import type { E2EConfig } from '@e2edev/e2e';
+import { createAgent } from '@e2edev/e2e/agent';
+import { agentDevice } from '@e2edev/agent-device';
+import { agentDeviceTools } from '@e2edev/agent-device/tools';
+
+const iphone = agentDevice({ platform: 'ios', app: 'com.example.app' });
+
+export default {
+  targets: [{ name: 'ios', platform: 'ios', engine: iphone }],
+  workers: 1,
+  agent: createAgent({ tools: agentDeviceTools(iphone) }),
+} satisfies E2EConfig;
+```
+
+- `app` is a bundle id, package name, or display name opened fresh per
+  attempt. `appPath` installs a `.app` or `.apk` once per worker; without
+  `app`, the installed bundle is the one opened.
+- `workers: 1`: workers share one simulator.
+- `screen`, `expect`, `app`, and `agent` work unchanged. Import `test` from
+  `@e2edev/agent-device` to type the `device` fixture (`setAppearance`,
+  `setNetwork`, `setPermission`, `installApp`, `locator('role=... id=...')`,
+  and more). Portable suites declare `requires: ['device']`.
+- No `state` capability: `test.setup` and `session` are unavailable on a
+  device. Sign in with deterministic `screen` actions; `agent.act` cannot
+  fill a `Secret` on a device.
+- A deterministic check that names a platform label runs on one platform
+  only: `test('...', { platforms: ['ios'] }, ...)`.
+- `selectOption`, `setInputFiles`, and `scrollIntoView` are
+  `UNSUPPORTED_CAPABILITY` on a device.
+
+## Done when
+
+- `npx --no-install e2e run tests/example.e2e.ts` passes against the app.
+- `package.json` has a script such as `"test:e2e": "e2e run"`.
+- `.gitignore` lists the `.e2e/` outputs (init adds them). Committing
+  `.e2e/cache/` is opt-in: remove that line to share `agent.act` replays.
+- CI runs the deterministic suite on pull requests; see `running`.

package/skills/e2e/references/writing-tests.md

@@ -0,0 +1,289 @@
+# Writing tests
+
+## A complete file
+
+```ts
+// tests/todos.e2e.ts
+import { test } from '@e2edev/playwright';
+import { expect } from '@e2edev/e2e';
+
+test.describe('todos', { tags: ['todos'] }, () => {
+  test.beforeEach(async ({ app }) => {
+    await app.open('/todos');
+  });
+
+  test('adds and completes a todo', async ({ screen, web }) => {
+    await screen.getByLabel('New todo').fill('Write the release notes');
+    await screen.getByRole('button', { name: 'Add' }).tap();
+
+    await expect(screen.getByRole('listitem')).toHaveCount(1);
+    await expect(screen.getByRole('status', { name: 'Remaining' })).toHaveText('1 remaining');
+
+    await screen.getByRole('checkbox', { name: 'Write the release notes' }).check();
+    await expect(screen.getByRole('status', { name: 'Remaining' })).toHaveText('0 remaining');
+    await expect(web).toHaveURL('/todos');
+  });
+
+  test('ignores an empty submission', async ({ screen }) => {
+    await screen.getByRole('button', { name: 'Add' }).tap();
+    await expect(screen.getByRole('listitem')).toHaveCount(0);
+  });
+});
+```
+
+Files match the config `tests` glob, default `tests/**/*.e2e.ts`. Every test
+starts from clean state: a fresh browser context and no page open, so a test
+calls `app.open()` first (here in `beforeEach`).
+
+## Registration
+
+`test` is the only registration surface; everything registers while the file
+is imported, so a `describe` body is synchronous (an `async` body is a
+`COLLECTION_ERROR`).
+
+```ts
+test('title', async ({ app, screen }) => {});
+test('title', { tags: ['smoke'], retries: 2, timeout: 60_000 }, async ({ app }) => {});
+test.describe('group', { tags: ['billing'] }, () => { /* tests and hooks */ });
+test.describe('checkout flow', { serial: true }, () => { /* ordered, shared app state */ });
+test.beforeEach(async ({ app }) => {});     // per attempt, with test fixtures
+test.afterEach(async ({ screen }) => {});   // runs after failures too, with its own cleanup budget
+test.beforeAll(async ({ platform }) => {}); // per suite realm, no app fixtures
+test.afterAll(async () => {});
+test.skip('later', async () => {});
+test.only('focus', async () => {});         // local only: CI fails with ONLY_IN_CI
+test.setup('sign in', { sessions: ['admin'] }, async ({ app, screen, session }) => {}); // see Sign-in sessions
+```
+
+| Option | Default | Notes |
+| --- | --- | --- |
+| `timeout` | `config.timeout`, 120 s | Covers `beforeEach` and the body. |
+| `retries` | `config.retries` | 0 to 10. On a serial group, the group's value applies. |
+| `tags` | `[]` | Union across layers. Select with `--tag smoke`; `--tag-mode all` requires every tag. |
+| `skip` | unset | `true` or a reason string. |
+| `platforms` | unset | Run only on targets with these platforms, e.g. `['ios']`. |
+| `requires` | `[]` | Capabilities the engine must contribute, e.g. `['web']`. Otherwise the test is skipped at selection instead of failing with `UNSUPPORTED_CAPABILITY`. |
+| `session` | unset | Restore state saved by a setup test. |
+| `agentContext` | unset | Extra context for `agent.*` calls in this test or group. |
+| `serial` | `false` | Groups only. Members share one app state, run in order on one worker, and retry as a whole. Inside, per-member `retries`, `session`, `platforms`, `requires`, and `skip` are errors. |
+
+Hook order follows nesting, not position: outer `beforeEach` first, inner
+`afterEach` first. `beforeAll` runs again for every retry and every serial
+group, because each is a fresh module realm.
+
+## Fixtures
+
+Fixtures are lazy; destructure them in the callback.
+
+| Fixture | Type | Available |
+| --- | --- | --- |
+| `app` | `App` | Always. |
+| `screen` | `Screen` | Always. |
+| `agent` | `Agent` | Needs a configured model, else `MODEL_UNAVAILABLE`. See the `agent` topic. |
+| `platform` | `'web' \| 'ios' \| 'android' \| string` | Always; also in `beforeAll` and `afterAll`. |
+| `web` | `Web` | Browser targets. Import `test` from `@e2edev/playwright`. |
+| `device` | `Device` | Device targets. Import `test` from `@e2edev/agent-device`. |
+| `session` | `SetupSession` | Only in `test.setup`. |
+
+### app
+
+| Method | Does |
+| --- | --- |
+| `open(path?)` | Opens the engine's `url`, a path relative to it, or an absolute URL inside `allowedOrigins`. |
+| `back()` | One history step back. |
+| `restart()` | Recreates the context and keeps persisted state, including a restored session. |
+| `clearState()` | Clears cookies and storage, then relaunches. Not inside a serial group. |
+| `deepLink(url)` | Opens an allowed deep or universal link. |
+| `screenshot(label?)` | Saves a redacted screenshot as an artifact and returns its path. |
+
+## Locators
+
+`screen.getBy*` builds a lazy query; nothing resolves until an action, read,
+or assertion runs. Every query also exists on a locator, scoped to its
+subtree.
+
+| Query | Matches |
+| --- | --- |
+| `getByRole(role, { name?, exact?, checked?, disabled?, selected?, expanded?, hidden?, visible? })` | Semantic role, optionally by accessible name and state. First choice. |
+| `getByLabel(text, { exact?, visible? })` | Form controls by label. |
+| `getByPlaceholder(text)` | Inputs by placeholder. |
+| `getByText(text, { exact?, visible? })` | Visible text. |
+| `getByDisplayValue(value)` | Inputs by current value. |
+| `getByTestId(id, { visible? })` | `data-testid` (or `screen.testIdAttribute`). Last resort. |
+
+Roles: `button`, `link`, `textbox`, `searchbox`, `combobox`, `listbox`,
+`option`, `checkbox`, `radio`, `switch`, `slider`, `image`, `heading`, `tab`,
+`menuitem`, `list`, `listitem`, `table`, `row`, `cell`, `columnheader`,
+`status`, `alert`, `dialog`, `alertdialog`, `main`, `navigation`, `banner`,
+`contentinfo`, `complementary`, `region`. The union is closed; anything else
+is a type error.
+
+Text matching is exact by default after whitespace normalization.
+`exact: false` is a case-insensitive substring match; a `RegExp` matches as
+written.
+
+Rules:
+
+- An action, read, or assertion needs exactly one match. Two matches fail
+  immediately with `LOCATOR_AMBIGUOUS`; zero matches poll until the timeout,
+  then `LOCATOR_NOT_FOUND`. `toHaveCount` and `toBeHidden` are the
+  exceptions.
+- Narrow with `filter({ hasText })`, `filter({ has: locator })`, `first()`,
+  `last()`, `nth(i)`, or by scoping under another locator.
+- `visible: true` drops nodes the page hides (a closed drawer, a prerendered
+  duplicate) before the exactly-one rule. Reach for it when a query is
+  ambiguous even though one element is on screen.
+
+```ts
+const row = screen.getByRole('listitem').filter({ hasText: 'Invoice 42' });
+await row.getByRole('button', { name: 'Void' }).tap();
+await screen.getByText('Save', { visible: true }).first().tap();
+await screen.scrollUntilVisible(screen.getByRole('button', { name: 'Accept' }));
+```
+
+### Actions
+
+Each action resolves one node, waits for it to be actionable within
+`config.actionTimeout` (30 s, or `{ timeout }`), and performs one operation.
+
+`tap()` (alias `click()`), `doubleTap()`, `longPress({ durationMs? })`,
+`fill(value | Secret)`, `clear()`, `press(key)`, `check()`, `uncheck()`,
+`selectOption(label | { label } | { index })`, `focus()`, `hover()`,
+`setInputFiles(paths)` (relative to the project root), `dragTo(locator)`,
+`scrollIntoView()`, `swipe({ direction, momentum? })`.
+
+### Reads
+
+Reads resolve once and do not retry: `textContent()`, `inputValue()`,
+`getAttribute(name)`, `isVisible()`, `isEnabled()`, `isChecked()`,
+`boundingBox()`, `count()`. `waitFor({ state?: 'visible' | 'hidden', timeout? })`
+waits for a state. When a value has to settle, use `expect` instead of a
+read. Reading a password field's value is `POLICY_DENIED`.
+
+## expect
+
+`expect(locator)` polls for up to `config.assertionTimeout` (5 s) or
+`{ timeout }`; `.not` inverts. `expect(web)` gives the browser matchers.
+`expect(value)` is synchronous.
+
+```ts
+await expect(screen.getByRole('status')).toHaveText('Saved');
+await expect(screen.getByRole('dialog')).not.toBeVisible({ timeout: 10_000 });
+await expect(screen.getByTestId('todo')).toHaveCount(3);
+await expect(web).toHaveURL('/dashboard');   // relative to the base URL, or a RegExp
+await expect(web).toHaveTitle(/Dashboard/);
+expect(await screen.getByTestId('total').textContent()).toContain('$');
+```
+
+| Locator matchers | Web matchers | Value matchers |
+| --- | --- | --- |
+| `toBeVisible`, `toBeHidden`, `toBeEnabled`, `toBeDisabled`, `toBeChecked`, `toBeSelected`, `toBeExpanded`, `toHaveText`, `toContainText`, `toHaveValue`, `toHaveCount`, `toHaveAccessibleName` | `toHaveURL`, `toHaveTitle` | `toBe`, `toEqual`, `toBeTruthy`, `toBeFalsy`, `toBeNull`, `toBeUndefined`, `toBeDefined`, `toContain`, `toMatch`, `toBeGreaterThan`, `toBeLessThan` |
+
+`toHaveText` compares the whole normalized text; `toContainText` a
+substring or a RegExp. A failed matcher is `ASSERTION_FAILED`, exit code 1.
+
+## Sign-in sessions
+
+Sign in once in a setup test, save the state under a name, and let other
+tests declare it. Selecting a dependent test alone still runs its setup.
+
+```ts
+// tests/auth.setup.e2e.ts
+import { test } from '@e2edev/playwright';
+import { expect, credentials } from '@e2edev/e2e';
+
+test.setup('authenticate as admin', { sessions: ['admin'] }, async ({ app, screen, session, web }) => {
+  const admin = credentials.user('admin');
+  await app.open('/login');
+  await screen.getByLabel('Email').fill(admin.username);
+  await screen.getByLabel('Password').fill(admin.password);
+  await screen.getByRole('button', { name: 'Sign in' }).tap();
+  await expect(web).toHaveURL('/dashboard'); // prove the sign-in worked before saving
+  await session.save('admin');
+});
+```
+
+```ts
+// tests/dashboard.e2e.ts
+import { test, expect } from '@e2edev/e2e';
+
+test('the dashboard opens directly', { session: 'admin' }, async ({ app, screen }) => {
+  await app.open('/dashboard');
+  await expect(screen.getByRole('heading', { name: 'Dashboard' })).toBeVisible();
+});
+```
+
+- Setup tests are top-level (not inside `describe`); exactly one setup saves
+  a given name; the body saves every declared name once (`SESSION_CONTRACT`
+  otherwise).
+- A session holds cookies, local storage, and IndexedDB, for one run only.
+  The files are encrypted and deleted at cleanup. Server state is not part of
+  it.
+- Credentials live in the config; values come from the environment:
+
+```ts
+credentials: {
+  admin: { username: 'admin@example.test', password: process.env.ADMIN_PASSWORD ?? '' },
+},
+```
+
+`E2E_USER_ADMIN_USERNAME` and `E2E_USER_ADMIN_PASSWORD` override either
+field per run. `credentials.user('admin').password` is a `Secret` with no
+plaintext accessor; only `fill()` and `agent.act` params accept it. Once a
+secret is filled, screenshots stop being attached for the rest of that
+attempt, so sign in inside a setup test and keep the evidence in the tests
+that matter.
+
+## The web fixture (browser only)
+
+Import `test` from `@e2edev/playwright`. Prefer `app` and `screen`; use
+`web` for what only a browser has. Portable suites declare
+`requires: ['web']` so device targets skip the test instead of failing.
+
+| Method | Does |
+| --- | --- |
+| `goto(url, { waitUntil? })`, `reload()`, `back()`, `forward()` | Navigation. `goto` accepts a path relative to the base URL. |
+| `url()`, `title()`, `waitForURL(url \| RegExp)` | Reads and a URL wait. |
+| `locator(css)` | Raw CSS or XPath. Not portable; a last resort. |
+| `frameLocator(css)` | A `Screen` scoped to one iframe: `web.frameLocator('#payment').getByLabel('Card number')`. |
+| `evaluate(fn, arg?)` | Runs serialized code in the page. JSON in and out only, no closures. |
+| `route(pattern, handler)`, `unroute(pattern)` | Intercept requests: `route.fulfill({ json })`, `route.continue()`, `route.abort()`. |
+| `waitForResponse(pattern)` | Resolves with `{ status, headers, json(), text() }`. |
+| `cookies()`, `setCookies([...])` | Cookies within `allowedOrigins`. |
+| `setViewport({ width, height })` | Resize. |
+| `onDialog('accept' \| 'dismiss' \| handler)` | Returns an unsubscribe function. Register it before the tap that opens the dialog. |
+| `waitForDownload(() => trigger)` | Returns `{ path, suggestedFilename }`. |
+| `keyboard.press(key)`, `keyboard.type(text)`, `mouse.*` | Unfocused input. Prefer `locator.press` and `locator.fill`. |
+
+```ts
+await web.route('**/api/quote', (route) => route.fulfill({ json: { cents: 4200 } }));
+const response = await web.waitForResponse('**/api/orders');
+expect(response.status).toBe(201);
+```
+
+## Patterns that keep suites honest
+
+- Find selectors in the source, not by guessing: read the component or
+  template for labels, roles, and text. Add an `aria-label` or a heading
+  where the app has no accessible name, rather than falling back to CSS.
+- Create the data a test needs under a name unique to the run
+  (`Invoice ${Date.now()}`) and clean up in `afterEach`. Replays and retries
+  then never trip over leftovers.
+- One flow across several tests: `test.describe('...', { serial: true })`.
+  Otherwise tests are independent and may run on different workers.
+- Tag by area and by cost (`smoke`, `billing`, `agent`) and run subsets with
+  `--tag`.
+- Mix agent steps in where the path varies and pin the outcome with
+  `expect`; see the `agent` topic.
+
+## Mistakes to avoid
+
+- Sleeps or manual polling loops. Use a matcher with a longer `timeout`.
+- `web.locator('.btn-primary')` when `getByRole('button', { name })` exists.
+- `expect(await locator.textContent()).toBe(...)` for a value that is still
+  changing; use `toHaveText`.
+- Hardcoded passwords or tokens.
+- Sharing state between tests without `serial`.
+- `test.only` left in a file: CI fails with `ONLY_IN_CI`.
+- Asserting an exact sentence a model produced; assert the fact with
+  `toContain`.