Documenting storybook test package

code/addons/interactions/README.md

@@ -9,7 +9,7 @@ Storybook Addon Interactions enables visual debugging of interactions and tests
 Install this addon by adding the `@storybook/addon-interactions` dependency:
 
 ```sh
-yarn add -D @storybook/addon-interactions @storybook/jest @storybook/testing-library
+yarn add -D @storybook/addon-interactions @storybook/test
 ```
 
 within `.storybook/main.js`:
@@ -24,19 +24,17 @@ Note that `@storybook/addon-interactions` must be listed **after** `@storybook/a
 
 ## Usage
 
-Interactions relies on "instrumented" versions of Jest and Testing Library, that you import from `@storybook/jest` and
-`@storybook/testing-library` instead of their original package. You can then use these libraries in your `play` function.
+Interactions relies on "instrumented" versions of Vitest and Testing Library, that you import from `@storybook/test` instead of their original package. You can then use these libraries in your `play` function.
 
 ```js
 import { Button } from './Button';
-import { expect } from '@storybook/jest';
-import { within, userEvent } from '@storybook/testing-library';
+import { within, userEvent, expect, fn } from '@storybook/test';
 
 export default {
   title: 'Button',
   component: Button,
-  argTypes: {
-    onClick: { action: true },
+  args: {
+    onClick: fn(),
   },
 };
 
@@ -45,17 +43,13 @@ const Template = (args) => <Button {...args} />;
 export const Demo = Template.bind({});
 Demo.play = async ({ args, canvasElement }) => {
   const canvas = within(canvasElement);
-  await userEvent.click(canvas.getByRole('button'));
+  await userEvent.click(await canvas.getByRole('button'));
   await expect(args.onClick).toHaveBeenCalled();
 };
 ```
 
-In order to enable step-through debugging, calls to `userEvent.*`, `fireEvent`, `findBy*`, `waitFor*` and `expect` have to
+In order to enable step-through debugging in the addon panel, calls to `userEvent.*`, `fireEvent`, `findBy*`, `waitFor*` and `expect` have to
 be `await`-ed. While debugging, these functions return a Promise that won't resolve until you continue to the next step.
 
 While you can technically use `screen`, it's recommended to use `within(canvasElement)`. Besides giving you a better error
 message when a DOM element can't be found, it will also ensure your play function is compatible with Storybook Docs.
-
-Any `args` that are marked as an `action` (typically via `argTypes` or `argTypesRegex`) will be automatically wrapped in
-a [Jest mock function](https://jestjs.io/docs/jest-object#jestfnimplementation) so you can assert invocations. See
-[addon-actions](https://storybook.js.org/docs/react/essentials/actions) for how to setup actions.

code/lib/instrumenter/README.md

@@ -31,7 +31,7 @@ Depending on the library and functions to be instrumented, you may want to confi
 
 `intercept` can take either a boolean (default `false`) or a function which returns a boolean. This enables you to only make specific library functions interceptable. This function receives a `method` and `path`, referring to the name of the function and the path to that function in the object tree. Some functions may return an object which is then instrumented as well, in which case the `path` will contain a "call ref", which is a plain object containing a `__callId__` property referencing the originating call.
 
-Here's an example `intercept` function (from `@storybook/testing-library`):
+Here's an example `intercept` function (from `@storybook/test`):
 
 ```js
 (method, path) => path[0] === 'fireEvent' || method.startsWith('findBy') || method.startsWith('waitFor'),

docs/essentials/actions.md

@@ -68,7 +68,7 @@ If you need more granular control over which `argTypes` are matched, you can adj
 
 <!-- prettier-ignore-end -->
 
-This is quite useful when your component has dozens (or hundreds) of methods and you do not want to manually use the `fn` function for each of those methods. However, **this is not the recommended** way of writing actions, especially if you are using the play function in your stories. That's because automatically inferred args **are not** turned into functions when passed down to the components. As a result, if your component relies on invoking functions passed down via args, they won't exist and your component will fail at rendering.
+This is quite useful when your component has dozens (or hundreds) of methods and you do not want to manually use the `fn` function for each of those methods. However, **this is not the recommended** way of writing actions. That's because automatically inferred args **are not available as spies in your play function**. If you use `argTypesRegex` and your stories have play functions, make sure to always explicitly define args with the `fn` function so you can test them in your play function.
 
 <div class="aside">
 

docs/essentials/interactions.md

@@ -10,9 +10,9 @@ Stories isolate and capture component states in a structured manner. While devel
 
 For example, clicking a button to open/close a dialog box, dragging a list item to reorder it, or filling out a form to check for validation errors. To test those behaviors, you have to interact with the components as a user would. Interactive stories enable you to automate these interactions using a play function. They are small snippets of code that run once the story finishes rendering, emulating the exact steps a user would take to interact with the component.
 
-### Powered by Testing Library and Jest
+### Powered by Testing Library and Vitest
 
-The interactions are written using a Storybook-instrumented version of [Testing Library](https://testing-library.com/) and [Jest](https://jestjs.io/). That gives you a familiar developer-friendly syntax to interact with the DOM and make assertions, but with extra telemetry to help with debugging.
+The interactions are written using a package called `@storybook/test`. It provides Storybook-instrumented versions of [Testing Library](https://testing-library.com/) and [Vitest](https://vitest.dev). That gives you a familiar developer-friendly syntax to interact with the DOM and make assertions, but with extra telemetry to help with debugging.
 
 ## Set up the interactions addon
 
@@ -47,7 +47,7 @@ Next, update [`.storybook/main.js|ts`](../configure/overview.md#configure-story-
 
 <div class="aside">
 
-💡 Make sure to list `@storybook/addon-interactions` **after** the [`@storybook/addon-essentials`](./introduction.md) addon (or the [`@storybook/addon-actions`](./actions.md) if you've installed it individually).
+💡 Make sure to list `@storybook/addon-interactions` **after** the [`@storybook/addon-essentials`](./introduction.md) addon.
 
 </div>
 
@@ -59,7 +59,7 @@ Now when you run Storybook, the Interactions addon will be enabled.
 
 Interactions run as part of the `play` function of your stories. We rely on Testing Library to do the heavy lifting.
 
-Make sure to import the Storybook wrappers for Jest and Testing Library rather than importing Jest and Testing Library directly.
+Make sure to import the Storybook wrappers for Vitest and Testing Library via `@storybook/test` rather than importing the original packages directly.
 
 <!-- prettier-ignore-start -->
 
@@ -81,10 +81,4 @@ The above example uses the `canvasElement` to scope your element queries to the
 
 While you can refer to the [Testing Library documentation](https://testing-library.com/docs/) for details on how to use it, there's an important detail that's different when using the Storybook wrapper: **method invocations must be `await`-ed**. It allows you to step back and forth through your interactions using the debugger.
 
-Any `args` that have been marked as an Action, either using the [argTypes annotation](./actions.md#action-argtype-annotation) or the [argTypesRegex](./actions.md#automatically-matching-args), will be automatically converted to a [Jest mock function](https://jestjs.io/docs/mock-function-api) (spy). This allows you to make assertions about calls to these functions.
-
-<div class="aside">
-
-ℹ️ To mock functions in your Storybook stories for reliable and isolated component testing, use the `jest` import from `@storybook/jest`. This allows you to avoid configuring Jest globally in your project.
-
-</div>
+In the example above, the `fn` helper is used in the arg, which maps to [`vi.fn`](https://vitest.dev/api/vi.html#vi-fn), a Vitest spy utility that allows you to make assertions about calls to these functions. This makes it possible to assert whether the function of that arg was called during the play function.

docs/get-started/why-storybook.md

@@ -133,7 +133,7 @@ Storybook is compatible with your continuous integration workflow. Add it as a C
 
 Storybook is powered by [Component Story Format](https://github.com/ComponentDriven/csf), an open standard based on JavaScript ES6 modules. This enables stories to interoperate between development, testing, and design tools. Each story is exported as a JavaScript function enabling you to reuse it with other tools. No vendor lock-in.
 
-Reuse stories with [Jest](https://jestjs.io/) and [Testing Library](https://testing-library.com/) to verify interactions. Put them in [Chromatic](https://www.chromatic.com/?utm_source=storybook_website&utm_medium=link&utm_campaign=storybook) for visual testing. Audit story accessibility with [Axe](https://github.com/dequelabs/axe-core). Or test user flows with [Playwright](https://playwright.dev/) and [Cypress](https://www.cypress.io/). Reuse unlocks more workflows at no extra cost.
+Reuse stories with [Jest](https://jestjs.io/) or [Vitest](https://vitest.dev/) and [Testing Library](https://testing-library.com/) to verify interactions. Put them in [Chromatic](https://www.chromatic.com/?utm_source=storybook_website&utm_medium=link&utm_campaign=storybook) for visual testing. Audit story accessibility with [Axe](https://github.com/dequelabs/axe-core). Or test user flows with [Playwright](https://playwright.dev/) and [Cypress](https://www.cypress.io/). Reuse unlocks more workflows at no extra cost.
 
 ---
 

docs/snippets/angular/storybook-interactions-play-function.ts.mdx

@@ -10,6 +10,7 @@ import { Form } from './Form.component';
 const meta: Meta<Form> = {
   component: MyComponent,
   args: {
+    // transform the arg into a spy
     onSubmit: fn(),
   },
 };
@@ -34,6 +35,7 @@ export const Submitted: Story = {
       await userEvent.click(canvas.getByRole('button'));
     });
 
+    // onSubmit is a spy so it can be asserted in various ways
     await waitFor(() => expect(args.onSubmit).toHaveBeenCalled());
   },
 };

docs/snippets/common/storybook-interactions-play-function.js.mdx

@@ -8,6 +8,7 @@ import { Form } from './Form';
 export default {
   component: Form,
   args: {
+    // transform the arg into a spy
     onSubmit: fn(),
   },
 };
@@ -30,6 +31,7 @@ export const Submitted = {
       await userEvent.click(canvas.getByRole('button'));
     });
 
+    // onSubmit is a spy so it can be asserted in various ways
     await waitFor(() => expect(args.onSubmit).toHaveBeenCalled());
   },
 };

docs/snippets/common/storybook-interactions-play-function.ts-4-9.mdx

@@ -11,6 +11,7 @@ import { Form } from './Form';
 const meta = {
   component: Form,
   args: {
+    // transform the arg into a spy
     onSubmit: fn(),
   },
 } satisfies Meta<typeof Form>;
@@ -35,6 +36,7 @@ export const Submitted: Story = {
       await userEvent.click(canvas.getByRole('button'));
     });
 
+    // onSubmit is a spy so it can be asserted in various ways
     await waitFor(() => expect(args.onSubmit).toHaveBeenCalled());
   },
 };

docs/snippets/common/storybook-interactions-play-function.ts.mdx

@@ -11,6 +11,7 @@ import { Form } from './Form';
 const meta: Meta<typeof Form> = {
   component: Form,
   args: {
+    // transform the arg into a spy
     onSubmit: fn(),
   },
 };
@@ -35,6 +36,7 @@ export const Submitted: Story = {
       await userEvent.click(canvas.getByRole('button'));
     });
 
+    // onSubmit is a spy so it can be asserted in various ways
     await waitFor(() => expect(args.onSubmit).toHaveBeenCalled());
   },
 };

