Skip to main content

Automated MFA Codes

Free · 1 codeShuttle · 5 codesBlastoff · 25 codes

Testronaut can retrieve stored TOTP MFA codes from the Testronaut API during a mission. This lets the agent complete supported MFA challenges without pausing for manual input.

Automated MFA uses the sessionToken saved by testronaut login and an MFA nickname that points to a stored QR code key in your Testronaut account.

See Plans & Feature Availability or Pricing for current allowances.

Before You Start​

  1. Create the MFA entry in Testronaut using the QR code key from the service you want to test.
  2. Give the entry a memorable nickname, such as github-test-mfa.
  3. Run testronaut login in the project so testronaut-config.json contains a valid sessionToken.
testronaut login

Pick an MFA Nickname​

The CLI can learn which stored MFA entry to use in three ways.

1. CLI Option​

Use -o mfa=<nickname> for one run:

testronaut login.mission.js -o mfa=github-test-mfa

This is useful when different environments or test accounts need different MFA entries.

2. Config JSON​

Set a default nickname in testronaut-config.json:

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

The nested form is also supported:

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

This is useful when a project normally uses the same MFA entry.

3. Mission Text​

You can name the MFA entry directly in the mission:

missions/login.mission.js
export const loginMission = `
  Visit ${process.env.URL}.
  Sign in with the test account.
  When prompted for MFA, use the MFA nickname github-test-mfa.
  Submit the MFA code and wait for the dashboard.
  If the dashboard is visible, report SUCCESS. Otherwise, report FAILURE.
`;

Mission text is useful when a mission needs to be self-contained or when different missions in the same project use different MFA entries.

Debugging MFA API Calls​

Enable debug logging when you need to inspect what the CLI is receiving from the MFA API:

testronaut --debug login.mission.js -o mfa=github-test-mfa

The CLI writes sanitized MFA API request and response details to:

missions/mission_reports/api-debug.log

Session tokens, Vercel bypass secrets, and MFA code values are redacted.

Fallback Behavior​

If automated MFA is unavailable, Testronaut can fall back to the human input tool when human input is enabled. Common reasons include:

  • the session token is missing or expired
  • the MFA nickname does not exist
  • the account's stored MFA allowance has been reached
  • the API is rate limited or unreachable

If the nickname is missing or slightly mismatched, the CLI can call the MFA list endpoint and retry simple case, spacing, or punctuation differences.