/gaia-test-run

user-facing
Category:
Testing
Lifecycle phase:
Anytime
Arguments:
[--tier 1|2|3] [--tag NAME] [--story KEY] [--file PATH] [--json] [--no-execute]

What it does

/gaia-test-run runs your project's automated test suite against the environment configured for the requested tier. It resolves the tier-to-environment mapping from .gaia/config/project-config.yaml, picks the right test runner (Vitest, pytest, bats, Go test), applies targeting filters, executes the tests, and emits a structured verdict with pass/fail counts and infrastructure-flake detection.

When to use it

  • You want to run tests manually against a specific tier without remembering tier-to-environment mappings or runner commands.
  • You want to run tests filtered by tag, story key, or specific file.
  • You need a structured verdict (JSON or plain text) for CI integration.

Prerequisites

  • test_execution must be configured in .gaia/config/project-config.yaml with at least one tier's placement setting.
  • A test runner must be detectable (Vitest, pytest, bats, or Go test).

How to invoke

/gaia-test-run
/gaia-test-run --tier 1
/gaia-test-run --tag auth
/gaia-test-run --story E3-S7
/gaia-test-run --file tests/unit/login.test.ts
/gaia-test-run --json
/gaia-test-run --no-execute
/gaia-test-run --tier 2 --tag auth

What it does step by step

  1. Resolve placement Reads test_execution.tier_N.placement from config (default tier 1). Only local placement executes locally; other placements emit a dry-run command.
  2. Resolve runner Detects the test runner from config or project files (vitest.config, pyproject.toml, *.bats, go.mod).
  3. Apply filters Forwards --tag, --story, or --file to the runner as targeting criteria.
  4. Execute Runs the test suite and captures stdout/stderr.
  5. Flake detection Scans failure output for infrastructure-flake patterns (timeout, ECONNREFUSED, OOM, network errors).
  6. Emit verdict Produces a structured verdict with status, tier, environment, duration, test counts, and flake-suspected flag.

Inputs

InputSourceDescriptionExample
--tierArgument (optional, default: 1)Which tier to run (1 = unit, 2 = integration, 3 = e2e)./gaia-test-run --tier 1
--tagArgument (optional)Filter tests by tag name./gaia-test-run --tag auth
--storyArgument (optional)Run tests associated with a specific story key./gaia-test-run --story E3-S7
--fileArgument (optional)Run a specific test file./gaia-test-run --file tests/unit/login.test.ts
--jsonArgument (optional)Output verdict as JSON instead of plain text./gaia-test-run --json
--no-executeArgument (optional)Dry-run: resolve placement and runner without executing tests./gaia-test-run --no-execute

Outputs

OutputLocationDescription
VerdictConversation outputStructured verdict with status, test counts, duration, and flake detection. No files modified.

Example session

> /gaia-test-run --tier 1 --tag auth

Tier: 1 (local)
Runner: vitest
Filter: tag=auth

Running 8 tests...
  8 passed, 0 failed, 0 skipped (1.2s)

Verdict: PASSED
  tier: 1
  environment: local
  test_count: 8
  pass_count: 8
  fail_count: 0
  flake_suspected: false

What to run next

  • If tests pass, proceed with /gaia-review-all to complete the review cycle.
  • If tests fail, fix the code and re-run.

Troubleshooting

"test_execution section not configured"

Add the test_execution section to .gaia/config/project-config.yaml via /gaia-config-test.

No runner detected

The command could not find a test runner. Ensure a test framework config file exists (vitest.config.*, pyproject.toml, *.bats, or go.mod).

Flake suspected

The failure output matches infrastructure-flake patterns. The verdict includes flake_suspected: true with a flake_reason. Re-run to confirm.