Serenity is a very popular behaviour driven development testing framework. It enables QA testers and developers write narrative style stories to describe user behaviour in applications and implement test logic to perform automated tests against real application.

Full example code available on Github.

By combining Serenity and MailSlurp you can create test email accounts in code and test your application end-to-end using real emails. In this example we will use Java and Selenium to test a demonstration web app hosted at

The application has a typical user sign up form that accepts an email address and password. Upon submission a confirmation code is emailed to the user containing a verification code. This code must be submitted to the page to confirm the user account, after which the user may log in and see a picture of a friendly dog.

Setup test project

We can create a Serenity test project with Java and JBehave using the command and then selecting the Jbehave Selenium option. This should generate a folder with a structure like so:

Edit the and add the MailSlurp dependency. This will allow us to create test email accounts in code. MailSlurp is free for personal use but you need an API KEY. Sign up to use the library.

Describe our test narrative

Inside the folder create a new directory called . Inside that folder add a to describe the test:

This is always a good step to prepare for what we hope to achieve with our tests.

Creating a story

Serenity uses a behaviour driven approach meaning we model our tests based on user behavior. Each test is called a story. A story is written in a file and the statements within this file map to functions we define in Java later.

We want to test the sign up, confirmation, and login process for our demo app. Let's create a file and enter a story:

The scenario describes what we expect to happen given an initial condition and a user action. The next step is to write Java methods that map to each statement in our scenario. Let's start.

Writing Java bindings

Create a package inside your folder. We will name ours . Next create a root class:

Configure the test suite

This will enable our tests to run with .

Add MailSlurp client

Next we need to set up a MailSlurp client to send and receive emails. This looks like so:

Create a PageObject for our webapp

Next we need a way for Selenium to load and query our webapp. Create a folder and add a class.

Each method describes a set of actions that will take place against the playground app such as submiting a login form. We will call these methods from our steps.

Writing test steps

The next stage is to write steps for our tests. This bind story statements to a series of Java methods.

Definition steps

Create a directory and inside that create a class.

Note how each , and annotation on a method maps to the same words used in the . This is the magic of Serenity and allows us to write tests in plain statements in story files that map to Java steps.

End user steps

We can abstract some of the step logic into an class. Place this inside a and add the following:

Run the tests

We now have a story and steps associated with it. Make sure you have the Firefox Geckodriver installed so that Selenium can open Firefox and execute our tests. Next run .

If successful the test will create a new email address, sign up a user, receive the confirmation code, extract the verification, submit it and login. Then a dog will be shown to welcome us.

How does it work?

That was a log of code. Let's review some important parts.

Creating inboxes

You can use MailSlurp to create test email accounts on demand.

Receiving emails in tests

Once the user has signed up we can then ues MailSlurp to wait for the email to arrive.

Then we can use a regex pattern to extract the verification code from the email body:


Serenity is a powerful BDD testing framework. With JBehave you can map stories to Java methods. By adding MailSlurp you can create real email addresses and use them to test user sign up, authentication, newsletters and more. See for more information and examples.