Merge pull request #26858 from storybookjs/module-mocking-docs

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`
+
+Unhandled errors might cause false positive assertions. Setting this to `true` will prevent the [play function](../writing-stories/play-function.md) from failing and showing a warning when unhandled errors are thrown during execution.
+
 ---
 
 ### Essential addons

docs/api/portable-stories-jest.md

@@ -26,10 +26,11 @@ Normally, Storybok composes a story and its [annotations](#annotations) automati
 
 <Callout variant="info">
 
-**Using `Next.js`?** You need to do two things differently when using portable stories in Jest with Next.js projects:
+**Using `Next.js`?** You need to do three things differently when using portable stories in Jest with Next.js projects:
 
 - Configure the [`next/jest.js` transformer](https://nextjs.org/docs/pages/building-your-application/testing/jest#manual-setup), which will handle all of the necessary Next.js configuration for you.
 - Import [`composeStories`](#composestories) or [`composeStory`](#composestory) from the `@storybook/nextjs` package (e.g. `import { composeStories } from '@storybook/nextjs'`).
+- Set up [internal module aliases](../get-started/nextjs.md#storybooknextjsexport-mocks) to ensure the framework configuration works correctly and to be able to mock and assert on them.
 
 </Callout>
 

docs/configure/images-and-assets.md

@@ -42,8 +42,8 @@ Configure a directory (or a list of directories) where your assets live when sta
 
 <CodeSnippets
  paths={[
- 'common/storybook-main-with-single-static-dir.js.mdx',
- 'common/storybook-main-with-single-static-dir.ts.mdx',
+ 'common/main-config-static-dirs.js.mdx',
+ 'common/main-config-static-dirs.ts.mdx',
  ]}
 />
 

docs/configure/story-rendering.md

@@ -2,7 +2,54 @@
 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.
+
+<If notRenderer={['angular', 'vue']}>
+
+Here's an example of how you might use the preview file to initialize a library that must run before your components render:
+
+```ts
+// .storybook/preview.ts
+// Replace your-renderer with the renderer you are using (e.g., react, vue3)
+import { Preview } from '@storybook/your-renderer';
+
+import { initialize } from '../lib/your-library';
+
+initialize();
+
+const preview: Preview = {
+ // ...
+};
+
+export default preview;
+```
+
+</If>
+
+<If renderer={['angular', 'vue']}>
+
+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 -->
+
+</If>
 
 ## Adding to &#60;head&#62;