<!-- zibby-template-version: 4 -->
# /zibby-test-run — execute a Zibby test spec

You are helping the user run an existing test spec through Zibby. A spec is a `.txt` file describing what to test in plain language; Zibby's runner turns it into a Playwright execution and produces a video + JSON results.

Canonical docs: **https://docs.zibby.app/tests/running**

## Steps

1. **Identify the spec.** Most projects keep specs under `test-specs/` (configurable in `.zibby.config.mjs` `paths.specs`). If user named one, use it. Otherwise list what's there and ask:
   ```
   ls test-specs/
   ```

2. **Run it.** From the project root:
   ```
   Bash(zibby test test-specs/<name>.txt)
   ```
   For a quick inline test without writing a spec file:
   ```
   Bash(zibby test "go to example.com and check that the title contains Example")
   ```

3. **Output to expect.** Zibby streams the run live — agent thinking, browser actions, assertion results, final pass/fail. Generated `.spec.js` lands in `tests/<name>.spec.js` (configurable via `paths.generated`). Video + traces under `test-results/`.

4. **If running headless / CI:**
   ```
   Bash(zibby test test-specs/<name>.txt --headless)
   ```

5. **If running a specific node only** (advanced — re-execute one phase of a prior session):
   ```
   Bash(zibby test --node execute_live --session last)
   ```

## Useful flags

- `--agent claude|cursor|codex|gemini` — override the configured agent for this run
- `--workflow QuickSmokeWorkflow` — use a non-default workflow for the run
- `--verbose` / `--debug` — escalate log levels
- `-m, --mem` — enable test memory (Dolt-backed knowledge from prior runs)
- `--sync` / `--no-sync` — force / skip cloud upload regardless of config
- `--sources <ids> --execution <id>` — run cloud-stored test cases from a specific execution (comma-separated IDs)

## Common failure modes

- **"No spec found"** — path is relative to project root, not cwd. Check `paths.specs` in `.zibby.config.mjs`.
- **"Browser crashed"** — usually the playwright browser cache is stale. Drop `--headless` once (default is headed) so you can see what's happening, then re-add `--headless` once it's healthy.
- **MCP errors during `execute_live`** — the agent's MCP tool config may need refreshing. See `/zibby-test-debug`.