/gaia-test-automate
user-facingWhat it does
/gaia-test-automate expands automated test coverage for a story. In its default mode, it plans which tests to write based on acceptance criteria coverage gaps, then implements the tests using the appropriate stack developer agent. It also supports three sub-commands: --status (show coverage map), --add-scenario (add a custom test scenario), and --scaffold (generate placeholder test skeletons).
When to use it
- A story's QA review surfaced uncovered acceptance criteria and you want to fill the gaps.
- You want to check the current test coverage status for a story (
--status). - You need to add a custom edge-case test scenario not covered by the standard AC-to-test mapping (
--add-scenario). - You want placeholder test skeletons generated so a developer can fill in the assertions later (
--scaffold).
Prerequisites
- A story file must exist under
.gaia/artifacts/implementation-artifacts/. - For default mode, the story should be in
reviewstatus with implementation complete.
How to invoke
/gaia-test-automate E3-S7
/gaia-test-automate E3-S7 --status
/gaia-test-automate E3-S7 --add-scenario
/gaia-test-automate E3-S7 --scaffoldThe story key is always required. The sub-command flags select which operation to perform.
What it does step by step
Default mode (fill gaps)
- Analyze coverage Maps each acceptance criterion to existing test files and identifies gaps.
- Plan tests Proposes which tests to write for uncovered ACs, including test type (unit, integration, e2e).
- Implement tests Delegates test writing to the appropriate stack developer agent.
- Verify Runs the new tests to confirm they pass. Updates the Review Gate Test Automation row.
--status sub-command
Displays a coverage map showing each AC, its mapped test case, test type, and file path. Summarizes as "N/M generated (X%)".
--add-scenario sub-command
Allocates the next custom scenario ID (CS-NNN), writes the scenario to the story's custom scenarios table and the project index.
--scaffold sub-command
Generates placeholder test skeletons for uncovered ACs. Does not update the Review Gate to PASSED -- scaffolds are incomplete by definition.
Inputs
| Input | Source | Description | Example |
|---|---|---|---|
story-key | Positional argument (required) | The story to automate tests for. | /gaia-test-automate E3-S7 |
--status | Argument (optional) | Display current coverage map without modifying files. | /gaia-test-automate E3-S7 --status |
--add-scenario | Argument (optional) | Add a custom scenario to the story's test index. | /gaia-test-automate E3-S7 --add-scenario |
--scaffold | Argument (optional) | Generate placeholder test skeletons only. | /gaia-test-automate E3-S7 --scaffold |
Outputs
| Output | Location | Description |
|---|---|---|
| Test files | Project test directories | New or expanded test files covering the gaps. |
| Review Gate update | Story file | Test Automation row set to PASSED (default mode only). |
Example session
> /gaia-test-automate E3-S7 --status
Coverage map for E3-S7:
AC1 TC-001 unit tests/unit/login.test.ts
AC2 TC-002 integration tests/int/auth.spec.ts
AC3 -- -- (not yet automated)
Summary: 2/3 generated (67%) | 1 pending automation
> /gaia-test-automate E3-S7
Planning tests for 1 uncovered AC...
AC3: password-reset edge case -> unit test
Implementing tests...
Written: tests/unit/password-reset.test.ts
Running tests... 1 passed.
Review Gate updated: Test Automation -> PASSEDWhat to run next
/gaia-review-all-- run remaining reviews to complete the Review Gate./gaia-test-gap-analysis-- verify overall coverage after automation.
Troubleshooting
"Story must be in review status"
Default mode requires the story to be implemented first. Use --scaffold to generate skeletons before implementation.
Tests fail after generation
The generated tests may need manual adjustment. Fix the assertions and re-run.