Skip to main content

Integration testing guide

email testing

MailSlurp was designed with QA and integration testing in mind. There are SDKs for many languages and plugins for common test frameworks such as Cypress, Selenium, and Playwright. You can also find a wide array of example test projects on GitHub.

Key features​

MailSlurp is a complete email and SMS testing solution. You can create phone numbers and email accounts on demand during automated tests and use them to test email and SMS related processes in your applications. There are SDK packages published for many test frameworks and methods that enable the following features:

  • Create email addresses and phone numbers on demand
  • Wait for emails and SMS to arrive in tests
  • Extract links and verification codes from emails
  • Test authentication and sign up flows
  • Validate emails for spam and viruses
  • Trap outbound email with fake SMTP servers

How it works​

MailSlurp is perfect for testing. You can create clean inboxes and phone numbers for each test run (or reuse existing) and mimic real user behavior and messaging in your tests. This is especially useful for testing user authentication flows in E2E browser tests.

How email testing works​

Use MailSlurp email accounts in your tests to create unlimited clean email addresses on demand. You can then send and receive emails and extract links and verification codes from them. Here is an example of how it works:

emails

How SMS testing works​

Use MailSlurp real phone numbers to receive SMS TXT messages in code and tests. You can receive two-factor authentication codes via SMS and verify TXT content. Here is an example of how it works:

sms

Creating inboxes​

You can create inboxes in the dashboard on in code. You can assign randomly allocated addresses or use a custom domain for full control over inbox addresses.

const inbox = await mailslurp.createInbox();
// { id: '123', emailAddress: '123@mailslurp.com' }

Receiving messages​

Waiting for matching content​

A key feature of MailSlurp is the ability to await expecting messages using the wait for methods. You can use wait methods to hold a connection open in tests until an expected email or SMS arrives. This is useful for testing asynchronous processes such as email verification and password resets so that tests are not flaky.

// wait for the latest unread sms
const [sms] = await mailslurp.waitController.waitForSms({
    waitForSmsConditions: {
        count: 1,
        unreadOnly: true,
        phoneNumberId: phoneNumber.id,
        timeout: 30_000
    }
});
// extract a code from body with regex
expect(sms.body).toContain('Your code: 123')
const [, code] = /.+:\s([0-9]{3})/.exec(sms.body)
expect(code).toEqual('123')

Receiving codes​

MailSlurp is perfect for receiving codes. You can use a simple regular expression on a message body to extract a code. Here is an example of receiving a code from an email:

cy.then(function () {
    // app will send user an email containing a code, use mailslurp to wait for the latest email
    cy.mailslurp()
        // use inbox id and a timeout of 30 seconds
        .then(mailslurp => mailslurp.waitForLatestEmail(this.inboxId, 30000, true))
        // extract the confirmation code from the email body
        .then(email => /.*verification code is (\d{6}).*/.exec(email.body!!)!![1])
        // fill out the confirmation form and submit
        .then(code => {
            cy.get("[name=code]").type(code).trigger('change');
            cy.get("[data-test=confirm-sign-up-confirm-button]").click();
        })
})

MailSlurp provide convenience functions for finding links in emails and SMS:

// extract the links using MailSlurp
const links = await mailslurp.emailController.getEmailLinks({
  emailId: email.id,
});
browser.assert.equal(
  links.links.length,
  1,
  "Expect to find 1 link in the email",
);
loginLink = links.links[0];

Query HTML​

Extract HTML content from emails using CSS query type selectors:

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

Testing email validity​

You can also test emails themselves using MailSlurp. This means you can receive emails from your servers and make assertions about their rendering, content, images, links and spam ratings.

Verifying email content​

You can visually test email content in the dashboard. This gives you details on email feature support across browsers.

Integrations​

MailSlurp has SDKs for many languages and integrations with popular test frameworks. Here are some major frameworks:

Cypress JS​

You can use email and SMS messages in CypressJS using the Cypress MailSlurp plugin. The plugin is open source and available on GitHub.

Using MailSlurp with Cypress enables you to create email addresses and phone numbers on demand during tests and then wait for emails and SMS to arrive. You can then extract links and verification codes from emails and use them to test your application. An example might look like this:

let code;
it('can receive the confirmation email and extract the code', () => {
  // wait for an email in the inbox
  cy.waitForLatestEmail(inboxId).then(email => {
    // verify we received an email
    assert.isDefined(email);

    // verify that email contains the code
    assert.strictEqual(/verification code is/.test(email.body), true);

    // extract the confirmation code (so we can confirm the user)
    code = /([0-9]{6})$/.exec(email.body)[1];
  });
});

Video example:

Next steps:

Cypress documentation

Jest​

Testing in NodeJS is easy using the mailslurp-client

// get the verification code for a given inboxId
async function getVerificationCode(inboxId: string) {
  const emails = await api.getEmails(inboxId, { minCount: 1 });
  const latestEmail = await api.getEmail(emails[0].id);
  const verificationCode = /code = (.*)/.exec(latestEmail.body)![1]!;
  return verificationCode;
}
expect(await getVerificationCode(id)).toContain('123');

Video example:

Next steps:

Node documentation

Playwright​

MailSlurp works natively with Playwright tests. Use it to create disposable mailboxes when running tests:

await page.click('[data-test="sign-up-create-account-button"]');
// wait for verification code
const sms = await mailslurp.waitController.waitForLatestSms({
  waitForSingleSmsOptions: {
    phoneNumberId: phone.id,
    unreadOnly: true,
    timeout: 30_000,
  }
})
// extract the confirmation code (so we can confirm the user)
const code = /([0-9]{6})$/.exec(sms.body)?.[1]!!;

Video example:

Next steps:

Playwright documentation

Selenium​

Integrate the MailSlurp Java, Python, or CSharp SDK with Selenium to test email and SMS in Java. See the example projects for more information.

/**
 * Create a real email address with MailSlurp and use it to start sign-up on the playground
 */
@Test
public void test3_canCreateEmailAddressAndSignUp() throws ApiException {
    logger.info("Create email address");
    // create a real, randomized email address with MailSlurp to represent a user
    InboxControllerApi inboxControllerApi = new InboxControllerApi(mailslurpClient);
    inbox = inboxControllerApi.createInboxWithDefaults();

    logger.info("Assert inbox exists");
    // check the inbox was created
    assertNotNull(inbox.getId());
    assertTrue(inbox.getEmailAddress().contains("@mailslurp"));

    logger.info("Fill elements");
    // fill the playground app's sign-up form with the MailSlurp
    // email address and a random password
    driver.findElement(By.name("email")).sendKeys(inbox.getEmailAddress());
    driver.findElement(By.name("password")).sendKeys(TEST_PASSWORD);

    logger.info("Submit sign-up button");
    // submit the form to trigger the playground's email confirmation process
    // we will need to receive the confirmation email and extract a code
    driver.findElement(By.cssSelector("[data-test=sign-up-create-account-button]")).click();
}

Video example:

Next steps:

Selenium documentation