Norvell, Please Merge

    gmail-tester
    TypeScript icon, indicating that this package has built-in type declarations

    1.3.5 • Public • Published

    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, token, options)

    credentials: Path to credentials JSON file or JSON Object.
    token: Path to OAuth2 token file or JSON Object.
    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.
    • include_attachments: boolean. Set to true to fetch the base64-encoded email attachments.
    • 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 <sender@email-address>",
        receiver: "your@email-address",
        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, token, options = {})

    credentials: Path to credentials JSON file or JSON Object.
    token: Path to OAuth2 token file or JSON Object.
    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.
    • include_attachments: boolean. Set to true to fetch the base64-encoded email attachments.
    • 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 <sender@email-address>",
        receiver: "your@email-address",
        subject: "string",
        body: {
          html: "string",
          text: "string"
        }
      }
      // ...
    ];

    In addition, verbose messages will be written to console.

    refresh_access_token(credentials_path, token_path)

    credentials_path: 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: "no-reply@domain.com", // We are looking for a sender header which is 'no-reply@domain.com'.
        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: "AccountSupport@ubi.com",
            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

    Install

    npm i gmail-tester

    DownloadsWeekly Downloads

    36,531

    Version

    1.3.5

    License

    MIT

    Unpacked Size

    120 kB

    Total Files

    24

    Last publish

    Collaborators

    • levz0r