Web QA

Web QA drives your web app in a browser and returns a verdict. You point Matcha, Coldtea's testing agent, at a URL, describe the path to walk, and read the result as evidence. Web QA is available today.

Decide what needs QA

Start with the behavior, not the tool. A good QA request says:

• Which URL or deployment to test.
• Which user path matters.
• Which test user to sign in as, if any.
• What would count as pass, warning, or fail.

Avoid "test the app." That produces broad exploration and weak review notes. Name the flow you care about, for example "add a coupon at checkout and confirm the discount applies."

Pick a target

A web run tests one of two kinds of target.

• A static URL: any reachable web address, including a static build you have hosted or a preview URL. You give Matcha the URL directly.
• A deployment URL: a target tied to a bound GitHub repo, where the URL comes from a deployment. A saved test with this target still needs the concrete URL at run time.

If the deployment sits behind a login wall or a preview gate, set up site protection first so Matcha can reach the app.

Start a run

You describe a run with a target URL and a description of the flow.

• targetUrl is the address to open.
• testDescription is the user path to walk, in plain English.
• label is a short name so the run is easy to find later. Keep it concrete: checkout coupon validation reads better than QA pass.
• A run signs in as a test user when you give it a run-as identity, or runs signed out when you do not. Running under a group inherits that group's identity.

You can start a run from the Matcha QA screen in the desktop, or ask an agent to start one with the qa_run_start tool. When retrying a start through the tool, reuse the same idempotency key so a failed call cannot start a second paid run. See MCP and local API for the qa_* tools.

Once Coldtea reports the run as started or queued, the backend owns execution, evidence collection, the final status, and any PR reporting. You can close the desktop from that point.

Read the result like evidence

A finished run carries a status, a verdict, a summary, ordered steps, and evidence. Read those as evidence, not as a final ruling. Check:

• Did the run hit the right URL?
• Did it use the intended test user or the signed-out state?
• Did the steps match the behavior you asked about?
• Did a failure come from the product, or from setup, auth, or the environment?

Runs and results covers statuses, verdicts, steps, and evidence in full.

Bring findings back to the task

When QA finds a real issue, attach the details to the task or the next agent prompt: the target URL, the run label or id, the failing step, the observed behavior, and the expected behavior. Then ask for the smallest fix and run the check again. Do not ask the next agent to infer the bug from "Matcha failed."

When to skip web QA

Skip web QA when the change is not browser-visible, the target is not reachable, or a unit test or local command verifies the behavior faster.