Storybook framework

Mocking

Mock Nuxt auto-imports, components and server endpoints in your stories.

@storybook-vue/nuxt ships mocking helpers of @nuxt/test-utils, adapted to Storybook.

Called at the top level of a story file, they apply to every story of that file. Called in a hook of a story, they apply to that story only.

mockNuxtImport

Replaces an auto-import for the stories of the file, and returns its storybook/test spy.

components/MyGreeting.stories.ts
import { 
mockNuxtImport
} from '@storybook-vue/nuxt'
import {
expect
,
within
} from 'storybook/test'
import
preview
from '../.storybook/preview'
import
MyGreeting
from './MyGreeting.vue'
const
useGreeting
=
mockNuxtImport
(
'useGreeting', () => (
name
: string) => `Bonjour ${
name
}`,
) const
meta
=
preview
.
meta
({
component
:
MyGreeting
,
args
: {
name
: 'Nuxt' } })
export const
Mocked
=
meta
.
story
({
async
play
({
canvasElement
}) {
await
expect
(
within
(
canvasElement
).
getByText
('Bonjour Nuxt')).
toBeVisible
()
await
expect
(
useGreeting
).
toHaveBeenCalledWith
('Nuxt')
}, })

Like in @nuxt/test-utils, the factory can be async, and the import can be named by itself instead of a string:

components/MyRouting.stories.ts
import { 
mockNuxtImport
} from '@storybook-vue/nuxt'
import {
useRoute
} from '#imports'
mockNuxtImport
(
useRoute
, () => () => ({
fullPath
: '/mocked' }))

The name must be a string literal or the import itself, and each name can only be mocked once per file. Without a factory, the import keeps its implementation and is only spied on.

Like a hoisted vi.mock, a factory runs once, when the story file loads: the mock is in place before the loaders, beforeEach and play of its stories run.

mockComponent

Replaces a Nuxt component for the stories of the file. It takes the mock component, or a factory returning it or importing a .vue file.

components/MyProfile.stories.ts
import { 
mockComponent
} from '@storybook-vue/nuxt'
mockComponent
('MyAvatar', () => import('./MyAvatar.mock.vue'))

Like in @nuxt/test-utils, the component can also be named in kebab case, or by its path, relative to the story file or with an alias:

components/MyProfile.stories.ts
import { 
h
} from 'vue'
mockComponent
('~/components/MyAvatar.vue', {
props
: {
name
:
String
},
setup
: (
props
) => () =>
h
('span', `👤 ${
props
.name}`),
})

The name must be a string literal, and it must name a Nuxt component.

Story mocks

Mock functions can be called in the loaders, beforeEach and play written in a story file. They then apply to that story only, over the mocks of the file:

components/MyGreeting.stories.ts
export const 
German
=
meta
.
story
({
beforeEach
() {
mockNuxtImport
('useGreeting', () => (
name
: string) => `Hallo ${
name
}`)
mockComponent
('MyAvatar', () => import('./MyAvatar.german.vue'))
registerEndpoint
('/api/users', () => ['Hans'])
}, })

registerEndpoint

Answers requests made with $fetch, useFetch or fetch from inside the preview, with an h3 handler running on your project's h3 version.

components/MyUsers.stories.ts
import { 
registerEndpoint
} from '@storybook-vue/nuxt'
// Every story of this file
registerEndpoint
('/api/users', () => ['Alice', 'Bob'])
export const
Empty
=
meta
.
story
({
// This story only, before the endpoints of the file
beforeEach
() {
registerEndpoint
('/api/users', () => [])
}, }) export const
Created
=
meta
.
story
({
// Or with the story parameters
parameters
: {
nuxt
: {
endpoints
: {
'/api/users': {
method
: 'POST',
handler
: () => ({
ok
: true }) },
}, }, }, })

A story stays on its route: router navigations, navigateTo(url, { external: true }), navigateTo(url, { open }) and clicks on links to other sites are blocked, and reported to the navigation spy instead:

components/MyNavigate.stories.ts
import { 
navigation
} from '@storybook-vue/nuxt'
import {
expect
,
userEvent
,
within
} from 'storybook/test'
export const
Docs
=
meta
.
story
({
async
play
({
canvasElement
}) {
await
userEvent
.
click
(
within
(
canvasElement
).
getByRole
('button'))
await
expect
(
navigation
).
toHaveBeenCalledWith
('https://nuxt.com/docs')
}, }) // Navigates for real export const
Allowed
=
meta
.
story
({
parameters
: {
nuxt
: {
navigation
: true } },
})

Limitations in Docs pages

On a docs page that renders stories from several files inline, spies use the mocks of the last story the user interacted with. For example, a click handler uses the mocks of the story that was clicked.

If the user hasn't interacted with any story yet, such a call (for example from an effect or a timer) throws a NuxtMocksSharedOnDocsPageError, because there's no way to tell which story's mocks to use.

To have full story isolation, render the stories of these files in their own iframe:

components/MyUsers.stories.ts
const 
meta
=
preview
.
meta
({
component
:
MyUsers
,
parameters
: {
docs
: {
story
: {
inline
: false } } },
})