Selenium email testing with MailSlurp

Use MailSlurp inbox and phone APIs in Selenium tests to verify signup, password reset, one-time password, and other messaging workflows. Add the Node.js, Java, C#, or Python SDK to your test project, create an isolated email address or phone number, and wait for the message your browser action triggers.

Selenium email testing quick start

1. Install the MailSlurp SDK used by your test suite.
2. Create a unique inbox or phone number for each test run or parallel worker.
3. Enter the generated address or number through Selenium and submit the workflow.
4. Wait for the expected email or SMS using the MailSlurp API.
5. Extract the confirmation link or OTP code, then continue the browser test and assert the result.

This keeps message delivery checks inside the test flow without relying on shared inboxes or fixed browser delays. For guidance on test architecture and failure modes, see Selenium email testing for transactional flows and MFA.

Examples

Resources

• C# Selenium example
• Java Selenium example
• Ruby Capybara
• Get free API KEY

Tutorial

Setup

Install the MailSlurp package for your language and then configure it with your API Key. See the SDKs page for more information.

Java

Add the maven central package.

<dependency>
    <groupId>com.mailslurp</groupId>
    <artifactId>mailslurp-client-java</artifactId>
</dependency>

C#

Use the Nuget package:

dotnet add package mailslurp

Node.js

Add the NPM package.

npm install --save mailslurp-client

Python

Use the PyPi package.

pip install mailslurp-client

Usage

Once you have installed the MailSlurp package you can use it to create email addresses, send and receive emails, and send and receive SMS messages in your Selenium tests.

The following sections give usage examples in Java and TypeScript, but you can use the same methods in any supported language.

Creating inboxes

You can create inboxes that are disposable or permanent. Use a name, description, or tags so you can find the inbox again.

// use names, description, and tags to identify an inbox
String randomString = String.valueOf(new Random().nextLong());
String customName = "Test inbox " + randomString;
String customDescription = "My custom description " + randomString;
String customTag = "test-inbox-" + randomString;
// create inbox with options so we can find it later
CreateInboxDto options = new CreateInboxDto()
        .name(customName)
        .description(customDescription)
        .tags(Collections.singletonList(customTag));
InboxDto inbox = inboxControllerApi.createInboxWithOptions(options).execute();

Finding inboxes

You can either create a new inbox for each test run or fetch an existing inbox. When fetching, you can get it directly by ID or search for it using an email address, name, description, or tags assigned when the inbox was created.

Get inbox by address or name

Get an inbox by name or address like so:

// get inbox by id
InboxDto inboxById = inboxControllerApi.getInbox(inbox.getId()).execute();

// lookup inbox by address
InboxByEmailAddressResult inboxByAddress =
    inboxControllerApi.getInboxByEmailAddress(inbox.getEmailAddress()).execute();
assertEquals(inboxByAddress.getInboxId(), inbox.getId());

// lookup inbox by name
InboxByNameResult inboxByName =
    inboxControllerApi.getInboxByName("Non-existing inbox").execute();
assertFalse(inboxByName.getExists());

Search for an inbox

Use search methods to search for an inbox:

PageInboxProjection inboxSearchResult = inboxControllerApi.searchInboxes(
        new SearchInboxesOptions()
                .search(customTag)
).execute();
assertEquals(inboxSearchResult.getNumberOfElements(), Integer.valueOf(1));
assertEquals(inboxSearchResult.getContent().get(0).getId(), inbox.getId());

Waiting for messages

MailSlurp wait for methods allow you to wait for an expected email or SMS to arrive during testing.

WaitForControllerApi waitForControllerApi = new WaitForControllerApi(mailslurpClient);
List matchingEmails = waitForControllerApi.waitFor(new WaitForConditions()
        .inboxId(inbox.getId())
        .timeout(120000L)
        .count(1)
        .countType(WaitForConditions.CountTypeEnum.ATLEAST)
        .unreadOnly(true)
        .addMatchesItem(new MatchOption()
                .field(MatchOption.FieldEnum.SUBJECT)
                .should(MatchOption.ShouldEnum.CONTAIN)
                .value("Test subject")
        )

).execute();

Searching for messages

You can search for messages too.

EmailControllerApi emailController = new EmailControllerApi(mailslurpClient);
PageEmailProjection emailSearch = emailController.searchEmails(
        new SearchEmailsOptions()
                .searchFilter("Test subject")
).execute();

Note: searching will not wait for matching conditions. Use the waitFor methods to wait for expected emails that have not yet arrived.

Getting content

You can get the content of emails and SMS messages.

Email email = emailController.getEmail(emailId).execute();
assertEquals(email.getSubject(), mySubject);
assertNotNull(email.getBody());
assertNotNull(email.getFrom());
assertNotNull(email.getAttachments());

Extract codes

Use RegExp patterns to extract codes from emails or SMS messages.

// query HTML for content
const { matches: [, captureGroup]} = await emailController.getEmailContentMatch({
  emailId: emailId,
  contentMatchOptions: {
    // use regex capture groups to extract codes
    pattern: 'Your verification code is: (\\d{6})',
  }
});
expect(captureGroup).toEqual(sentVerificationCode)

Get links

You can also extract links from messages.

// get links from email content
const { links } = await emailController.getEmailLinks({
  emailId: emailId,
});

Query HTML

You can use XPath or CSS selectors to query HTML content.

// query HTML for content
const { lines } = await emailController.getEmailHTMLQuery({
  emailId: emailId,
  htmlSelector: '.heading > .username'
});