4.3 KiB
| title |
|---|
| Actions |
The actions addon is used to display data received by event handler (callback) arguments in your stories.
Action args
Actions work via supplying special Storybook-generated “action” arguments (referred to as "args" for short) to your stories. There are two ways to get an action arg:
Via @storybook/test fn spy function
The first and recommended way to write actions, is to use the fn function from @storybook/test. This package provides a utility to help mock and spy args, which is very useful for writing tests with the play function. You can mock your component's methods by assigning them with the fn() function:
<CodeSnippets paths={[ 'angular/button-story-onclick-action-spy.ts.mdx', 'common/button-story-onclick-action-spy.js.mdx', 'common/button-story-onclick-action-spy.ts.mdx', ]} />
If your component calls an arg which is spied on (based on the user's interaction or through the play function), the event will show up in the action panel:
Automatically matching args
Another option is to use a global parameter to match all argTypes that match a certain pattern. The following configuration automatically creates actions for each on argType (which you can either specify manually or can be inferred automatically).
<CodeSnippets paths={[ 'common/storybook-preview-matching-argtypes.js.mdx', 'common/storybook-preview-matching-argtypes.ts.mdx', ]} />
If you need more granular control over which argTypes are matched, you can adjust your stories and include the argTypesRegex parameter. For example:
<CodeSnippets paths={[ 'angular/button-story-matching-argtypes.ts.mdx', 'web-components/button-story-matching-argtypes.js.mdx', 'web-components/button-story-matching-argtypes.ts.mdx', 'common/button-story-matching-argtypes.js.mdx', 'common/button-story-matching-argtypes.ts.mdx', ]} />
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.
💡 If you're generating argTypes with another addon (like docs, which is the common behavior), ensure the actions addon AFTER the other addon. You can do this by listing it later in the addons registration code in .storybook/main.js. This is default in essentials.
Action event handlers
It is also possible to detect if your component is emitting the correct HTML events using the parameters.actions.handles parameter.
<CodeSnippets paths={[ 'angular/button-story-action-event-handle.ts.mdx', 'web-components/button-story-action-event-handle.js.mdx', 'web-components/button-story-action-event-handle.ts.mdx', 'common/button-story-action-event-handle.js.mdx', 'common/button-story-action-event-handle.ts.mdx', ]} />
This will bind a standard HTML event handler to the outermost HTML element rendered by your component and trigger an action when the event is called for a given selector. The format is <eventname> <selector>. The selector is optional; it defaults to all elements.
Advanced / legacy usage
There are also some older ways to use actions as documented in the advanced README.