Codex subagents QA workflows are useful when a test automation change has several risks that should be reviewed from different angles. Instead of asking one AI assistant to inspect everything at once, you can ask Codex to spawn focused subagents: one for changed code context, one for failing-test evidence, and one for assertion and regression risk. The QA engineer still owns the final decision, but the parallel review can make the first pass faster and more structured.

This tutorial shows a practical workflow for QA engineers, SDETs, and automation testers who review Playwright, Selenium, API, or CI test changes. The goal is not to let AI approve code. The goal is to collect better review notes before you run the final checks yourself.

Why Use Codex Subagents for QA?

Official Codex documentation describes subagents as specialized agents that can run in parallel and then return one consolidated response. The docs also state that Codex only creates subagents when you explicitly ask it to. That matters for QA work because parallel review should be intentional. You want a clear split of responsibilities, not three agents doing the same vague review.

A good QA review usually has multiple tracks:

  • Does the changed code match the product behavior?
  • Do the failing logs, screenshots, traces, or CI output support the proposed fix?
  • Are the assertions strong enough to catch the real regression?
  • Can the test pass for the wrong reason?
  • What still needs a deterministic rerun before merge?

These tracks are related, but they are not identical. Splitting them helps reduce shallow review comments like “looks good” or “add more tests” and produces a clearer checklist for the human reviewer.

Before You Start: Prepare the Review Inputs

Codex works best when the task has a goal, context, constraints, and done criteria. For a test risk review, prepare a small review packet before asking for subagents:

  • The branch or diff to review.
  • The failing test name, if this is a bug fix.
  • Relevant CI logs, Playwright traces, screenshots, API responses, or console output.
  • Repository QA rules from AGENTS.md, if your project has them.
  • The exact validation command you expect to run at the end.

If your team uses AGENTS.md, keep practical QA rules there: locator policy, assertion standards, test data rules, retry policy, and the commands required before a pull request can be accepted. Codex reads those instructions before doing work, so a shared file keeps repeated reviews more consistent.

Codex Subagents QA Workflow

Use this workflow when a pull request changes test automation, page objects, API clients, test data setup, or a bug fix that may affect regression coverage.

Step 1: Ask for Three Focused Review Lanes

Start with a direct prompt. Tell Codex to spawn one subagent per review lane, wait for all results, and summarize only actionable findings.

Try This Prompt

Review this branch as a QA test risk review.
Spawn three subagents and wait for all results.

Agent 1: Code context
- Identify changed production and test files.
- Explain which user behavior or API behavior is affected.
- Note any hidden dependency on test data, timing, environment, or permissions.

Agent 2: Test evidence
- Inspect the supplied failing logs, screenshots, traces, or CI output.
- Decide whether the proposed test change matches the observed failure.
- Flag missing evidence that a QA engineer should collect before merge.

Agent 3: Assertion and regression risk
- Review selectors, waits, mocks, fixtures, and assertions.
- Flag weak checks that could pass while the bug remains.
- Suggest one minimal validation command or scenario per risk.

Return a consolidated table with: risk, evidence, recommendation, validation command, and owner.

Step 2: Read the Consolidated Result Like a Reviewer

Do not accept the combined response as a final verdict. Treat it as a structured review draft. Look for agreement across agents. If the code-context agent says a checkout flag changed, but the evidence agent only inspected login screenshots, you have a gap. If the assertion-risk agent recommends a stronger business assertion, check whether that assertion is stable and meaningful.

Step 3: Convert Findings into a QA Decision Table

Ask Codex to keep the output small enough for a pull request comment. A useful review table has five columns:

  • Risk: the behavior that could regress.
  • Evidence: the log, screenshot, trace, or file that supports the concern.
  • Recommendation: the smallest review action.
  • Validation: the exact test, command, or manual check to run.
  • Owner: QA, developer, or product owner.

This prevents the review from turning into a long AI transcript. The team needs decisions, not raw conversation.

Step 4: Run Deterministic Validation

After the subagents finish, run the targeted checks yourself. For a Playwright example, that might be:

