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 information like method, headers, body, query.

Example

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

import { createMSWInspector } from 'msw-inspector';
import { server } from '@/mocks/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 test preparation

    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, // Any `msw` SetupServer or SetupWorker instance
  mockFactory, // Function returning a mocked function instance to be inspected in your tests
  requestMapper, // Optional mapper function to customize how requests are stored
});

Options object

createMSWInspector accepts the following options object:

 {
  mockSetup: SetupServer | SetupWorker;
  mockFactory: () => FunctionMock;
  requestMapper?: (req: MockedRequest) => Promise<{
    key: string;
    record: Record<string, any>;
  }>;
}

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...	-
requestMapper	Customize default request's key and record mapping with your own logic. Async function.	See defaultRequestMapper

getRequests

Returns a mocked function containing all the calls intercepted at the given absolute url (by default):

mswInspector.getRequests('http://my.url/path');

Each intercepted request calls the matching mocked function with the following default payload:

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

Todo

• Consider a better name for getRequests
• 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

Changelog

1.0.0

Breaking change

• Support msw v1+