[RFC] Module automocking

[shilman]

Summary

We introduced Typesafe module mocking in Storybook 8.1, which uses the Node.js subpath imports standard. We took this approach because it’s supported across the JS ecosystem, meaning that module mocked stories will work in both Vite/Webpack/Node/TS. Since then, we’ve learned that subpath imports can be challenging to set up, and require more manual work than users want. We also explored vi.mock inline module mocking, but it adds a lot of complexity and surface area. In this RFC, we propose a stylized module mocking approach that tries to strike a balance between the two solutions.

Problem Statement

The biggest problems with subpath imports for module mocking are:

• More work. For every file that you want to mock, it requires setting up a separate file that implements the mock AND adding that file to your package.json subpath imports.
• Invasive. If you want to import things absolutely, it requires that you prefix paths with # (e.g. #config/main.ts), whereas many projects choose other characters like ~ or @.
• Finicky. There are confusing cases where subpath imports can conflict with TypeScript aliases. Or when you’re working in a monorepo, and so on.
• Global. It requires that you have a single global mock for a module, where as Jest/Vitest users are used to being able to mock inline using utilities like vi.mock.
• Unfamiliar. In addition to all of the technical problems listed above, mocking with subpath imports is simply not what users are accustomed to. We invested in subpath imports with the rationale that it’s an ecosystem standard, so people shouldn’t mind learning it. But the reality is that when it comes to mocking/testing, people are just used to inline mocking, and mocking is complex enough that asking them to learn something new seems like too much.

Non-goals

We also acknowledge that users want inline module mocking because they are most familiar with it. However, that solution has its own challenges and complexities, which is why we’re considering a simpler approach.

We want a simpler approach so that we can provide a module mocking approach that extends to other builders like Webpack/Rspack. However, enabling that today in Webpack/Rspack is also a non-goal of this RFC. We just want to preserve the future option. In the short term, Webpack/Rspack users should continue to use the subpath imports standard.

Implementation

While "happy path" inline mocking is straightforward, the API docs reveal a dizzying array of warnings and complexities.

The implementation of vi.mock is even more complex. And that's our primary concern with inline mocking. Though Storybook Test is Vitest-based and we are getting Vitest's implementation "for free", we want the option to extend module mocking to our Webpack/Rspack users in the future and we worry that will be prohibitively difficult with vi.mock (or a hypothetical sb.mock).

The key observation behind this proposal is that inline module mocking consists of two aspects:

• Mocking a module: vi.mock('my-module')
• Specifying how a module should be mocked: vi.mock('my-module', myFactoryFn), vi.mocked(my_module.x).mockImplementation(myFn)

We can simplify module mocking by decoupling these two concepts.

Declarative, global module mocking

We propose that mocking should be declarative and global rather than imperative and local.

Rather than writing vi.mock in each story file, you do it once in the project's preview file:

// .storybook/preview.ts
import type { Preview } from '@storybook/react';

const preview: Preview = {
  mocks: {
    auto: ['package1', 'package2'],
    spy: ['../src/path/to/some/File.ts'],
  }
};
export default preview;

This is equivalent to the following Vitest code:

vi.mock('package1');
vi.mock('package2');
vi.mock('../path/to/Todos.ts', { spy: true });

It's a lot simpler because it happens once in your Storybook. The downside is that if you want to manually mock the module in one set of stories and leave that module unmocked in other stories, e.g. for performance reasons, that is not possible. The crux of this proposal is that this is an acceptable constraint.

Specifying the mock

While mocking is global and declarative, we believe that specifying the mock should be co-located with your stories/tests. That's what's great about inline mocking, and that's also possible in this setup:

// TodoList.stories.ts
import type { Meta, StoryObj } from '@storybook/react';
import TodoList from './TodoList';
import Todos from './Todos';

const meta  = {
  component: TodoList
} satisfies Meta<typeof TodoList>;
export default meta;