docs/snippets/web-components/storybook-interactions-play-function.js.mdx

@@ -6,6 +6,7 @@ import { userEvent, waitFor, within, expect, fn } from '@storybook/test';
 export default {
   component: 'my-form-element',
   args: {
+    // transform the arg into a spy
     onSubmit: fn(),
   },
 };
@@ -27,6 +28,7 @@ export const Submitted = {
       await userEvent.click(canvas.getByRole('button'));
     });
 
+    // onSubmit is a spy so it can be asserted in various ways
     await waitFor(() => expect(args.onSubmit).toHaveBeenCalled());
   },
 };

docs/snippets/web-components/storybook-interactions-play-function.ts.mdx

@@ -8,6 +8,7 @@ import { userEvent, waitFor, within, expect, fn } from '@storybook/test';
 const meta: Meta = {
   component: 'my-form-element',
   args: {
+    // transform the arg into a spy
     onSubmit: fn(),
   },
 };
@@ -32,6 +33,7 @@ export const Submitted: Story = {
       await userEvent.click(canvas.getByRole('button'));
     });
 
+    // onSubmit is a spy so it can be asserted in various ways
     await waitFor(() => expect(args.onSubmit).toHaveBeenCalled());
   },
 };

docs/writing-tests/interaction-testing.md

