npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

nightwatch-mailtrap

v1.0.6

Published

Nightwatch plugin adding custom assertions for e2e email test scenarios with mailtrap.io

Downloads

17

Readme

nightwatch-mailtrap

Nightwatch.js 🦉 plugin adding custom assertions for covering email functionality in e2e test scenarios with mailtrap.io 📨

Node.js CI

Purpose

In your end-to-end (e2e) Nightwatch browser test automation you may encounter scenarios where you need to ensure an email is sent out by the system under test to the correct recipient and verify its contents. Other scenarios, like user registration, may require following a link received in an email. This is hard to do programmatically with most mail services in a CI/CD system, but Mailtrap provides an email sandbox service with API that let's you programmatically receive and read email messages to their virtual inboxes.

The nightwatch-mailtrap plugin will allow one to programmatically

  • Assert inbox message count (optionally filtered by subject, recipient name, or recipient address)
  • Assert partial text match of email message body
  • Assert partial text match of email subject
  • Extract the first link from an email message body

Examples

module.exports = {
  'should get messages': async (browser) => {
    const inboxId = browser.globals.mailtrap.mailboxId;

    // Ability to grab the link URL out of the message body
    let url = await browser.getLinkFromEmail(inboxId);
    // Example navigating the browser to the URL from the message body link
    browser.url(url);

    // Test inbox contains 5 emails
    browser.assert.expectedInboxCount(5, inboxId);

    // Test inbox has 1 email if subject, to_email, or to_name matches "hello"
    browser.assert.expectedInboxCount(1, inboxId, 'hello');

    // Test that the first email message containing Welcome has "Bienvenue à Nightwatch" in the message body
    browser.assert.emailBodyContains(
      'Bienvenue à Nightwatch',
      inboxId,
      'Welcome'
    );

    // Assert the text of the first email matching 'latest tests' matches 'The latest tests delivered...'
    browser.assert.emailSubjectContains(
      'The latest tests delivered straight to your inbox',
      inboxId,
      'latest tests' // optional search filter
    );
  },

    browser.end();
  },
};

Installation (for Nightwatch >= v2.0)

  1. In an existing working Nightwatch.js test project open nightwatch.conf.js
  2. Locate or add the plugins: section and append nightwatch-mailtrap to the array.
// nightwatch.conf.js
module.exports = {
  ...
  src_folders: ['test'],

  plugins: ['nightwatch-mailtrap'],
  ...
}
  1. Run npm install nightwatch-mailtrap --save to ensure the library is added to your project and can be used as a plugin.

Alternate Installation (Older method not using plugin pattern)

  1. Run npm install nightwatch-mailtrap --save
  2. Specify the paths for the custom commands and custom assertions in the nightwatch.conf.js file
//nightwatch.conf.js
module.exports = {
...
  custom_commands_path: './node_modules/nightwatch-mailtrap/nightwatch/commands',
  custom_assertions_path: './node_modules/nightwatch-mailtrap/nightwatch/assertions',
...
}

Configuration

nightwatch-mailtrap extends Nightwatch commands and assertions to work with an existing Mailtrap.io account. For that to work you need to provide your Mailtrap API Token and mailbox id (mailbox id is optional and can be provided at the test level). Those values are read from the nightwatch.conf.js globals section.

//nightwatch.conf.js
test_settings: {
    default: {
      launch_url: 'http://localhost',
      desiredCapabilities: {
        browserName: 'chrome',
      },

      globals: {
        mailtrap: {
          apiToken: '${MAILTRAP_API_TOKEN}',
          mailboxId: '${MAILTRAP_MAILBOX_ID}',
        },
      },
    },

It's recommended you use environment variables as shown instead of hardcoding these values

Usage

Once the configuration changes are made the commands and assertions will be made available to the Nightwatch API (browser object) in your test cases.

browser.getLinkFromEmail(mailboxId: string, searchText: string?) => string

This will return the href value of the first link found in the most recent email in the specified mailbox id.

const url = await browser.getLinkFromEmail('12345', 'activate your account');
browser.navigate(url);

browser.assert.emailBodyContains(expectedText: string, mailboxId: string, searchText: string?) => NightwatchAPI

This is a custom assertion that will return pass or fail if a partial match is found of your expectedText in the most recent email, filtered by the searchText parameter if provided.

browser.assert.emailBodyContains(
  'reaching out to you',
  browser.globals.mailtrap.mailboxId,
  'car warranty'
);

browser.assert.expectedInboxCount(expectedCount: number, mailboxId: string, searchText: string?) => NightwatchAPI

browser.assert.expectedInboxCount(
  2,
  browser.globals.mailtrap.mailboxId,
  'Jane'
);

See full article Automated Email Testing with Nightwatch and MailTrap for more information.