Unstable tests debugging

Image and font rendering can be tricky. Resources that load from unpredictable or flaky sources may not load within the 15-second capture window. Work around this by:

• Ensure that fonts load in Chromatic.
• Ensure that resources load in Chromatic.
• Serve resources as static files to improve test speed.
• Use a placeholder service.

If your resources are behind a firewall, whitelist our domain so we can load your resources.

The srcset attribute is a useful mechanism that provides the browser with a list of potential images to display, based on specified conditions such as media queries.

In most cases, Chromatic will capture the correct image from the srcset list. However, if multiple tests list the same image in their respective srcset lists, browser cache issues can result in unstable tests.

In situations like this, make the srcset URLs unique for each test by adding a query parameter value.

For instance, one test could use a srcset query parameter of ?cachebuster=1714593641616.

<picture>
  <source
    sizes="(max-width: 768px) 100vw, 50vw"
    type="image/webp"
    srcset="
​      https://placehold.co/384x384.webp?cachebuster=1714593641616 384w,
​      https://placehold.co/640x640.webp?cachebuster=1714593641616 640w,
​      https://placehold.co/750x750.webp?cachebuster=1714593641616 750w"
  />
  <img
    alt="Alt text"
    loading="eager"
    width="1500"
    height="1500"
    decoding="async"
    sizes="(max-width: 768px) 100vw, 50vw"
    src="https://placehold.co/3840x3840.jpeg"
    style="color: transparent;"
  />
</picture>

If another test uses the same images, they can alter the query parameter in the URL to ?currenttime=1714593641620.

<picture>
  <source
    sizes="(max-width: 768px) 100vw, 50vw"
    type="image/webp"
    srcset="
​      https://placehold.co/384x384.webp?currenttime=1714593641620 384w,
​      https://placehold.co/640x640.webp?currenttime=1714593641620 640w,
​      https://placehold.co/750x750.webp?currenttime=1714593641620 750w"
  />
  <img
    alt="Alt text"
    loading="eager"
    width="1500"
    height="1500"
    decoding="async"
    sizes="(max-width: 768px) 100vw, 50vw"
    src="https://placehold.co/3840x3840.jpeg"
    style="color: transparent;"
  />
</picture>

You can use any query parameter name as long as its value is unique to each test and stable across runs.

Emojis are handled by your operating system’s emoji font. Most operating systems use different emoji fonts, and those fonts tend to change over time. For example, if you view a story on a Mac, you’ll see Apple’s set of emojis.

Chromatic captures Chrome and Firefox snapshots in a Linux environment. It includes a common set of emojis used by most systems. Those emojis will likely look different from emojis on a consumer OS like Mac or Windows. Unfortunately, there’s no workaround available at this time.

Videos are interactive and time-based, which can make a test unstable. Chromatic hides videos by default to prevent false positives. You’ll see the poster image, if specified, or a blank space where the video is supposed to render.

Most likely, you are calling into window.parent somewhere in your code. As we serve your test preview iframe inside our www.chromatic.com domain, this leads to an x-origin error as your code doesn’t have access to our frame (with good reason!).

Generally speaking it is a good idea to wrap calls like that in a try { } catch in case the code is running in a context where that’s not possible (e.g., Chromatic).

Make sure there are no elements inadvertently cutting off content through the use of overflow or height styles.

For elements that have relative height styles based on the size of the viewport (such as height: 100vh), all content nested under that element will appear in a snapshot unless either overflow: hidden or overflow: scroll is used to hide what is outside of that element (and therefore outside of the viewport).

When Chromatic captures a snapshot of an element that has a viewport-relative height and styling that hides or scrolls overflow, it uses a default viewport height of 900px. This default applies only when Chromatic can’t detect a natural height for the outermost DOM element (root ancestor), such as a scrollable div.

To set the height, you can add a decorator for stories that wraps them in a container with a fixed height:

// Adjust this import to match your framework (e.g., nextjs, vue3-vite)
import type { Meta } from "@storybook/your-framework";

