CONFIG REFERENCE (testronaut-config.json)

Compatibility

Verified against Testronaut CLI v1.11.0. Run testronaut config to inspect the effective configuration used by your installed version.

{
  "provider": "openai",
  "model": "gpt-5.6",
  "initialized": true,
  "outputDir": "missions/mission_reports",
  "projectName": "name_of_your_repo",
  "maxTurns": 20,
  "tags": ["smoke"],
  "tagMatch": "any",
  "addTags": ["nightly"],
  "sessionToken": "*******************",
  "mfaName": "github-test-mfa"
}

provider: LLM provider (openai, gemini, or anthropic; claude is accepted as a CLI alias)

model: specific model to use for test runs

reporter: json, html

outputDir: artifact/report location. JSON, HTML, run-specific screenshots, upload discovery, and serve all use this directory. Relative paths resolve from the project root.

maxTurns: number of agent actions given per mission to accomplish a goal (minimum 5, maximum 200 - any values beyond these bounds are currently clipped automatically by the CLI to avoid overruns and to better ensure performance)

sessionToken: used for cli comands with authentication needed (i.e. testronaut upload)

mfaName: optional default MFA nickname for automated MFA code retrieval.

tags: default mission-selection tags. CLI --tags overrides this value. Ignored when mission filenames are explicitly supplied.

tagMatch: any (OR, the default) or all (AND). CLI --tag-match overrides this value.

addTags: tags added to every executed main mission. CLI --add-tags combines with this list.

recovery.permitted: project-wide list of permitted recovery action names, such as reload or dismiss_dialog. A recovery block passed directly to runMissions overrides this project default. An explicit empty list forbids recovery.

recovery.failBuild: when true, recovered missions produce a nonzero suite exit code. This is equivalent to --strict-recovery; it does not rewrite recovered report statuses as failures.

Mission discovery and ordering

Configure which mission files belong to an automatically discovered suite and the order in which they run:

{
  "missions": {
    "root": "missions",
    "include": ["**/*.mission.js", "**/*.mission.ts"],
    "exclude": ["**/*.draft.mission.js"],
    "order": [
      "login.mission.js",
      "*",
      "logout.mission.js"
    ]
  }
}

• root: directory used for mission discovery. Defaults to missions.
• include: glob patterns relative to root. Defaults to JavaScript and TypeScript mission files recursively when a missions block exists.
• exclude: glob patterns removed from the included files.
• order: ordered filenames or glob patterns. Matches within a pattern are alphabetical. * places otherwise unmatched missions while reserving files for patterns that follow it. Remaining unlisted files are appended alphabetically.

Without a missions block, legacy discovery reads JavaScript and TypeScript mission files directly inside missions/ and sorts them alphabetically. Without missions.order, configured discovery is also alphabetical.

The order setting applies when testronaut discovers the suite. Explicit mission filenames run in command-line order instead. See Order Mission Suites for examples and verification commands.

Jev guardrails

Guardrails are opt-in and use a user-supplied TESTRONAUT_JEV_API_KEY:

{
  "guardrails": {
    "enabled": true,
    "mode": "live",
    "completionProbability": 0.8
  }
}

mode accepts live, shadow, or off. The completion probability is clamped to 0–1 and defaults to 0.8. Guardrails fail open and never change the execution model. Run testronaut config --json to check credential readiness without exposing the key.

The older optimization.objective: "tokens" configuration remains compatible. Model routing is beta and separately opt-in.

Use testronaut config to inspect resolved values and their sources. Add --json for machine-readable output; sensitive token values are not included.

Automated MFA

Automated MFA uses sessionToken plus a stored MFA nickname to retrieve a current TOTP code from the Testronaut API.

Default nickname:

{
  "sessionToken": "eyJ...",
  "mfaName": "github-test-mfa"
}

Nested form:

{
  "sessionToken": "eyJ...",
  "mfa": {
    "nickname": "github-test-mfa"
  }
}

Stored MFA entries are available on every Mission Control plan. Current allowances are 1 on Free, 5 on Shuttle, and 25 pooled in a Blastoff workspace. See Plans & Feature Availability.

See Automated MFA Codes for CLI, config JSON, and mission text examples.

Hosted email inboxes

Hosted inboxes let the agent retrieve short verification codes and safely open invitation or magic-login links.

Default inbox nickname:

{
  "emailInboxName": "github staging"
}

The nested form is also accepted:

{
  "emailInbox": {
    "nickname": "github staging"
  }
}

For invitation and magic-login links, allowlist the expected destination hosts:

{
  "emailInboxName": "staging",
  "emailLinks": {
    "allowedHosts": ["accounts.example.test", "app.example.test"]
  }
}

Environment overrides:

• TESTRONAUT_EMAIL_INBOX — inbox nickname
• TESTRONAUT_EMAIL_LINK_HOSTS — comma-separated trusted destination hosts
• TESTRONAUT_SESSION_TOKEN — session token override

See Hosted Test Inboxes for the complete setup and security model.

Human input

Controls whether the agent can pause and prompt the terminal user for short verification codes (TOTP, SMS, email codes).

• Config block:

  "humanInput": {
    "enabled": true,
    "timeoutSeconds": 60
  }

• Env overrides:
  • TESTRONAUT_HUMAN_INPUT (true/false)
  • TESTRONAUT_HUMAN_INPUT_TIMEOUT_SECONDS (number)

enabled defaults to true. Set to false for headless CI runs. Timeout is clamped to 5–300 seconds.

Accepted aliases: humanInputEnabled, allowHumanInput, humanInput.timeout, humanInputTimeoutSeconds, humanInputTimeout.

DOM list trimming

• dom.listItemLimit / dom.listLimit / domListLimit (number 0–100, "all", or "none")
• Env override: TESTRONAUT_DOM_LIST_LIMIT
• Default: 3 items per list. "all" keeps everything but can massively increase tokens and may break flows.

Table body rows use the same list-item limit. Automatic DOM snapshots injected after clicks have a separate character limit:

• dom.automaticLimit (number 1,000–100,000)
• Env override: TESTRONAUT_AUTO_DOM_LIMIT
• Default: 15000 characters

Agents can also pass a CSS selector to get_dom when only one page region is relevant.

Resource guard (list/table completeness)

Ensures detected resources (documents/files/rows) are fully processed before reporting success.

• Config block:

  "resourceGuard": {
    "enabled": true,
    "hrefIncludes": ["/document/", "/file/", "/download", "/attachment/"],
    "dataTypes": ["document", "file", "item", "row"]
  }

• Env overrides:
  • TESTRONAUT_RESOURCE_GUARD (true/false)
  • TESTRONAUT_RESOURCE_HREF_PATTERNS (comma-separated)
  • TESTRONAUT_RESOURCE_DATA_TYPES (comma-separated)

enabled defaults to true. Adjust patterns to fit your app. Set to false to disable.

Key env vars (summary)

• TESTRONAUT_DOM_LIST_LIMIT — cap list items (0-100, all, none)
• TESTRONAUT_AUTO_DOM_LIMIT — cap automatic post-action DOM snapshots (1000-100000)
• TESTRONAUT_RESOURCE_GUARD — enable/disable resource guard
• TESTRONAUT_RESOURCE_HREF_PATTERNS — comma list of href substrings
• TESTRONAUT_RESOURCE_DATA_TYPES — comma list of data-type values