New API to define handlers by object syntax to reuse handlers, like CSF3

[KoichiKiyokawa]

Scope

Adds a new behavior

Compatibility

• This is a breaking change

Feature description

First, thank you for all of your work on this library 🎉

Motivation

There are cases where one handler wants to be reused by another handler.
For example,

const userShowHandler = rest.get("http://localhost:3000/users/:id", (req, res, ctx) => {
    return res(ctx.status(200), ctx.json({ id: 1, name: "user1", age: 10 }), ctx.delay(500));
  }
);

const userListHandler = rest.get("http://localhost:3000/users", (req, res, ctx) => {
    return res(ctx.status(200), ctx.json([{ id: 1, name: "user1", age: 10 }]), ctx.delay(500));
  }
);

Even though these two handlers are mostly similar, it is difficult to reuse userShowHandler when we write userListHandler.
Also, it is difficult to inject spy method to existing handlers in test.

const requestUrlSpy = jest.spy()
const userShowHandler = rest.get("http://localhost:3000/users/:id", (req, res, ctx) => {
    requestUrlSpy(req.url.toString()) // We have to copy and paste the whole of `userShowHandler` definition, and inject this line.
   // ^^^^^^^^^^^^^^^^^^^^^^
    return res(ctx.status(200), ctx.json({ id: 1, name: "user1", age: 10 }), ctx.delay(500));
  }
);

Proposed Solution

