Skip to main content

Gmail Service

wdio-gmail-service is a 3rd party package, for more information please see GitHub | npm

A WebdriverIO plugin to fetch e-mails from Google Mail using Gmail Tester.


The easiest way is to keep wdio-gmail-service as a devDependency in your package.json.

"devDependencies": {
"wdio-gmail-service": "^1.0.0"

You can simply do it by:

npm install wdio-gmail-service --save-dev


Gmail Authentication​

You'll need to follow the instructions at Gmail Tester to create the credentials.json (the OAuth2 Authentication file) and token.json (the OAuth2 token).


Add the service by adding gmail to the service list, e.g.:

// wdio.conf.js
import path from 'path'

export const config = {
// ...
services: [['gmail', {
credentialsJsonPath: path.join(process.cwd(), './credentials.json'),
tokenJsonPath: join(process.cwd(), './token.json'),
intervalSec: 10,
timeoutSec: 60
// ...

Service Options​


Absolute path to a credentials JSON file.

Type: string

Required: true


Absolute path to a token JSON file.

Type: string

Required: true


The interval between Gmail inbox checks.

Type: number

Default: 10

Required: false


The maximum time to wait for finding the email for the given filters.

Type: number

Default: 60

Required: false

Writing tests​

In your WebdriverIO test, you can now check if an email was received.

describe('Example', () => {
it('Should check email', () => {
// perform some actions that will send an email to setup gmail account
const emails = await browser.checkInbox({ from: '', subject: 'Ubisoft Password Change Request' });

checkInbox parameters​

The command parameters require at least one of from, to, or subject:

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.
includeBody: boolean. Set to true to fetch decoded email bodies.
includeAttachments: 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

For more information on WebdriverIO see the homepage.