Test Execution Bridge

The Test Execution Bridge is what turns GAIA's test-execution review gates from self-attested into evidence-backed. When the bridge is enabled, a review gate that claims tests passed must be backed by a small execution-evidence JSON file describing the actual run. The review gate inspects that file and refuses to record a passing verdict if the evidence shows a red or skipped suite.

This page explains how to enable the bridge and documents the exact execution-evidence shape the gate consumes — so the evidence you supply actually satisfies the gate. For the companion input manifest that tells the bridge how to run your tests, see the test-environment.yaml Reference; this page covers the evidence the run produces, not the manifest it consumes.

Overview

A test-execution review gate (for example QA Tests, Test Automation, or Test Review) can be recorded as PASSED, FAILED, or UNVERIFIED. With the bridge enabled, a PASSED verdict on one of these gates is only accepted when it is accompanied by an execution-evidence file whose contents confirm a clean run. The gate reads three fields from that file and refuses PASSED if any of them indicate a problem.

This closes a gate-integrity hole: without the content check, a gate could be marked PASSED against evidence that recorded a failing suite, and a story with a red test run could reach done with every review gate showing “PASSED”.

Bridge on vs. bridge off

The bridge is controlled by a single boolean in project configuration: test_execution_bridge.bridge_enabled.

StateBehaviour
bridge_enabled: false (default) Test-execution gates are recorded from a written report. No execution-evidence file is required. Suitable for projects that have not yet wired a real test runner.
bridge_enabled: true A PASSED verdict on a test-execution gate requires an execution-evidence file, and that file's contents are inspected. Evidence showing a non-zero exit code, any failed tests, or a skipped suite causes the gate to refuse PASSED.

Enabling real test execution

Turn the bridge on with the dedicated command: 

/gaia-bridge-enable

This sets test_execution_bridge.bridge_enabled = true in .gaia/config/project-config.yaml. The flag takes effect immediately. The command is idempotent — running it when the bridge is already enabled is a no-op. To turn the bridge back off, use /gaia-bridge-disable.

You also need a manifest

Enabling the bridge tells GAIA to require evidence. To tell GAIA how to run your tests — the runner commands, tiers, and tier-to-gate mapping — author a test-environment.yaml manifest. See the test-environment.yaml Reference.

The execution-evidence contract

When the bridge is enabled, a PASSED test-execution gate is recorded with a path to an execution-evidence JSON file. The review gate reads exactly three fields from that file:

FieldTypeMeaning
exit_code integer The process exit code of the test run. 0 means the run succeeded. Defaults to 0 when absent.
suites[].fail_count array of objects Per-suite failure counts. The gate sums fail_count across every entry in suites. A missing count is treated as 0.
skipped boolean Whether the suite was skipped (not actually exercised). A real run stamps false; true means “tier not run” and is not a passing signal. Defaults to false when absent.

A clean run that the gate will accept as PASSED looks like this: 

{
  "exit_code": 0,
  "skipped": false,
  "suites": [
    { "name": "unit",        "fail_count": 0 },
    { "name": "integration", "fail_count": 0 }
  ]
}

Any additional fields you include (timestamps, durations, a command string, per-suite pass counts) are ignored by the gate and safe to add for your own auditing — only the three fields above affect the verdict.

When the gate refuses PASSED

With the bridge enabled, the gate refuses to record PASSED — and tells you why — when the evidence shows any of:

ConditionGate response
exit_code is not 0 Refuses PASSED (red suite). Fix the failing tests and re-capture evidence, or record FAILED.
summed suites[].fail_count is greater than 0 Refuses PASSED (failing tests). Fix and re-capture, or record FAILED.
skipped is true Refuses PASSED (suite did not run). Run the suite and re-capture, or record UNVERIFIED.

A FAILED verdict is always allowed against red evidence — recording that a gate failed is correct and expected. The refusal applies only to a PASSED claim that the evidence contradicts.

Documented escape hatches

Two deliberate bypasses exist for situations where attaching real evidence is not possible. Recording a gate with an explicit missing-evidence reason satisfies the gate without an evidence file (the reason is preserved for audit), and a project can disable the content check entirely via the REVIEW_GATE_PROOF_OF_EXECUTION=off environment override. Both are escape hatches — the default, enabled behaviour is the evidence-backed path above.

Worked example

Suppose a suite ran but two integration tests failed. The execution-evidence file would record: 

{
  "exit_code": 1,
  "skipped": false,
  "suites": [
    { "name": "unit",        "fail_count": 0 },
    { "name": "integration", "fail_count": 2 }
  ]
}

Attempting to record this gate as PASSED is refused on two counts: exit_code is 1 and the summed fail_count is 2. The correct action is to fix the two failing integration tests, re-run, and re-capture evidence showing exit_code: 0 with all fail_count values at 0 — or to record the gate as FAILED until the fix lands.