type Story = StoryObj<typeof meta>;

const ALL_TODOS = [/* fixture data */];

// vi.mocked is a type helper
const { getTodos } = vi.mocked(Todos);

export const Empty: Story = {
  beforeEach() { getTodos.mockReturnValue([]) },
};

export const Full: Story = {
  beforeEach() { getTodos.mockReturnValue(ALL_TODOS) },
};

export const Dynamic: Story = {
  beforeEach() { getTodos.mockImplementation(/* some fn */) },
};

Benefits

We believe that the above scheme is simple and solves all of the problems listed above:

• More work. We’re no longer using subpath imports, so the user does not need to modify package.json. Nor is there an extra mock file.
• Invasive. We no longer need absolute imports, so the user does not need to modify their application/components.
• Finicky. We’re no longer using subpath imports, so we shouldn’t have any issues with e.g. TypeScript aliases. If we are able to reuse Vitest’s mocking logic, we should be as robust as Vitest in this regard.
• Global. This solution is still global, but its simplicity can help us encourage users to colocate their mocks with their tests as shown above. This is not as explicit as inline mocking, but we believe it's a big step in the right direction and a good tradeoff for simplicity.
• Unfamiliar. This pattern differs from inline mocking, but we believe it is close enough that the benefits far out weight the costs.

File-based mocking (advanced)

This scheme is more restrictive than inline mocking, so by definition it cannot satisfy every single use case. But the question is whether it can solve every single important use case. We know of one such use case, and to solve it, we also propose file-based mocking as an advanced maneuver.

In Jest, when the user creates path/to/__mocks__/File.ts, it will automatically use it to mock path/to/File.ts. In Vitest, the same is true, but the user has to explicitly enable it with vi.mock (see end of vi.mock docs).

We propose using this existing behavior when the user wants to implement a specific module behavior in their tests. This has come up in our own work on component testing RSCs. In the case where an RSC accesses a Node-based database client, we want to swap out the database module for an in-memory, browser-based mock.

By creating a mock file, lib/__mocks__/db.ts that mocks out the Node-equivalent lib/db.ts, we can ensure that the Node code is never loaded. The user would also need to declare this:

// .storybook/preview.ts
import type { Preview } from '@storybook/react';

const preview: Preview = {
  mocks: {
    manual: ['../lib/db.ts'],
  }
};
export default preview;

This also matches the Vitest behavior, so although the syntax of vi.mock vs mocks.manual is slightly different, conceptually and implementation-wise these should line up exactly.

Prior Art

We are building on the shoulders of giants by repacking Vitest's module mocking in a slightly more restrictive way, which in turn builds on Jest manual mocks.

Deliverables

1. Implementation. Update the Vite builder to implement the scheme above, leveraging Vitest's implementation entirely.
2. Experimental release. We would release it behind a feature flag to begin, to ensure that users are aware it’s an experimental feature.
3. Update documentation. This would include the new mocking features and best practices for how to use them.
4. Full release. Once the feature has stabilized, remove the feature flag and announce the feature.

Risks

It’s possible that even after doing more work for the subpath imports solution, users still want inline module mocking and Storybook Test remains uncompetitive when it comes to module mocking.

It's also possible that there are specific use cases that are important but not covered by the above scheme.

It's also possible that even with the restrictive version of module mocking, we are still unable to implement this in Webpack/Rspack if the time comes that we want to.

Unresolved Questions

• Should we use the existing pattern of lib/__mocks__/db.ts, or should we use the Storybook pattern of lib/db.mock.ts which is non-standard but feels a little nicer?

Alternatives considered / Abandoned Ideas

As mentioned above, we are also considering just supporting vi.mock directly, or potentially sb.mock which behaves identically. The main reason we're not doing this is that we don't want to commit to all of vi.mock's surface area.

[JReinhold]

I don't think there are actual use cases for inline mocking, it's more about familiarity. And AFAIK some Vitest maintainers are of the same opinion, they only have the functionality to be familiar with Jest, and not because they want to actually recommend setting different mocks per test/file.

