Cypress Guide ​

If you haven't already, see Getting Started to get setup and find your API key. The following examples will assume you have already received your API key and created a namespace.

Examples ​

• Password Reset w/ Cypress (Github, Blog)
• Email Verification w/ Cypress (Github, Blog)

Install Mailisk Plugin ​

Mailisk provides an official library with a custom set of commands for testing email in Cypress. These commands wrap the API endpoints.

Install cypress-mailisk ​

npm install --save-dev cypress-mailisk

After installing the package add the following in your project's cypress/support/e2e.js:

import "cypress-mailisk";

Setup API Key ​

To be able to use the API you will need to add your API key to cypress.config.js:

module.exports = defineConfig({
  env: {
    MAILISK_API_KEY: "YOUR_API_KEY",
  },
});

Usage ​

The cypress-mailisk plugin provides additional commands which can be accessed on the cypress object, for example cy.mailiskSearchInbox(). These commands extend the Chainable object which allows you to use the then() method to chain commands.

cy.mailiskSearchInbox ​

This is the main command to interact with Mailisk, it wraps the Search Inbox endpoint.

cy.mailiskSearchInbox("yournamespace", { to_addr_prefix: "test.user@" }).then((response) => {
  const emails = response.data;
  // ...
});

This Cypress command does a few extra things out of the box compared to calling the raw API directly:

• By default it uses the wait flag. This means the call won't return until at least one email is received. Disabling this flag via wait: false can cause it to return an empty response immediately.
• The request timeout is adjustable by passing timeout in the request options. By default it uses a timeout of 5 minutes.
• By default from_timestamp is set to current timestamp - 5 seconds. This ensures that only new emails are returned. Without this, older emails would also be returned, potentially disrupting you if you were waiting for a specific email. This can be overriden by passing the from_timestamp parameter (from_timestamp: 0 will disable filtering by email age).

// timeout of 5 minute
cy.mailiskSearchInbox(namespace);
// timeout of 1 minute
cy.mailiskSearchInbox(namespace, {}, { timeout: 1000 * 60 });
// returns immediately, even if the result would be empty
cy.mailiskSearchInbox(namespace, { wait: false });

The implementation of these features is explained in the NodeJS Guide.

Example ​

This example demonstrates going to a password reset page, requesting a new password, receiving reset code link via email and finally setting the new password.

describe("Test password reset", () => {
  let resetLink;
  const namespace = "yournamespace";
  const testEmailAddr = `test.test@${namespace}.mailisk.net`;

  it("Starts a password reset", () => {
    cy.visit("https://example.com/password_reset");
    cy.get("#email_field").type(testEmailAddr);
  });

  it("Gets a password reset email", () => {
    cy.mailiskSearchInbox(namespace, {
      to_addr_prefix: testEmailAddr,
    }).then((response) => {
      expect(response.data).to.not.be.empty;
      const email = response.data[0];
      expect(email.subject).to.equal("Please reset your password");
      resetLink = email.text.match(/.(https:\/\/example.com\/password_reset\/.*)>\n*/)[1];
      expect(resetLink).to.not.be.undefined;
    });
  });

  it("Goes to password reset link", () => {
    cy.visit(resetLink);
    cy.title().should("contain", "Change your password");
    cy.get("#password").type("MyNewPassword");
    cy.get("#password_confirmation").type("MyNewPassword");
    cy.get("form").submit();
  });
});