@@ -20,7 +20,7 @@ In Storybook, this familiar workflow happens in your browser. That makes it easi
 You start by writing a [**story**](../writing-stories/introduction.md) to set up the component's initial state. Then simulate user behavior using the **play** function. Finally, use the **test-runner** to confirm that the component renders correctly and that your interaction tests with the **play** function pass. Additionally, you can automate test execution via the [command line](./test-runner.md#cli-options) or in your [CI environment](./test-runner.md#set-up-ci-to-run-tests).
 
 - The [`play`](../writing-stories/play-function.md) function is a small snippet of code that runs after a story finishes rendering. You can use this to test user workflows.
-- The test is written using Storybook-instrumented versions of [Jest](https://jestjs.io/) and [Testing Library](https://testing-library.com/).
+- The test is written using Storybook-instrumented versions of [Vitest](https://vitest.dev/) and [Testing Library](https://testing-library.com/) coming from the [`@storybook/test`](https://npmjs.com/package/@storybook/test) package.
 - [`@storybook/addon-interactions`](https://storybook.js.org/addons/@storybook/addon-interactions/) visualizes the test in Storybook and provides a playback interface for convenient browser-based debugging.
 - [`@storybook/test-runner`](https://github.com/storybookjs/test-runner) is a standalone utility—powered by [Jest](https://jestjs.io/) and [Playwright](https://playwright.dev/)—that executes all of your interactions tests and catches broken stories.
 
@@ -91,7 +91,7 @@ Once the story loads in the UI, it simulates the user's behavior and verifies th
 
 ### API for user-events
 
-Under the hood, Storybook’s interaction addon mirrors Testing Library’s [`user-events`](https://testing-library.com/docs/user-event/intro/) API. If you’re familiar with [Testing Library](https://testing-library.com/), you should be at home in Storybook.
+Under the hood, Storybook’s `@storybook/test` package provides Testing Library’s [`user-events`](https://testing-library.com/docs/user-event/intro/) APIs. If you’re familiar with [Testing Library](https://testing-library.com/), you should be at home in Storybook.
 
 Below is an abridged API for user-event. For more, check out the [official user-event docs](https://testing-library.com/docs/user-event/utility/).
 
@@ -107,6 +107,27 @@ Below is an abridged API for user-event. For more, check out the [official user-
 | `type`            | Writes text inside inputs, or textareas <br/>`userEvent.type(await within(canvasElement).getByRole('my-input'),'Some text');`                            |
 | `unhover`         | Unhovers out of element <br/>`userEvent.unhover(await within(canvasElement).getByLabelText(/Example/i));`                                                |
 
+### Assert tests with Vitest's APIs
+
+Storybook’s `@storybook/test` also provides APIs from [Vitest](https://vitest.dev/), such as [`expect`](https://vitest.dev/api/expect.html#expect) and [`vi.fn`](https://vitest.dev/api/vi.html#vi-fn). These APIs improve your testing experience, helping you assert whether a function has been called, or an element exists in the DOM, and much more. If you are used to `expect` from testing packages such as [Jest](https://jestjs.io/) or [Vitest](https://vitest.dev/), you will feel at home.
+
+<!-- prettier-ignore-start -->
+
+<CodeSnippets
+  paths={[
+    'angular/storybook-interactions-play-function.ts.mdx',
+    'web-components/storybook-interactions-play-function.js.mdx',
+    'web-components/storybook-interactions-play-function.ts.mdx',
+    'common/storybook-interactions-play-function.js.mdx',
+    'common/storybook-interactions-play-function.ts.mdx',
+  ]}
+  usesCsf3
+  csf2Path="essentials/interactions#snippet-storybook-interactions-play-function"
+/>
+
+<!-- prettier-ignore-end -->
+
+
 ### Group interactions with the `step` function
 
 For complex flows, it can be worthwhile to group sets of related interactions together using the `step` function. This allows you to provide a custom label that describes a set of interactions: