Cypress is a powerful end-to-end browser testing framework for Javascript and Typescript. With the official MailSlurp Cypress plugin you can create real email addresses in code. Send and receive email in Cypress to test user authentication, password reset, MFA, newsletters and more.
Quick links
- Example code repository
- CypressJS Plugin documentation
- CypressJS Plugin source
- Tutorial using mailslurp-client
- Example repository using mailslurp-client
In this example we will use MailSlurp and Cypress JS to test the sign-up process of a dummy app hosted at playground.mailslurp.com.
Example application
Our example app is a simple React SPA. It allows a user to sign up with an email address and password. After sign up an email verification code is sent to the user's email address. The code must be read and entered into the app to confirm the user. Once confirmed a user may login and see a picture of a happy dog.
Install Cypress and MailSlurp plugin
To use MailSlurp with Cypress first install the MailSlurp Cypress Plugin and CypressJS.
If you wish to write tests using the standard MailSlurp client install instead.
Initialize Cypress directories
To generate test directories in your project run:
A tree of directories will be created under a . Edit yours to look like this:
Import the MailSlurp plugin
Include the MailSlurp plugin in your file.
Your should look something like this:
Typescript support
If you wish to use Typescript run:
Then use reference comments in your tests to allow for MailSlurp type hints:
Or define the type yourself like so:
Setup API Key
The MailSlurp plugin expects a MailSlurp API Key. Create a MailSlurp account to get a free API Key.
Then set the environment variable or use the
file
property:
Environment variable
You can configure the api key in Mac/Linux environments using the environment variable.
For Windows environments:
Cypress env property
Alternatively you can setup the env using the cypress config file:
Configure timeouts
For MailSlurp to send and receive emails set timeout values in :
Using the MailSlurp command
The MailSlurp Cypress plugin adds the command to the global
object:
This returns a promise that can be accessed using Cypress commands. The MailSlurp client passed to the
methods is an instance of the standard mailslurp client. It has many methods for creating inboxes, sending emails, and receiving email content. Most methods are asynchronous.
Chaining then commands
MailSlurp methods are async so you can chain commands and access the results using Cypress methods.
Sharing variables across tests
You can also store variables like inboxes and emails between tests using Cypress and
methods.
When accessing aliased variables that have been wrapped you must use function notation (dynamic scope) not arrow syntax (lexical scope) so that refers to a Cypress context.
- Good:
- Bad:
Access the stored variables using inside a function.
Full example
Let's put the Cypress MailSlurp plugin to work on a real example. The demo application at playground.mailslurp.com allows a user to sign up with an email address and password. They then receive a confirmation code by email that must be entered to confirm the account. Next the user can sign in and see a happy dog. We will next each stage next.
Setup test
Create a test file at . (We will use Typescript but you can use Javascript if you prefer.)
Create an email address before test run
We want to create a new email address for each test run. Use a block inside the describe function to do so:
Notice how we wrap the inbox and
as separate aliases. We will use those in other test methods to sign up a user and receive a confirmation code.
Navigate to test application
Next we can load the playground application and assert the page title is shown.
Sign up a user
Now we fill out the sign-up form using our created email address and a test password. Notice how we access the wrapped variables using .
Cypress submits the form and the playground app will send our user a confirmation email.
In the next step we will wait for the email to be received and then extract the code from the body.
Receive emails with Cypress
MailSlurp inboxes have real email addresses. We can use the methods to receive emails for a given inbox. In this test we wait for an email to arrive at the inbox we created and then use a regular expression to extract the confirmation code.
Lastly we submit the code to the confirmation form.
Sign in with confirmed account
Now that our user has confirmed their account we can sign in and see a welcome message.
The code to sign in and test the welcome message looks like this:
Then we can see authorized welcome screen:
If successful we should see a welcoming dog.
Building your own commands
If you want to create your own Cypress commands that use MailSlurp then install the default MailSlurp client:
Then add your own commands to :
For instance you can create your own or
commands:
Now in Cypress tests we can do the following:
Or
Conclusion and next steps
Cypress is a great way to test applications end to end. You can use the Cypress MailSlurp plugin to create real email addresses during tests. Use it to send and receive emails and attachments in Cypress while testing user sign-up, login, and more. For more help see the MailSlurp examples pages or the developer documentation.
As always, example code is available on GitHub.