Mailosaur and Cucumber quickstart guide

What you’ll need

You’ll need a Mailosaur account. If you don’t already have one, just create a free trial account first.
Log in to your account and generate an API key, which you will need to run automated tests.
Finally, make sure you know how to send emails (or SMS) into your account.

Create a Cucumber starter project

Create a new project for your programming language, then run the following commands to install Cucumber and any testing libraries you need.

Create and initialize a Node.js project

mkdir mailosaur-nodejs-cucumber
cd mailosaur-nodejs-cucumber
npm init -y

Install Cucumber

Use npm to install Cucumber. There's no need to also install an assertion library, as you can just use Node.js's built-in Assert module.

npm install --save-dev @cucumber/cucumber

Create a Java project

mkdir mailosaur-java-cucumber
cd mailosaur-java-cucumber

Install Cucumber and JUnit

Gradle users can add these dependencies to their project’s build file:

// Cucumber for Java
testImplementation "io.cucumber:cucumber-java:CUCUMBER_JAVA_VERSION"

// Cucumber JUnit integration
testImplementation "io.cucumber:cucumber-junit:CUCUMBER_JUNIT_VERSION"

// JUnit
testImplementation "junit:junit:JUNIT_VERSION"

Maven users should add these dependencies to their project’s POM:

<dependency>
    <groupId>io.cucumber</groupId>
    <artifactId>cucumber-java</artifactId>
    <version>CUCUMBER_JAVA_VERSION</version>
    <scope>test</scope>
</dependency>
<dependency>
    <groupId>io.cucumber</groupId>
    <artifactId>cucumber-junit</artifactId>
    <version>CUCUMBER_JUNIT_VERSION</version>
    <scope>test</scope>
</dependency>
<dependency>
    <groupId>junit</groupId>
    <artifactId>junit</artifactId>
    <version>JUNIT_VERSION</version>
    <scope>test</scope>
</dependency>

If you don’t use Gradle or Maven, refer to the README within the GitHub repository.

Create a Ruby project

mkdir mailosaur-ruby-cucumber
cd mailosaur-ruby-cucumber

Install Cucumber and RSpec testing libraries

Add the following lines to your Gemfile:

gem "cucumber"
gem "rspec-expectations"

Create a Python project

mkdir mailosaur-python-cucumber
cd mailosaur-python-cucumber

Create a virtual environment

python -m venv venv
source venv/bin/activate

Install Behave

Behave is Python’s answer to Cucumber. It uses the same Gherkin syntax for feature files and a similar step definition concept. There's no need to install an assertion library, as you can use Python's built-in assert statement.

pip install behave

Create a .NET XUnit project using the XUnit project template

dotnet new xunit -n mailosaur-dotnet-cucumber
cd mailosaur-dotnet-cucumber

Install Reqnroll and XUnit testing libraries

Reqnroll is .NET's answer to Cucumber. It uses the same Gherkin syntax for feature files and a similar step definition concept.

dotnet add package Reqnroll
dotnet add package Reqnroll.Xunit
dotnet add package xunit.core

Integrate Mailosaur with an existing Cucumber project

If you have an existing Cucumber project (or created one just now), here is how to install and configure Mailosaur's API client library:

Install the Mailosaur Node.js library

Use npm to install the Mailosaur Node.js library.

npm install --save-dev mailosaur

Install the Mailosaur Java library

Gradle users can add this dependency to their project’s build file:

// MAILOSAUR_JAVA_VERSION available at:
// https://github.com/mailosaur/mailosaur-java/releases/latest)
implementation "com.mailosaur:mailosaur-java:MAILOSAUR_JAVA_VERSION"

Maven users should add this dependency to their project’s POM:


  com.mailosaur
  mailosaur-java
  MAILOSAUR_JAVA_VERSION

If you don’t use Gradle or Maven, refer to the README within the GitHub repository.

Install the Mailosaur Ruby library

Run this command to install the Mailosaur Ruby package:

gem install mailosaur

Install the Mailosaur Python library

Run this command to install the Mailosaur Python package:

pip install mailosaur

Install the Mailosaur .NET library

Run this command to install the Mailosaur NuGet package:

dotnet add package mailosaur

Write your first Cucumber test

Cucumber tests are BDD (behavior-driven development) tests and have two parts:

Feature files: Cucumber groups its tests by feature, and a feature file consists of lists of scenarios made up of steps, all written in human-like Gherkin syntax in the form of Given, When, and Then statements.
Step definition files: These contain the code that implements each step from the feature files, including the test setup, actions, and assertions.

Your first test is to check that the Mailosaur library is able to connect to the Mailosaur API and see at least one inbox. This includes:

Writing a Gherkin scenario in a feature file using Given, When, and Then steps, such as:

