Mocking
@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.
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:
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.
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:
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:
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.
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 }) },
},
},
},
})
Navigation
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:
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:
const meta = preview.meta({
component: MyUsers,
parameters: { docs: { story: { inline: false } } },
})