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.

1. Install using npm:

npm install --save-dev gmail-tester 

2. Save the Google Cloud Platform OAuth2 Authentication file named credentials.json inside an accessible directory (see instructions below).
3. 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:

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

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.

   

   The credentials.json file should look like this:

   

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

4. Configure OAuth consent screen:

   • Go to OAuth consent screen
   • If your app is in "Testing" mode (not published), you must add the Gmail accounts you want to test as Test users
   • Note: Refresh tokens for apps in testing mode expire after 7 days. To avoid this, publish your app (verification not required for personal use)

5. Add authorized redirect URI:

   • Go to your OAuth 2.0 Client ID settings
   • Under "Authorized redirect URIs", add http://localhost:32019
   • If using a custom port, add http://localhost:<your-port> instead

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!

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 before the specified date.
• after: Date. Filter messages received after 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.

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 before the specified date.
• after: Date. Filter messages received after 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.

credentials: Path to credentials JSON file or JSON Object.
token: Path to OAuth2 token file or JSON Object.

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

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!"); }

cypress.config.js:

const { defineConfig } = require("cypress"); const gmailTester = require("gmail-tester"); const path = require("path"); module.exports = defineConfig({ e2e: { setupNodeEvents(on, config) { on("task", { "gmail:get-messages": async (args) => { const messages = await gmailTester.get_messages( path.resolve(__dirname, "credentials.json"), path.resolve(__dirname, "token.json"), args.options ); return messages; }, }); }, }, });

spec.cy.js:

/// <reference types="Cypress" /> describe("Email assertion:", () => { it("Using gmail_tester.get_messages(), 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!" ); }); }); });

 

Please feel free to contribute to this project.

• Built using googleapis.