Skip to content

GrandadEvans/cypress-mailpit

 
 

Repository files navigation

cypress-mailpit

Work in progress

Point to note

  • Mailpit works on port 8025, not 8090
  • Mailpit will also need installing on you system (I've yet to look to see if I can simple include it as a dependency)

Current State

  • mpGetMailsBySubject() - working
  • mpFirst() - working
  • mpGetHtml() - working
  • mpGetText() - working
  • mpDeleteAll() - working

Changelog

v0.0.6

  • Simply previous refactor

v0.0.5

  • Simple refactor of mpMessageSummary to remove duplicate code

v0.0.4

  • Set a default for the Mailpit UI

v0.0.3

  • Added mpGetText() to get the text version of a message
  • Increased spacing to 4
  • Extensive reformatting ready for conversion to TS
  • Configured a few .eslint rules for my preference
  • Changed Cypress version requirement to 12+, as I want to use Cypress.command.addQuery
  • Still not written any tests!

v0.0.2

  • Added mpGetHtml to get the Html version of a message

v0.0.1

  • Initial fork of the project, so that I can get Cypress to run with Mailpit, as MailHog hasn't been touched recently.
  • Simple rename from 'mh...' to 'mp...' method names'

Plans

  • Create a repository so that people can use any mail program they like (MailHog, Mailpit etc), and just switch out the binding
  • Write proxy functions so that others can simple install it and use it as a drop-in replacement for cypress-mailhog
  • Continue converting functions to mailpit
  • Write tests (currently I'm writing it and using my dev project for the tests)
  • ...

Original readme, with a few alterations

A collection of useful Cypress commands for Mailpit 🐗.

This package supports TypeScript out of the box.

Setup

Install this package:

# bun
bun add --dev cypress-mailpit

# npm
npm install --save-dev cypress-mailpit

# pnpm
pnpm add -D cypress-mail

# yarn
yarn add --dev cypress-mailpit

Include this package into your Cypress command file:

// cypress/support/commands
import 'cypress-mailpit';

Add the base url of your Mailpit installation in the e2e block of your Cypress config file:

export default defineConfig({
  projectId: "****",
  env: {
    mailpitUrl: "http://localhost:8025/",
  },
});

If your Mailpit instance uses authentication, add mailpitAuth to your Cypress env config:

{
  ...
  "mailpitAuth": {"user": "mailpit username", "pass": "mailpit password"}
}

or add mailpitUsername and mailpitPassword in Cypress env config

{
  ...
  "mailpitUsername": "mailpit username",
  "mailpitPassword": "mailpit password"
}

Commands

Mail Collection

mpGetAllMails( limit=50, options={timeout=defaultCommandTimeout} )

Yields an array of all the mails stored in Mailpit. This retries automatically until mails are found (or until timeout is reached).

cy
  .mpGetAllMails()
  .should('have.length', 1);

mpGetMailsBySubject( subject, limit=50, options={timeout=defaultCommandTimeout} )

Yields an array of all mails with given subject. This retries automatically until mails are found (or until timeout is reached).

cy
  .mpGetMailsBySubject('My Subject')
  .should('have.length', 1);

mpGetMailsBySender( from, limit=50, options={timeout=defaultCommandTimeout} )

Yields an array of all mails with given sender. This retries automatically until mails are found (or until timeout is reached).

cy
  .mpGetMailsBySender('sender@example.com')
  .should('have.length', 1);

mpGetMailsByRecipient( recipient, limit=50 )

Yields an array of all mails with given recipient.

cy
  .mpGetMailsByRecipient('recipient@example.com')
  .should('have.length', 1);

mpFirst()

Yields the first mail of the loaded selection.

cy
  .mpGetAllMails()
  .should('have.length', 1)
  .mpFirst();

mpDeleteAll()

Deletes all stored mails from Mailpit.

cy.mpDeleteAll();

Collection Filtering 🪮

Note: the below described filter functions can be chained together to build complex filters. They are currently not automatically retrying. So make sure to either wait a certain time before fetching your mails or to implement you own re-try logic.

mpFilterBySubject( subject )

Filters the current mails in context by subject and returns the filtered mail list.

cy
  .mpGetMailsBySender('sender@example.com')
  .mpFilterBySubject('My Subject')
  .should('have.length', 1);

mpFilterByRecipient( recipient )

Filters the current mails in context by recipient and returns the filtered mail list.

cy
  .mpGetMailsBySender('sender@example.com')
  .mpFilterByRecipient('recipient@example.com')
  .should('have.length', 1);

mpFilterBySender( sender )

Filters the current mails in context by sender and returns the filtered mail list.

cy
  .mpGetMailsByRecipient('recipient@example.com')
  .mpFilterBySender('sender@example.com')
  .should('have.length', 1);

Chaining Filters

Filters can be infinitely chained together.

cy
  .mpGetAllMails()
  .mpFilterBySubject('My Subject')
  .mpFilterByRecipient('recipient@example.com')
  .mpFilterBySender('sender@example.com')
  .should('have.length', 1);

Handling a Single Mail ✉️

mpGetSubject()

Yields the subject of the current mail.

cy
  .mpGetAllMails()
  .should('have.length', 1)
  .mpFirst()
  .mpGetSubject()
  .should('eq', 'My Mails Subject');

mpGetBody()

Yields the body of the current mail.

cy
  .mpGetAllMails()
  .should('have.length', 1)
  .mpFirst()
  .mpGetBody()
  .should('contain', 'Part of the Message Body');

mpGetSender()

Yields the sender of the current mail.

cy
  .mpGetAllMails()
  .should('have.length', 1)
  .mpFirst()
  .mpGetSender()
  .should('eq', 'sender@example.com');

mpGetRecipients()

Yields the recipient of the current mail.

cy
  .mpGetAllMails()
  .should('have.length', 1)
  .mpFirst()
  .mpGetRecipients()
  .should('contain', 'recipient@example.com');

mpGetAttachments()

Yields the list of all file names of the attachments of the current mail.

cy
  .mpGetAllMails()
  .should('have.length', 1)
  .mpFirst()
  .mpGetAttachments()
  .should('have.length', 2)
  .should('include', 'sample.pdf');

Asserting the Mail Collection 🔍

mpHasMailWithSubject( subject )

Asserts if there is a mail with given subject.

cy.mpHasMailWithSubject('My Subject');

mpHasMailFrom( from )

Asserts if there is a mail from given sender.

cy.mpHasMailFrom('sender@example.com');

mpHasMailTo( recipient )

Asserts if there is a mail to given recipient (looks for "To", "CC" and "BCC").

cy.mpHasMailTo('recipient@example.com');

Helper Functions ⚙️

mpWaitForMails( moreMailsThen = 0 )

Waits until more then <moreMailsThen> mails are available on Mailpit. This is especially useful when using the mpFilterBy<X> functions, since they do not support automatic retrying.

// this waits until there are at least 10 mails on Mailpit
cy
  .mpWaitForMails(9)
  .mpGetAllMails()
  .mpFilterBySender("sender-10@example.com")
  .should("have.length", 1);

Package Development

Start Local Test Server

Navigate into the test-server directory.

cd ./test-server/

Install dependencies.

composer install
yarn # or npm install

Start docker server.

docker-compose up

Open the test page in your browser: http://localhost:3000/cypress-mp-tests/

Open Mailpit in your browser: http://localhost:8025/

Open the Cypress testclient.

yarn cypress:open

About

Cypress Commands for Mailpit

Topics

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages

  • TypeScript 36.4%
  • JavaScript 35.1%
  • HTML 15.0%
  • PHP 13.0%
  • Dockerfile 0.5%