Request Mocking Protocol

Request Mocking Protocol (RMP) is designed for declarative mocking of HTTP requests. It provides JSON schemas for capturing requests and building responses. The schemas can be serialized and transmitted over the network, enabling both client-side and server-side mocking (e.g., in React Server Components).

Features

• Server-side mocking: Apply mocks on the server by transmitting them via a custom HTTP header.
• Per-test mock isolation: Define mocks within each test and run the entire suite in parallel against the same app instance.
• Modern test runner support: Seamlessly integrates with Playwright, Cypress, and any custom test runner.
• Framework-agnostic interceptors: Use built-in interceptors for Next.js, Astro, or integrate with any other framework.
• Flexible request matching: Match requests by exact URL, wildcards, query parameters, headers, or body content.
• Parameter substitution: Dynamically replace route or query parameters in mock responses using {{ }} syntax.
• Response patching: Fetch real API responses and override only what you need, keeping mocks in sync with backend changes.
• Intuitive API: Provides a first-class MockClient for setting up the mocks.
• Debug-friendly: Add debug: true to any mock and get a nicely formatted breakdown of the mocking process.

How it works

1. The test runner declares a request mock in the JSON format.
2. The mock is attached to the webpage navigation request inside a custom HTTP header.
3. The application server reads the header and applies the mock to outgoing API calls.
4. The page is rendered with data from the mocked response.

Check out the Concepts and Limitations for more details.

Installation

npm i -D request-mocking-protocol

Test-runner Integration

RMP is designed to work seamlessly with popular test runners like Playwright and Cypress, and can also be integrated with custom runners.

Each test defines its own mocks using a MockClient class. Mocks are not shared across tests, enabling per-test mock isolation and full parallelization.

Playwright

1. Set up a custom fixture mockServerRequest:

   import { test as base } from '@playwright/test';
   import { MockClient } from 'request-mocking-protocol';
   
   export const test = base.extend<{ mockServerRequest: MockClient }>({
     mockServerRequest: async ({ context }, use) => {
       const mockClient = new MockClient();
       mockClient.onChange = async (headers) => context.setExtraHTTPHeaders(headers);
       await use(mockClient);
     },
   });

2. Use mockServerRequest in test to define server-side mocks:

   test('my test', async ({ page, mockServerRequest }) => {
     // set up server-side mock
     await mockServerRequest.GET('https://jsonplaceholder.typicode.com/users', {
       body: [{ id: 1, name: 'John Smith' }],
     });
   
     // navigate to the page
     await page.goto('/');
   
     // assert page content according to mock
     await expect(page).toContainText('John Smith');
   });

Check out MockClient API for other methods.

Cypress

1. Add a custom command mockServerRequest in support files, see example mock-server-request.js.

2. Use the custom command to define mocks:

   it('shows list of users', () => {
     // set up server-side mock
     cy.mockServerRequest('https://jsonplaceholder.typicode.com/users', {
       body: [{ id: 1, name: 'John Smith' }],
     });
   
     // navigate to the page
     cy.visit('/');
   
     // assert page content according to mock
     cy.get('li').first().should('have.text', 'John Smith');
   });

Custom

You can integrate RMP with any test runner. It requires two steps:

1. Use the MockClient class to define mocks.
2. Attach mockClient.headers to the navigation request.

Framework Integration

On the server side, you should set up an interceptor to catch the requests and apply your mocks.

Next.js (App router)

Add the following code to the instrumentation.ts file:

Add the following code to the top level layout.tsx:

// app/layout.tsx
import { headers } from 'next/headers';

if (process.env.NEXT_RUNTIME === 'nodejs' && process.env.NODE_ENV !== 'production') {
  const { setupFetchInterceptor } = await import('request-mocking-protocol/fetch');
  setupFetchInterceptor(() => headers());
}

// ...

Note

Apply interceptor only in nodejs runtime.

Important

Don't load interceptor inside instrumentation.ts, as it will be cleared in dev server after re-compilation.

Astro

See astro.config.ts in the astro-cypress example.

Custom

You can write an interceptor for any framework. It requires two steps:

1. Read the HTTP headers of the incoming request.
2. Capture outgoing HTTP requests.

Check out the reference implementations in the src/interceptors directory.

Request Matching

RMP offers flexible matching options to ensure your mocks are applied exactly when you need them:

• Exact URL matching: Match requests by providing a full URL string.

  await mockClient.GET('https://api.example.com/users', { body: [] });

• Wildcard matching: Use wildcards with URLPattern-style syntax.

  await mockClient.GET('https://api.example.com/users/*', { body: [] });

• Regular expression matching: Match requests using JavaScript regular expressions.

  await mockClient.GET(/\/users\/\d+$/, { body: {} });

• Query parameter matching: Match specific query parameters for more targeted mocks.

  await mockClient.GET({
    url: 'https://api.example.com/users',
    query: { role: 'admin' },
  }, { body: [] });

• Method-based matching: Explicitly define the HTTP method (GET, POST, etc.) to avoid accidental matches.

  await mockClient.POST('https://api.example.com/users', { status: 201 });

• Schema matching: Use full request schemas to match by method, URL, query, and optionally enable debug mode for inspection.

  await mockClient.GET({
    method: 'GET',
    url: 'https://api.example.com/users',
    query: { active: 'true' },
    debug: true,
  }, { body: [] });

Parameter Substitution

