Cucumber is an extremely popular behaviour driven test framework used by developers around the world. It started as a Ruby project but now supports many languages and use cases. Cucumber tests are written in plain language and can be used to test any application. In this post we will show you how to use Cucumber to test email related processes in your application using disposable email addresses.

Email in tests

When writing an acceptance test using the cucumber bdd approach you may need to test email related processes. For instance, you may want to test that a user can sign-up and receive a verification email. Or you may want to test that a user can reset their password and receive a password reset email. These are common test scenarios that require real email addresses to test. But how do we do that?

Using email in Cucumber test

MailSlurp is a free Email API that lets you generate random email addresses on demand for use in QA tests and test driven development. You can use them to send and receive real emails in a range of languages (including Ruby, Java, Javascript and more).

This post will demonstrate how to use MailSlurp with Cucumber to test the authentication features of a web application using selenium webdriver.

The Gherkin Syntax

Cucumber tests are built around human-readable scenarios written in syntax, a form of plain english. These tests look a bit like this:

This is known as a behavior driven development bdd framework. The syntax is easy to understand and serves as documentation. This is because the piece of code describes the expectations we have for a test and document what should occur.

Note: Gherkins are very popular in Germany, where MailSlurp is based 😄.

Testing Email with Cucumber

To test email using real emails all we need to do is wire MailSlurp into our Cucumber tests. Let's write an example in Ruby to demonstrate. We could use this approach to load a web application home page, generate test email accounts, and fill a username and password form using them.


To get started make sure you have Ruby installed. Create a new project and add the following to a file.

Now run and we are ready to write some tests.

Writing tests

Cucumber tests live in a folder. Let's create that and add a new test feature and some step definitions.

Inside the file let's write a scenario that tests the sending and receiving of an email in a Cucumber test.

If we run Cucumber will tell us (rightly) that we are missing step definitions for each , clause. We will define those next.

Defining steps

The magic of Cucumber tests happens in your steps files. Theses files map scenarios to real logic in your chosen programming language. Here we are using Ruby as it is popular but MailSlurp supports all other Cucumber supported languages.

Configuring MailSlurp

Inside let's add the following:

This instantiates a MailSlurp client for our email logic with an API KEY environment variable.

⚠️ Note: MailSlurp requires an api key. You can get one free in the dashboard.

Writing email logic

Now that MailSlurp is configured we can use it in our step definitions to create new email addresses, send real emails, and wait for emails to be received. We can then make assertions on the content of the received email.

MailSlurp supports many other features like custom domains, attachments, email pattern matching and more. See the about page for more information.

Running the tests

Now if we run we will see the following output!

Next steps

Imagine the possibilities. Unlimited real email addresses at your disposal in Cucumber test. MailSlurp is free for personal use and available now.

Source code

You can find the full source for this post plus more on our Github page.

If you have ideas for future posts please let us know on Twitter.