@unotest/web 0.9.0 → 0.10.0

package/src/mcp/prompts/agent-test-author.md

@@ -69,6 +69,65 @@ Disambiguate multi-matches with `.filter({hasText: '…'})` or
 `.nth(N)`. The linter flags index-based picking
 (`lint:disambig-by-index`) because element order is brittle.
 
+## Discovery: snapshot mode vs ground mode
+
+Which discovery tool exists depends on the server's mode — check the
+tool list once. `get_page_snapshot` present — snapshot mode. Absent
+(the server runs with `UNOTEST_SNAPSHOT=0`, ground mode) — it does not
+exist, do NOT search or retry for it. In ground mode you normally need
+no discovery call at all — act directly with an **intent locator**;
+the runner grounds it inside the same call:
+
+```
+locator: {kind:"locator", steps:[{kind:"intent",
+          intent:"<the element in the user's words>",
+          ordinal?: "first" | "last" | N}]}
+```
+
+Positions go in `ordinal` (typed), never in the intent text. Name the
+target itself, not its page region. Lookups for when you must look
+before acting: `ground_element {intent, ordinal?}` (element line +
+top-20 candidates) and `find_element {role, name, near?}` (exact ARIA
+query). Any "re-`get_page_snapshot`" advice below reads as "retry the
+intent step / re-ground via `ground_element`" in ground mode.
+
+## Batching: `explore_steps`
+
+When the next several steps are known in advance, 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.
+
+Every step whose locator was an intent replies with `groundedTo` — the
+element line the intent resolved to. Check the target there rather than
+pre-probing with `ground_element`. A step that CHANGED the address also
+replies with `url`: the last one in the batch is where you ended up, so
+`get_active_context` / `get_url` afterwards re-reads what you have.
+
+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}`. When the brief names no check, verify with the
+text it DID give you — the last thing you were told to click is on the
+page you land on, so assert that name inside the same batch, quoting
+the text alone (`"<name>"`, not `heading "<name>"` — the words often
+live in a row or a link, and a role word then grounds to nothing);
+don't spend calls hunting for something assertable.
+`assert_url` is for briefs that name the destination URL. On a checkbox
+/ radio / switch `assert_value`
+takes `"true"` / `"false"` and asserts the checked state — no CSS
+`:checked` selector. They execute live, so a recorded assert has
+already passed against the real page; never hand-edit assertions into
+the generated file. The final batch of a scenario can pass `autoRun:
+true`: when every step succeeds, a verification step is recorded and
+the draft has no blocking warnings (FRAGILE_LOCATOR passes and is
+reported in the reply; DYNAMIC_TEXT / NO_DSL_PRIMITIVE block), the same
+call saves the scenario, resets the context and runs it
+(`autoRun.run.next.outcome === "completed"` is the pass signal);
+otherwise `autoRun.status: "skipped"` + reason and the manual
+generate → save → run flow applies.
+
 ## Recording: name the `section` like a test-plan line
 
 Each `explore_step`/`explore_record` carries a `section` that becomes a
@@ -99,24 +158,36 @@ completion signal).
 ## When a scenario fails
 
 The MCP server keeps a paused-failure runtime alive (default
-`pauseOnFailure: true`) — the browser context is still open. Use that:
+`pauseOnFailure: true`) and `run_test` auto-attaches you to that live
+page — your `get_page_snapshot` / `find_element` / `check_locator`
+already target the page being debugged (no manual
+`attach_debug_session`). Use that:
 
 1. **`inspect_runtime {runtimeId}`** — shows `lastFailure` (error +
    line/col + AST node) and `vars` (every assignment up to the pause).
    This tells you what was observed vs expected, and what intermediate
    state the scenario built up.
-2. **`get_page_snapshot`** — compact outline of the active page in
+2. **`check_locator {locator}`** — paste the EXACT locator from the
+   failing line (e.g. `getByRole('row').filter({hasText: 'Uma Quinn'}).first()`).
+   It parses that string with the same DSL parser the runner uses and
+   evaluates it against the live paused page: `count` of matches, and —
+   when the chain ends in `.first()`/`.last()`/`.nth()` — `pinned.ofCount`,
+   how many elements that index op silently collapsed (a `.first()`
+   hiding 16 identical rows is the classic break), plus per-match
+   role/name/text/testId so you see WHERE it points. Verify the selector
+   at runtime instead of guessing or re-running the whole test.
+3. **`get_page_snapshot`** — compact outline of the active page in
    its failed state: regions grouped by kind (navigation / form /
    main / dialog / cmp / overlay / …), interactive actions per
    region, off-screen actions partitioned by side (top / bottom /
    left / right). Look for whether the locator is reachable, or
    whether the page navigated somewhere unexpected. The `_meta`
    section carries viewport + totals.
-3. **`list_failures` + `get_failure_*`** — read from the failure bundle
+4. **`list_failures` + `get_failure_*`** — read from the failure bundle
    (failure.json, console.json, snapshot.json, screenshot.png).
    `get_failure_console` is often the giveaway when the failure is
    actually a runtime error in the app.
-4. **`agent_fix {runId}`** — composes a structured prompt with the
+5. **`agent_fix {runId}`** — composes a structured prompt with the
    failure, the relevant scenario excerpt, and a classifier
    suggestion (`edit-locator` / `edit-assertion` / `edit-wait` /
    `edit-flow` / `investigate-app`). Use it as a starting hypothesis.