# Quickstart guide for Mailosaur and Cucumber Get Mailosaur up and running within your Cucumber project in a few steps. ## What you’ll need - You’ll need a Mailosaur account. If you don’t already have one, just [create a free trial account first](/app/signup). - 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](https://cucumber.io/) and any testing libraries you need. ### Create and initialize a Node.js project ```js mkdir mailosaur-nodejs-cucumber cd mailosaur-nodejs-cucumber npm init -y ``` ### Install Cucumber Use npm to install [Cucumber](https://www.npmjs.com/package/@cucumber/cucumber). There's no need to also install an assertion library, as you can just use Node.js's built-in [Assert](https://nodejs.org/api/assert.html#assert) module. ```js npm install --save-dev @cucumber/cucumber ``` ### Create a Java project ```java mkdir mailosaur-java-cucumber cd mailosaur-java-cucumber ``` ### Install Cucumber and JUnit Gradle users can add these dependencies to their project’s build file: ```java // 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: ```java io.cucumber cucumber-java CUCUMBER_JAVA_VERSION test io.cucumber cucumber-junit CUCUMBER_JUNIT_VERSION test junit junit JUNIT_VERSION test ``` If you don’t use Gradle or Maven, refer to the README within the GitHub repository. ### Create a Ruby project ```ruby mkdir mailosaur-ruby-cucumber cd mailosaur-ruby-cucumber ``` ### Install Cucumber and RSpec testing libraries Add the following lines to your Gemfile: ```ruby gem "cucumber" gem "rspec-expectations" ``` ### Create a Python project ```py mkdir mailosaur-python-cucumber cd mailosaur-python-cucumber ``` ### Create a virtual environment ```py 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](https://docs.python.org/3/reference/simple_stmts.html#the-assert-statement). ```py pip install behave ``` ### Create a .NET XUnit project using the XUnit project template ```dotnet 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 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](https://www.npmjs.com/package/mailosaur) library. ```js 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](https://github.com/mailosaur/mailosaur-java). ### 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](https://github.com/mailosaur/mailosaur-dotnet): ``` dotnet add package mailosaur ``` ## Write your first Cucumber test Cucumber tests are BDD (behavior-driven development) tests and have two parts: 1. **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. 2. **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: 1. 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. ```js 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'); }); ``` ```java private String apiKey; private MailosaurClient client; private List 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()); } ``` ```ruby @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 ``` ```py @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' ``` ```dotnet private String apiKey; public MailosaurClient? mailosaurClient; private IList? 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](/docs/automation/cucumber/email-testing) - [SMS testing with Cucumber](/docs/automation/cucumber/sms-testing) - [Email testing](/docs/email-testing) — test password resets, account verification, order confirmations, etc. - [SMS testing](/docs/sms-testing) — test alerts, notifications, and 2FA logins - [2FA app testing](/docs/authenticator) — mimic the functionality of apps like Google Authenticator and Auth0 - [Email deliverability testing](/docs/api)