Add capability to use named handlers in server.use() to match behaviour of msw-storybook-addon and enable reuse of mocks between tests and Storybook

[ahayes91]

Scope

Adds a new behavior

Compatibility

• This is a breaking change

Feature description

https://github.com/mswjs/msw-storybook-addon?tab=readme-ov-file#advanced-usage details a way to use named handlers to allow merging of global handlers and individual story handlers in Storybook, where handlers can be this shape:

type MswParameter = {
  handlers: RequestHandler[] | Record<string, RequestHandler | RequestHandler[]>
}

Whereas setupServer and server.use can only accept an array of handlers RequestHandler[]

msw/src/node/setupServer.ts

Line 7 in f4be9ce

* @param {RequestHandler[]} handlers List of request handlers.

msw/src/node/glossary.ts

Line 30 in f4be9ce

use(...handlers: Array<RequestHandler | WebSocketHandler>): void

This makes it a little bit tricker for us to nicely define a handlers object/array of commonly mocked API endpoints, and reuse it between our tests and Storybook.

Note that there's an argument to be made here about moving tests into Storybook test runner altogether to be able to use that syntax and just not bother with some UI tests in Jest/vitest/Cypress component tests/whatever, and maybe I'll end up doing that anyway! 😂

Thanks for reading, let me know what you think!

[kettanaito]

Hi, @ahayes91. Thanks for proposing this!

First of all, sorry for you having trouble reusing the mocks. I believe I can help with some of the information below.

It's worth noting that while the current Storybook add-on promotes the usage of named handlers, I've opened an RFC to move away from that pattern. In short, I don't see any practical benefit for grouping handlers that way. It also makes a simple thing which is handler call order a bit more confusing once you deal with objects, which are order-insensitive by design.

That behavior will be removed in the future version of the add-on.

Bear in mind that you still can and sometimes should group your handlers. You can even group them in objects, if you so choose. Here's how I recommend doing it:

// mocks/handlers/user.ts
export const handlers = [
  http.get('/user', resolver),
  http.post('/login', resolver)
]

Then, upon usage:

import { handlers as userHandlers } from './mocks/handlers.user'

someApi(
  ...userHandlers,
  ...otherHandlers,
)

Using import aliases produces the same affect here and gives you named handlers that will be compatible with Storybook but also plain usage of MSW.

Let me know if you have any questions around this.