@unotest/web 0.9.1 → 0.11.0

package/.claude/skills/write-e2e-test-ground/SKILL.md

@@ -0,0 +1,787 @@
+---
+name: write-e2e-test-ground
+description: Write a new E2E test for the web application under test using @unotest/web, on a server running in GROUND mode (UNOTEST_SNAPSHOT=0 — no page snapshots; discovery via the semantic ground_element tool). Records actions through explore_step against the live browser, generates a DSL test file, and verifies it via run_test. Use when the user asks to write/cover/add a test AND the unotest-web server has no get_page_snapshot tool.
+---
+
+# Skill: write-e2e-test-ground
+
+You are writing an end-to-end test using `@unotest/web` against a web
+app. The test lives in `unotest/e2e/<feature>/<name>.js` in the project
+under test (NOT in the `@unotest/web` package itself). Scenarios are
+grouped by feature/page in subfolders — never placed directly in the
+`unotest/e2e/` root (the linter rejects that with `lint:scenario-in-root`).
+
+**Default mode is verify-against-live-app.** A test that hasn't been
+run is unverified — selectors may be invented, transitions may race,
+the scenario may not actually pass. Producing a test you can't show
+green is the failure case.
+
+Two modes, picked at Phase 1:
+
+- **Interactive (preferred)** — phases 1–5 below. The MCP server is up
+  (`new_context`, `ground_element`, `explore_start`, `explore_step`,
+  `run_test`, …). You drive the browser live, record the flow, generate
+  the DSL, save it, run it, iterate until green.
+
+- **Draft-only (fallback)** — if no MCP / no working `explore_start`,
+  write the file from the description the user gave you, mark it as
+  unverified in your final reply ("⚠ unverified — no live browser —
+  run `npx @unotest/web e2e <name>` after fixing the env"), and STOP.
+  Don't pretend a draft is a working test.
+
+**This server runs in ground mode (`UNOTEST_SNAPSHOT=0`).** Page
+snapshots do not exist here — there is NO `get_page_snapshot` tool.
+You normally need NO separate discovery call either: act directly
+with an **INTENT LOCATOR** — the runner grounds it to the element
+inside the same call:
+
+```
+locator: {kind:"locator", steps:[{kind:"intent",
+          intent:"<the element in the user's words>",
+          ordinal?: "first" | "last" | N}]}
+```
+
+One `explore_step` per action, no lookup round-trip. Positions go in
+`ordinal` (typed), NEVER in the intent text ("first Pending row" →
+intent `"the Pending row"` + `ordinal: "first"`). Name the target
+itself, not its page region.
+
+Lookup tools — only when you must LOOK before acting:
+
+- `ground_element {intent, ordinal?}` — same grounding as a lookup:
+  returns the element line + top-20 candidates. Use to explore an
+  unknown page or after an intent-locator error. NOT needed to check
+  what an intent resolves to when you are about to use it in a step —
+  the step's own reply carries `groundedTo`.
+- `find_element {role, name, near?}` — exact ARIA role+name query.
+
+## Workflow — record then generate then verify
+
+Five phases, in this order. Don't skip phases.
+
+### Phase 0 — read exactly these files, nothing else
+
+Three reads. Don't `find`/`tree`/`ls` the project. Don't open files
+outside this list — they won't tell you anything Phase 1+ doesn't.
+
+1. **`unotest/e2e/_template.js`** — Read it. Shows the DSL syntax.
+   When your default JS instincts disagree with the template, the
+   template wins.
+2. **`unotest/e2e/_helpers/`** — `Glob` to list `*.js`. If a filename
+   matches the flow you're about to record ("signin", "seed",
+   "checkout"), `Read` THAT file only. If `signin_as(email, password)`
+   exists, the test calls it instead of re-recording the same steps.
+   No matches → skip; move on.
+3. **`unotest/.env`** — Read it. Pulls `APP_BASE_URL`,
+   `DATABASE_URL`, etc. that the scenario will reach for.
+
+Then move to Phase 1. Three files in, exploration done.
+
+### Phase 1 — start the exploration
+
+```
+explore_start { scenario_name: "<feature>/<name>" } → { explorationId }
+```
+
+Keep the `explorationId` — every recorded step needs it.
+
+`explore_start` opens the browser itself. Do NOT call `new_context`
+first — it's for RESETTING the browser (Phase 5), not for starting.
+
+### Phase 2 — record the known steps as ONE batch
+
+**Batch-first default.** When the task brief already spells out the
+sequence (navigate → click X → click Y → verify), do NOT issue the
+steps one `explore_step` at a time — send them as ONE `explore_steps`
+call: `goto`, the actions, the CHECKS, and `autoRun: true`:
+
+```
+explore_steps {
+  explorationId,
+  autoRun: true,
+  steps: [
+    {action: "goto", url: "<FULL absolute URL from the task>",
+     description: "Open <page>", section: "Open <page>"},
+    {action: "click",
+     locator: {kind:"locator", steps:[{kind:"intent",
+               intent:"<target in the user's words>"}]},
+     description: "Click <target>", section: "<goal of the block>"},
+    {action: "assert_url", pattern: "<expected substring>",
+     description: "Arrived at <page>", section: "<goal of the block>"},
+    {action: "assert_text",
+     locator: {kind:"locator", steps:[{kind:"intent",
+               intent:"\"<expected text>\""}]},
+     text: "<expected text>", options: {exact: false},
+     description: "Shows <expected text>", section: "<goal of the block>"}
+  ]
+}
+```
+
+Up to 25 steps, per-step shape identical to `explore_step` (each step
+carries its OWN `section` + `description`). Sequential; stops at the
+FIRST failure; the reply has per-step status + `firstError`; only the
+steps that executed are recorded. Intent locators ground at execution
+time against the then-current page — navigation mid-batch is fine.
+
+Two intent rules that decide whether the batch survives first try:
+- `goto` takes the FULL absolute URL (relative paths are rejected
+  unless the project config defines a baseUrl).
+- Assert intents NAME THE VISIBLE TEXT of the target — quote it:
+  `"Space Rangers Junior Cadets"`, never a bare role like `main page
+  heading`: a page holds a dozen same-role units and the quoted text
+  is what disambiguates. Add a role word (`heading "…"`) ONLY when the
+  brief says the target is one — on many pages the text you are
+  verifying lives in a row or a link, and `heading "…"` then honestly
+  grounds to nothing.
+
+**The brief has no verification step? Verify with the text you already
+have.** The LAST thing the brief told you to click is named in the
+brief, so that same name is on the page you land on — assert it:
+
+```
+{action: "assert_text",
+ locator: {kind:"locator", steps:[{kind:"intent",
+           intent:"\"<the name you just clicked>\""}]},
+ text: "<the name you just clicked>", options: {exact: false},
+ section: "<goal of the block>", description: "Page shows <name>"}
+```
+
+Quote the text and nothing else — no `heading`, no `title`, unless the
+brief called it that. The intent is grounded against whatever unit
+actually carries those words (a link inside a table row counts).
+
+Do NOT go looking for something to assert. A `get_url` /
+`get_active_context` / lookup round-trip before the assert costs calls
+and buys nothing the brief didn't already give you. Where you ARE is
+in the reply already: a step that changed the address carries `url`,
+and what an intent hit carries `groundedTo`. `assert_url` is for
+when the brief names the destination URL — otherwise the text you
+clicked is the check. `autoRun` needs at least one verification step,
+so a batch without one splits the flow in two.
+
+**Record the checks as steps, not by hand.** `assert_text` /
+`assert_visible` / `assert_hidden` / `assert_value` / `assert_count` /
+`assert_url` execute live — a recorded assert has already passed
+against the real page, and the saved test gets the matching
+`assertText(...)` / `assertUrl(...)` lines. Never hand-edit assertions
+into the generated file.
+
+**A checkbox is verified with `assert_value` and `"true"` / `"false"`**
+— it asserts the CHECKED STATE. Do not reach for a CSS `:checked`
+selector: raw `locator(...)` is exactly what the recording flow exists
+to avoid, and the same intent locator that ticked the box verifies it.
+
+```
+explore_step {explorationId, action: "assert_value",
+  locator: {kind:"locator", steps:[{kind:"intent",
+            intent:"selection checkbox of the Pending row",
+            ordinal:"first"}]},
+  value: "true", description: "First Pending row is selected"}
+```
+
+**`autoRun: true` finishes the whole flow in this one call** when every
+step succeeded, at least one verification step (assert_* / wait_for_*)
+is recorded, the draft has no blocking warnings (DYNAMIC_TEXT /
+NO_DSL_PRIMITIVE — FRAGILE_LOCATOR passes and rides along in the
+reply), and the target file is new: it saves
+`unotest/e2e/<scenario_name>.js`, resets the browser context and runs
+the test — the reply carries `autoRun.run.next.outcome` (passed ⇔
+`"completed"`). Surface any returned `warnings` to the user. If a gate
+fails, the reply says `autoRun.status: "skipped"` + reason, the session
+stays active, and you finish with Phases 4–5 below.
+
+**When a batch stops at step N:** the executed prefix is already
+recorded — do not redo it. Repair step N with a single `explore_step`
+(re-phrase the intent / add a preparatory `wait_for` or
+`scroll_into_view`), then continue the remaining steps as a new batch
+(`autoRun` works there too).
+
+Fall back to single `explore_step` only when you genuinely don't know
+the next step yet (need a `ground_element` probe or an ad-hoc look at
+the page).
+
+### Phase 3 — discover, then act (loop)
+
+For each page state you traverse (when NOT covered by the Phase 2
+batch):
+
+1. **Act directly — intent locator, no discovery round-trip.**
+
+   ```
+   explore_step {
+     explorationId,
+     action: "check",
+     locator: {kind:"locator", steps:[{kind:"intent",
+               intent:"selection checkbox of the Pending row",
+               ordinal:"first"}]},
+     description: "Check the first Pending row",
+     section: "Select rows"
+   }
+   ```
+
+   The runner grounds intent → element → stable locator in ONE call.
+   The reply echoes `groundedTo` — the element line each intent hit
+   (`checkbox "Select row R-00147" (in row "…Pending…")`). Read it to
+   confirm the target instead of pre-probing with `ground_element`:
+   a probe grounds the same intent twice and buys nothing the reply
+   doesn't already say.
+   On `IntentResolveError`:
+   - `none` — re-phrase (name the target itself, not its page
+     region), or call `ground_element {intent}` to see the top-20
+     `candidates` of what IS perceived;
+   - resolves to a SET — add `ordinal` (`"first"` / `"last"` / N).
+
+2. **Act + record — pass the `[eN]` ref locator.**
+
+   ```
+   explore_step {
+     explorationId,
+     action: "click",
+     locator: {kind: "locator", steps: [{kind: "ref", ref: "e6"}]},
+     description: "Open sign-in dialog",
+     section: "Sign in"
+   }
+   ```
+
+   **CRITICAL — the locator is exactly one of three forms:**
+   - a single `{kind:"intent"}` step (preferred — no discovery call);
+   - `{kind:"locator", steps:[{kind:"ref", ref:"eN"}]}` where `eN` is
+     the **`ref`** field of a `find_element` reply;
+   - the ready-made **`locator`** object copied verbatim from a
+     `ground_element` reply (it already has that ref shape).
+
+   Never assemble a locator yourself from what those tools SHOW
+   (role, name, css) — that is not a fallback. Anything else
+   (synthesised `{kind:"getByRole",
+   ...}`, `{kind:"css", ...}`, multi-step chains) is **rejected by
+   `explore_step` in recording mode** with a `recording mode accepts
+   only ref locators` error. The recorder reads the ref off the live
+   DOM, picks the best stable identifier (testId → role+name → label →
+   text → href), verifies it uniquely matches the same element, and
+   writes the resolved form into the log. The agent never touches the
+   resolved locator — the saved test gets a clean `getByRole(...)` /
+   `getByTestId(...)` automatically.
+
+   **If the intent can't resolve** — that's a missing *preparatory*
+   step, not a reason to bypass the ref-resolver. Almost always one of:
+   - Off-screen → `scroll_into_view` action on the nearest visible
+     anchor, then retry the intent step.
+   - Async-rendered → `wait_for` / `wait_for_text`, then retry.
+   - Hover/click-revealed (menu, dropdown) → action on the trigger,
+     then retry.
+   - Inside iframe → `enter_frame`, then retry.
+
+   **`allowNoRef: true`** is an escape hatch for the truly-no-ref case
+   (Shadow DOM piercing, cross-context element with no shapshot entry).
+   It lets a hand-written locator through verbatim; the saved scenario
+   will be brittle. Use only after the preparatory steps above have
+   been exhausted. If you find yourself reaching for `allowNoRef`
+   repeatedly, stop and ask the user.
+
+   **Batching.** When the next several steps are known in advance
+   (fill + fill + click, a row of checks), send ONE
+   `explore_steps {explorationId?, steps:[…]}` call — up to 25 steps,
+   each with the same shape as `explore_step`. Sequential; stops at
+   the first failure; the reply carries per-step status +
+   `firstError`; only the steps that executed are recorded. A step that
+   CHANGED the address also carries `url` — that's where you are now,
+   no `get_url` / `get_active_context` round-trip needed.
+
+   **Record checks as assert steps** — `assert_text {locator, text,
+   options?: {exact}}`, `assert_visible {locator}`, `assert_hidden
+   {locator}`, `assert_value {locator, value}`, `assert_count
+   {locator, count}`, `assert_url {pattern}`. They execute live (poll
+   up to 5s), so a recorded assert has already passed against the real
+   page, and the generated test carries the matching `assertText(...)`
+   / `assertCount(...)` lines. Never hand-edit assertions into the
+   saved file.
+   Assert targets are looked up as WHOLE UNITS, not clickable
+   controls: the intent legally resolves to the heading / table row /
+   card itself — pass the `{kind:"intent"}` step and let the runner
+   pin it. Do NOT detour to `find_element` for assert targets. Name
+   the target by its VISIBLE TEXT, not by role alone: `heading
+   "Space Rangers Junior Cadets"`, not `main page heading` — a grid
+   page has a dozen look-alike headings and a role-only intent picks
+   the wrong one (the text in the intent is what disambiguates).
+   The final `explore_steps` batch of a scenario can add
+   `autoRun: true` — when every step succeeds, a verification step is
+   recorded and the draft has no blocking warnings (FRAGILE_LOCATOR
+   passes and is reported), it saves + resets context + runs the test
+   in the same call (reply: `autoRun.run.next.outcome`); otherwise it
+   reports `autoRun.status: "skipped"` + reason and the manual Phases
+   4–5 apply.
+
+   When recording, `description` and `section` are **required**.
+   Adjacent same-section entries are wrapped in one `step("...", () => { … })`
+   block in the generated test, so the `section` must read
+   like a line in a human test PLAN — the user-facing GOAL of the block
+   ("Sign in", "Open first car card", "Apply status filter"), **never** a
+   generic mechanic ("Navigation", "Actions", "Click", "Load data"). Use the
+   SAME label for every step of one block; don't reuse a label for a
+   different block, and never split one block into two same-named blocks
+   (e.g. two "Navigation" groups around the login). The `description` is one
+   short line naming the target concretely ("Double-click the first car
+   row"), not a vague "click".
+
+3. **Re-discover** after every action that changes the page (navigate,
+   open dialog, async re-render). Refs from the previous snapshot are
+   stale — using them throws `StaleRefError`.
+
+4. **Wrong step?** Remove before continuing:
+   ```
+   explore_remove_step { explorationId, entryId: "<from explore_step result>" }
+   ```
+   To add an assertion you forgot (or any step that you want recorded
+   without executing again): `explore_record { explorationId, action,
+   …, description, section }` — same shape as `explore_step` but
+   no execution.
+
+**Ad-hoc probes** — to try a click or fill without polluting the
+recording, **omit `explorationId`**. Refs forwarded as-is to the
+driver, no resolve/verify, nothing written.
+
+### Phase 4 — stop, generate, save
+
+**Skip Phases 4–5 when the last `explore_steps` ran with `autoRun` and
+replied `autoRun.status: "ran"`** — the scenario is already saved and
+executed; `autoRun.run.next.outcome === "completed"` is the pass
+signal. This manual flow is the fallback for `autoRun.status:
+"skipped"` (its `reason` names the gate) and for step-by-step authoring.
+
+```
+explore_stop { explorationId }
+generate_dsl_from_exploration { explorationId }  → { draftDsl, warnings }
+```
+
+**Warnings are instructions, not commentary — from BOTH generate and
+save.** Each carries its own fix recipe; a warning you read and skip
+resurfaces as a red run or a rejected review. Act on every one before
+moving to Phase 5:
+
+- **`FRAGILE_LOCATOR`** — element resolved but its identifier is
+  fragile (no testId / aria-label; only deep text). Best fix: ask the
+  app team to add a `data-testid`, then re-record the step. Acceptable
+  fallback: keep the warning and document.
+- **`DYNAMIC_TEXT`** — a matcher string carries a live value (counter /
+  date / amount): green today, red on the next page load. Replace with
+  the stable prefix or a regex matcher as the message suggests, then
+  regenerate.
+- **`NO_DSL_PRIMITIVE`** — captured shape has no matching DSL function.
+  The line renders as `// SKIPPED …`. Fix the entry (`explore_remove_step`
+  + `explore_record` with a different action) or pass `force: true` on
+  save to keep the comment inline.
+- **`NO_VERIFICATION`** (from save) — **the test is NOT ready.** It
+  performs actions but asserts nothing, so it stays green when the flow
+  silently breaks. Record an `assert_text` / `assert_url` (or
+  `wait_for_url` / `wait_for_text`) step — expected values taken from
+  the FACTUAL page (`get_url`), never guessed — and save again with
+  `overwrite: true`.
+
+Then persist:
+
+```
+save_exploration_as_test { explorationId, scenarioName: "<feature>/<name>" }
+```
+
+Writes `unotest/e2e/<feature>/<name>.js`. `scenarioName` MUST include a
+feature subfolder (e.g. `auth/login`) — a bare name is rejected. File
+exists? Pass `overwrite: true`. Re-read the returned `warnings` — save
+is the tool that reports `NO_VERIFICATION`.
+
+### Phase 5 — reset state, then run_test
+
+The recorded scenario starts wherever you left the browser. The saved
+test must start from a clean baseline. If your recording assumed
+"already signed in", the test won't be repeatable.
+
+Reset between recording and the first `run_test`:
+
+```
+close_context { }
+new_context { }
+```
+
+If the scenario relies on seeded data (DB rows, API state), make sure
+the seeder helpers run as the first scenario steps — `wipe_e2e_users();
+seed_user(...)` belong in the SETUP section.
+
+Then verify:
+
+```
+run_test { name: "<scenario-name>" }
+```
+
+`run_test` BLOCKS until the run settles — do NOT poll
+`inspect_runtime` to wait for completion (it stays a diagnostic tool
+for paused runs). The response carries `next.outcome`. **The scenario
+passed only when `next.outcome === "completed"`.** Any other value
+(`"failed"`, `"paused-failure"`, `"aborted"`) means the test failed —
+read `next.error` and iterate. `"running"` means the settle-wait timed
+out (`waitMs`, default 180s) — only then check `inspect_runtime`.
+`status: "started"` is just a lifecycle marker, not a pass signal.
+
+`paused-failure` keeps the browser context open and the runtime
+addressable by `runtimeId`. See **Failure recovery** below.
+
+Iterate until `next.outcome === "completed"`.
+
+## DSL cheat-sheet (web vocab)
+
+Method chains on locators are encouraged:
+`locator('.row').filter({hasText:'X'}).getByRole('button').click()`. Options-objects
+are standard: `click(loc, {force: true, timeout: 5000})`. Raw template
+strings are allowed for multi-line literals, but `${...}` interpolation
+is a parse error — pass values as positional args.
+
+What's **not allowed** (parser / runtime will reject): `import` /
+`export` / `require`, top-level `await`, `class`, JSX, `while` /
+`do…while` / `continue` / `++`. Bounded `for (i = 0; i < N; i = i + 1)`
+loops ARE supported, and `break` is legal inside a loop body — poll with
+`for` + `if (…) { break; }` + `pause(ms) // reason: …`. Index access
+reads data (`docs[0].count`, bare variable only, never a Locator);
+`obj.prop[i]` does not parse — assign the member first:
+`m = state.matches; last = m[m.length - 1];`. `arr[i] = v` stays
+rejected.
+
+Navigation:
+- `goto(url, opts?)`, `reload(opts?)`, `getUrl()`, `goBack()`, `goForward()`.
+
+Actions (selector arg always first):
+- `click(loc, opts?)`, `doubleClick(loc, opts?)`, `fill(loc, text, opts?)`,
+  `press(loc, key)`, `check(loc)`, `uncheck(loc)`, `selectOption(loc, value)`,
+  `hover(loc)`, `scrollIntoView(loc)`.
+
+Selectors (locator hierarchy — D-22, hard rule):
+1. **`getByTestId(id)`** — most stable.
+2. **`getByRole(role, {name})`** — accessibility-tree based.
+3. **`getByLabel(text)`** — form controls bound to a `<label>`.
+4. **`getByText(text)`** — visible text; brittle to copy edits.
+5. **`locator(cssSelector)`** — last resort. Linter warns on `>` /
+   descendant combinators and hashed CSS-module / Tailwind-JIT classes.
+
+**CSS selectors go through `locator("css-here")`, not `css("...")`.**
+There is no `css(...)` function. Read the line right above this one:
+when you reach for an attribute selector like `a[href*='catalogTree']`,
+write `locator("a[href*='catalogTree']")` — **not** `css("a[href*='catalogTree']")`.
+The validator rejects unknown function names as
+`validator:unknown-function` errors at lint time. Same for any other
+identifier you might guess — if it's not in this skill, it doesn't
+exist; don't invent.
+
+**Regex literals are allowed in matcher positions** — `getByText(/^Sets/)`,
+`getByRole("link", {name: /^Sets\b/})`, `.filter({hasText: /items/i})`.
+ES5 subset only (flags `g i m`; no lookbehind / named groups). Anywhere
+else (`nth(/x/)` etc.) a regex is a type error.
+
+When the live accessible name contains dynamic content (counts,
+timestamps, user data), anchor the **stable prefix** — regex is the
+preferred form because it can't collide the way substring matching does:
+
+```js
+// Live text on the page: "Sets 21,414 items"
+// BAD — captures the count, breaks on every page load:
+click(getByText("Sets 21,414 items", {exact: true}));
+// GOOD — regex anchored at the stable prefix:
+click(getByRole("link", {name: /^Sets\b/}));
+// RISKY — substring match: "Sets" also matches "Newest Sets" and
+// "Most Wanted Sets" → strict-mode violation with 3 elements. Use only
+// after check_locator proves it's unique:
+click(getByRole("link", {name: "Sets"}));
+```
+
+`getByRole` and `getByText` are **substring + word-boundary** by
+default; omit `exact: true` whenever the captured name includes
+content that may change.
+
+**Any locator you write or edit BY HAND must pass `check_locator`
+BEFORE run_test** — it proves `ofCount === 1` on the live page in one
+call. Every strict-mode violation in past runs came from a hand-edited
+locator that was never checked; a red run_test costs 10× more calls
+than the check.
+
+Prefer a semantic anchor over raw CSS: `locator("a[href*='…']")` is a
+LAST resort (and substring-href can match several links — check it
+too). A file whose locators are mostly `locator(css)` fails review.
+
+Disambiguate with `.filter({hasText: '…'})` or `.filter({has: …})` —
+**not** `.first()` / `.last()` / `.nth(N)` (linter flags
+`lint:disambig-by-index`).
+
+Waits:
+- `waitFor(loc, opts?)`, `waitForText(text, opts?)`,
+  `waitForCount(loc, n, opts?)`, `waitForUrl(pattern)`, `pause(ms)` —
+  `pause` requires `// reason: <why>` comment immediately above (linter
+  flags `lint:pause-explicit` otherwise).
+- `waitForText` waits for ≥1 VISIBLE occurrence (repeated text in a feed
+  is fine); substring by default — `{exact: true}` or a regex
+  (`waitForText(/\bhi\b/)`) when substring would false-match.
+- `waitForCount` polls until the locator matches AT LEAST n elements
+  (`{exact: true}` → exactly n) — the "wait for reply №N" chat pattern;
+  pass `{timeout}` generously for slow producers (LLM replies).
+
+Assertions:
+- `assertText(loc, text, opts?)`, `assertVisible(loc)`, `assertHidden(loc)`,
+  `assertCount(loc, n)`, `assertUrl(pattern)`, `assertTrue(expr, msg?)`.
+
+State reads:
+- `getTitle()`, `getUrl()`, `getAttribute(loc, name)`, `getInnerText(loc)`,
+  `getInputValue(loc)`.
+
+Sandbox primitives:
+- `shell("cmd", "arg", …)` — `execFile` style, no shell interpretation.
+- `dbQuery(sql, …params)`, `dbExec(sql, …params)` — parameterized.
+- `apiCall(method, path, body?, headers?, opts?)` — path-only against
+  `sandbox.apiBaseUrl`; another host via `{base: 'API_BASE_X'}` — the
+  NAME of a `unotest/.env` variable, never a URL. Multipart upload:
+  pass `upload('fixtures/doc.pdf', {field?, fields?})` as the body
+  (relative path inside the project / `sandbox.uploadDir`; don't set
+  Content-Type yourself). A JSON body with a `file` key posts as plain
+  JSON — there is no key-name magic.
+
+Escape hatch:
+- `evaluate(\`js body\`, …args)` — raw backticks, no `${}`. Linter
+  warns `lint:evaluate-discouraged`. Use only when nothing above fits.
+
+Time helpers: `nowMs()`, `today()`, `daysFromNow(n)`.
+
+## Helpers convention
+
+Reusable flows live in `unotest/e2e/_helpers/<group>.js` as plain `.js`
+exporting `snake_case` functions:
+
+```js
+// unotest/e2e/_helpers/signin.js
+function signin_as(email, password) {
+  // 2. ENTER — bring the app to the initial UI state
+  goto('/sign-in');
+
+  // 3. ACT — actions you are testing
+  fill(getByLabel('Email'), email);
+  fill(getByLabel('Password'), password);
+  click(getByRole('button', {name: 'Sign in'}));
+
+  // 4. ASSERT — UI + DB / API checks
+  waitForUrl('/dashboard');
+}
+```
+
+The runner auto-discovers helpers — no `import`. Call them like
+built-in DSL functions.
+
+**Naming:** `snake_case` distinguishes helpers from core DSL
+(`camelCase`); `test_*` is reserved for entry functions; `flow_*` for
+composite multi-step helpers.
+
+**Saved test structure.** Every step in a `test_*` entry must sit inside a
+`step("description", () => { … })` block (linter enforces). The title is the
+plain-English intent of the group; when a step later breaks you read it
+back to repair the group. The recorder groups by phase automatically; when
+you hand-edit, keep each chunk inside its own block:
+
+```js
+function test_dashboard_loads_with_widgets() {
+  step("Seed a fresh demo user", () => {
+    wipe_e2e_users();
+    seed_user('demo@example.com', 'secret');
+  });
+
+  step("Sign in as the demo user", () => {
+    signin_as('demo@example.com', 'secret');
+  });
+
+  step("Dashboard shows the Today widget", () => {
+    assertVisible(getByRole('region', {name: 'Today'}));
+  });
+}
+```
+
+(Helpers and `flow_*` composites are NOT wrapped — the rule applies only to
+`test_*` scenario entries.)
+
+## Failure recovery
+
+`paused-failure` from `run_test` keeps the browser context alive and
+the runtime addressable by `runtimeId`. `run_test` also auto-attaches
+you to that live page, so `ground_element` / `find_element` /
+`check_locator` already target the page being debugged — no manual
+`attach_debug_session`. Use the diagnostic tools:
+
+1. **`inspect_runtime { runtimeId }`** — `lastFailure` (error + line/col
+   + AST node) + `vars` (every assignment up to the pause). Tells you
+   what was observed vs expected and the state the scenario built.
+2. **`check_locator { locator }`** — paste the EXACT locator from the
+   failing line (e.g. `getByRole('row').filter({hasText:'Uma Quinn'}).first()`).
+   Reports, against the live paused page, how many elements it matches
+   and — when the chain ends in `.first()`/`.last()`/`.nth()` —
+   `pinned.ofCount`, the count that index op silently collapsed (a
+   `.first()` hiding 16 identical rows is the classic break), plus
+   per-match role/name/text/testId. Verify a selector at runtime
+   instead of guessing or re-running the whole test.
+3. **`ground_element { intent }`** — is the failing target perceived on
+   the CURRENT page at all? The `candidates` list also reveals whether
+   the page navigated somewhere unexpected (it shows what IS there).
+4. **`list_failures` + `get_failure_console` / `get_failure_trace` /
+   `get_failure_network`** — failure bundle. `get_failure_console` is
+   often the giveaway when the failure is really a runtime error in
+   the app.
+5. **`agent_fix { runId }`** — composes a structured fix-context
+   prompt. **It does NOT patch your code** (D-25); you apply edits.
+6. **`open_viewer { }`** — boots the localhost viewer for the project
+   if it isn't running, returns its URL. The viewer renders the block-
+   tree of the failing scenario with live status, plus a log-tail of
+   the child runner's stdio. Useful when you want a human (or yourself)
+   to look at the failure visually instead of paging through MCP-tool
+   output. Idempotent: a second call returns the same URL.
+
+After editing the scenario, `abort_runtime { runtimeId }` to release
+the old browser context, then `run_test` again.
+
+## `explore_step` cheat-sheet
+
+| `action`           | required                                | optional             |
+|--------------------|-----------------------------------------|----------------------|
+| `goto`             | `url`                                   | `options`            |
+| `reload`           |                                         | `options`            |
+| `go_back`          |                                         |                      |
+| `go_forward`       |                                         |                      |
+| `click`            | `locator`                               | `options`            |
+| `double_click`     | `locator`                               | `options`            |
+| `fill`             | `locator`, `value`                      | `options`            |
+| `press`            | `locator`, `value` (the key)            | `options`            |
+| `check` / `uncheck`| `locator`                               | `options`            |
+| `select_option`    | `locator`, `value`                      |                      |
+| `hover`            | `locator`                               | `options`            |
+| `scroll_into_view` | `locator`                               |                      |
+| `wait_for`         | `locator`                               | `options`            |
+| `wait_for_text`    | `value` (the text)                      | `options`            |
+| `wait_for_count`   | `locator`, `count`                      | `options`            |
+| `wait_for_url`     | `value` (the pattern)                   | `options`            |
+| `enter_frame`      | `locator`                               |                      |
+| `exit_frame`       |                                         |                      |
+
+When recording (`explorationId` present): `description` + `section`
+are required. Ad-hoc (no `explorationId`): no description/section,
+no recording.
+
+## Failure modes you will hit
+
+- **`StaleRefError`** — a ref from an earlier lookup is no longer in
+  the DOM. Intent locators don't go stale (grounded per call) — retry
+  with the intent step, or re-ground via `ground_element`.
+- **`RefResolveError`** — element has no stable identifier (testId /
+  role+name / aria-label / placeholder / alt / title / text / href /
+  stable id / name attribute). Best fix: ask the app team to add
+  `data-testid`. Fallbacks: provide a hand-written locator with
+  `allowNoRef: true` — e.g. `{locator:{kind:"locator",steps:[{kind:
+  "getByPlaceholder",text:"Foo"}]}, allowNoRef:true}` — **do NOT** pass
+  a `{kind:"ref"}` step with `allowNoRef:true`, the ref still tries to
+  resolve. Or use `find_element({role, name, near})` and use its ref.
+- **`AmbiguousResolveError`** — the resolved locator matches more than
+  one element (e.g. two `Sign in` buttons in different regions). Same
+  fix: add a testId or pass a more specific locator.
+
+## When a locator matches `N elements`
+
+Every locator must resolve to exactly one element. When you see
+`getByRole('row', {name: 'X'}) resolved to 301 elements`:
+
+- **`check_locator { locator }`** (when a browser is live) — paste the
+  chain and it tells you the exact `count` and, for a `.first()`/`.nth()`
+  chain, `pinned.ofCount` (how many it collapsed). The fastest way to
+  confirm a locator is over-matching and by how much, without re-running.
+- Narrow the `name` to a uniquely-identifying substring. `name`
+  substring-matches: pick wording that hits only one row (a header's
+  full label `"Pending (300)"` or a row-specific ID like `"573"`).
+- Use `find_element({role: 'row', name: '573', near: '<table-ref>'})`
+  to skip manual disambiguation — scoped search returns the single ref
+  directly.
+- Only use `.first()` / `.nth(N)` when the position itself is the
+  semantic anchor — and `check_locator` shows `pinned.ofCount === 1`.
+
+## Anti-patterns
+
+- **Don't explore the project before Phase 1.** No `find`, no `tree`,
+  no broad `ls`. Phase 0 lists three reads — do those, then start
+  recording. You learn the page by ACTING on it (intent locators) and
+  by `ground_element`, not from static project structure.
+- **Don't invent locators.** Pass a `{kind:"intent"}` step, or the
+  `locator` from a `ground_element` / `find_element` reply verbatim.
+  The recorder produces the stable form.
+- **Don't put positions into intent text.** "first"/"last"/№ go into
+  `ordinal` as data — the grounder never parses positions out of
+  words.
+- **Don't write `css(...)`.** That function does not exist. CSS
+  selectors go through `locator("css-here")`. Every time you reach for
+  `css("a[href*='...']")`, rewrite as `locator("a[href*='...']")`.
+  The validator rejects `css(...)` as `validator:unknown-function`
+  at lint time — your scenario will not pass `verify`.
+- **Don't pass `getByRole('link', {name: 'Sets 21,414 items'})`** —
+  the count is dynamic; anchor the stable prefix with a regex matcher
+  (`{name: /^Sets\b/}`). Hand-written `name` strings are guesses; the
+  ref resolver reads the real accessible name from the live DOM.
+- **Don't run run_test with a hand-edited locator you never
+  `check_locator`-ed.** Uniqueness on the live page is one call to
+  prove and every past strict-mode violation skipped it.
+- **Don't use `.first()` / `.last()` / `.nth(N)` to disambiguate
+  multi-matches.** Element order is brittle. Use `.filter({hasText:
+  '…'})` or `.filter({has: someLocator})`. Linter flags index-based
+  picking as `lint:disambig-by-index`.
+- **Don't reach for `locator(...)` with `>` combinators, hashed class
+  names, or `xpath=…`.** Stop and ask the user whether the app should
+  expose a `data-testid` or accessible name.
+- **Don't omit `section` / `description` when recording.** They shape
+  the generated test into readable `step(...)` blocks — and they're
+  required.
+- **Don't consider the task done without `next.outcome === "completed"`.**
+  "I recorded the flow, generated the file, looks right" is not done.
+  A green `run_test` is done.
+- **Don't `import` / `export` / `await` / `class` / arrow-functions
+  in the saved scenario.** DSL, not Node.
+
+## Fast feedback
+
+After editing any scenario (recorded or hand-written):
+
+```sh
+npx @unotest/web lint
+```
+
+The linter runs two passes:
+
+1. **Validator** (`validator:unknown-function`, `validator:dsl`) —
+   `error` severity (fails `npx @unotest/web lint`). Catches unknown function
+   names (`css`, typos), wrong arg kinds, malformed `for`/`if`
+   shapes. **If you see `validator:unknown-function`, you invented
+   a function name** — re-read the DSL cheat-sheet above and use the
+   real one.
+2. **Brittle-pattern linter** (`lint:deep-css`, `lint:xpath`,
+   `lint:obfuscated-class`, `lint:pause-explicit`,
+   `lint:evaluate-discouraged`) — `warn` severity. Doesn't gate
+   `verify` but indicates fragile locators that will break under
+   refactor.
+
+If lint flags `import` / `export` / `await` / `const` — re-read the
+DSL section above and rewrite as bare statements + function
+definitions.
+
+## What this surface is NOT for
+
+- **Production data mutation.** `apiCall` / `dbExec` against a
+  production base URL is a footgun — the `sandbox.*` pin model in
+  `unotest.config.{js,mjs,ts}` prevents it. Don't bypass.
+- **Browser automation for scraping.** This is an E2E testing tool;
+  scraping violates many target sites' terms of service.
+- **Calling external LLM APIs.** `agent_fix` builds prompts for the
+  agent **you** are. It does not delegate. No LLM client in this
+  package (D-25).
+
+## Commands you'll run
+
+```sh
+npx @unotest/web init           # one-time bootstrap (unotest/, config)
+npx @unotest/web e2e <name>     # run a scenario by basename
+npx @unotest/web lint           # validator + linter; errors gate verify
+```
+
+Always use `npx @unotest/web …` — not `pnpm` / `yarn` (those don't
+exist for end users).