Why describe-me

Stories drift from components because nothing runs them. Tests do run. describe-me makes the tests the documentation.

What you get #

Stories that do not rot

Your stories are tests. When one drifts from its component, CI goes red.

No change to your tests

The plugin redirects the render import. Tests that render through vitest-browser-react or @testing-library/react, directly or through your test utils, record as they are.

A frame per interaction

Every render and every interaction leaves a frame you can step through.

Live

A test mounts for real in the viewer, as it arranged it, and you can use it.

Props and their coverage

Props come from TypeScript, and the overview marks the values your tests passed. A red cross is an invitation to write a test.

Foundations without MDX

The view reads the tokens your project already has, where a hand-written docs page lists them by hand.

Diagnostics

The viewer lists what it could not document, such as unnamed components, missing assets and fonts.

Small output

Identical DOM and large stylesheets are stored once, however many frames share them.

A static site

Any static host can serve the viewer. There is no backend.

A framework-agnostic core

Recording and the viewer know nothing about React. React is an adapter.

Existing jsdom suites

Testing Library suites in jsdom record too, styled-components included.

Tests that render some other way are left out, see what is left out.

Compared with Storybook #

Storybook is the established tool for component documentation, with a large community. If you know it, this table maps its ideas onto describe-me.

Storybook	describe-me	Notes
Story	An `it` test	A test that renders a component is a story, named after the test.
Canvas	A test in Live	In Live the test mounts as its arrange phase set it up. The recorded frames show the steps after it.
Args	Props passed to `render`	The viewer shows the props each test passed.
Decorators	The `wrapper` in your test utils	Providers and global styles wrap each render, as they do in your tests.
`preview-head.html`	`previewHead`	HTML added to the head of every frame, such as font links. You can read an existing `preview-head.html` into it.
Play function	The test body	Each interaction leaves a frame. The assertions are the test's own.
Actions	`vi.fn()` props in Live	Each call shows in the inspector under the prop's name.
Autodocs	The component overview	The props table, with the values your tests cover.
`ColorPalette` and `Typeset` doc blocks in MDX	Foundations	Tokens read from the CSS the tests load, the Tailwind 4 theme and an optional theme module, with presets for Tailwind, shadcn/ui and Material UI. Nothing to write or keep in sync.
Controls	A props table without inputs	Live exists, controls do not. You cannot change props in the viewer yet. See the roadmap.
Addons	None	Storybook has a large addon ecosystem. describe-me has no plugin system.
Visual tests (such as Chromatic)	None	describe-me records DOM and CSS and compares nothing.
Static build	`describe-me build`	Both produce a static site any static host can serve. `describe-me build --live` makes the site mount tests too.

Newer Storybook versions can run your stories as Vitest tests. describe-me goes the other way and turns your tests into stories. If your stories are where your examples live, stay with Storybook. If your tests are, describe-me documents them as they are.

What it costs #

Recording makes every recorded test take longer. Performance has the measurements and ways to cut the cost.

The plugin changes your Vitest and Vite config. It redirects the render import and adds a reporter, among other things. See the plugin.
It writes a .describe-me/ directory into your project, which you will want to ignore in git.
All four packages must share one version. A mismatch can stop the tests with an error, and the viewer warns about data from another version. See lockstep versions.
describe-me is early. Expect rough edges and changes, see Limitations.

When it is not the right tool #

You need to change props in the viewer. In Live the test mounts as written, and there are no controls yet, see the roadmap.
You use a framework other than React. See scope.
You need visual regression testing. describe-me does not compare frames, so use a visual testing tool.
Your components depend on layout and your tests run in jsdom, which does no layout. See jsdom's limits.
Your suites run tests concurrently. Concurrent tests are never recorded, see both environments.