FeaturesAuth TestingEmail OTP & Magic Link

Email OTP & Magic Link Testing

Test passwordless authentication flows automatically using Mailosaur integration.

What We Cover

  • Email OTP — Codes sent via email (expire in 2–3 minutes)
  • Magic Links — Passwordless login links (one-use)

Both use Mailosaur to automatically intercept emails and retrieve codes/links.

Prerequisites

  1. Mailosaur account — Sign up for free
  2. Mailosaur API key — Found in Mailosaur dashboard → Settings
  3. Mailosaur server ID — Found in Mailosaur dashboard → Servers
  4. Test email address — Provided by Mailosaur (e.g., qa+test@example.mailosaur.com)

Set these as environment variables:

MAILOSAUR_API_KEY=your_api_key_here
MAILOSAUR_SERVER_ID=your_server_id_here
⚠️

Without Mailosaur credentials set, OTP and magic link tests cannot run. The platform will return a clear error message.

Email OTP Setup

1
Create Persona
Dashboard → Personas → Create Persona
2
Select 'Email OTP' Type
Choose from auth type dropdown
3
Enter Email Address
Use your Mailosaur inbox (e.g., qa+test@example.mailosaur.com)
4
Set Mailosaur Address
Same as email field (auto-filled)
5
Save
Persona is ready to use
6
Use in Tests
Select persona when running tests. AI retrieves OTP automatically

How It Works

During test execution with an Email OTP persona:

1. Test reaches OTP page
2. AI sends login request
3. Mailosaur intercepts email with OTP code
4. BugBrain calls Mailosaur API to retrieve OTP
5. AI enters OTP code in form
6. Login succeeds
7. Test continues with authenticated state

Total time: 2–3 seconds (incredibly fast)

Magic Link Setup

1
Create Persona
Dashboard → Personas → Create Persona
2
Select 'Magic Link' Type
Choose from auth type dropdown
3
Enter Email Address
Mailosaur test email
4
Save
Ready to use
5
Use in Tests
AI will automatically retrieve and open the magic link

How Magic Link Works

1. Test reaches login page
2. User enters email
3. Mailosaur intercepts magic link email
4. BugBrain retrieves link from Mailosaur API
5. AI opens the link
6. User is logged in
7. Test continues

Advantage: No password needed, even more secure than OTP.

Persona Fields

FieldRequiredExampleNotes
Name✓QA OTP UserUser-friendly name
Project✓AcmeWhich project
Email✓qa@example.mailosaur.comMailosaur address
Auth Type✓email_otp or magic_linkChoose one
Mailosaur Address✓qa@example.mailosaur.comUsually same as email

Using in Tests

Create a test that uses the OTP persona:

Test: "User can sign up with OTP"
├─ Use Persona: QA OTP User
├─ Step 1: Navigate to signup page
├─ Step 2: Enter email
├─ Step 3: Click "Send OTP"
├─ Step 4: Wait for OTP email
├─ (AI automatically retrieves OTP)
├─ Step 5: Verify OTP was entered correctly
└─ Result: ✓ Signup successful

Important Notes

OTP Timeout Window

OTP codes typically expire in 2–3 minutes. If test takes longer to reach the OTP field, the code expires:

  • ✅ Fast tests: 30 seconds to OTP screen (no problem)
  • ❌ Slow tests: 10 minutes before OTP screen (code expires)

Solution: Create focused tests that reach the OTP screen quickly.

Email Address Reusability

Mailosaur addresses are reusable. The same qa@example.mailosaur.com can be used for multiple tests:

Test 1: qa@example.mailosaur.com (runs at 9:00 AM)
Test 2: qa@example.mailosaur.com (runs at 9:05 AM)
Test 3: qa@example.mailosaur.com (runs at 9:10 AM)

Mailosaur stores all emails separately. Each test gets the correct code.

One-Time Links

Magic links are one-time use:

Run 1: Link works, user logged in ✓
Run 2: Same link doesn't work ❌ (already used)

Solution: Use fresh Mailosaur address per test, OR
          accept that magic link tests can't be rerun without new email

Troubleshooting

”Could not retrieve OTP code”

  • Mailosaur credentials not set (check env vars)
  • Email not received (check Mailosaur inbox manually)
  • OTP code already read in previous test
  • Timeout waiting for email (increase timeout)

“Magic link not found”

  • Email intercepted but link missing
  • Link format different than expected
  • Mailosaur credentials invalid

Tests Running Too Slow

OTP window is tight (2–3 minutes). If tests run slowly:

  • Optimize page performance
  • Simplify test steps before OTP
  • Increase element_wait_timeout_ms

Best Practices

  1. Use dedicated Mailosaur inbox — Don’t mix with production emails
  2. Create per-test addresses — qa+test1@, qa+test2@, etc.
  3. Keep tests fast — Reach OTP screen within 30 seconds
  4. Don’t reuse magic links — Each magic link is one-use only
  5. Test OTP expiration — Write a test that verifies expired code fails
  6. Monitor Mailosaur usage — Free tier has limits on email retrieval

Next Steps

Username & PasswordTOTP / MFA