# Troubleshooting

> For the complete documentation index, see [llms.txt](/llms.txt)

## Diagnostics

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

```sh
UNOTEST_DEBUG=1 npx @unotest/web e2e <name>
```

## 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](/concepts/selectors/)
  (`getByTestId` / `getByRole`).
- **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](/agent/authoring/).