how to test .mdx files indexed with stories?

[PoornimaKaruppasamy]

Summary

I am using test-runner to test my stories. Storybook indexers identifies the related .mdx files. How to test the .mdx files? For example: If we delete an import needed in the documentation, it renders error.

Additional information

No response

Create a reproduction

No response

[dosubot[bot]]

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

You can test .mdx files indexed as stories in Storybook using the test-runner just like regular stories. The test-runner automatically renders all stories—including those from .mdx files—and will fail if there are rendering errors, such as missing imports in your documentation. To ensure .mdx files are tested, include them in your stories glob pattern (e.g., '../src/**/*.mdx') in your Storybook config.

If you want stricter error detection, run the test-runner with the --failOnConsole flag to catch browser console errors caused by missing imports or other issues in your .mdx docs. For extra validation, you can use the CLI tool npx @hipster/mdx2-issue-checker to scan for MDX-specific errors before running Storybook or the test-runner.

If you use Vite and addon-vitest, be aware that certain plugin setups can break MDX rendering in Storybook 9—splitting your Vite and Vitest configs is the recommended workaround.

In summary: as long as your .mdx files are indexed, the test-runner will catch documentation errors at render time, and you can enhance this with console error checks and MDX linting tools.
Docs: Storybook test-runner
Docs: MDX troubleshooting & linting

To reply, just mention @dosu.

---

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

[PoornimaKaruppasamy]

Storybook config:
[ '../src//*.mdx', '../src/app//*.stories.@(js|jsx|ts|tsx)']

Still test-runner has not reported rendering error when there is missing import. For example: button.stories.ts turns into tests and it passes everytime, although the related mdx file button.mdx has missing import. It did not report any errors.

[dosubot[bot]]

By default, the Storybook test-runner only tests CSF stories (like .stories.ts files) and does not run docs-only MDX files. That means errors from missing imports in .mdx documentation won't be reported unless you explicitly configure the test-runner to include docs-only stories.

To catch these errors, you can:

• Adjust your test-runner config to include docs-only stories (look for an includeDocsOnly option or similar in your test-runner or StoryStore setup).
• Run the test-runner with the --failOnConsole flag to fail tests on browser console errors, which helps catch runtime MDX errors like missing imports (docs).
• Use a static analysis tool like npx @hipster/mdx2-issue-checker to lint your MDX files for missing imports before running tests (docs).

If you want strict documentation testing, make sure your test setup renders and checks docs-only MDX files, not just stories. This is a common gap in default Storybook test setups.

To reply, just mention @dosu.

---

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

[PoornimaKaruppasamy]

Is there a possibility to add 'tag' in the *.mdx file for the test runner to identify and test ? I have tags added in CSF stories.

How to adjust test-runner config to include docs-only stories (includeDocsOnly option) in your test-runner?

[dosubot[bot]]

No, Storybook does not currently support adding user-defined tags in MDX files for the test runner to identify or filter them. Tagging is fully supported in CSF stories via the tags property, but this does not extend to MDX files—any tags you add in <Meta> in MDX are ignored by the test runner and Storybook's filtering logic. This is a known limitation, and there is an open feature request to add support for tags in MDX files, but it hasn't been implemented yet (discussion).

If you need to test MDX docs, the current options are to adjust your test-runner config to include docs-only stories (if supported by your setup), use the --failOnConsole flag to catch runtime errors, or use static analysis tools to lint your MDX files for issues. But tag-based filtering for MDX docs is not possible at this time.

To reply, just mention @dosu.

---

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

[PoornimaKaruppasamy]

--failOnConsole flag did not help to get runtime errors from .mdx file like missing imports

[dosubot[bot]]

The --failOnConsole flag doesn't catch missing import errors in .mdx files because the Storybook test-runner only renders and tests CSF stories by default—not docs-only MDX files. So, if an MDX file has a missing import, its error won't surface in the test-runner or trigger --failOnConsole unless the MDX file is rendered as a story, which isn't the default behavior. There’s currently no config or flag to force the test-runner to render docs-only MDX files for error detection docs.

To catch MDX errors like missing imports, use static analysis tools such as npx @hipster/mdx2-issue-checker before running Storybook or the test-runner. The MDX VS Code extension with IntelliSense can also highlight these issues in your editor migration guide.

To reply, just mention @dosu.

---

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