Docs: Module mocking, and more

docs/api/parameters.md

@@ -141,6 +141,51 @@ When specifying a custom sorting function, the function behaves like a typical J
 
 See [the guide](../writing-stories/naming-components-and-hierarchy/#sorting-stories) for usage examples.
 
+### `test`
+
+Type:
+
+```ts
+{
+  clearMocks?: boolean;
+  mockReset?: boolean;
+  restoreMocks?: boolean;
+  dangerouslyIgnoreUnhandledErrors?: boolean;
+}
+```
+
+#### `clearMocks`
+
+Type: `boolean`
+
+Default: `false`
+
+[Similar to Vitest](https://vitest.dev/config/#clearmocks), it will call `.mockClear()` on all spies created with `fn()` from `@storybook/test` when a story unmounts. This will clear mock history, but not reset its implementation to the default one.
+
+#### `mockReset`
+
+Type: `boolean`
+
+Default: `false`
+
+[Similar to Vitest](https://vitest.dev/config/#mockreset), it will call `.mockReset()` on all spies created with `fn()` from `@storybook/test` when a story unmounts. This will clear mock history and reset its implementation to an empty function (will return `undefined`).
+
+#### `restoreMocks`
+
+Type: `boolean`
+
+Default: `true`
+
+[Similar to Vitest](https://vitest.dev/config/#restoremocks), it will call `.restoreMocks()` on all spies created with `fn()` from `@storybook/test` when a story unmounts. This will clear mock history and reset its implementation to the original one.
+
+#### `dangerouslyIgnoreUnhandledErrors`
+
+Type: `boolean`
+
+Default: `false`
+
+Setting this to `true` will prevent the [play function](../writing-stories/play-function.md) from failing and showing a warning when an uncaught exception is thrown.
+
 ---
 
 ### Essential addons

docs/configure/story-rendering.md

@@ -2,7 +2,28 @@
 title: 'Story rendering'
 ---
 
-In Storybook, your stories render in a particular “preview” iframe (Canvas tab) inside the larger Storybook web application. The JavaScript build configuration of the preview is controlled by a [webpack](../builders/webpack.md) config, but you also may want to directly control the rendered HTML to help your stories render correctly.
+In Storybook, your stories render in a particular “preview” iframe (also called the Canvas) inside the larger Storybook web application. The JavaScript build configuration of the preview is controlled by a [builder](../builders/index.md) config, but you also may want to run some code for every story or directly control the rendered HTML to help your stories render correctly.
+
+## Running code for every story
+
+Code executed in the preview file (`.storybook/preview.js|ts`) runs for every story in your Storybook. This is useful for setting up global styles, initializing libraries, or anything else required to render your components.
+
+For example, with Vue, you can extend Storybook's application and register your library (e.g., [Fontawesome](https://github.com/FortAwesome/vue-fontawesome)). Or with Angular, add the package ([localize](https://angular.io/api/localize)) into your `polyfills.ts` and import it:
+
+<!-- prettier-ignore-start -->
+
+<CodeSnippets
+  paths={[
+    'vue/storybook-preview-with-library-decorator.library-3.js.mdx',
+    'vue/storybook-preview-with-library-decorator.library-3.ts.mdx',
+    'vue/storybook-preview-with-hoc-component-decorator.component-3.js.mdx',
+    'vue/storybook-preview-with-hoc-component-decorator.component-3.ts.mdx',
+    'angular/add-localize-package-to-polyfills.ts.mdx',
+    'angular/storybook-preview-with-angular-polyfills.js.mdx',
+  ]}
+/>
+
+<!-- prettier-ignore-end -->
 
 ## Adding to &#60;head&#62;
 

docs/get-started/nextjs.md

@@ -671,6 +671,104 @@ import 'styles/globals.scss';
 // ...
 ```
 
+<Callout variant="warning">
+
+Absolute imports **cannot** be mocked in stories/tests. See the [Mocking modules](#mocking-modules) section for more information.
+
+</Callout>
+
+## Module aliases
+
+[Module aliases](https://nextjs.org/docs/app/building-your-application/configuring/absolute-imports-and-module-aliases#module-aliases) are also supported.
+
+```jsx
+// index.js
+// All good!
+import Button from '@/components/button';
+// Also good!
+import styles from '@/styles/HomePage.module.css';
+
+export default function HomePage() {
+  return (
+    <>
+      <h1 className={styles.title}>Hello World</h1>
+      <Button />
+    </>
+  );
+}
+```
+
+## Subpath imports
+
+As an alternative to [module aliases](#module-aliases), you can use [subpath imports](https://nodejs.org/api/packages.html#subpath-imports) to import modules. This follows Node package standards and has benefits when [mocking modules](#mocking-modules).
+
+To configure subpath imports, you define the `imports` property in your project's `package.json` file. This property maps the subpath to the actual file path. The example below configures subpath imports for all modules in the project:
+
+```json
+// package.json
+{
+  "imports": {
+    "#*": ["./*", "./*.ts", "./*.tsx"]
+  }
+}
+```
+
+<Callout variant="info">
+
+Because subpath imports take the place of module aliases, you can remove the path aliases from your TypeScript configuration.
+
+</Callout>
+
+Which can then be used like this:
+
+```jsx
+// index.js
+import Button from '#components/button';
+import styles from '#styles/HomePage.module.css';
+
+export default function HomePage() {
+  return (
+    <>
+      <h1 className={styles.title}>Hello World</h1>
+      <Button />
+    </>
+  );
+}
+```
+
+## Mocking modules
+
+Components often depend on modules that are imported into the component file. These can be from external packages or internal to your project. When rendering those components in Storybook or testing them, you may want to [mock those modules](../writing-stories/mocking-modules.md) to control and assert their behavior.
+
+### Built-in mocked modules
+
+This framework provides mocks for many of Next.js' internal modules:
+
+1. [`@storybook/nextjs/cache.mock`](#storybooknextjscachemock)
+2. [`@storybook/nextjs/headers.mock`](#storybooknextjsheadersmock)
+3. [`@storybook/nextjs/navigation.mock`](#storybooknextjsnavigationmock)
+4. [`@storybook/nextjs/router.mock`](#storybooknextjsroutermock)
+
+### Mocking other modules
+
+How you mock other modules in Storybook depends on how you import the module into your component.
+
+The first step, with either approach, is to [create a mock file](../writing-stories/mocking-modules.md#mock-files).
+
+TK: More here?
+
+#### With subpath imports
+
+If you're using [subpath imports](#subpath-imports), you can adjust your configuration to apply [conditions](../writing-stories/mocking-modules.md#conditional-imports) so that the mocked module is used inside Storybook.
+
+TK: Add example of mocking modules with subpath imports
+
+#### With module aliases
+
+If you're using [module aliases](#module-aliases), you can add a Webpack alias to your Storybook configuration to point to the mock file.
+
+TK: Add example of mocking modules with module aliases
+
 ## Runtime config
 
 Next.js allows for [Runtime Configuration](https://nextjs.org/docs/pages/api-reference/next-config-js/runtime-configuration) which lets you import a handy `getConfig` function to get certain configuration defined in your `next.config.js` file at runtime.
@@ -783,6 +881,12 @@ If your server components access data via the network, we recommend using the [M
 
 In the future we will provide better mocking support in Storybook and support for [Server Actions](https://nextjs.org/docs/app/api-reference/functions/server-actions).
 
+## Portable stories
+
+You can test your stories in a Jest environment by using the [portable stories](../api/portable-stories-jest.md) API.
+
+When using portable stories with Next.js, you need to mock the Next.js modules that your components depend on. You can use the [`@storybook/nextjs/export-mocks` module](#storybooknextjsexport-mocks) to generate the aliases needed to set up portable stories in a Jest environment.
+
 ## Notes for Yarn v2 and v3 users
 
 If you're using [Yarn](https://yarnpkg.com/) v2 or v3, you may run into issues where Storybook can't resolve `style-loader` or `css-loader`. For example, you might get errors like:
@@ -885,54 +989,83 @@ You can refer to the [Install `sharp` to Use Built-In Image Optimization](https:
 
 ## API
 
-### Parameters
+### Modules
 
-This framework contributes the following [parameters](../writing-stories/parameters.md) to Storybook, under the `nextjs` namespace:
+The `@storybook/nextjs` package exports a number of modules that enables you to [mock](#mocking-modules) Next.js's internal behavior.
 
-#### `appDirectory`
+#### `@storybook/nextjs/export-mocks`
 
-Type: `boolean`
+Type: `{ getPackageAliases: ({ useESM?: boolean }) => void }`
 
-Default: `false`
+`getPackageAliases` is a helper to generate the aliases needed to set up [portable stories](#portable-stories).
 
-If your story imports components that use `next/navigation`, you need to set the parameter `nextjs.appDirectory` to `true`. Because this is a parameter, you can apply it to a [single story](../api/parameters.md#story-parameters), [all stories for a component](../api/parameters.md#meta-parameters), or [every story in your Storybook](../api/parameters.md#project-parameters). See [Next.js Navigation](#nextjs-navigation) for more details.
+```ts
+import type { Config } from 'jest';
+import nextJest from 'next/jest.js';
+// 👇 import the utility function
+import { getPackageAliases } from '@storybook/nextjs/export-mocks';
+
+const createJestConfig = nextJest({
+  // Provide the path to your Next.js app to load next.config.js and .env files in your test environment
+  dir: './',
+});
+
+// Add any custom config to be passed to Jest
+const config: Config = {
+  coverageProvider: 'v8',
+  testEnvironment: 'jsdom',
+  // Add more setup options before each test is run
+  // setupFilesAfterEnv: ['<rootDir>/jest.setup.ts'],
+  moduleNameMapper: {
+    ...getPackageAliases(), // 👈 add the utility as a moduleNameMapper
+  },
+};
 
-#### `navigation`
+// createJestConfig is exported this way to ensure that next/jest can load the Next.js config which is async
+export default createJestConfig(config);
+```
 
-Type:
+#### `@storybook/nextjs/cache.mock`
 
-```ts
-{
-  asPath?: string;
-  pathname?: string;
-  query?: Record<string, string>;
-  segments?: (string | [string, string])[];
-}
-```
+Type: `typeof import('next/cache')`
 
-Default value:
+TK: Description
 
-```js
-{
-  segments: [];
-}
-```
+TK: Example snippet
 
-The router object that is passed to the `next/navigation` context. See [Next.js's navigation docs](https://nextjs.org/docs/app/building-your-application/routing) for more details.
+#### `@storybook/nextjs/headers.mock`
 
-#### `router`
+Type: [`cookies`](https://nextjs.org/docs/app/api-reference/functions/cookies#cookiessetname-value-options), [`headers`](https://nextjs.org/docs/app/api-reference/functions/headers) and [`draftMode`](https://nextjs.org/docs/app/api-reference/functions/draft-mode) from Next.js
 
-Type:
+Exports _writable_ mocks that replaces the actual implementation of `next/headers` exports. Use this to set up cookies or headers that are read in your story, and to later assert that they have been called.
 
-```ts
-{
-  asPath?: string;
-  pathname?: string;
-  query?: Record<string, string>;
-}
-```
+Next.js's default [`headers()`](https://nextjs.org/docs/app/api-reference/functions/headers) export is read-only, but this module exposes methods allowing you to write to the headers:
 
-The router object that is passed to the `next/router` context. See [Next.js's router docs](https://nextjs.org/docs/pages/building-your-application/routing) for more details.
+- **`headers().append(name: string, value: string)`**: Appends the value to the header if it exists already.
+- **`headers().delete(name: string)`**: Deletes the header
+- **`headers().set(name: string, value: string)`**: Sets the header to the value provided.
+
+For cookies, you can use the existing API to write them, eg. `cookies().set('firstName', 'Jane')`.
+
+Because `headers()`, `cookies()` and their sub-functions are all mocks you can use any [mock utilities](https://vitest.dev/api/mock.html) in your stories, like `headers().getAll.mock.calls`.
+
+TK: Example snippet
+
+#### `@storybook/nextjs/navigation.mock`
+
+Type: `typeof import('next/navigation')`
+
+Exports mocks that replaces the actual implementation of `next/navigation` exports. Use these to mock implementations or assert on mock calls in a story's `play`-function.
+
+TK: Example snippet
+
+#### `@storybook/nextjs/router.mock`
+
+Type: `typeof import('next/router')`
+
+Exports mocks that replaces the actual implementation of `next/router` exports. Use these to mock implementations or assert on mock calls in a story's `play`-function.
+
+TK: Example snippet
 
 ### Options
 
@@ -976,6 +1109,55 @@ Type: `string`
 
 The absolute path to the `next.config.js` file. This is necessary if you have a custom `next.config.js` file that is not in the root directory of your project.
 
+### Parameters
+
+This framework contributes the following [parameters](../writing-stories/parameters.md) to Storybook, under the `nextjs` namespace:
+
+#### `appDirectory`
+
+Type: `boolean`
+
+Default: `false`
+
+If your story imports components that use `next/navigation`, you need to set the parameter `nextjs.appDirectory` to `true`. Because this is a parameter, you can apply it to a [single story](../api/parameters.md#story-parameters), [all stories for a component](../api/parameters.md#meta-parameters), or [every story in your Storybook](../api/parameters.md#project-parameters). See [Next.js Navigation](#nextjs-navigation) for more details.
+
+#### `navigation`
+
+Type:
+
+```ts
+{
+  asPath?: string;
+  pathname?: string;
+  query?: Record<string, string>;
+  segments?: (string | [string, string])[];
+}
+```
+
+Default value:
+
+```js
+{
+  segments: [];
+}
+```
+
+The router object that is passed to the `next/navigation` context. See [Next.js's navigation docs](https://nextjs.org/docs/app/building-your-application/routing) for more details.
+
+#### `router`
+
+Type:
+
+```ts
+{
+  asPath?: string;
+  pathname?: string;
+  query?: Record<string, string>;
+}
+```
+
+The router object that is passed to the `next/router` context. See [Next.js's router docs](https://nextjs.org/docs/pages/building-your-application/routing) for more details.
+
 <!-- End supported renderers -->
 
 </If>