# MockRequest

# MockRequest

This helper allows to mock requests while running tests in Puppeteer or WebDriver. For instance, you can block calls to 3rd-party services like Google Analytics, CDNs. Another way of using is to emulate requests from server by passing prepared data.

MockRequest helper works in these modes (opens new window):

  • passthrough (default) - mock prefefined HTTP requests
  • record - record all requests into a file
  • replay - replay all recorded requests from a file

Combining record/replay modes allows testing websites with large datasets.

To use in passthrough mode set rules to mock requests and they will be automatically intercepted and replaced:

// default mode
I.mockRequest('GET', '/api/users', '[]');

In record-replay mode start mocking to make HTTP requests recorded/replayed, and stop when you don't need to block requests anymore:

// record or replay all XHR for /users page

# Installations

npm i @codeceptjs/mock-request --save-dev

Requires Puppeteer helper or WebDriver helper enabled

# Configuration

# With Puppeteer

Enable helper in config file:

helpers: {
   Puppeteer: {
     // regular Puppeteer config here
   MockRequestHelper: {
     require: '@codeceptjs/mock-request',

Polly config options (opens new window) can be passed as well:

// sample options
helpers: {
  MockRequestHelper: {
     require: '@codeceptjs/mock-request',
     mode: record,
     recordIfMissing: true,
     recordFailedRequests: false,
     expiresIn: null,
     persisterOptions: {
       keepUnusedRequests: false
       fs: {
         recordingsDir: './data/requests',

TROUBLESHOOTING: Puppeteer does not mock requests in headless mode:

Problem: request mocking does not work and in debug mode you see this in output:

Access to fetch at {url} from origin {url} has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource. If an opaque response serves your needs, set the request's mode to 'no-cors' to fetch the resource with CORS disabled.

Solution: update Puppeteer config to include --disable-web-security arguments:

 Puppeteer: {
   show: false,
   chrome: {
     args: [

# With WebDriver

This helper partially works with WebDriver. It can intercept and mock requests only on already loaded page.

helpers: {
   WebDriver: {
     // regular WebDriver config here
   MockRequestHelper: {
     require: '@codeceptjs/mock-request',

Record/Replay mode is not tested in WebDriver but technically can work with REST Persister (opens new window)

# Usage

# πŸ‘» Mock Requests

To intercept API requests and mock them use following API

Calling mockRequest or mockServer will start mocking, if it was not enabled yet.

I.startMocking(); // optionally
I.mockRequest('/google-analytics/*path', 200);
// return an empty successful response 
I.mockRequest('GET', '/api/users', 200);
// mock users api
I.mockServer(server => {
    intercept((req, res) => { res.status(200).json(users);
});'Get users);

# πŸ“Ό Record & Replay

At this moment works only with Puppeteer

Record & Replay mode allows you to record all xhr & fetch requests and save them to file. On next runs those requests can be replayed. By default, it stores all passed requests, but this behavior can be customized with I.mockServer

Set mode via enironment variable, replay mode by default:

// enable replay mode
helpers: {
 Puppeteer: {
   // regular Puppeteer config here
 MockRequest: {
    require: '@codeceptjs/mock-request',
    mode: process.env.MOCK_MODE || 'replay',

Interactions between I.startMocking() and I.stopMocking() will be recorded and saved to data/requests directory.

I.startMocking() // record requests under 'Test' name
I.startMocking('users') // record requests under 'users' name

Use I.mockServer() to customize which requests should be recorded and under which name:

I.mockServer((server) => {
  // mock request only from and and
  // store recording into two different files

To stop request recording/replaying use I.stopMocking().

πŸŽ₯ To record HTTP interactions execute tests with MOCK_MODE environment variable set as "record":

MOCK_MODE=record npx codeceptjs run --debug

πŸ“Ό To replay them launch tests without environment variable:

npx codeceptjs run --debug

# Parameters

  • config

# flushMocking

Waits for all requests handled by MockRequests to be resolved:


# mockRequest

Mock response status

I.mockRequest('GET', '/api/users', 200);
I.mockRequest('ANY', '/secretsRoutes/*', 403);
I.mockRequest('POST', '/secrets', { secrets: 'fakeSecrets' });
I.mockRequest('GET', '/api/users/1', 404, 'User not found');

Multiple requests

I.mockRequest('GET', ['/secrets', '/v2/secrets'], 403);

# Parameters

# mockServer

Use PollyJS Server Routes API (opens new window) to declare mocks via callback function:

I.mockServer((server) => {
  // basic usage
  server.get('/api/v2/users').intercept((req, res) => {
    res.sendStatus(200).json({ users });

  // passthrough requests to "/api/v2"

In record replay mode you can define which routes should be recorded and where to store them:

I.mockServer((server) => {

  // record requests from and save them to data/recording/xml
  // record requests from and save them to data/recording/svg

  // record requests from /api and save them to data/recording/mock (default)

# Parameters

  • configFn

# passthroughMocking

Forces passthrough mode for mocking. Requires mocking to be started.


# recordMocking

Forces record mode for mocking. Requires mocking to be started.


# replayMocking

Forces replay mode for mocking. Requires mocking to be started.


# startMocking

Starts mocking of http requests. In record mode starts recording of all requests. In replay mode blocks all requests and replaces them with saved.

If inside one test you plan to record/replay requests in several places, provide recording name (opens new window) as the parameter.

// start mocking requests for a test

// start mocking requests for main page
// do actions

To update PollyJS configuration (opens new window) use secon argument:

// change mode
I.startMocking('comments', { mode: 'replay' });

// override config
I.startMocking('users-loaded', {
   recordFailedRequests: true

# Parameters

  • title any (optional, default 'Test')
  • config (optional, default {})

# stopMocking

Stops mocking requests. Must be called to save recorded requests into faile.

Last Updated: 2/4/2022, 2:53:32 AM