msw-inspector

MSW inspector

Plug-and-play request assertion utility for any msw mock setup, as highly discouraged by msw authors :)

Why?

From msw docs:

Instead of asserting that a request was made, or had the correct data, test how your application reacted to that request.

There are, however, some special cases where asserting on network requests is the only option. These include, for example, polling, where no other side effect can be asserted upon.

MSW inspector has you covered for these special cases.

How

MSW inspector provides a thin layer of logic over msw life-cycle events.

Each request is saved as a function mock call retrievable by URL. This allows elegant assertions against request records like method, headers, body, query fully integrates with your test assertion library.

Installation

npm install msw-inspector -D

Example

This example uses Jest, but MSW inspector integrates with any testing framework.

import { jest } from '@jest/globals';
import { createMSWInspector } from 'msw-inspector';
import { server } from './your-msw-server';

const mswInspector = createMSWInspector({
  mockSetup: server,
  mockFactory: () => jest.fn(), // Provide any function mock supported by your testing library
});

beforeAll(() => {
  mswInspector.setup();
});

beforeEach(() => {
  mswInspector.clear();
});

afterAll(() => {
  mswInspector.teardown();
});

describe('My test', () => {
  it('My test', async () => {
    // Perform your tests

    expect(mswInspector.getRequests('http://my.url/path')).toHaveBeenCalledWith(
      {
        method: 'GET',
        headers: {
          'my-header': 'value',
        },
        body: {
          'my-body': 'value',
        },
        query: {
          'my-query': 'value',
        },
      },
    );
  });
});

API

createMSWInspector

Create a MSW inspector instance bound to a specific msw SetupServer or SetupWorker instance:

import { createMSWInspector } from 'msw-inspector';

createMSWInspector({
  mockSetup, // You `msw` SetupServer or SetupWorker instance
  mockFactory, // Function returning a mocked function instance to be inspected in your tests
  requestLogger, // Optional logger function to customize request logs
});

createMSWInspector Options

createMSWInspector accepts the following options object:

 {
  mockSetup: SetupServer | SetupWorker;
  mockFactory: () => FunctionMock;
  requestLogger?: (req: MockedRequest) => Promise<Record<string, unknown>>;
}

Option	Description	Default value
mockSetup (required)	The instance of msw mocks expected to inspect (setupWorker or setupServer result)	-
mockFactory (required)	A function returning the function mock preferred by your testing framework: It can be () => jest.fn() for Jest, () => sinon.spy() for Sinon, () => vi.fn() for Vitest, etc...	-
requestLogger	Customize request records with your own object. Async function.	See requestLogger

getRequests

Returns a mocked function pre-called with all the request records whose absolute url match the provided one.

The matching url can be provided as:

• plain absolute url string
• path-to-regexp matching pattern

// Full string match
mswInspector.getRequests('http://my.url/path/foo');

// Url matching patter
mswInspector.getRequests('http://my.url/path/:param');

By default, each matching request results into a mocked function call with the following request log record:

type DefaultRequestLogRecord = {
  method: string;
  headers: Record<string, string>;
  body?: any;
  query?: Record<string, string>;
};

...the call order is preserved.

If you want to create a different request record you can do so by providing a custom requestLogger:

import { createMSWInspector, defaultRequestLogger } from 'msw-inspector';

const mswInspector = createMSWInspector({
  requestLogger: async (req) => {
    // Optionally use the default request mapper to get the default request log
    const defaultRecord = await defaultRequestLogger(req);

    return {
      myMethodProp: req.method,
      myBodyProp: defaultRecord.body,
    };
  },
});

getRequests Options

getRequests accepts an optional options object

mswInspector.getRequests(string, {
  debug: boolean, // Throw debug error when no matching requests found (default: true)
});

Todo

• Consider listening to network layer with @mswjs/interceptors and make MSW inspector usable in non-msw projects
• Todo find out why SetupServer | SetupWorker union causes a type error in lifecycle events
• Consider optionally returning requests not intercepted by msw (request:start/ request:match)

Changelog

2.0.0

Breaking change

• Drop support for Node.js v16
• Query object parsed with qs library
• requestMapper option replaced by requestLogger

New Features

• Pattern matching powered by path-to-regexp
• debug option added
• Throw error when invalid URL provided