Hi @alanTechGC! I'm Dosu and I’m helping the storybook team.

This kind of inconsistency is common when interaction tests rely on elements being immediately available, but Chromatic (and CI/headless environments) can have different rendering or asset loading timing than your local dev setup. The best way to make your tests robust across both environments is to always use async Testing Library queries like findBy..., always await userEvent actions in your play functions, and wrap assertions in waitFor when you expect the UI to update asynchronously. This ensures your tests wait for the DOM to be ready before making assertions, mirroring the async race conditions that can happen in Chromatic or CI runs [example].

For even more reliability, you can use the waitForPageReady utility in your test runner config (e.g., in the postVisit hook) to ensure the page and all assets are fully loaded before running assertions or taking snapshots [docs].

There’s no built-in flag to simulate Chromatic’s environment locally, but running your tests with the Storybook test runner (headless mode, matching browser version) and following these async patterns will help you catch these issues before pushing to Chromatic. Also, make sure your global styles, fonts, and assets are loaded identically in both environments, and check that your .storybook/preview.ts and test setup files are consistent [discussion].

If you still see discrepancies, try comparing DOM snapshots or enabling debug logging to spot differences in asset loading or DOM structure between local and Chromatic.

To reply, just mention @dosu.

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}   

Thank you @dosu.
The best solution is to add the waitForPageReady, but as that uses TestRunner, I think it is outdated and not compatible with vitest. Is there another way to do the same with Storybook + Vitest?

You're right—waitForPageReady is specific to the Storybook Test Runner (Playwright-based) and isn't available for Vitest. There isn't a direct equivalent for Vitest, but the recommended approach is to use async Testing Library patterns in your play functions and tests. That means always using async queries like findBy..., wrapping assertions in waitFor, and using waitForElementToBeRemoved when waiting for elements to disappear. These patterns are shown in the official Storybook Vitest templates:

import { waitFor, waitForElementToBeRemoved, within } from '@storybook/test';

export const SyncWaitFor = {
  play: async ({ canvasElement, step }) => {
    const canvas = within(canvasElement);
    await step('Submit form', Callback.play);
    await waitFor(() => canvas.getByText('Completed!!'));
    await waitForElementToBeRemoved(() => canvas.queryByText('Completed!!'), { timeout: 2000 });
  },
};

You can also use loaders to simulate network or rendering delays if needed:

export const WithLoaders = {
  loaders: [async () => new Promise((resolve) => setTimeout(resolve, 2000))],
  play: async ({ step }) => {
    await step('Submit form', Callback.play);
  },
};

There’s no global DOM readiness hook in addon-vitest, so you need to handle async waits explicitly in each test or play function. This is the best way to ensure your tests are robust across local, CI, and Chromatic runs. More details and examples are in the addon-vitest template stories.

If you run into persistent issues even with these patterns, let me know what you’re seeing and I can help troubleshoot further.

To reply, just mention @dosu.

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}