Use object to define handler.
I was inspired by CSF3 (https://storybook.js.org/blog/component-story-format-3-0/), which is a reusable story definition for storybook and others.

import { defineBaseRestBuilder, createRestHandler, RestBuilder } from "msw/object";
import { setupServer } from "msw";

const baseBuilder = defineBaseRestBuilder({
  basePath: "http://localhost:3000",
  // Set default delay as 500ms
  // It cannot be done with current msw.
  delay: 500,
});

// extends baseBuilder
const userShowBuilder: RestBuilder = {
  ...baseBuilder,
  path: "/users/:id",
  resolve: () => ({ id: 1, name: "user1", age: 10 }),
};

// extends userShowBuilder
const userListBuilder: RestBuilder = {
  ...userShowBuilder,
  path: "/users",
  resolve: () => [userShowBuilder.resolve()],
};

// In test, inject spy method
 const requestUrlSpy = jest.fn();
 const builder: RestBuilder = {
    path: "/users/:id",
    resolve: () => ({ id: 1, name: "user1", age: 10 }),
    // You can specify onRequest hook. It is fired before mock handler return a response.
    // vvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvv
    onRequest: (req) => {
      requestUrlSpy(req.url.toString());
    },
    // ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  };

I created a POC library to implement this syntax.
https://github.com/KoichiKiyokawa/msw-object

[kettanaito]

Hey, @KoichiKiyokawa. Thanks for drafting this proposal! Let me start by addressing some of your concerns from the motivation section.

Even though these two handlers are mostly similar, it is difficult to reuse userShowHandler when we write userListHandler.

I think the difficulty here arises from the fact that these are two handlers controlling two separate resources. The mocking logic itself (the response status code, headers, body) may look repetitive but you're defining two different responses, and it's important to keep that in mind.

What you really want to reuse here is the dataset. We have a library called Data that pushes the source of truth to abstract data models and manages handlers for you, if you so wish. But you can also go with a manual approach here, defining your data and then reusing it those two handlers:

const users = [
  { id: 1, name: 'John' },
  { id: 2, name: 'Kate' }
]

export const handlers = [
  rest.get('/user/:id', (req, res, ctx) => {
    const user = users.find(user => user.id === req.params.id)

    if (!user) {
      return res(ctx.status(404))
    }

    return res(ctx.json(user))
  }),
  rest.get('/users', (req, res, ctx) => {
    return res(ctx.json(users))
  })
]

Notice how little there is actually to reuse across these handlers once you've moved the data outside.

Also, it is difficult to inject spy method to existing handlers in test.

Consider using the Life-cycle API to spy on request/response events. You can attach listeners at any point, even within your test, so they stand separated from your request handlers.

// some.test.js
import { handlers } from './handlers'

const server = setupServer(...handlers)
// ...the regular setup here


it('some test', () => {
  const requestListener = jest.fn()
  server.on('request:start', requestListener)

  // ...make your request

  expect(requestListener).toHaveBeenCalledTimes(1)
  expect(requestListener).toHaveBeenCalledWith(expect.objectContaining({
    method: 'GET',
    url: new URL('https://example.com/resource')
  })
})

Note that request/response assertions are generally discouraged and I recommend writing your tests around the data/state that requests affect rather than spying on them directly. I write about it at length in here.

---

Now to the proposal.

If I understand it correctly, you suggest supporting an object-based declaration syntax for the request handlers. Your main goal here is to be able to compose handlers, so to derive new handlers from the old ones, opening more room for the reusability of things like delays, headers, paths, etc.

Interestingly enough, MSW supports exactly what you're proposing with the exception of using a functional API to achieve that.

import { createResponseComposition, context } from 'msw'

const baseResolver = (resolver) => {
  return (req, res, ctx) => {
    const customResponseFn = createResponseComposition(null, [
      // Delay all responses by 500ms by default.
      // You can define any "ctx.*" methods here just as you do
      // when calling the "res()" function by default.
      context.delay(500)
    ])

    // Notice that we're passing the custom "res" function here
    // that has the default delay built-in.
    return resolver(req, customResponseFn, ctx)
  }
}

const userResolver = baseResolver((req, res, ctx) => {
  // The response will be delayed based on the base resolver.
  return res(ctx.json(singleUser))
})

const usersResolver = baseResolver((req, res, ctx) => {
  return res(ctx.json(allUsers))
})

export const handlers = [
  rest.get('/user/:id', userResolver),
  rest.get('/users', usersResolver)
]

Notice that the data returned from the userResolver is not reused in the usersResolver. I find that kind of reusability rather dangerous and that's where I highly suggest lifting the dataset up as I've described in this comment above. Returning the same or similar data is in no way a characteristic of a resolver or a handler. The fact that the data may intersect must be addressed by abstracting that data reference. It's both easier to do and safer to maintain.

My main concern with the syntax you propose is that handlers stop being as deterministic. Since a handler may depend on a bunch of things from another handler (keep in mind, implicitly), it becomes really hard to understand and reason about your network behavior. This is especially true if you rely on things like userShowBuilder.resolve()—basically creating a strong dependency on whatever that handler may return.

There's a great advantage in keeping request handlers plain. Bear in mind, that doesn't mean repetitive. You can reuse a fair share of logic but you must keep the resource path/resolver contract explicit and clear.

I don't think we will adopt a proposed API any time soon. I am always open to making MSW APIs simpler and plainer, and I find your proposal bringing a bit of complication to how handlers are defined. Although it may seem like you're saving yourself some effort by reusing things, in actuality you'd be causing more harm than meets the eye.

I'm thankful for the proposal regardless. Feel free to elaborate below, maybe we can come to a different conclusion or a compromise after giving this a due discussion. Thanks!

[KoichiKiyokawa]

Thank you for the detailed explanation 👍

I find that kind of reusability rather dangerous

I realized that reusing data returned by another resolver is a bad idea.

How about the case when we want to define handlers that is almost the same expect for delay msec? (I often need it when using MSW with Storybook to check display changes depending on network time)

1. userShowHandler (100ms delay, normal case)
2. userShowHandler (2000ms delay, component should show It's taking a long time... in Storybook)
3. userShowHandler (5000ms delay, component should show timeout error in Storybook)

Or, when we define handlers that is mostly the same other than status code.

[kettanaito]

In those situations, you create a withDelay() higher-order resolver to abstract the delay logic without repeating the actual resolver logic.

import { context } from 'msw'

function withDelay(duration, resolver) {
  return (...args) => {
    const response = resolver(...args)
    return context.delay(duration)(response)
  }
}

// One.stories.jsx
const handlers = [
  rest.get('/user', withDelay(100, userResolver)
]

// Another.stories.jsx
const handlers = [
  rest.get('/user', withDelay(2000, userResolver)
]

You can also achieve this using Custom response composition.