@unotest/web 0.9.1 → 0.11.0

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

@@ -1,6 +1,6 @@
 ---
 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.
+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. If the unotest-web server runs WITHOUT page snapshots (no get_page_snapshot tool, UNOTEST_SNAPSHOT=0), use write-e2e-test-ground instead.
 ---
 
 # Skill: write-e2e-test
@@ -23,12 +23,13 @@ Two modes, picked at Phase 1:
   `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`,
+- **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.
 
+
 ## Workflow — record then generate then verify
 
 Five phases, in this order. Don't skip phases.
@@ -54,12 +55,14 @@ 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: "<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 — first recorded step: navigate
 
 ```
@@ -124,7 +127,8 @@ For each page state you traverse:
    ```
 
    **CRITICAL — pass `{kind:"ref", ref:"eN"}` from the most recent
-   `get_page_snapshot`.** Anything else (synthesised `{kind:"getByRole",
+   `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
@@ -151,6 +155,31 @@ For each page state you traverse:
    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.
+   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
@@ -182,21 +211,40 @@ 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 }
 ```
 
-Read the warnings before saving:
+**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:
 
@@ -206,7 +254,8 @@ 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`.
+exists? Pass `overwrite: true`. Re-read the returned `warnings` — save
+is the tool that reports `NO_VERIFICATION`.
 
 ### Phase 5 — reset state, then run_test
 
@@ -231,11 +280,14 @@ 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.
+`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.
@@ -251,8 +303,14 @@ 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).
+`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()`.
@@ -279,40 +337,56 @@ The validator rejects unknown function names as
 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.
+**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), use **substring matching by dropping
-`exact: true`**:
+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 update:
+// BAD — captures the count, breaks on every page load:
 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']"));
+// 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)`, `waitForUrl(pattern)`,
-  `pause(ms)` — `pause` requires `// reason: <why>` comment immediately
-  above (linter flags `lint:pause-explicit` otherwise).
+- `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)`,
@@ -325,8 +399,13 @@ State reads:
 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`.
+- `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
@@ -444,6 +523,7 @@ the old browser context, then `run_test` again.
 | `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`       |                                         |                      |
@@ -501,13 +581,13 @@ Every locator must resolve to exactly one element. When you see
   `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.
+  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