{"id":44034938,"url":"https://github.com/levz0r/gmail-tester","last_synced_at":"2026-02-07T19:40:38.529Z","repository":{"id":34245148,"uuid":"173452788","full_name":"levz0r/gmail-tester","owner":"levz0r","description":"A simple Node.js Gmail client which checks the inbox for message existence","archived":false,"fork":false,"pushed_at":"2025-12-04T18:13:19.000Z","size":196,"stargazers_count":280,"open_issues_count":4,"forks_count":72,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-12-07T22:02:10.154Z","etag":null,"topics":["automation","cypress-io","emails","gmail-api","gmail-checker","google-api","nodejs"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/levz0r.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["levz0r"]}},"created_at":"2019-03-02T13:42:37.000Z","updated_at":"2025-12-04T18:11:14.000Z","dependencies_parsed_at":"2024-06-18T13:59:05.376Z","dependency_job_id":"bff6e618-0ad9-4f9b-9f30-59f51a3e14a6","html_url":"https://github.com/levz0r/gmail-tester","commit_stats":{"total_commits":116,"total_committers":21,"mean_commits":5.523809523809524,"dds":0.646551724137931,"last_synced_commit":"bff54009b394fba89f53b95084f5bc7dcf973ae5"},"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/levz0r/gmail-tester","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/levz0r%2Fgmail-tester","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/levz0r%2Fgmail-tester/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/levz0r%2Fgmail-tester/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/levz0r%2Fgmail-tester/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/levz0r","download_url":"https://codeload.github.com/levz0r/gmail-tester/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/levz0r%2Fgmail-tester/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29205604,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-07T17:44:10.191Z","status":"ssl_error","status_checked_at":"2026-02-07T17:44:07.936Z","response_time":63,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automation","cypress-io","emails","gmail-api","gmail-checker","google-api","nodejs"],"created_at":"2026-02-07T19:40:37.918Z","updated_at":"2026-02-07T19:40:38.518Z","avatar_url":"https://github.com/levz0r.png","language":"JavaScript","readme":"\u003cp align=\"center\"\u003e\u003cimg alt=\"gmail-tester\" src=\"https://user-images.githubusercontent.com/4564386/122464439-814de100-cfbf-11eb-9227-95a9cc3cc2f1.png\" width=\"80%\"/\u003e\u003c/p\u003e\n\n# gmail-tester\n\n\u003cspan align=\"center\"\u003e\n\n[![npm version](https://badge.fury.io/js/gmail-tester.svg)](https://www.npmjs.com/package/gmail-tester)\n\u003cspan class=\"badge-npmdownloads\"\u003e\u003ca href=\"https://npmjs.org/package/badges\" title=\"View this project on NPM\"\u003e\u003cimg src=\"https://img.shields.io/npm/dt/badges.svg\" alt=\"NPM downloads\" /\u003e\u003c/a\u003e\u003c/span\u003e\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n![GitHub stars](https://img.shields.io/github/stars/levz0r/gmail-tester?style=social)\n\n\u003c/span\u003e\n\nA simple Node.js Gmail client which checks/returns email message(s) straight from any Gmail-powered account (both private and company).\u003cbr/\u003e\nThere are two main functionalities this library provides:\u003cbr\u003e\n\n1.  `check_inbox()`: Polls a mailbox for a given amount of time. At the end of the operation, the desired message is returned (if found).\n2.  `get_messages()`: Can be used to perform various assertions on the email objects (see example [below](https://github.com/levz0r/gmail-tester/blob/master/README.md#using-get_messages-to-assert-email-body-using-cypress)).\n\nP.S, I have written a [story](https://medium.com/@levz0r/how-to-poll-a-gmail-inbox-in-cypress-io-a4286cfdb888) on medium, how using [Cypress](https://cypress.io), we are testing our user registration process at Tastewise.\n\n# Usage\n\n1.  Install using `npm`:\n\n```\nnpm install --save-dev gmail-tester\n```\n\n2.  Save the Google Cloud Platform OAuth2 Authentication file named `credentials.json` inside an accessible directory (see instructions [below](https://github.com/levz0r/gmail-tester/blob/master/README.md#how-to-get-credentialsjson)).\n3.  In terminal, run the following command:\n\n```\nnode \u003cnode_modules\u003e/gmail-tester/init.js \u003cpath-to-credentials.json\u003e \u003cpath-to-token.json\u003e \u003ctarget-email\u003e\n```\n\n`\u003cpath-to-credentials.json\u003e` Is the path to OAuth2 Authentication file.\u003cbr/\u003e\n`\u003cpath-to-token.json\u003e` Is the path to OAuth2 token. If it doesn't exist, the script will create it.\u003cbr/\u003e\nThe script will prompt you to go to google.com to activate a token.\nGo to the given link, and select the account for `\u003ctarget-email\u003e`. Grant permission to view your email messages and settings. At the end of the process you should see the token:\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://i.ibb.co/sJm97H1/copy-token.png\" alt=\"copy-token\" border=\"0\"\u003e\n\u003c/p\u003e\n\nHit the copy button and paste it to `init.js` script.\nThe process should look like this:\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://i.ibb.co/k94bkzB/run-script.png\" alt=\"Run script\"\u003e\n\u003c/p\u003e\n\n# How to get credentials.json?\n\n1.  Follow the instructions to [Create a client ID and client secret](https://developers.google.com/identity/gsi/web/guides/get-google-api-clientid). Make sure to select `Desktop app` for the application type.\n2.  Once done, go to [https://console.cloud.google.com/apis/credentials?project=(project-name)\u0026folder\u0026organizationId](\u003chttps://console.cloud.google.com/apis/credentials?project=(project-name)\u0026folder\u0026organizationId\u003e) and download the OAuth2 credentials file, as shown in the image below. Make sure to replace `(project-name)` with your project name.\n\n    \u003cp align=\"center\"\u003e\n      \u003cimg src=\"https://i.ibb.co/z5FL6YK/get-credentials-json.png\" alt=\"Get credentials.json\"\u003e\n    \u003c/p\u003e\n\n    The `credentials.json` file should look like this:\u003cp align=\"center\"\u003e\n    \u003cimg src=\"https://i.ibb.co/1stgn28/credentials.png\" alt=\"Credentials file\"\u003e\n\n    \u003c/p\u003e\n\n3.  Make sure the [Gmail API is activated](https://console.developers.google.com/apis/library/gmail.googleapis.com) for your account.\n\n4.  **Configure OAuth consent screen:**\n    - Go to [OAuth consent screen](https://console.cloud.google.com/apis/credentials/consent)\n    - If your app is in **\"Testing\"** mode (not published), you must add the Gmail accounts you want to test as **Test users**\n    - Note: Refresh tokens for apps in testing mode expire after 7 days. To avoid this, publish your app (verification not required for personal use)\n\n5.  **Add authorized redirect URI:**\n    - Go to your OAuth 2.0 Client ID settings\n    - Under \"Authorized redirect URIs\", add `http://localhost:32019`\n    - If using a custom port, add `http://localhost:\u003cyour-port\u003e` instead\n\nIf everything is done right, the last output from the script should be:\n\n\u003e [gmail] Found!\n\nCongratulations! `gmail-tester` is ready to use.\n\n⛔️ **Never share or commit `credentials.json` nor `token.json`!!! Whoever has it will have full access to your inbox!**\n\n# API\n\n### `get_messages(credentials, token, options)`\n\n`credentials`: Path to credentials JSON file or JSON Object.\u003cbr\u003e\n`token`: Path to OAuth2 token file or JSON Object.\u003cbr\u003e\n`options`: \u003cbr\u003e\n\n- `from`: String. Filter on the email address of the receiver.\n- `to`: String. Filter on the email address of the sender.\n- `subject`: String. Filter on the subject of the email.\n- `include_body`: boolean. Set to `true` to fetch decoded email bodies.\n- `include_attachments`: boolean. Set to `true` to fetch the base64-encoded email attachments.\n- `before`: Date. Filter messages received _before_ the specified date.\n- `after`: Date. Filter messages received _after_ the specified date.\n- `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\n\n**Returns:**\nAn array of `email` objects with the following fields:\u003cbr\u003e\n\n```javascript\n[\n  {\n    from: \"Human Friendly Name \u003csender@email-address\u003e\",\n    receiver: \"your@email-address\",\n    subject: \"string\",\n    body: {\n      html: \"string\",\n      text: \"string\"\n    }\n  }\n  // ...\n];\n```\n\n_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._\n\n### `check_inbox(credentials, token, options = {})`\n\n`credentials`: Path to credentials JSON file or JSON Object.\u003cbr\u003e\n`token`: Path to OAuth2 token file or JSON Object.\u003cbr\u003e\n`options`: \u003cbr\u003e\n\n- `from`: String. Filter on the email address of the receiver.\n- `to`: String. Filter on the email address of the sender.\n- `subject`: String. Filter on the subject of the email.\n- `include_body`: boolean. Set to `true` to fetch decoded email bodies.\n- `include_attachments`: boolean. Set to `true` to fetch the base64-encoded email attachments.\n- `before`: Date. Filter messages received _before_ the specified date.\n- `after`: Date. Filter messages received _after_ the specified date.\n- `wait_time_sec`: Integer. Interval between inbox checks (in seconds). _Default: 30 seconds_.\n- `max_wait_time_sec`: Integer. Maximum wait time (in seconds). When reached and the email was not found, the script exits. _Default: 60 seconds_.\n- `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\n\n\n**Returns:**\nAn array of `email` objects with the following fields:\u003cbr\u003e\n\n```javascript\n[\n  {\n    from: \"Human Friendly Name \u003csender@email-address\u003e\",\n    receiver: \"your@email-address\",\n    subject: \"string\",\n    body: {\n      html: \"string\",\n      text: \"string\"\n    }\n  }\n  // ...\n];\n```\n\nIn addition, verbose messages will be written to console.\n\n### `refresh_access_token(credentials, token)`\n\n`credentials`: Path to credentials JSON file or JSON Object.\u003cbr\u003e\n`token`: Path to OAuth2 token file or JSON Object.\u003cbr\u003e\n\nRefresh the access token. A new file will overwrite the existing one in `token_path`.\n\n# Example\n\n## Using `check_inbox()` to look for a specific message:\n\n```javascript\nconst path = require(\"path\");\nconst gmail = require(\"gmail-tester\");\nconst email = await gmail.check_inbox(\n  path.resolve(__dirname, \"credentials.json\"), // Assuming credentials.json is in the current directory.\n  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).\n  {\n    subject: \"Activate Your Account\", // We are looking for 'Activate Your Account' in the subject of the message.\n    from: \"no-reply@domain.com\", // We are looking for a sender header which is 'no-reply@domain.com'.\n    to: \"\u003ctarget-email\u003e\", // Which inbox to poll. credentials.json should contain the credentials to it.\n    wait_time_sec: 10, // Poll interval (in seconds).\n    max_wait_time_sec: 30, // Maximum poll time (in seconds), after which we'll giveup.\n    include_body: true\n  }\n);\nif (email) {\n  console.log(\"Email was found!\");\n} else {\n  console.log(\"Email was not found!\");\n}\n```\n\n## Using `get_messages()` to assert email body using Cypress\n\n_[cypress.config.js](https://github.com/levz0r/cypress-gmail-tester/blob/main/cypress.config.js):_\n\n```javascript\nconst { defineConfig } = require(\"cypress\");\nconst gmailTester = require(\"gmail-tester\");\nconst path = require(\"path\");\n\nmodule.exports = defineConfig({\n  e2e: {\n    setupNodeEvents(on, config) {\n      on(\"task\", {\n        \"gmail:get-messages\": async (args) =\u003e {\n          const messages = await gmailTester.get_messages(\n            path.resolve(__dirname, \"credentials.json\"),\n            path.resolve(__dirname, \"token.json\"),\n            args.options\n          );\n          return messages;\n        },\n      });\n    },\n  },\n});\n```\n\n_[spec.cy.js](https://github.com/levz0r/cypress-gmail-tester/blob/main/cypress/e2e/spec.cy.js):_\n\n```javascript\n/// \u003creference types=\"Cypress\" /\u003e\n\ndescribe(\"Email assertion:\", () =\u003e {\n  it(\"Using gmail_tester.get_messages(), look for an email with specific subject and link in email body\", function () {\n    // debugger; //Uncomment for debugger to work...\n    cy.task(\"gmail:get-messages\", {\n      options: {\n        from: \"AccountSupport@ubi.com\",\n        subject: \"Ubisoft Password Change Request\",\n        include_body: true,\n        before: new Date(2019, 8, 24, 12, 31, 13), // Before September 24rd, 2019 12:31:13\n        after: new Date(2019, 7, 23), // After August 23, 2019\n      },\n    }).then((emails) =\u003e {\n      assert.isAtLeast(\n        emails.length,\n        1,\n        \"Expected to find at least one email, but none were found!\"\n      );\n      const body = emails[0].body.html;\n      assert.isTrue(\n        body.indexOf(\n          \"https://account-uplay.ubi.com/en-GB/action/change-password?genomeid=\"\n        ) \u003e= 0,\n        \"Found reset link!\"\n      );\n    });\n  });\n});\n```\n\n# Contributors\n\n\u003ca href=\"https://github.com/levz0r/gmail-tester/graphs/contributors\"\u003e\n  \u003cimg src=\"https://contributors-img.web.app/image?repo=levz0r/gmail-tester\" /\u003e\n\u003c/a\u003e\n\nPlease feel free to contribute to this project.\n\n# Credits\n\n- Built using [googleapis](https://github.com/googleapis/googleapis).\n","funding_links":["https://github.com/sponsors/levz0r"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flevz0r%2Fgmail-tester","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flevz0r%2Fgmail-tester","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flevz0r%2Fgmail-tester/lists"}