Registry / testing / wdio-gmail-service

wdio-gmail-service

library2.1.0jsnpmunverified

WebdriverIO plugin for fetching emails from Gmail using the Gmail API. Integrates with WebdriverIO tests to poll inbox for emails matching filters (from, to, subject, date range, label). Uses gmail-tester for OAuth2 authentication. Version 2.1.0 supports Node >=18, TypeScript types included. Key differentiator: seamless integration with WebdriverIO's browser object via custom command 'checkInbox'.

testing

npm install wdio-gmail-service

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · WDIO-GMAIL-SERVICE

wdio-gmail-service

testingjavascriptv2.1.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

GmailServiceConfig

✓ import type { GmailServiceConfig } from 'wdio-gmail-service'

✗ import { GmailServiceConfig } from 'wdio-gmail-service'

GmailServiceConfig is a TypeScript type, use import type.

config (wdio.conf.js)

✓ import path from 'path'; export const config = { services: [['gmail', { credentialsJsonPath: path.join(process.cwd(), './credentials.json'), tokenJsonPath: path.join(process.cwd(), './token.json') }]] }

✗ const config = { services: ['gmail'] }

Service options are passed as array entries: ['gmail', {...}]. Missing options or wrong paths cause runtime errors.

browser.checkInbox

✓ const emails = await browser.checkInbox({ from: 'sender@example.com', subject: 'Test' })

✗ browser.checkInbox({ from: 'sender@example.com' })

checkInbox is a custom command added by the service to browser object. Must be used inside a WebdriverIO test (browser context).

Shows how to configure the Gmail service in wdio.conf.js and use browser.checkInbox in a test.

// wdio.conf.js import path from 'path'; export const config = { services: [['gmail', { credentialsJsonPath: path.join(process.cwd(), 'credentials.json'), tokenJsonPath: path.join(process.cwd(), 'token.json'), intervalSec: 10, timeoutSec: 60 }]], // ... other config }; // test.spec.js describe('Gmail Service Test', () => { it('should fetch emails', async () => { const emails = await browser.checkInbox({ from: 'sender@example.com', subject: 'Test Email', includeBody: true }); expect(emails.length).toBeGreaterThan(0); expect(emails[0].body.text).toContain('Hello'); }); });

Debug

Known issues

breakingNode.js >=18 required (v2.0). Older versions won't work.

fix

Update Node.js to v18 or later.

affects: >=2.0.0

gotchacredentialsJsonPath and tokenJsonPath must be absolute paths. Relative paths will silently fail.

fix

Use path.join(process.cwd(), 'file.json') or absolute paths.

affects: *

gotchaThe service adds browser.checkInbox only after initialization. It is not available before the config is loaded.

fix

Ensure the service is correctly configured in wdio.conf.js. Call browser.checkInbox only inside WebdriverIO tests (before/after hooks work).

affects: *

deprecatedGmail Tester OAuth2 tokens expire periodically. No built-in token refresh.

fix

Implement external token refresh or regenerate token.json before expiry.

affects: *

gotchacheckInbox returns empty array if no email matches; does not throw error. Tests relying on receiving email may pass incorrectly.

fix

Check email array length and assert non-empty. Consider increasing timeoutSec.

affects: *

Errors

Common errors & fixes

TypeError: browser.checkInbox is not a function

Service not properly configured or not added to wdio.conf.js services array.

fix

Ensure services includes ['gmail', {...}] with correct options. Check path to configuration files.

Error: ENOENT: no such file or directory, open 'credentials.json'

credentialsJsonPath or tokenJsonPath is relative. WebdriverIO resolves relative to CWD, but paths must be absolute.

fix

Use path.join(process.cwd(), 'file.json') for both paths.

Gmail API error: 401 Unauthorized

Invalid or expired token.json.

fix

Regenerate token.json via Gmail Tester steps. Ensure credentials.json is valid.

Upgrade

Version history

2.1.0latest on npm

Audit

Dependencies

gmail-testerrequiredUsed to fetch emails from Gmail API

@wdio/typesoptionalTypeScript types for WebdriverIO service configuration

Agent activity

12 hits · last 30 days

node

Resources

githubhttps://github.com/webdriverio-community/wdio-gmail-service ↗

packagewdio-gmail-service ↗

homepagehttps://github.com/webdriverio-community/wdio-gmail-service#readme ↗