:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Mocking data in stories
Stories talk to the PostHog API through a Mock Service Worker that starts in preview.tsx.
A global loader holds every story's render until the worker is ready, so the first story on a fresh page gets its mocks too.
Every request goes to the worker first: a story mock, then a default mock, then the network.
Mock API responses
Two helpers in frontend/src/mocks/browser.tsx add mocks for one story:
| Helper | Where it goes | Use it when |
|---|---|---|
mswDecorator(mocks) |
decorators: [...] on the meta or on a story |
The mocks are fixed for the story. This is the usual choice. |
useStorybookMocks(mocks) |
Inside render, a story function or a decorator |
The mocks depend on args or on other values built in render. |
decorators: [
mswDecorator({
get: {
'/api/environments/:team_id/insights/': toPaginatedResponse([insight]),
'/api/environments/:team_id/insights/:id/': ({ params }) => insightsById[params.id as string],
},
post: {
'/api/environments/:team_id/query/': async ({ request }) => {
const body = await request.json()
return body.query.kind === 'TrendsQuery' ? trendsResult : [400, { detail: 'Unexpected query' }]
},
},
delete: { '/api/environments/:team_id/insights/:id/': [204] },
}),
]
- The methods are
get,post,put,patch,deleteandoptions. Paths use MSW syntax::parammatches one segment. mswDecoratoradds a trailing slash to every path, so a default mock with a slash can't shadow a story mock without one.- Story mocks go before the defaults, so a story mock always wins.
mswDecoratoralso readsparameters.msw.mocks, and its own argument wins over them.parameters.msw.mocksdoes nothing withoutmswDecoratoron the story or meta.- A meta
mswDecoratorand a storymswDecoratorboth apply. The story's decorator runs last, so its mocks win for the same path. worker.resetHandlers()runs before each story, so no mock carries over to the next one.
What a mock returns
| The mock returns | The response |
|---|---|
| An object, an array or any other JSON value | That value as a JSON body, status 200 |
[status, body] |
That body with that status |
[status] |
An empty body with that status |
A Response or an MSW HttpResponse |
That response, as is |
undefined or null |
An empty 200 |
A function ({ request, params, cookies }) => … |
Whatever the function returns, from this list. It can be async. |
- An empty 200 is not a network error. Return
HttpResponse.error()to model a failed request. - A request that never answers keeps a loader on screen:
() => new Promise(() => {}). SettestOptions.waitForLoadersToDisappear: falseand wait for the loading state withwaitForSelector, or the story times out. toPaginatedResponse(results)andEMPTY_PAGINATED_RESPONSEfrom~/mocks/handlersbuild a DRF page.
environments and projects paths
/api/environments/ is an alias of /api/projects/ on the backend.
A mock on an /api/environments/... path also answers the same /api/projects/... path, unless a mock already covers that one.
The alias goes one way only: a /api/projects/... mock never answers an /api/environments/... request.
Requests nobody mocks
The worker logs a warning and lets the request through to the network. Locally that is the Storybook server, in CI the static build, so the request fails or returns HTML.
That can resolve after the snapshot and change it. Mock every request the story makes.
Look for [MSW] Warning: intercepted a request without a matching request handler in the browser console to find them.
Default mocks
frontend/src/mocks/handlers.ts answers the requests most scenes make on load, so a story mocks only what it shows. Among them:
/api/users/@me/,/api/organizations/@current/,/api/environments/@current/and/api/projects/@current/return the default user, organization, team and project./_preflightreturnsfrontend/src/mocks/fixtures/_preflight.json: not cloud, debug on, region US,site_urlhttp://localhost:6006.- Many common lists return empty pages, for example dashboards, actions, feature flags and experiments. Cohorts return one default cohort.
POST /api/environments/:team_id/query/returns{ results: [] }.- The posthog-js endpoints answer
ok, so the app's own analytics never reach a real host. - Requests that would add a banner that changes over time return a quiet answer: the posthog-js release check returns no tags, and the proxy check returns a working proxy.
- The sidebar starts with four starred products, so a scene story doesn't show the whole product catalog.
Read handlers.ts before you mock a path. A default may already return what you need, and your mock replaces it for the whole story.
The app context every story starts with
common/storybook/.storybook/app-context.ts sets window.POSTHOG_APP_CONTEXT:
current_teamisMOCK_DEFAULT_TEAM, andcurrent_projectisMOCK_DEFAULT_PROJECT, both fromlib/api.mock.current_userandpreflightare empty, so the app fetches/api/users/@me/and/_preflight, and the default mocks answer.persisted_feature_flagsholds the story'sfeatureFlags.resource_access_controlgivesmanageraccess to everything except the activity log and the toolbar, which areviewer.
To change the user, the organization or the preflight, mock its endpoint with a copy of the default:
import { MOCK_DEFAULT_USER } from 'lib/api.mock'
mswDecorator({ get: { '/api/users/@me/': { ...MOCK_DEFAULT_USER, is_staff: true } } })
The team and the project work differently.
teamLogic and projectLogic take them from the app context when they mount and never request them, so a mock of their endpoint changes nothing.
Set them after mount instead, with teamLogic.actions.loadCurrentTeamSuccess or projectLogic.actions.loadCurrentProjectSuccess:
render: () => {
const { loadCurrentTeamSuccess } = useActions(teamLogic)
useDelayedOnMountEffect(() => {
loadCurrentTeamSuccess({ ...MOCK_DEFAULT_TEAM, created_at: '2023-05-23T00:00:00Z' })
})
return <App />
},
OnboardingWelcome.stories.tsx uses this pattern. withKea remounts the logics for the next story, so nothing carries over.
lib/api.mock.ts holds MOCK_DEFAULT_USER, MOCK_DEFAULT_TEAM, MOCK_DEFAULT_ORGANIZATION, MOCK_TEAM_ID and the other defaults. frontend/src/mocks/fixtures/ holds larger JSON fixtures.
Plan features: useAvailableFeatures
import { useAvailableFeatures } from '~/mocks/features'
import { AvailableFeature } from '~/types'
export const WithAdvancedPermissions: Story = {
render: () => {
useAvailableFeatures([AvailableFeature.ADVANCED_PERMISSIONS])
return <MyComponent />
},
}
- The default user and organization mocks return these features as
available_product_features, so paywalled UI unlocks. withKearesets the list to none before each story. The list is module state, so set it in every story that needs it, not once in a shared helper that runs only for the first story.- Call it in a decorator or in
render, before the component mounts. The user loads once per story.
Kea and the router
withKea gives each story a fresh start:
- It resets the mocks to the defaults.
- It unmounts every logic the previous story mounted, so an unfinished listener can't write into the next story's store.
- It clears the cached "has data" answers that empty states read, so one story's data can't hide the next story's empty state.
- It starts kea with an in-memory router history.
- It mounts
featureFlagLogic,teamLogic,projectLogic,userLogicand the router.
The story renders only after this reset. A story can then mount its own logics, for example with useMountedLogic(myLogic(props)), and drive them with actions to reach a state.
Drive a logic from a useEffect or a play function, after mount, and wait for the result with testOptions.waitForSelector.
Helpers for common surfaces
createInsightStory(insight, mode)infrontend/src/scenes/insights/__mocks__/createInsightScene.tsxmocks the endpoints an insight scene needs and renders it.- Story-only fixtures and fakes live next to the story in a
__mocks__/folder, for examplefrontend/src/toolbar/__mocks__/.