Skip to main content

Passed after recovery

A mission is recovered when it reaches its success criteria only after the agent takes an action that an ordinary user would not know to take, such as reloading, resending, or dismissing an unexpected dialog. Recovered is amber in local reports and Mission Control.

The agent records these events with record_recovery. Each record includes the turn, action, reason, optional evidence text, and an optional screenshot. A final failure remains failed even when recoveries were recorded.

Permit recovery actions​

Declare stable action names in the runMissions options:

export async function executeMission() {
  return runMissions({
    mission: sendMessageMission,
    recovery: {
      permitted: ['reload'],
    },
  }, 'send message');
}
  • Omitting recovery uses the project policy when configured; without a project policy, recorded recovery actions are permitted and eventual success is reported as recovered.
  • permitted: ['reload'] permits only reload.
  • permitted: [] forbids every recovery action. A recorded recovery then fails the mission even if the success criteria are eventually reached.

For a project-wide default, put the same policy in testronaut-config.json:

{
  "recovery": {
    "permitted": ["reload", "dismiss_dialog"],
    "failBuild": false
  }
}

A policy supplied to runMissions takes precedence over the project default.

Use short stable names such as reload, resend, or dismiss_dialog. Mission instructions can explain when an action is permitted, but the structured recovery block controls the verdict.

Build behavior​

Recovered missions count as successful for the CLI exit code by default. Use strict mode when CI requires clean passes only:

testronaut --strict-recovery

Or configure it for every run:

{
  "recovery": {
    "failBuild": true
  }
}

Strict mode changes the process exit code, not the recorded status: the report still says recovered.

Report schema​

Recovery support is report schema version 3. A mission can contain:

{
  "status": "recovered",
  "recoveries": [
    {
      "turn": 4,
      "action": "reload",
      "reason": "The submitted message was still missing after two checks",
      "evidence": "The message appeared immediately after reload",
      "screenshot": "./screenshots/run_123/recovery.png"
    }
  ]
}

Run summaries contain mutually exclusive passed, recovered, and failed counts. Consumers that validate mission status values must add recovered when reading schema version 3.