@unotest/web 0.9.1 → 0.11.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
@@ -176,6 +235,11 @@ result = evaluate(
 );
 ```
 
+Index access reads data off a **bare variable** only — `obj.prop[i]`
+does not parse; assign the member first:
+`m = state.matches; last = m[m.length - 1];`. `arr[i] = v` stays
+rejected.
+
 ## Sandbox primitives
 
 For test setup / teardown that touches the host machine, the registry
@@ -187,9 +251,13 @@ exposes four primitives — **but the consumer project's
 - **`dbQuery(sql, …params)`** / **`dbExec(sql, …params)`** —
   parameterized SQL against `sandbox.database` (postgres / mysql /
   sqlite, picked by URL scheme).
-- **`apiCall(method, path, body?, headers?)`** — HTTP fetch against
-  `sandbox.apiBaseUrl`. **Path-only** — absolute URLs throw to prevent
-  scenarios from hitting arbitrary hosts.
+- **`apiCall(method, path, body?, headers?, opts?)`** — HTTP fetch
+  against `sandbox.apiBaseUrl`. **Path-only** — absolute URLs throw to
+  prevent scenarios from hitting arbitrary hosts. 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.
 
 If a primitive throws with "sandbox.X is not configured", tell the
 user to add it to `unotest.config.*`. Do not infer secrets from the