Awesome Open Source
Awesome Open Source

gmail-tester

gmail-tester

npm version NPM downloads License: MIT GitHub stars

A simple Node.js Gmail client which checks/returns email message(s) straight from any Gmail-powered account (both private and company).
There are two main functionalities this library provides:

  1. check_inbox(): Polls a mailbox for a given amount of time. At the end of the operation, the desired message is returned (if found).
  2. get_messages(): Can be used to perform various assertions on the email objects (see example below).

P.S, I have written a story on medium, how using Cypress, we are testing our user registration process at Tastewise.

Usage

  1. Install using npm:
npm install --save-dev gmail-tester
  1. Save the Google Cloud Platform OAuth2 Authentication file named credentials.json inside an accessible directory (see instructions below).
  2. In terminal, run the following command:
node <node_modules>/gmail-tester/init.js <path-to-credentials.json> <path-to-token.json> <target-email>

<path-to-credentials.json> Is the path to OAuth2 Authentication file.
<path-to-token.json> Is the path to OAuth2 token. If it doesn't exist, the script will create it.
The script will prompt you to go to google.com to activate a token. Go to the given link, and select the account for <target-email>. Grant permission to view your email messages and settings. At the end of the process you should see the token:

copy-token

Hit the copy button and paste it to init.js script. The process should look like this:

Run script

How to get credentials.json?

  1. Follow the instructions to Create a client ID and client secret. Make sure to select Desktop app for the application type.

  2. Once done, go to https://console.cloud.google.com/apis/credentials?project=(project-name)&folder&organizationId and download the OAuth2 credentials file, as shown in the image below. Make sure to replace (project-name) with your project name.

    Get credentials.json

    The credentials.json file should look like this:

    Credentials file

  3. Make sure the Gmail API is activated for your account.

If everything is done right, the last output from the script should be:

[gmail] Found!

Congratulations! gmail-tester is ready to use.

⛔️ Never share or commit credentials.json nor token.json!!! Whoever has it will have full access to your inbox!

API

get_messages(credentials_json, token_path, options)

credentials_json: Path to credentials JSON file.
token_path: Path to OAuth2 token file.
options:

  • from: String. Filter on the email address of the receiver.
  • to: String. Filter on the email address of the sender.
  • subject: String. Filter on the subject of the email.
  • include_body: boolean. Set to true to fetch decoded email bodies.
  • before: Date. Filter messages received after the specified date.
  • after: Date. Filter messages received before the specified date.
  • label: String. The default label is 'INBOX', but can be changed to 'SPAM', 'TRASH' or a custom label. For a full list of built-in labels, see https://developers.google.com/gmail/api/guides/labels?hl=en

Returns: An array of email objects with the following fields:

[
  {
    from: "Human Friendly Name <[email protected]>",
    receiver: "[email protected]",
    subject: "string",
    body: {
      html: "string",
      text: "string"
    }
  }
  // ...
];

Some senders will send you text/html content, the others will send you plain/text, and some will send you both. Make sure you are looking for the content in the right body field.

check_inbox(credentials_json, token_path, options = {})

credentials_json: Path to credentials JSON file.
token_path: Path to OAuth2 token file.
options:

  • from: String. Filter on the email address of the receiver.
  • to: String. Filter on the email address of the sender.
  • subject: String. Filter on the subject of the email.
  • include_body: boolean. Set to true to fetch decoded email bodies.
  • before: Date. Filter messages received after the specified date.
  • after: Date. Filter messages received before the specified date.
  • wait_time_sec: Integer. Interval between inbox checks (in seconds). Default: 30 seconds.
  • max_wait_time_sec: Integer. Maximum wait time (in seconds). When reached and the email was not found, the script exits. Default: 60 seconds.
  • label: String. The default label is 'INBOX', but can be changed to 'SPAM', 'TRASH' or a custom label. For a full list of built-in labels, see https://developers.google.com/gmail/api/guides/labels?hl=en

Returns: An array of email objects with the following fields:

[
  {
    from: "Human Friendly Name <[email protected]>",
    receiver: "[email protected]",
    subject: "string",
    body: {
      html: "string",
      text: "string"
    }
  }
  // ...
];

In addition, verbose messages will be written to console.

refresh_access_token(credentials_json, token_path)

credentials_json: Path to credentials JSON file.
token_path: Path to existing OAuth2 token file.

Refresh the access token. A new file will overwrite the existing one in token_path.

Example

Using check_inbox() to look for a specific message:

const path = require("path");
const gmail = require("gmail-tester");
const email = await gmail.check_inbox(
  path.resolve(__dirname, "credentials.json"), // Assuming credentials.json is in the current directory.
  path.resolve(__dirname, "gmail_token.json"), // Look for gmail_token.json in the current directory (if it doesn't exists, it will be created by the script).
  {
    subject: "Activate Your Account", // We are looking for 'Activate Your Account' in the subject of the message.
    from: "[email protected]", // We are looking for a sender header which is '[email protected]'.
    to: "<target-email>", // Which inbox to poll. credentials.json should contain the credentials to it.
    wait_time_sec: 10, // Poll interval (in seconds).
    max_wait_time_sec: 30, // Maximum poll time (in seconds), after which we'll giveup.
    include_body: true
  }
);
if (email) {
  console.log("Email was found!");
} else {
  console.log("Email was not found!");
}

Using get_messages() to assert email body using Cypress

examples\cypress\plugins\index.js:

/// <reference types="Cypress" />
const debug = require("debug");
const path = require("path");
const gmail_tester = require("../../../../../gmail-tester");

module.exports = (on, config) => {
  on("before:browser:launch", (browser = {}, args) => {
    if (browser.name === "chrome") {
      args.push("--remote-debugging-port=9221");
      return args;
    }
  });
  on("task", {
    "gmail:get-messages": async args => {
      const messages = await gmail_tester.get_messages(
        path.resolve(__dirname, "credentials.json"),
        path.resolve(__dirname, "token.json"),
        args.options
      );
      return messages;
    }
  });
};

examples\cypress\integration\gmail.spec.js:

/// <reference types="Cypress" />

describe("Email assertion:", () => {
  it("Look for an email with specific subject and link in email body", function () {
    // debugger; //Uncomment for debugger to work...
    cy.task("gmail:get-messages", {
      options: {
        from: "[email protected]",
        subject: "Ubisoft Password Change Request",
        include_body: true,
        before: new Date(2019, 8, 24, 12, 31, 13), // Before September 24rd, 2019 12:31:13
        after: new Date(2019, 7, 23) // After August 23, 2019
      }
    }).then(emails => {
      assert.isAtLeast(
        emails.length,
        1,
        "Expected to find at least one email, but none were found!"
      );
      const body = emails[0].body.html;
      assert.isTrue(
        body.indexOf(
          "https://account-uplay.ubi.com/en-GB/action/change-password?genomeid="
        ) >= 0,
        "Found reset link!"
      );
    });
  });
});

Contributors

 

Please feel free to contribute to this project.

Credits


Get A Weekly Email With Trending Projects For These Topics
No Spam. Unsubscribe easily at any time.
Javascript (1,538,296
Nodejs (53,495
Automation (6,618
Email (2,545
Google Api (643
Cypress Io (171
Related Projects