UNPKG

cypress-maildev

Version:

An easy-to-use cypress bunch of commands to use Maildev API for tests messages reception !

196 lines (129 loc) 4.64 kB
# Cypress Maildev Cypress Maildev is a bunch of Cypress commands in order to test your messages (SMS and Emails) by using [Maildev REST API](https://github.com/maildev/maildev/blob/master/docs/rest.md). ![CI](https://github.com/Clebiez/cypress-maildev/workflows/CI/badge.svg?branch=main) [![npm version](https://badge.fury.io/js/cypress-maildev.svg)](https://badge.fury.io/js/cypress-maildev) ## Installation ```bash npm install cypress-maildev --save-dev yarn add cypress-maildev --dev ``` ## Usage ### 1. Register the plugin : ```JavaScript // cypress/support/e2e.js require('cypress-maildev'); ``` ### 2. Specify your maildev address > By default, Maildev API is started at the `http://localhost:1080`. If you are using default maildev instance, you have nothing to do! You can also use env vars in your `cypress.config.js` as below : ```javascript const { defineConfig } = require("cypress"); module.exports = defineConfig({ env: { MAILDEV_PROTOCOL: "http", MAILDEV_HOST: "localhost", MAILDEV_SMTP_PORT: "1025", MAILDEV_API_PORT: "1080", }, }); ``` For example, by using like this project a docker compose with **cypress** and **maildev** containers, you have to configure your `cypress.config.js` like this: ```javascript const { defineConfig } = require("cypress"); module.exports = defineConfig({ env: { MAILDEV_PROTOCOL: "http", MAILDEV_HOST: "127.0.0.1", MAILDEV_SMTP_PORT: "1025", MAILDEV_API_PORT: "1080", }, }); ``` > Check the [Maildev REST API documentation](https://github.com/maildev/maildev/blob/master/docs/rest.md) for what you can expect in responses. ## Commands ### Usage > All of theses commands use directly `cy.request()` which return a Cypress Promise like. Check [the doc](https://docs.cypress.io/api/commands/request.html) ! Using one of this commands must be like this example : ```JavaScript cy.maildevGetLastMessage().then((email) => { expect(email.subject).to.equal("I'm the last email sent !"); }); ``` For more examples you can check directly the [test file](./cypress/integration/maildev.spec.js). ### Documentation Get all messages received in the Maildev instance. ```JavaScript cy.maildevGetAllMessages() ``` --- Get the last message received. ```JavaScript cy.maildevGetLastMessage() ``` --- Each messages got an internal ID. If you know it, you can find it directly. ```JavaScript cy.maildevGetMessageById(id: String) ``` --- You can also directly access to the HTML of your email by calling. ```JavaScript cy.maildevVisitMessageById(id: String) ``` And you can use Cypress promise to manipulate or assert the DOM of your email : ```JavaScript cy.maildevVisitMessageById(id: String); cy.get('body h1').should('have.text', 'Email incoming !'); cy.get('body a').should('exist').and('have.text', 'click on this link'); ``` > You must have to specify `"chromeWebSecurity": false,` because you will access to another domain than your app. > Unfortunately, Cypress can't deactivate the cross-origin requests for Firefox actually. --- Get all messages and find one by containing a specific subject. It's a simple string detection case-sensitive. ```JavaScript cy.maildevGetMessageBySubject(subject: String) ``` --- Get all messages and find the last containing a sent to address. Use a strict string comparison. ```JavaScript cy.maildevGetMessageBySentTo() ``` --- Delete a message by giving the ID. In can be useful if you to only keep message that you haven't read yet. ```JavaScript cy.maildevDeleteMessageById() ``` --- Delete all message in order to flush your mailbox ! ```JavaScript cy.maildevDeleteAllMessages() ``` --- Get an OTP code from a string. It can be used **outside of maildev box** because it doesn't use maildev API but generally OTP code are sent by messages. This function find in a string a specific amount of digits (default 6). ```JavaScript cy.maildevGetOTPCode(string, digits = 6) ``` Or use with another maildev command ```JavaScript cy.maildevGetMessageBySubject("Your code").then(message => { cy.maildevGetOTPCode(message.text).then(code => { // Do something with the code }); }); ``` --- Simple test command that return true if Maildev is opened. ```JavaScript cy.maildevHealthcheck() ``` ## Contributing Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change. - Clone the repo - Install dependencies: `make install` - Start maildev: `make start` Please make sure to update tests as appropriate and run `make test` command ## License [MIT](https://choosealicense.com/licenses/mit/)