@unotest/web 0.5.0

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

@@ -0,0 +1,551 @@
+---
+name: write-e2e-test
+description: Write a new E2E test for the web application under test using @unotest/web. Records actions through explore_step (execute + record in one call) 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 for a feature, flow, or page.
+---
+
+# Skill: write-e2e-test
+
+You are writing an end-to-end test using `@unotest/web` against a web
+app. The test lives in `unotest/e2e/<name>.js` in the project under
+test (NOT in the `@unotest/web` package itself).
+
+**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`, `get_page_snapshot`, `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 `new_context`,
+  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.
+
+## 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
+
+```
+new_context { }                                  → { ok, url: "about:blank" }
+explore_start { scenario_name: "<flow-name>" }   → { explorationId }
+```
+
+Keep the `explorationId` — every recorded step needs it.
+
+### Phase 2 — first recorded step: navigate
+
+```
+explore_step {
+  explorationId,
+  action: "goto",
+  url: "<starting URL>",
+  description: "Open <page>",
+  section: "Setup"
+}
+```
+
+`goto` is almost always the first recorded step. Wait for the page to
+settle before discovering (the explore tooling waits for `load` by
+default — usually enough).
+
+### Phase 3 — discover, then act (loop)
+
+For each page state you traverse:
+
+1. **Discover** — `get_page_snapshot { }`. Default outline format:
+
+   ```
+   on_screen:
+     navigation:
+       - link "Sets 21,414 items" [e3]
+       - link "Themes" [e4]
+     main:
+       - heading "Browse the catalog" [e5]
+       - button "Sign in" [e6]
+   off_screen:
+     bottom:
+       - link "Help" [e21]
+   _meta:
+     viewport: 1280x720
+     totalNodes: 142
+   ```
+
+   Line grammar: `- [role] ["name"] [#testId] [eN]`. The `[eN]` ref
+   is what you'll pass back — refs are **wire-only**, never typed into
+   the saved test. Sections (navigation / main / dialog / form / cmp /
+   overlay) group related elements.
+
+   `off_screen` lists items past the viewport — they exist in the DOM
+   but aren't visible. Scroll first (`explore_step { action:
+   "scroll_into_view", locator: {kind:"locator", steps:[{kind:"ref", ref:"e21"}]} }`),
+   then re-snapshot.
+
+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 — pass `{kind:"ref", ref:"eN"}` from the most recent
+   `get_page_snapshot`.** 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 element you need isn't in the snapshot** — 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 re-`get_page_snapshot`.
+   - Async-rendered → `wait_for` / `wait_for_text`, then re-snapshot.
+   - Hover/click-revealed (menu, dropdown) → action on the trigger,
+     then re-snapshot.
+   - Inside iframe → `enter_frame`, then re-snapshot.
+
+   **`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.
+
+   When recording, `description` and `section` are **required**.
+   Adjacent same-section entries collapse into one `//@collapse(...) …
+   //@endcollapse` 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
+
+```
+explore_stop { explorationId }
+generate_dsl_from_exploration { explorationId }  → { draftDsl, warnings }
+```
+
+Read the warnings before saving:
+
+- **`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.
+- **`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.
+
+Then persist:
+
+```
+save_exploration_as_test { explorationId, scenarioName: "<name>" }
+```
+
+Writes `unotest/e2e/<name>.js`. File exists? Pass `overwrite: true`.
+
+### 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>" }
+```
+
+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. `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, `for`/`while`
+loops (use the `maxSteps` budget guards).
+
+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.
+
+**No regex literals.** `/pattern/` is a **parse error** (`Invalid
+token Token(type: SLASH)`) — the DSL lexer has only one meaning for
+`/`: division. Playwright-style `getByRole("link", {name: /^Sets/})`
+will NOT parse.
+
+When the live accessible name contains dynamic content (counts,
+timestamps, user data), use **substring matching by dropping
+`exact: true`**:
+
+```js
+// Live text on the page: "Sets 21,414 items"
+// BAD — captures the count, breaks on every update:
+click(getByText("Sets 21,414 items", {exact: true}));
+// BAD — regex doesn't parse:
+click(getByRole("link", {name: /^Sets/}));
+// GOOD — substring match against the stable prefix:
+click(getByRole("link", {name: "Sets"}));        // matches "Sets …"
+click(getByText("Sets", {exact: false}));        // also fine; exact: false is the default
+// ALSO GOOD — when href is stable:
+click(locator("a[href*='catalogTree.asp?itemType=S']"));
+```
+
+`getByRole` and `getByText` are **substring + word-boundary** by
+default; omit `exact: true` whenever the captured name includes
+content that may change.
+
+Disambiguate with `.filter({hasText: '…'})` or `.filter({has: …})` —
+**not** `.first()` / `.last()` / `.nth(N)` (linter flags
+`lint:disambig-by-index`).
+
+Waits:
+- `waitFor(loc, opts?)`, `waitForText(text)`, `waitForUrl(pattern)`,
+  `pause(ms)` — `pause` requires `// reason: <why>` comment immediately
+  above (linter flags `lint:pause-explicit` otherwise).
+
+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?)` — path-only against
+  `sandbox.apiBaseUrl`.
+
+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
+`//@collapse("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() {
+  //@collapse("Seed a fresh demo user")
+  wipe_e2e_users();
+  seed_user('demo@example.com', 'secret');
+  //@endcollapse
+
+  //@collapse("Sign in as the demo user")
+  signin_as('demo@example.com', 'secret');
+  //@endcollapse
+
+  //@collapse("Dashboard shows the Today widget")
+  assertVisible(getByRole('region', {name: 'Today'}));
+  //@endcollapse
+}
+```
+
+(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`. 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. **`get_page_snapshot { }`** — current page outline. Look for whether
+   the locator is reachable, or whether the page navigated somewhere
+   unexpected.
+3. **`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.
+4. **`agent_fix { runId }`** — composes a structured fix-context
+   prompt. **It does NOT patch your code** (D-25); you apply edits.
+5. **`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_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`** — ref no longer in the DOM. Re-`get_page_snapshot`
+  and use the new ref.
+- **`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`:
+
+- 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.
+
+## 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 from `get_page_snapshot`, not from
+  static project structure.
+- **Don't invent locators.** Use a ref from `get_page_snapshot`. The
+  `[eN]` ref already exists in the snapshot — copy it as
+  `{kind:"locator", steps:[{kind:"ref", ref:"eN"}]}` into the
+  `explore_step` call. The recorder produces the stable form.
+- **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 write regex literals.** `/^Sets/` is a parse error.
+  Substring-match instead: `getByRole("link", {name: "Sets"})` is
+  already substring (no `exact: true`).
+- **Don't pass `getByRole('link', {name: 'Sets 21,414 items'})`** —
+  the count is dynamic and the accessible name is usually `'Sets'`
+  alone. Hand-written `name` strings are guesses; the ref resolver
+  reads the real accessible name from the live DOM.
+- **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 `//@collapse` 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, gates `pnpm verify`. 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).