Skip to main content

Automated MFA 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.

Premium Access​

Creating or updating stored MFA entries is a premium feature. You need an active paid subscription to add a new MFA QR code key or change an existing one.

Reading existing MFA entries is not paid-gated. If an account downgrades after creating MFA entries, the CLI can still list and retrieve those existing codes, but the account cannot create new entries or update stored QR code keys until premium access is restored.

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.

Staging and Protected Deployments​

Use --dev to send CLI API calls to the staging API:

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

If staging is protected by Vercel, provide the bypass secret:

testronaut --dev --vercel-bypass=YOUR_SECRET login.mission.js -o mfa=github-test-mfa

You can also set it with an environment variable:

export VERCEL_AUTOMATION_BYPASS_SECRET=YOUR_SECRET
testronaut --dev login.mission.js -o mfa=github-test-mfa

Debugging MFA API Calls​

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

testronaut --debug --dev 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 MFA feature flag is disabled for the environment
  • the account is not allowed to create or update MFA entries
  • the staging request is missing a Vercel bypass secret
  • 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.