WDIO Intercept Service

4.4.1 verified Sat Apr 25 auth: no javascript

A WebdriverIO plugin for capturing and asserting HTTP AJAX calls (XHR and fetch) during e2e tests. Current stable version is 4.4.1, targeting WebdriverIO v8+. It works by injecting a script into the browser after page load to intercept requests initiated by user actions within test code. Key differentiators: supports both XMLHttpRequest and fetch APIs, allows asserting request method, URL (string or regex), status code, and response details. Cannot intercept requests made on initial page load.

Common errors

error TypeError: Cannot read properties of undefined (reading 'before') ↓

cause Calling serviceLauncher.before before the service is initialized or with incorrect arguments.

fix

Ensure the service is initialized with const serviceLauncher = WebdriverAjax(); and then call serviceLauncher.before(null, null, browser); passing the browser instance.

error Error: expectRequest requires a method, url, and statusCode. ↓

cause Calling expectRequest with missing or invalid arguments (e.g., no statusCode).

fix

Use browser.expectRequest('GET', '/api/foo', 200); – all three arguments are required.

error AssertionError: expected 0 to equal 1 ↓

cause Request was not intercepted because setupInterceptor() was not called or the request was made before it was called.

fix

Ensure browser.setupInterceptor() is called before the action that triggers the request.

error SyntaxError: Unexpected token 'export' ↓

cause Using ES module import syntax in a CommonJS environment (e.g., Node.js without 'type': 'module' or .mjs extension).

fix

Use const WebdriverAjax = require('wdio-intercept-service'); or configure your project for ESM.

Warnings

gotcha Requests initiated on page load cannot be intercepted. Only requests triggered within test code after calling setupInterceptor() are captured. ↓

fix Ensure that setupInterceptor() is called before the user action that triggers the desired HTTP request.

breaking Version 4.x requires WebdriverIO v8. Compatibility with WDIO v5-v7 is dropped. ↓

fix Upgrade to WebdriverIO v8 or use wdio-intercept-service v3.x (if available) for older versions.

gotcha When using fetch, requests with 'no-cors' mode may not be intercepted due to browser limitations. ↓

fix Use CORS-enabled endpoints or switch to XMLHttpRequest if interception is required.

gotcha The getRequest(index) method returns undefined if the index is out of range. No error is thrown. ↓

fix Check the return value or use getRequests() to iterate.

deprecated assertRequests() does not accept options for timeout or retries. Use manual pauses or WebdriverIO waits instead. ↓

fix Use browser.pause() or browser.waitUntil() before calling assertRequests() to ensure requests have completed.

Install

npm install wdio-intercept-service

yarn add wdio-intercept-service

pnpm add wdio-intercept-service

Imports

default (function)
wrong
```
const WebdriverAjax = require('wdio-intercept-service').default
```
correct
```
import WebdriverAjax from 'wdio-intercept-service'
```
ESM default export. Do not use .default with require() – you will get an object with a default property instead of the function.
setupInterceptor
wrong
```
browser.setupinterceptor()
```
correct
```
browser.setupInterceptor()
```
Case-sensitive command added to browser object after service is initialized. Must be called before making requests you want to intercept.
expectRequest
wrong
```
browser.expectRequest('GET', '/api/foo')
```
correct
```
browser.expectRequest('GET', '/api/foo', 200)
```
Third argument (statusCode) is required. Can use string or RegExp for URL.
assertRequests
wrong
```
browser.assertRequests({ timeout: 2000 })
```
correct
```
browser.assertRequests()
```
assertRequests does not accept options. Use separate pause() or wait strategies before calling it.

Quickstart

Demonstrates setting up the service manually with WebdriverIO standalone, intercepting an XHR/fetch request, and asserting it.

import { remote } from 'webdriverio';
import WebdriverAjax from 'wdio-intercept-service';

async function run() {
  const browser = await remote({
    logLevel: 'warn',
    capabilities: { browserName: 'chrome' }
  });

  const serviceLauncher = WebdriverAjax();
  serviceLauncher.before(null, null, browser);
  serviceLauncher.beforeTest();

  await browser.url('https://example.com');
  await browser.setupInterceptor();
  await browser.expectRequest('GET', '/api/data', 200);
  await browser.click('#load-data');
  await browser.pause(1000);
  await browser.assertRequests();

  const request = await browser.getRequest(0);
  console.log('Request method:', request.method);

  await browser.deleteSession();
}
run().catch(console.error);