import { MyComponent } from "./MyComponent";

const meta = {
  component: MyComponent,
  title: "Example Story",
  decorators: [
    (Story) => (
      <div style={{ margin: "3em" }}>
        <Story />
      </div>
    ),
  ],
} satisfies Meta<typeof MyComponent>;

Scrollable divs constrain the height of their children. Change the height of the scrollable div to ensure all content fits. It’s not possible for Chromatic to infer how tall scrollable divs are intended to be.

Chromatic intentionally disables scrollbars during snapshot capture to focus on testing your content rather than browser UI elements. This ensures consistent snapshots across different browsers and operating systems, since scrollbar appearance varies significantly between platforms.

Unfortunately, there are currently no workarounds available to capture scrollbars in snapshots. This applies to both default browser scrollbars and custom-styled scrollbars using CSS.

If you’re testing custom scrollbar styling or need to detect overflow issues, you may need to use alternative testing approaches outside of Chromatic’s visual regression testing.

If you use an animateIn effect, set a delay so Chromatic captures the snapshot after the animation completes.

Your component might be rendering outside of the viewport. Either reposition the component or adjust the viewport size.

Yes. Chromatic’s Modes simplify visual testing for stories with different global configurations, such as themes. Follow the Themes guide to get started.

Chromatic snapshots sometimes show the initial or intermediate loading state of the UI, instead of the final state with the mocked data. This can lead to visual tests failing, even though the Storybook renders correctly locally. To debug this issue, follow these steps:

1. Ensure that MSW (Mock Service Worker) is correctly initialized by following the MSW Storybook add-on setup instructions.

2. Confirm that you’re not using outdated versions of msw, msw-storybook-addon, or any other community add-ons.

3. Run npm run build-storybook and npx http-server storybook-static -o locally to check the console and address any MSW warnings or errors. A setup that works locally can still fail in Chromatic.

4. Pay close attention to how you define MSW handlers, especially for API requests with query parameters. MSW recommends matching only the path in the handler URL and accessing query parameters inside the resolver function using req.url.searchParams.get().

5. Ensure all necessary assets, such as CSS files, load correctly in your stories. Consider preloading them in .storybook/preview-head.html.

6. Add an interaction test to your story to assert that mocked data is present and the component is in the expected state before the test concludes.

7. Use delays to ensure that mocked data is fully available before Chromatic takes a snapshot.

Blank snapshots are often caused by:

• An animateIn effect—If your component uses an animateIn effect, set a delay so Chromatic captures the snapshot after the animation completes.

• position: fixed—Fixed-position elements may depend on viewport size but don’t have dimensions themselves. Wrap your component in an element with defined height and width.

Learn how to improve test stability.

By default, Chromatic’s diffing algorithm skips the DOM elements marked with either a .chromatic-ignore CSS class or data-chromatic="ignore" attribute.

If you’re using this functionality but incoming changes are still captured, ensure that both the baseline and new snapshots retain the same dimensions, including width, height, and relative positioning.

Certain UI libraries like Material calculate the dimensions of each tab by measuring the rendered width of the tab’s children using JavaScript (for example, via getBoundingClientRect()).

However, loading a custom font can make the test unstable. Fonts affect the dimensions of text within tabs. Because custom fonts can load before, during, or after the tab component, the dimensions calculated by the component can vary across runs.

The solution we recommend is to use a <link rel="preload"> in your .storybook/preview-head.html to preload the font before the story renders. This ensures that the dimensions of the contents inside of the tab component remain consistent when measured.

Certain charting libraries like Highcharts measure the available space to determine where elements should be laid out.

Loading a custom font can make the test unstable. Fonts can load before, during, or after the component, and different fonts have different rendered dimensions.

The solution we recommend is to use a <link rel="preload"> in your .storybook/preview-head.html to preload the font before the story renders. This ensures that the dimensions and position of the fonts inside of the graph component remain consistent.