Skip to Content
webagent docs
QA testing

Agent setup

A snippet to paste into AGENTS.md or CLAUDE.md so your agent runs webagent smoke tests the right way and reports clearly.

Open as .md

Your agent can see webagent's tools after you connect it, but it does not know how you want to test. A short instruction file fixes that. It tells the agent which tool to pick, how to wait for a result, what to do with a localhost app, and what a good report contains.

Where to put it

AgentFile
Codex CLIAGENTS.md in your project root. Codex also reads ~/.codex/AGENTS.md for every project.
Claude CodeCLAUDE.md in your project root. Claude Code also reads ~/.claude/CLAUDE.md for every project.

Use the same text for both. The snippet calls the server lookover-webagent, the name used in the connect pages. If you chose another name, change it.

The snippet

## Smoke testing with webagent

Use the `lookover-webagent` MCP tools to test web apps in a cloud browser.
Do not use a local browser for this.

### Pick the tool
- To test a page or a flow (load, log in, sign up, check out, submit a form):
  `smoke_test`. Give it `url`, the plain-language `steps`, and what must be true
  afterwards: `expectText` (text that must be on the page), `expectUrl` (text the
  address must contain) and `expectNoText` (text that must not be on the page).
  One call opens a recorded browser, runs the test and returns a report.
- To explore, or to do something open-ended: `run_task` with a goal in plain
  language. It checks nothing: `ok` only means the agent says it is done.
- Only to read a page: `scrape` or `screenshot`.
- Always give `smoke_test` an `expectText`, `expectUrl` or `expectNoText`. Without
  one it only checks that the page loads, the links work and the console is clean.

### Waiting
- `smoke_test` waits up to 60 seconds. If the verdict is `running`, call `get_report`
  with the `id` from the result until the verdict is `pass`, `fail` or `error`.
- A `run_task` that is not done in about 90 seconds answers with `status: running`,
  a `sessionId` and a `taskId`. That is normal. Call `get_report` with the `taskId`
  until it has finished. Then call `stop_session` for a session you left open.
- To keep one browser over several `run_task` calls, give the first one `startUrl`
  and `keepOpen: true`, and pass the same `sessionId` to the next ones (without
  `startUrl`). Call `stop_session` at the end.

### Apps on localhost
The cloud browser cannot open `localhost` or private addresses. If the app is on
localhost, start a tunnel in the shell first:
`cloudflared tunnel --url http://localhost:<port>`.
Read the `https://...trycloudflare.com` address it prints and use that as `url`.
Stop the tunnel when the test ends. Tell me that the app is open to the internet
while the tunnel runs.

### Test data and secrets
- Log in only with the test account I give you. Never use a real person's account.
- Never put API keys, tokens or real passwords in a goal, a step or the report.
  Goals and steps are stored with the run.
- Only test sites I own or may test. If a page shows a CAPTCHA, stop and report it.
  Do not try to get past it.

### Read the result
- Read `verdict` in the report, not only `isError`. `fail` means the test ran and
  found a problem. `error` means the test could not run. A failed test is a normal
  result, not a tool error.
- For a `run_task` report, `pass` only means the agent says it is done. Say so.
- Console errors and failed network calls come from a log that is saved when the
  session ends. If the report says the log is not available, call `get_report` again
  after a few seconds before you say there were no errors.

### Report
Finish with a report that has:
1. Verdict: PASS, FAIL or COULD NOT TEST (the report's `pass`, `fail` or `error`).
   - FAIL: the app did something wrong, and you can say what and where.
   - COULD NOT TEST: the test did not run to a result (CAPTCHA, blocked address,
     cancelled run, an error from the tool). Do not call this a bug in the app.
2. The URL tested (`url`), and where the browser ended (`finalUrl`).
3. The `summary` of the report, then one line per failed step: its `title`, its
   `error` and its screenshot link.
4. Console errors and failed network calls: the first few, with their `text`,
   `method`, `url` and `status`. Give the totals from `counts`.
5. Findings (broken links, accessibility), worst first, with the `fix` line.
6. Evidence: the session id, the report link and the recording path. The links
   expire in minutes (`evidence.urlsExpireAt`), so say when the report was made.
   Do not claim to have seen anything the tool results do not show.

What each rule is for

  • smoke_test first. One call gives a verdict from real checks and a report with the proof. A goal task checks nothing, so the snippet keeps it for exploring.
  • Expectations. A smoke test that has no expectText, expectUrl or expectNoText only checks that the page loads and is clean. The text you expect is what makes a flow pass or fail.
  • Polling. The MCP server answers in one reply and waits at most 90 seconds. A longer test keeps running, and get_report reads the result when it is ready. See Tasks.
  • One sessionId per task flow. A browser that is closed loses its page, its cookies and its login. run_task closes a session it opened unless you pass keepOpen, so a multi-step task flow needs keepOpen on the first call and the same sessionId after it.
  • Tunnel. A cloud browser cannot reach your machine. A tunnel gives the app a public address for as long as it runs. Anyone with the address can open your dev server while it is up, so use test data and close it after.
  • Verdicts. fail means the app is wrong. error means the test could not run. The snippet asks the agent to say which. Reading results explains the report and lists every stop reason of a task.
  • Secrets. The text of a goal or a step is stored with the task or skill run and can show up in reports. The agent has to type the test password into a goal, so use a throwaway test account whose password you can change afterwards.

Tips

  • Keep the file short. If the agent skips a rule, move that rule to the top.
  • Re-read the first report with care. If the agent calls a test a PASS without evidence, tighten the "Report" rules.

On this page