[RFC] Storybook MSW add-on

[kettanaito]

Summary

This RFS aims to improve the user experience of the msw-storybook-addon by aligning it with the new CSF and other things.

Problem Statement

1. The current version of the add-on is cumbersome to set up. I dislike the initialize() step.
2. The current version of the add-on doesn't play nicely with the test() function, it all feels disjoined.
3. The current version of the add-on makes does not ship proper defaults while making customizations a bit awkward.
4. Handler inheritance has been confusing developers for years.

Non-goals

1. Maintain and foster the established development experience around using MSW.
2. Leverage common patterns and best practices of add-on usage for Storybook users without compromising the aforementioned MSW experiences.

Implementation

This RFC includes multiple changes to the add-on.

Add-on renaming

This is irrelevant in the context of Storybook, but I am considering renaming the addon from msw-storybook-adddon to @mswjs/storybook. We are likely to provide more targeted integrations with tools, like Storybook, Playwright, or Cypress, in the future. I would like for this add-on to be one of the first adopters of this naming pattern to shape a great user experience.

Initialization

Initialize add-on as a plugin.

// .storybook/main.ts
export default {
  addons: ['@mswjs/storybook']
}

This will wrap all the necessary steps for the add-on to apply itself depending on the environment (browser/Node.js). No initialize call needed.

Another argument for using the addons option is that it makes the add-on, well, a fully-fledged actual add-on, and not just a loader. This will enable us to ship more experiences in the future, like the "Network" tab in the Storybook panel, without asking the users to tweak their configs now and then.

Default usage

By default, the user provides request handlers as arguments to their stories. Arguments represent props of a story, and network description can be treated as one.

const meta = config.meta({
  args: {
    handlers: [
      http.get('/resource', () => Response.json(resource))
    ]
  }

})

Defining request handlers on the story args serves as happy-path handlers that all variants of this story will automatically inherit and abide by.

Handler overrides

You can then override the base request handlers on a per-variant basis (or in the test function) like so:

// Example of overriding request handlers in a story variant.
const ComponentWithError = meta.story({
  args: {
    handlers: [
      http.get('/resource', () => new Response(null, { status: 500 }))
    ]
  }
})

// Example of overriding request handlers during the test.
Component.test('handles server errors', ({ msw }) => {
  msw.use(
    http.get('/resource', () => new Response(null, { status: 500 }))
  )
})

The msw object is a SetupApi instance that provides a familiar experience to prepend request handlers on runtime.

Alternatively, you can grab a reference to the SetupApi instance in the beforeEach hook:

meta.story({
  beforeEach({ msw }) {
    msw.use(...overrides)
  }
})

Handler inheritance

I highly suggest provide a familiar handler inheritance experience as it is in the MSW usage outside of Storybook:

• Handlers are accumulative (happy-path handlers are merged with runtime handlers).
• Handlers can be grouped by domain by creating an array with the relevant handlers.

This point advocates for deprecating named-object handler groups as that's a behavior specific only to Storybook. It creates an experience that doesn't exist outside of Storybook, which is confusing and has a detrimental effect on people learning these two tools.

I've already showcase the handler overrides scenario above.

Here's an example of combining multiple handlers in a single story:

import { userHandlers } from '~/mocks/handlers/user'
import { checkoutHandlers } from '~/mocks/handlers/checkout'

config.meta({
  args: {
    handlers: [...userHandlers, ...checkoutHandlers]
  }
})

Disabling a handlers group

In the past, you could disable a certain group of handlers by providing null as the value to their key/value pair in the named-object configuration.

I find that to be convoluted. Instead, you should compose the array of handlers that are relevant to the current story. Do not put all handlers in the base meta to then exclude some of them in particular stories. That makes you reference all around the file just to understand what handlers apply for a particular story.

This is the recommended way:

const CaseA = meta.story({ args: { handlers: [...a] } })
const CaseB = meta.story({ args: { handlers: [...a, ...b] } })
const CaseC = meta.story({ args: { handlers: [...b, ...c] } })

There is no price to doing this, and explicitness always wins.

For users with a large number of handlers, spreading them may have performance implications. They should consider .concat() instead in that case: a.concat(b).concat(c) as it doesn't re-iterate over the arrays.

Configuring setup

You can customize the SetupApi instance like so:

{
  loaders: [mswLoader({ onUnhandledRequest: 'error' })]
}

This implies initiating the add-on in a loader, which I believe to be suboptimal. I could use your help to see if there's an options pattern to the addons property of the main.ts config. Something like addons: [['@mswjs/storybook', options]].

[kettanaito]

The majority of the points above is the result our prior discussion with @yannbf, to whom I am greatly thankful!

[kylegach]

This looks great! Seems like a nice balance of MSW and Storybook patterns.

I'm concerned that args.handlers could collide with a component that accepts a handlers prop. But we've discussed some kind of "non-component arg" API that would work nicely here.

