This documentation is available as Markdown. For the complete index, see llms.txt. Skip to content
unotest

Troubleshooting

For the complete documentation index, see llms.txt
View Markdown Open in ChatGPT Open in Claude

Diagnostics

In normal operation the CLI prints a single actionable line — no stack traces. For full diagnostics (JSONL log + per-call artifacts), set:

Terminal window
UNOTEST_DEBUG=1 npx @unotest/web e2e <name>

The JSONL lands in unotest/.debug/<pid>-<start-time>/log.jsonl (rotated as log-001.jsonl, …, with index.jsonl and one folder per tool call beside it); stdout stays as it was. The log is layered (tool, step, resolver, driver, refs, snapshot, network); the step layer carries enter / exit events per scenario statement (file, line, column, the enclosing step("…") label), so every driver action below it says which statement it happened under.

Common issues

  • astro: not found / command missing — install dependencies first (npm install).
  • No MCP tools in the editor — re-run init, then reload the editor so it re-reads .mcp.json.
  • Selector keeps drifting — switch to a stable selector (getByTestId / getByRole).
  • A JS global in a scenario — the DSL has no JSON, Date or string methods, and lint names the replacement: JSON.stringify(x) → validator:unknown-function … use json(value); Date.now() → use nowMs(); s.indexOf("x") → use textContains(haystack, needle) — the DSL has no string methods. !ok is refused earlier, by the parser (parse error — Invalid token: unexpected EXCL): write the check as an assertion (assertHidden, assertCount) instead.
  • run_test answers spawn_failed — the runner child died before it wrote its first runtime.json; the reason carries its exit code and the last lines of spawn.stderr.log in the run’s directory. A runner that is alive is waited for (up to 60 s; a run waiting in the queue is reported as queued instead), so this is a real start failure — read the stderr tail.
  • Flaky tab/iframe timing — waitForPage() isn’t shipped; use pause(ms) with a // reason: comment.
  • iOS: “command not found” on xcrun — you’re not on macOS or missing Xcode CLI tools. iOS is macOS-only.

Known limitations

  • Network HAR & video aren’t captured yet (failure bundle tier 3). Use screenshot + console + semantic DOM + trace.
  • dragAndDrop / clipboard paste use synthetic events, not native HTML5 DragEvent / ClipboardEvent. For apps that require native events, dispatch via evaluate().
  • The viewer currently drives web only. Its runner architecture is multi-runner-ready, but mobile isn’t wired into it yet.

For agent-facing rules, see the Authoring guide.