You can define route parameters in the URL pattern and use them in the response:

await mockClient.GET('https://jsonplaceholder.typicode.com/users/:id', {
  body: {
    id: '{{ id:number }}',
    name: 'User {{ id }}',
  }
});

The request:

GET https://jsonplaceholder.typicode.com/users/1

will be mocked with the response:

{
  id: 1,
  name: 'User 1',
}

Response Patching

Response patching allows to make a real request, but modify parts of the response for the testing purposes. RMP supports response patching by providing the bodyPatch key in the response schema:

await mockClient.GET('https://jsonplaceholder.typicode.com/users', {
  bodyPatch: {
    '[0].address.city': 'New York',
  },
});

The final response will contain actual and modified data:

[
  {
    "id": 1,
    "name": "Leanne Graham",
    "address": {
-      "city": "Gwenborough",
+      "city": "New York",
      ...
    }
  }
  ...
]    

This technique is particularly useful to keep your tests in sync with actual API responses, while maintaining test stability and logic.

The bodyPatch contains object in a form:

{
  [path.to.property]: new value
}

path.to.property uses dot-notation, evaluated with lodash.set.

Debugging

You can debug the mocking process by providing debug: true option to either request or response schema:

await mockClient.GET(
  {
    url: 'https://jsonplaceholder.typicode.com/users',
    query: {
      foo: 'bar',
    },
    debug: true, // <-- use debugging
  },
  {
    body: [{ id: 1, name: 'John Smith' }],
  },
);

When applying this mock, the server console with output the following:

Concepts

Request Schema

The request schema is a serializable object that defines parameters for matching a request.

Example:

{
  method: 'GET', 
  url: 'https://jsonplaceholder.typicode.com/users',
  query: {
    foo: 'bar'
  }
}

This schema will match the request:

GET https://jsonplaceholder.typicode.com/users?foo=bar

Full schema definition.

Response Schema

The response schema is a serializable object that defines how to build the mocked response.

Example:

{
  status: 200,
  body: 'Hello world'
}

Full schema definition.

Transport

Request-mocking-protocol uses a custom HTTP header x-mock-request for transferring JSON-stringified schemas from the test runner to the application server.

Example:

x-mock-request: [{"reqSchema":{"method":"GET","patternType":"urlpattern","url":"https://example.com"},"resSchema":{"body":"hello","status":200}}]

On the server side, the interceptor will read the incoming headers and apply the mocks.

Limitations

1. Static Data Only: The mock must be serializable to JSON. This means you can't provide arbitrary function-based mocks. To mitigate this restriction, RMP supports Parameter Substitution and Response Patching techniques.

2. Header Size Limits: HTTP headers typically support 4KB to 8KB of data. This approach is best suited for small payloads.

API

MockClient

The MockClient class is used on the test-runner side to define HTTP request mocks.

Constructor

constructor(options?: MockClientOptions)

Creates a new instance of MockClient.

• options (optional): An object containing configuration options.
  • debug (optional): A boolean indicating whether to enable debug mode.
  • defaultMethod (optional): The default HTTP method to use for requests.

Properties

headers: Record<string, string>

Returns HTTP headers that are built from the mock schemas. Can be sent to the server for mocking server-side requests.

onChange?: (headers: Record<string, string>) => void

A callback function that is called whenever the mocks are changed.

Methods

async addMock(reqSchema, resSchema): Promise<void>

async GET(reqSchema, resSchema): Promise<void>

async POST(reqSchema, resSchema): Promise<void>

async PUT(reqSchema, resSchema): Promise<void>

async DELETE(reqSchema, resSchema): Promise<void>

async HEAD(reqSchema, resSchema): Promise<void>

async ALL(reqSchema, resSchema): Promise<void>

Adds a new mock for the corresponding HTTP method.

• reqSchema: string | RegExp | object – The request schema for the mock.

  • If defined as string, it is treated as URLPattern for matching the request only by URL.
  • If defined as RegExp, it is treated as RegExp for matching the request only by URL.

• resSchema: number | object: The response schema for the mock.

  • If defined as number, it is treated as an HTTP status code.

Examples:

// mock any GET request to https://example.com
await mockServerRequest.GET('https://example.com/*', {
  body: { 
    id: 1, 
    name: 'John Smith' 
  },
});

// mock any POST request to https://example.com having foo=bar in query
await mockServerRequest.POST({
  url: 'https://example.com/*',
  query: {
    foo: 'bar'
  },
}, {
  body: { 
    id: 1, 
    name: 'John Smith' 
  },
});

async reset(): Promise<void>

Clears all mocks and rebuilds the headers.

Interceptors

Interceptors are used on the server to capture HTTP requests and apply mocks. Currently, there are two interceptors available.

Fetch

This interceptor overwrites the globalThis.fetch function.

Basic usage:

const { setupFetchInterceptor } = await import('request-mocking-protocol/fetch');

setupFetchInterceptor(() => { 
  // read and return headers of the incoming HTTP request
});

The actual function for retrieving incoming headers depends on the application framework.

MSW

You can use MSW to intercept server-side requests:

import { setupServer } from 'msw/node';
import { createHandler } from 'request-mocking-protocol/msw';

const mockHandler = createHandler(() => { 
  // read and return headers of the incoming HTTP request
});
const mswServer = setupServer(mockHandler);
mswServer.listen();

The actual function for retrieving incoming headers depends on the application framework.

License

MIT