Your tests are your stories
describe-me records the DOM after every step of your component tests and shows the frames as browsable documentation. There are no stories to write and nothing to keep in sync.
How it fits together #
Four packages share the work:
-
@describe-me/core: the recorder,step()and the manifest types. The other packages depend on it, so you do not add it yourself. -
@describe-me/react: the recordingrender, forvitest-browser-reactand for@testing-library/react. -
@describe-me/vitest: the Vitest plugin, the setup files and the reporter. describe-me: the viewer and its CLI.
How it works follows a frame from the test to the viewer.
What you get #
Stories from tests
Every describe is a heading in the sidebar and every it a
story. There is no separate story abstraction.
A frame for every step
Frames after render, after each interaction and after each step(), on a
timeline you can scrub.
Component overview
Props read from TypeScript, and which of their values your tests cover.
Foundations
The tokens of your design system, from colors and type to breakpoints and motion. They are read from the CSS the tests load and an optional theme module, without stories or MDX.
Diagnostics
What could not be documented, such as anonymous components or missing assets, in the terminal and in the viewer.
A static site
describe-me build writes a site you can host anywhere.
Live
A test mounts for real in the viewer, as its arrange phase set it up. You click and
type, and vi.fn() calls show as actions.
See it in the examples #
Browser mode
Buttons, a counter, a menu and a search box, recorded in Chromium through Vitest browser mode.
jsdom
A design-system style suite with Testing Library, user-event and styled-components, recorded in jsdom.
shadcn/ui on Tailwind
shadcn/ui on Tailwind 4 in browser mode, with a dark variant.
Material UI
Material UI with Emotion in jsdom, with a theme for both color schemes.
Examples describes all four projects, and Run them locally builds them on your machine.
What it does not do yet #
- React only. The core is framework-agnostic, but React is the only adapter.
- No controls. In Live a test mounts for real, but you cannot change its props in the viewer yet. See Roadmap.
- jsdom has no layout and loads no fonts inside the test. See Limitations in jsdom.
-
:activeis not recorded. Hover and focus are, and in jsdom they follow the test's gestures. See Limits in both environments.
Limitations lists every known limit.