I like that __mocks__/my-module.js will feel familiar to Vitest users and especially Jest users. And that's also the downside with the mocks annotation:

1. it is yet another concept to understand vs. just requiring __mocks__/my-module.js files, as users are used to.
2. it introduces manual and spy mocks, which I personally don't think anyone knows what is, I only learned about it yesterday.

For those reasons, personally I'd lean towards ditching the mocks annotation and always autoloading __mocks__, even though it does introduce more verbosity, because it requires a file for each module. It's more discoverable that way however, as you're now always co-locating the mock with the module, instead of in the global preview file. It's not as colocated as inline mocks would be, but it's closer at least.

One question I have though - which I think is relevant with our without the mocks annotation: Will this introduce mock collisions between test runners? Eg. if a user mocks out a module with __mocks__/my-module.js and uses mocks from Storybook, won't those same mocks be picked up by Jest/Vitest if you have unit tests that depends on that module? And I'd guess that will fail, because you can't use Storybook mocks in Jest/Vitest. The opposite situation also applies, where you have a Jest mock file and Storybook auto-loads that.
You can assume that the user wants the mock to behave the same in Vitest and Storybook, but the problem is that fn() is either imported from Storybook or Vitest.

I guess in these (probably very rare) situations, our current subpath imports would help solve the issue? Allowing users to point Storybook towards another mock file, potentially?

[shilman]

I personally like the pattern in the proposal better then the __mocks__ approach. Putting the mocks in the stories/test file is actually more colocated than a __mocks__ file. And I think 95% of the time you don't actually need the flexibility of the __mocks__ file, which is why I called it an advanced solution. The rest of the time you'd just be cluttering up your codebase with boilerplate. But I'm open to the solution and would like to hear what others think.

[shilman]

As for mock collisions that's actually a very good point. I suppose that subpath imports can always be a reasonable fallback as you suggest

[JReinhold]

Putting the mocks in the stories/test file is actually more colocated than a mocks file.

Yes but that's not the proposal here, is it? This proposal puts the mocks in the preview file, a place that is neither close to the stories nor the mocked module.

[kasperpeulen]

I would say the proposal is in the spirit of leveraging vitest automocking/autospying algorithm, so that people don't have to manually write mock files anymore, which are not (necessarily) close to their test/story file.

The actual mocks will be written in the story file:

// vi.mocked is a type helper
const { getTodos } = vi.mocked(Todos);

export const Empty: Story = {
  beforeEach() { getTodos.mockReturnValue([]) },
};

export const Full: Story = {
  beforeEach() { getTodos.mockReturnValue(ALL_TODOS) },
};

export const Dynamic: Story = {
  beforeEach() { getTodos.mockImplementation(/* some fn */) },
};

Which is in the (co)located in the story file.

I think you could see the stuff in preview as kind of a compiler hint, as you don't actually write the mock implementation there.

const preview = {
  mocks: [
    mock(import('../src/path/to/some/File'), { spy: true })
  ],
};

At least it is an improvement over having to write manual mock files all the time, which are not co-located as well,

[kylegach]

As far as the colocation argument goes, doesn't the pattern of:

1. Implement a mock that merely re-exports the actual module, wrapped in fn (e.g. as we recommend for subpath imports today)
2. Use fn utilities like mockedModule.mockReturnValue() or mockedModule.mockImplementation() in the stories file to manipulate the mock (again, as we currently document)

Allow for colocating the specifics of the mock with where it is used in the stories? The extra mock file is just boilerplate to enable the functionality. The important logic is colocated.

And, of course, this pattern could also apply to the API proposed here.

[shilman]

Yes, but the existence of that boilerplate is a temptation to mock the data there and I guarantee that users get confused about that (at least I do!). Removing it in all but advanced cases should help enforce best practices. I agree with your point though.

