| name | manual-ui-testing |
| description | Run manual UI test cases using agent-browser against a running stack. Use when the user asks to run UI tests, test the UI, run manual tests, or verify UI behavior. |
| metadata | {"internal":true} |
| user-invocable | true |
| allowed-tools | Bash(npx agent-browser:*), Bash(agent-browser:*), Bash(just:*), Bash(doppler:*) |
Manual UI Testing
Execute the test cases in test_cases/ui/ against a running stack with agent-browser, record
results, and file issues for failures. knowledge/evaluation/test-cases.md defines
the test case format.
Scope
Each subdirectory of test_cases/ui/ is a category — list the directory rather than assuming a
fixed set. Every case states its own preconditions (auth mode, existing data), test data, steps, and
expected result; read them before running. With no scope given, run everything in dependency order:
auth → org → features.
Stack
Full auth mode needs the real stack, not DEV_MODE. Start it with a unique per-worktree prefix and
wait for PostgreSQL, Valkey, NATS, API, worker, UI, and Caddy to come up. Follow the canonical
coding-agent startup contract in the root AGENTS.md, selecting the auth mode
required by the test case. Verify it through the documented /health endpoint before testing.
If a stack is already running, confirm its PORT_PREFIX and auth mode before using it.
Driving the browser
agent-browser runs headless Chromium via npx; the daemon persists between commands in a session.
agent-browser open http://localhost:<prefix>00/<path>
agent-browser wait --load networkidle
agent-browser snapshot -i
agent-browser fill @e1 "value"
agent-browser click @e2
agent-browser wait --load networkidle
agent-browser snapshot -i
agent-browser screenshot /tmp/test_<category>_<tc>.png
Hints that cost time to rediscover:
- Refs are invalidated by any navigation or DOM change — re-snapshot after every one.
- Always
wait --load networkidle after navigation, form submission, and before screenshots.
- Chain independent commands with
&&; do not chain when the next ref depends on reading a snapshot.
- Next.js dev compilation can add 2–5s to a first page load.
- Keyboard shortcuts (Ctrl+K) often do not reach headless Chromium — drive the equivalent click.
- Screenshot each significant step, not just the verdict.
- Element missing from a snapshot?
agent-browser scroll down first.
- Login redirect loop usually means
AUTH_MODE does not match the test category.
Recording
Write or update test_cases/ui/MANUAL_TEST_RESULTS_<YYYY-MM-DD>.md using
references/results-template.md. Partial or re-test runs append to
(or update) the existing file for that date.
If the user asks for issues to be filed, create them via Linear MCP (EVE team, OSS project) with
severity, repro steps, expected vs actual, and the test case ID (e.g. org_creation/TC003).
