QA with Matcha

Use Matcha QA when your workspace has the Matcha surface enabled and you need browser-style verification around a change.

Availability depends on the build, team setup, credentials, and target app. If you do not see Matcha in your workspace, treat this page as the shape of the QA workflow, not a promise that the feature is enabled for your team.

Decide what needs QA

Start with the behavior, not the tool.

A good QA request says:

• Which URL or deployment should be tested.
• Which user path matters.
• Which account or test user should be used, if any.
• What would count as pass, warning, or failure.
• Which browser state or setup matters before the run.

Avoid “test the app.” That produces broad exploration and weak review notes.

Check setup first

Before starting a run, confirm the basics:

• The target URL is reachable.
• The app build has the Matcha surface enabled.
• The team has the needed credentials and provider access.
• Test users are configured if the flow needs authentication.
• GitHub deployment-based runs are configured if you expect deployment triggers.

If any of those are missing, fix setup before treating a failed QA run as a product bug.

Start the run

For a manual URL run, choose the target URL and describe the behavior to verify.

For a saved test, pick the existing test or group and confirm the target. For a deployment-backed run, confirm the GitHub deployment and target URL are the ones you meant to test.

Keep the run label concrete. A label like checkout coupon validation is easier to read later than QA pass.

Read the result like evidence

A Matcha run can include a status, verdict, summary, steps, observations, target URL, and run metadata. 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 anonymous state?
• Did the steps match the behavior you asked about?
• Did the failure come from the product, setup, auth, or environment?
• Is there a video, live preview, or step detail worth inspecting?

If the run failed because the setup was wrong, log that plainly and rerun after setup is fixed.

Bring findings back to the task

When QA finds a real issue, attach the important details to the task or next agent prompt:

• Target URL.
• Run label or run id.
• The failing step.
• The observed behavior.
• The expected behavior.
• Any screenshot, video, or summary the reviewer should open.

Then ask for the smallest fix and rerun the relevant check. Do not ask the next agent to infer the bug from “Matcha failed.”

When to skip Matcha

Skip Matcha when the change is not browser-visible, the target environment is not available, or the behavior can be verified faster with a unit test or local command.

QA is useful when it tests the thing users do. It is noise when it only proves that setup is unfinished.

Next: review agent work or monitoring loop when the change is already deployed and your team has that workflow configured.