FYI, there is an API to pass options to an addon when registering it, which you can see here: https://storybook.js.org/docs/essentials#configuration.

Unfortunately, it looks like we haven't documented how an addon author can set that up. It appears that they're passed in to preset functions? Here's the docs addon source showing that usage.

[kettanaito]

I'm concerned that args.handlers could collide with a component that accepts a handlers prop.

I believe Michael's correction that handlers should live in the parameters may affect this. Overall, I agree, grouping the handlers under something like an msw property is likely better for the future. I need to think if the parameters.msw.handlers isn't a chaining too long though.

FYI, there is an API to pass options to an addon when registering it, which you can see here:

This! This is fantastic. I think that's how we should ask for the setup options.

I am not sure how the initial request handlers fit in the scheme of things. In the wild, the flow of initializing MSW and adding initial handlers looks like this:

// 1. Pre-configure the worker instance.
const worker = setupWorker(...handlers)

// 2. Start the worker instance.
worker.start(options) 

If we are to mimic this flow, then the add-on options look like a proper place to add initial handlers, while the setup options are, probably, better off somewhere else? It's hard to say. Neither are meant to change over the lifecycle of a story.

What's important is that both support HMR, but I trust Storybook already reloads itself is you change its config.

I am not decided yet if mixing options here would be a good or bad idea:

addons: [
  {
    name: '@mswjs/storybook',
    options: {
      handlers: initialHandlers,
      options: setupOptions
    }
  }
]

[shilman]

Hi @kettanaito ! This is so exciting -- it's great to see MSW get cleaned up and improved alongside Storybook's own efforts to improve component testing. Since mocking is critical to Storybook, I hope that this conversation can not only improve the addon but also improve Storybook's approach to mocking and data handling!

Initialization

Automatic initialization certainly simplifies things. Is there nothing that the user would want to specify during initialization? Will there not be in the future either? I'm not familiar enough with MSW, so I want to double check.

Handler definition

By default, the user provides request handlers as arguments to their stories. Arguments represent props of a story, and network description can be treated as one.

Disagree with this. MSW handlers belong in parameters rather than args.

In Storybook args represent dynamic inputs to the stories, i.e. they are modifiable via interactive UI controls and query params. This means that in general args should be simple JS objects, not functions. Storybook has a somewhat clunky "mapping" concept for representing complex data.

If there was a way to do this mapping that led to a nice way to interactively edit your mock data in Storybook's UI, we should explore this direction together. The team has lots of ideas about how this might work.

If you believe that tests should be as simple as possible, and that adding mock data editing violates that objective, then I can also appreciate that point of view, especially for v1 of the addon.

Storybook parameters are statically defined per story, and are a natural home for functions and other complex data. You could take the same scheme proposed here and move them directly to parameters with very similar inheritance semantics (define on the component meta, potentially override per story):

config.meta({
  parameters: {
    handlers: [...userHandlers, ...checkoutHandlers]
  }
})

Inheritance

I highly suggest provide a familiar handler inheritance experience as it is in the MSW usage outside of Storybook

I agree with this. We are generally moving away from "magic" in Storybook, and your proposal is consistent with this.

[kettanaito]

Thanks for the early feedback, Michael!

Is there nothing that the user would want to specify during initialization?

Yes, in fact, there is. This is the place to configure the unhandled request listener, logging, and perhaps even the initial request handlers list. This is why I asked if loader arguments were a thing:

loaders: [
  [import('@mswjs/storybook', { quiet: true }]
]

MSW handlers belong in parameters rather than args.

Please treat this as my lack of proper terminology. Parameters do sound better, and I believe that's how we have it in the current version of the add-on as well.

Although, we were toying with the idea of request handlers being editable from the UI in Storybook. That's why I advocate for making the add-on fully realized so it's able to register panels in the future.

We are generally moving away from "magic" in Storybook, and your proposal is consistent with this.

I am really happy to hear this. I know this mustn't have been easy, but I find it to be the right direction.

[tmeasday]

@kettanaito I wondered about your comment:

Handlers are accumulative (happy-path handlers are merged with runtime handlers).

Are "happy path handlers" like global handlers that you would want to apply to all stories? If so what is the recommended syntax for adding them? Would it be a beforeEach in preview.ts?

[kettanaito]

Yes, happy-path handlers are meant to be your fallback handlers, applicable to all stories.

MSW-wise, you provide the list of those handlers to your setup functions. Storybook-wise, it should probably live where the server/worker is created, in the config (preview/main) rather than stories. People are meant to reuse those from their general development/testing workflow to achieve the same baseline network behavior.

[donaldpipowitch]

I'd love to see an easy way to mock a certain endpoint per story. The last time I looked at msw it worked on a global basis and when I want to embed multiple different storybook examples on the same page I'd like to return different mock data even if the same endpoint is requested. Currently we use axios-mock-adapter for this, but a more native solution would be nice.