[kasperpeulen]

I like the proposal. I agree with @JReinhold that there is no existing familiarity with the mocks annotations.

We could consider adding a mock function that can only be used in the mocks annotations, similar to vi.mock:

import { mock } from 'storybook/test';

export default definePreview({
  mocks: [
    mock(import('../lib/db.ts')),
    mock(import('package1')),
    mock(import('../src/path/to/some/File.ts'), { spy: true })
  ],
});

This makes the API more familiar at first glance, but we can still keep it constrained:

• It will only have an effect when used in the mocks property and doesn't allow manual mocking a file, so that it is easier to extend this solution to other builders (webpack/rspack) some day.
• It only accepts an import('./module') statement for better typesafety and autocompletion for paths.

Vitest also supports a module promise instead of a string in the vi.mock and vi.doMock methods for better IDE support. When the file is moved, it will give a type error that the file doesn't exist anymore.

vi.mock(import('./path/to/module.js'))

[shilman]

Nice!! I like this improvement if we can make it work 🫶

[sheremet-va]

This was also my thought when I was reading this. The import auto-update is quite useful.

I hope one day we can do something like this without TypeScript being angry:

import Todos from './Todos' with { mock: 'spy' }
Todos.mockReturnValue([])

This is actually how I was planning to support this in the Browser Mode when Vite start supporting module attributes:

// __mocks__/Todos.ts
export * from './Todos' with { mock: 'spy' }
export default vi.fn().mockReturnValue([])

Which is similar to how Storybook already promotes the file based mocking.

[kettanaito]

My initial impression of seeing the subpath module mocking (using the special Storybook imports directive) was that it's quite brittle and will lead to developers constantly modifying their package.jsons when working in Storybook.

Instead, I encourage you to collocate module mocks with the layer that needs them, which in this case it's a story.

// stories/Dashboard.stories.tsx
mock(moduleIdentifier, implementation)

As to how to implement this, I think it's worth considering going ESM (if not already) and utilizing HTTP-based module mocking. Vitest does this to a great effect in the Browser Mode, where vi.mock() creates an MSW request handler for the provided module identifier. Look into that! Automatic module mocking in this case is a question of a permissive request handler with a response resolver that always responds with some module content (e.g. you can parse the original module and provide dummy exports to match the original ones).

You can also alias vi.mock from storybook, which I believe was suggested above too. I like that!

[shilman]

Thanks so much @kettanaito ! We will definitely run the Vitest-based POC by you when it's ready, which I believe is built on MSW under the hood. If we ever try to port this solution to another builder, we will need your expertise!!! 🙏

[kettanaito]

Sure thing! In-browser imports follow the same pattern so no matter the tooling, the mock implementation will remain the same (you can still sprinkle some DX on top).

[kettanaito]

Worth mentioning that Vitest is likely migrating away from using MSW for module mocking. You can double-check with the team regarding the reasoning and how that may affect your decision in adopting MSW for the same purpose in Storybook. Thanks!

[JReinhold]

How is this supposed to be implemented? AST parsing on the preview file?

[shilman]

Yeah, we would:

• parse preview.js and extract the mocks annotation
• then, either:
  • transform preview.js to add the corresponding inline mocks to the file
  • add a virtual module that does the inline mocks

I don't know what the corresponding Webpack, etc. implementation would look like, but that's not part of the proposal and it's assumed that we could figure that out if we really wanted it.

[yannbf]

Great RFC. What I wonder (and we should make clear is):

• How the __mocks__ solution will work in tandem with other testing solutions, as mocking something for Storybook could end up affecting non-Storybook tests which is not ideal (already mentioned by Jeppe)
• Whether all mocks done in story files (via vi.mocked(xyz)) will be used only for that story and get reset between stories. I believe there are already mechanisms for that, but we should write down how they'd work with this implementation

If this helps in any way, for reference, here are two community addons that provide ways of mocking:

• For Webpack based projects
• For Vite based projects