Retrieving the Mailosaur API key
Connecting to the Mailosaur API using the Mailosaur library
Confirming that at least one inbox is present

Create the following scenario in a Quickstart.feature file:

Feature: Quick start testing with Mailosaur

Scenario: Check the Mailosaur API works by checking we can access an email inbox
    Given the Mailosaur API client is setup
    When I connect to the Mailosaur API
    Then I should see at least one inbox

To implement the scenario, define the step definitions for each Cucumber step.

let apiKey;
let mailosaurClient;
let emailServers;

Given('the Mailosaur API client is setup', function () {
 apiKey = process.env.MAILOSAUR_API_KEY;

 assert.ok(apiKey, 'MAILOSAUR_API_KEY environment variable must be set');
});

When('I connect to the Mailosaur API', async function () {
 mailosaurClient = new MailosaurClient(apiKey);

 // Make a simple API call to get a list of inboxes
 const result = await mailosaurClient.servers.list();
 emailServers = result.items;
});

Then('I should see at least one inbox', function () {
 assert.ok(emailServers, 'Expected emailServers to be defined');
 assert.ok(emailServers.length > 0, 'Expected at least one inbox');
});

private String apiKey;
private MailosaurClient client;
private List<Server> emailServers;

@Given("the Mailosaur API client is setup")
public void a_mailosaur_api_key_is_configured() {
   Dotenv dotenv = Dotenv.load();
   apiKey = dotenv.get("MAILOSAUR_API_KEY");
  
   assertNotNull("MAILOSAUR_API_KEY must be set", apiKey);
   assertFalse("MAILOSAUR_API_KEY must not be empty", apiKey.isEmpty());
}

@When("I connect to the Mailosaur API")
public void i_connect_to_the_mailosaur_api() throws Exception {
   mailosaurClient = new MailosaurClient(apiKey);

   // Make a simple API call to get a list of inboxes
   emailServers = mailosaurClient.servers().list().items();
}

@Then("I should see at least one inbox")
public void i_should_see_at_least_one_inbox() {
   assertNotNull("Server list should not be null", emailServers);
   assertFalse("Expected at least one inbox", emailServers.isEmpty());
}

@client = nil
@email_servers = nil

Given('the Mailosaur API client is setup') do
 @api_key = ENV['MAILOSAUR_API_KEY']
 expect(@api_key).not_to be_nil
 expect(@api_key.strip).not_to be_empty, 'MAILOSAUR_API_KEY must not be empty'
end

When('I connect to the Mailosaur API') do
 @mailosaurClient = Mailosaur::MailosaurClient.new(@api_key)
 @email_servers = @mailosaurClient.servers.list.items
end

Then('I should see at least one inbox') do
 expect(@email_servers).not_to be_nil
 expect(@email_servers).not_to be_empty
end

@given('the Mailosaur API client is setup')
def step_impl(context):
   global apiKey
   apiKey = os.getenv('MAILOSAUR_API_KEY')
   assert apiKey, 'MAILOSAUR_API_KEY environment variable must be set'

@when('I connect to the Mailosaur API')
def step_impl(context):
   global mailosaurClient
   global emailServers
   mailosaurClient = MailosaurClient(apiKey)
   result = mailosaurClient.servers.list()
   emailServers = result.items

@then('I should see at least one inbox')
def step_impl(context):
   assert emailServers, 'Expected emailServers to be defined'
   assert len(emailServers) > 0, 'Expected at least one inbox'

private String apiKey;
public MailosaurClient? mailosaurClient;
private IList<Server>? emailServers;

[Given("the Mailosaur API client is setup")]
public void GivenTheApiKeyIsSetForMailosaur()
{
   apiKey = _config["appSettings:MAILOSAUR_API_KEY"]!;

   Assert.NotNull(apiKey);
   Assert.NotEmpty(apiKey);
}

[When("I connect to the Mailosaur API")]
public void WhenIConnectToTheMailosaurApi()
{
   mailosaurClient = new MailosaurClient(apiKey);

   // Make a simple API call to get a list of inboxes
   emailServers = mailosaurClient.Servers.List().Items;
}

[Then("I should see at least one inbox")]
public void ThenIShouldSeeAtLeastOneInbox()
{
   Assert.NotNull(emailServers);
   Assert.True(emailServers.Any(), "Expected at least one inbox");
}

Start testing

Now that you have a project connected to the Mailosaur API, you can start creating all kinds of tests:

Email testing with Cucumber
SMS testing with Cucumber
Email testing — test password resets, account verification, order confirmations, etc.
SMS testing — test alerts, notifications, and 2FA logins
2FA app testing — mimic the functionality of apps like Google Authenticator and Auth0
Email deliverability testing

Quickstart guide for Mailosaur and Cucumber