Mechasmmechasm logoMechasmbeta
Back to Docs

Using Emails in Tests

Retrieve 2FA and verification codes from email during test execution

Mechasm can read incoming emails during test execution so your tests can continue through flows that require a code sent by email.

This is most useful for:

  • Sign in flows with email-based 2FA
  • Sign up flows with verification codes
  • Password reset flows that send a code to the inbox

Before You Start

Before using email retrieval inside a test, make sure your project email inbox setup is configured in Project Settings.

See IMAP Integration Setup.

How It Works

When your test needs a code from email, the runner connects to your configured inbox and checks recent unread emails in the INBOX.

It can look for emails using filters such as:

  • subject
  • from
  • bodyIncludes

Once a matching email is found, Mechasm parses the content and extracts a token using common code formats.

Supported Token Patterns

Mechasm automatically detects tokens in these formats:

  • 6-digit codes like 123456
  • 4-digit codes like 1234
  • 8-digit codes like 12345678
  • Labelled codes like code: 123456

Using It in a Test

The test runner supports both a get2FAToken action and an openEmailLink action.

At a high level, the flow is:

  1. Trigger an action in the app that sends the verification email.
  2. Wait for the email and retrieve the token.
  3. Store the token in a variable.
  4. Use that variable in the next step to complete the flow.

Example Usage

A typical test flow could look like this:

  1. Enter the user email and password.
  2. Submit the login form.
  3. Wait for the email with the verification code.
  4. Read the token from the inbox.
  5. Fill the OTP field with that token.
  6. Submit and continue the test.

You can describe this naturally in your prompt, for example:

"Log in with [email protected]. Wait for the email verification code, enter it in the OTP field, and continue to the dashboard."

For flows that send a link instead of a code, Mechasm can find the matching email, resolve the right link, and open it during the test.

This is useful for:

  • Password reset emails
  • Magic login links
  • Invite and onboarding links
  • Email verification links

In those cases, Mechasm can use the openEmailLink action instead of get2FAToken.

Use get2FAToken when the product expects the user to copy a code from email and paste it into a field.

Use openEmailLink when the product expects the user to follow a link from the email.

When opening a link from email, Mechasm can narrow the match using:

  • Email filters such as from, subject, and bodyIncludes
  • Link filters such as partial link text, partial URL matches, or a URL regex pattern

This helps when a mailbox receives multiple emails or when one email contains several links.

Opening in the Same or a Different Context

Email links can be opened in different ways depending on the flow:

  • In the current active page
  • In a new tab in the same session
  • In a separate isolated context

This is helpful for flows such as:

  • Staying logged in while opening a reset or verification link in a new tab
  • Following an invite link as a different user in an isolated session
  • Opening authentication links without losing the main test state

A natural-language prompt could look like this:

"Request a password reset, open the reset link from the email from [email protected] in a new tab in the same session, and continue the flow."

Filter Matching

When using emails in tests, Mechasm can narrow the search using email metadata and body content.

Examples of useful filters:

  • from: when you know which sender delivers the code
  • subject: when the email uses a stable subject line such as "Verification Code"
  • bodyIncludes: when the email content contains a specific phrase

This helps make email-based tests more reliable when the inbox receives multiple messages.

Debugging Failures

If the runner cannot find a token in time, the error output includes useful debugging details such as:

  • The active search filters
  • The number of emails found in the time window
  • Partially matching emails
  • Whether any tokens were detected in those emails
  • A short preview of the matching message content

This makes it easier to understand whether the failure was caused by:

  • Missing or incorrect filters
  • Slow email delivery
  • The code being outside the supported token formats
  • The wrong inbox being configured

Good Use Cases

Using emails in tests works especially well for:

  • Login flows with email OTP
  • Password reset verification
  • Sign-up confirmation steps
  • Admin approval flows that send codes or verification emails