[IanVS]

IIUC, this will only be compatible with the vitest-based test runner, and not with @storybook/test-runner, right? It would be amazing to find a way to support both, but in the meantime, I wonder if this limiation should somehow be reflected in the configuration structure, to help avoid confusion and an increased reliance on documentation (which many users will not read). Failing that, it would be great to have a clear error message if someone does try to use these mocks without the vitest runner, to guide them in the right direction.

[shilman]

Indeed, great callout. Part of the motivation for proposing a simple, declarative API is that we think it should be possible to support this in multiple environments in the future. But at least to start, we'll be focused on making it work in Vitest only.

[valentinpalkovic]

The implementation I am currently working on will work in all Vite-based frameworks, and hence it will work in Storybook, Vitest, and of course also in the @storybook/test-runner.

[ndelangen]

how high is the combinatorial complexity of this RFC when considering:

• multiple builders
• docs & canvas
• portable stories
• stories.extend
• dev & build -modes
• use of args in mocks?
• isolation of stories from each other (fila 1, causing file 2 to behave differently)
• save-from-controls
• msw
• subpath imports

[valentinpalkovic]

Here's my assessment of the complexity when viewed through different lenses:

Multiple Builders: High complexity. We're starting with Vite, relying on @vitest/mocker which registers a Vite plugin. This is a great starting point, but it's not portable. To support other builders like Webpack or Rspack, we would need to reimplement the core module-swapping logic from scratch for each one. This is by far the biggest piece of work and the highest source of complexity for wider adoption.

Docs & Canvas: Low complexity. The proposed solution should be view-agnostic. Since the mock registration happens globally in the preview file and the mock data is supplied via beforeEach hooks at the story or meta level, it should work seamlessly in both Docs and Canvas views without extra effort.

Portable Stories: High complexity for cross-runner support. This implementation will only work with the @storybook/addon-vitest when it's using Vitest. It's not compatible with Jest because the mocking requires a code transformation step. To achieve true portability, we'd need to build a new transpiler-based solution (perhaps with SWC or Babel), which could then potentially be reused for Webpack support as well.

Dev & Build Modes: High complexity / Major TBD. The reliance on @vitest/mocker presents a significant challenge as it currently depends on a running dev server. This means our static build mode won't work out-of-the-box. We have a major architectural decision to make: either invest in making this work in a static build or pivot Storybook to always require a server (requires a heavy, long-term investment to make this work with the rest of the surrounding ecosystem), effectively deprecating the "fully static" build. This question is unresolved and adds significant complexity.

Use of Args in Mocks: Low complexity. This should work quite naturally. Args are accessible within the beforeEach hook, so users can easily leverage them to dynamically configure their mock data.

Isolation of Stories (file 1 vs. file 2): Low complexity. The pattern reuses established Vitest concepts. By encouraging users to set up and tear down mocks in beforeEach, we ensure that each story runs in isolation, preventing mock configurations from leaking between stories.

Save from Controls: Low complexity. Since we aren't changing the CSF syntax, I don't foresee any issues with features like "Save from Controls." When a user creates a new story in an existing file, it will copy the content of the source story, including any beforeEach mock setups. We wouldn't attempt to auto-generate mocks when creating a brand new story file from scratch, as that would be far too complex to infer reliably.

stories.extend: Low complexity. I don't see any immediate issues or conflicts arising from the use of stories.extend with this proposal.

MSW: Low complexity. There should be no conflict here. The proposed module mocking operates at the module level (swapping out code), while MSW operates at the network level (intercepting requests). They can coexist without interfering with each other.

Subpath Imports: Medium complexity. We inherit the same limitations that Vitest has. When a module is mocked via sb.mock(<module>), it must be referenced with a relative path. Path aliases like @ or ~ won't work in this context, which might be a point of friction for some users.

[shilman]

@valentinpalkovic Do you stand by your assessment now that you've implemented it?