npx playwright test tests/checkout.spec.ts --project=chromium --trace=on

For API tests, it might be a focused collection run, a pytest marker, or a contract test. The important point is that a subagent review can suggest where to look, but it does not replace the evidence generated by the actual test run.

Example Review Scenario

Imagine a pull request that changes a checkout page object and updates a failing payment test. The old test checked that the page showed a success banner. The new test checks only that the URL contains /thank-you. That could be weaker if the application can navigate to the thank-you page while still failing to create an order.

In this case, the code-context subagent may identify changes to the payment submit flow. The test-evidence subagent may note that the CI screenshot shows the success banner missing. The assertion-risk subagent may recommend checking the order confirmation number or a visible success message instead of relying only on URL navigation.

The QA engineer should then run a focused checkout test and confirm the business outcome. A good final comment could be: “Risk: URL-only assertion may pass without order creation. Evidence: CI screenshot shows missing confirmation banner. Recommendation: assert confirmation number or success state. Validation: rerun focused checkout test with trace.”

Use AGENTS.md to Keep Subagent Reviews Consistent

If every review prompt repeats your QA standards, they will drift. Put the stable rules in AGENTS.md. Keep it short and operational:

## QA review rules
- Prefer user-visible assertions over implementation-only checks.
- Do not accept URL-only assertions for critical checkout, payment, or account flows.
- Check test data setup before changing waits or retries.
- For flaky tests, inspect evidence before proposing a locator change.
- Done means the focused test command is documented and rerun evidence is captured.

Then your prompt can focus on the current PR instead of restating team policy. Codex documentation also describes /review in the CLI as a dedicated review workflow that reads selected diffs and reports prioritized actionable findings without touching the working tree. For many teams, a good pattern is to run a normal /review pass first, then use subagents only when the risk is broad enough to justify parallel analysis.

Screenshot Checklist

  • The Codex prompt asking for three subagents.
  • The subagent activity or summarized lane results.
  • The consolidated QA risk table.
  • The failing test log, trace, screenshot, or API response used as evidence.
  • The final targeted test command and passing result.

Common Mistakes

  • Asking for generic review: use named lanes and explicit output columns.
  • Skipping evidence: subagents need logs, diffs, traces, or screenshots to avoid guessing.
  • Accepting every suggestion: remove noisy or speculative findings before posting a PR comment.
  • Replacing test execution: AI review is not a substitute for running the right checks.
  • Overusing subagents: simple diffs often need one focused review, not parallel agents.

Best Practices for QA Teams

Use Codex subagents when a change crosses multiple concerns: UI behavior, test data, CI stability, accessibility, API contracts, or security-sensitive workflows. Keep each agent narrowly scoped. Ask for evidence-backed findings. Require a validation command for every significant risk. Store stable team rules in AGENTS.md. Keep the final review comment short enough that a developer can act on it immediately.

Most importantly, decide what “done” means before the review starts. For a QA engineer, done usually means the risky behavior is covered by a meaningful assertion, the focused test has been rerun, and the remaining risk is documented.

FAQ

Should QA engineers use Codex subagents for every pull request?

No. Use them for complex or risky changes. A small locator update or a simple documentation change usually does not need parallel AI review.

Can Codex subagents replace manual QA judgment?

No. They can help collect findings and organize risk, but the QA engineer still needs to inspect evidence, run tests, and decide whether coverage is acceptable.

What is the best number of subagents for a test review?

Three is often enough: code context, test evidence, and assertion risk. More agents can add cost and noise unless the change is very large.

How does AGENTS.md help this workflow?

It stores reusable project guidance such as test commands, locator rules, assertion standards, and done criteria so each Codex review starts with the same expectations.

References

Conclusion

Codex subagents QA reviews work best when they are narrow, evidence-based, and followed by deterministic validation. Use parallel agents to inspect different risk lanes, consolidate the result into a small table, and then run the actual tests before approving the change. That gives QA teams the speed of AI-assisted review without giving up the discipline of test evidence.