describe(me) docs
early v0.12.1 browser mode · jsdom Live · Foundations
Examples npm GitHub

Troubleshooting

After every run describe-me lists what it could not document. This page explains each item, the warnings it prints once, the symptoms people run into most and what to do when Live does not mount a test.

Diagnostics after a run #

When a run ends, the reporter writes the manifest and prints what it could not document, one line per kind. Setup warnings come first, one line each, because they can explain failing tests. Problems reading the design-system foundations follow, also one line each. A line names at most 5 items and sums up the rest as (+n more). When everything is fine, it prints nothing.

The viewer shows the same list behind an "issues" chip in its header, with links to the tests. See Viewer and CLI. In this repository, pnpm check-manifest fails on any of them in react-browser and react-jsdom.

Key Console line What it means and how to fix it
anonymous describe-me: 2 tests render an anonymous component; export it from a project module or give it a displayName The component a test renders has no usable name, so the test is documented under Anonymous. Export the component from a project module, which names it after its export, or give it a displayName. See Naming.
undocumented describe-me: 3 components have no props docs: Card, Menu, Tabs The reporter could not read the props of these named components. Host elements such as div never count. Check that the component is exported from a TypeScript module and that typescript 5 or 6 is installed. See Props.
assetsMissing describe-me: 1 asset was not found in the project and will not load in the viewer: /logo.svg A snapshot points at a file that is neither under the project root nor in public/, so the viewer cannot load it. Put the file where the path points. See Assets.
fontsMissing describe-me: 1 font family is used but never loaded: Inter (12 tests) — add it to previewHead The captured CSS uses the family, but no @font-face rule or font stylesheet loads it, in the frames or in the preview head. A family installed only on your machine counts as missing too. Load it in previewHead. See Fonts and the font check.
remoteStylesheets describe-me: frames load stylesheets from 1 remote host, which the viewer fetches from the network: use.typekit.net (8 frames) Frames link stylesheets from these hosts, so the viewer loads them from the network. Links in the preview head do not count here. Put font links in previewHead, and let describe-me build download what it can. See Vendoring.
setupWarnings describe-me: styled-components 6.1.8 resolves tslib 2.4.1, which has no tslib.es6.mjs, so its browser build may fail to load … The plugin or the reporter found a problem in your setup. The plugin warns about the browser build of styled-components with a tslib older than 2.5.3, which can make tests fail. Upgrade styled-components to 6.1.10 or later, or override tslib to 2.5.3 or later. See styled-components. The reporter warns about a key of sidebar.groups that gets no test file. Fix its globs, move the key above the keys that take its files, or remove it. See Sidebar groups.
foundationsErrors describe-me: foundations.theme: src/theme.ts has no export named theme or default The reporter could not read part of the design-system foundations, and wrote the rest to foundations.json. For a theme module, check the path and the export in foundations.theme. Material UI's defaults need @mui/material to resolve from the root. For the Tailwind 4 theme, install @tailwindcss/vite or @tailwindcss/postcss. See foundations.

One-off warnings #

These lines show up once, when their cause does. None of them stops the run. Errors that do are under Symptoms and fixes.

Plugin and setup file

Warning When What to do
`test.css` is false, so imported stylesheets are stubbed … When Vitest starts, in a DOM environment whose config sets test.css: false. Remove the setting. The plugin then turns CSS on. See What the plugin changes.
using the browser build of styled-components, for createGlobalStyle When Vitest starts, in a DOM environment with styled-components 5 or later. It is information, not a warning. Nothing. See styled-components for why.
concurrent tests are not recorded (src/Menu.test.tsx) Once per test file that has concurrent tests. Concurrent tests would share one recorder, so they run but record nothing. Make them sequential to record them. See Environments.

Reporter

Warning When What to do
previewHead contains a <script>, which the viewer never runs. When Vitest starts. Remove the script. Load fonts with <link> or <style>. See Fonts.
include is an empty list, so no test file is recorded. … When Vitest starts, with include: []. Leave include out to record every test file, or use exclude: '**' to record none without the warning. See Which tests record.
the font audit failed: … At the end of a run, when the font check throws. The manifest gets empty fontsMissing and remoteStylesheets lists, so those diagnostics may miss something. Please report it with the message.
typescript is not installed, component props will not be documented At the end of a run where a recorded test rendered a component and typescript cannot be imported. Before 0.5.2 it also showed on runs that recorded no component. Install typescript as a dev dependency. See Installation.
typescript 7.0.2 has no compiler API that describe-me can use, component props will not be documented At the end of a run where a recorded test rendered a component and the installed typescript is 7 or later, whose package exports only its version. Once per process. Before 0.12.1 such a run failed with a TypeError and wrote no manifest. The run records as usual, without props tables. They need typescript 5 or 6. See the limit.
component props could not be read: … At the end of a run, when reading the props throws. The manifest of that run has no props tables. Please report it with the message.
[describe-me] could not read props of Card from src/Card.tsx At the end of a run, once per component whose props type it cannot find. Give the export a props type TypeScript can read. The component shows up under undocumented. See Props.
[describe-me] two components are named Card: src/a/Card.tsx and src/b/Card.tsx. Only the first is documented. At the end of a run, once per name, when two files export the same name. Props docs are keyed by name. Rename one of the exports. See Naming.

Recorder

Warning When What to do
renderFrame.pending is not a valid CSS selector: "…". Render frames fall back to 'lazy'. Once per test file, when the setup file configures the recorder. Fix the selector. Until then render frames are taken as with 'lazy'. See Render frame timing.

describe-me build

Warning When What to do
font vendoring stopped (…). Fonts keep loading from the network. When downloading the fonts fails as a whole. The build still finishes. Build again with network access, or pass --no-vendor-fonts. See Vendoring.
remote stylesheet hosts were not counted again (…). The issues menu keeps the list from the test run. After the build downloaded fonts and could not count the hosts again. The issues chip of the built site may still list hosts whose fonts were downloaded. See remoteStylesheets.
left remote: use.typekit.net (Adobe Fonts do not allow self-hosting) For each host the build does not download from: Adobe Fonts, hosts not on its allowlist, or any host once the 100 MB font budget is used up. Nothing, if the site may load them from the network. Otherwise host the font files in your project. See Vendoring.
… did not download (…). It keeps loading from the network., then and n more that did not download. For each stylesheet or font file that failed, the first 5 of them. Check the network and build again. Downloads are cached, so a later build fetches only what is missing. See Vendoring.
… imports node:fs, which does not load in the browser: it is a Node module With --live, once for each file of the project that imports a module the browser cannot load: a Node module, or one that cannot be resolved. The build still finishes. Tests of a file that imports it report import-failed in Live, and a setup file setup-failed. Keep such imports out of test files, and list a browser version of a setup file in live.setupFiles.
the live build leaves out test files that are not in …: … With --live, when the manifest names test files that are gone. Their tests report import-failed in Live. Run the tests again, then build again.

Viewer

Warning When What to do
style chunk styles/<hash>.css did not load In the browser console, when a stylesheet chunk fails twice. The frame shows with a gap in its styles, and the chunk is fetched again next time. Deploy the whole data directory, styles/ included. See Hosting.

Symptoms and fixes #

Symptom Cause Fix
Buttons look like browser defaults and text is in Times. Global styles, such as a reset or a body font, are missing. Render them in the wrapper of your custom render. See Global styles.
Cannot destructure property '__extends' when a test loads styled-components. The browser build of styled-components with a tslib older than 2.5.3. Upgrade styled-components to 6.1.10 or later, or override tslib to 2.5.3 or later. styledComponentsBrowserBuild: false also avoids it, but drops global styles from the snapshots. See styled-components.
Every test file fails with "all describe-me packages must be on the same version". Two copies of @describe-me/core at different versions, such as a 0.5.1 core next to 0.5.2 packages. Install all four packages at one version. See One version for all packages.
"cannot resolve @describe-me/react (the recording replacement for …). Install @describe-me/react." The adapter package is not installed. Install it. See Packages.
"include and exclude expect non-empty glob strings", "renderFrame expects …" or "sidebar …" before any test runs. An option has a value the plugin does not accept. Fix the option. See include, Render frame timing and Sidebar groups.
The viewer shows "no manifest yet — run vitest first". No test run has written data yet, or --data points elsewhere. Run the tests, or pass the output directory with --data. See Viewer and CLI.
A built site opened from disk shows a blank page or "no manifest yet". The viewer fetches its data, which needs HTTP. Serve the folder over HTTP. See Hosting and the limitation.
A banner under the viewer header says the data comes from another version. The tests ran with another describe-me release line than the viewer. Install every package at the same version. See Viewer and CLI and Upgrading.
A popover sits in the top-left corner (jsdom). jsdom has no layout, so the library positions it at zero. Record such tests in browser mode. See Limitations in jsdom.
A test is missing from the sidebar. It recorded no frame before the closing one, it rendered outside the recording render, include or exclude leave it out, it is concurrent, or test.projects roots disagree on the path. Call step() to keep a test, or fix the globs. See Tests that are left out and Which tests record.
A component shows as Anonymous. It has no export name and no displayName. Export it from a project module. See Naming.
Fonts are missing in the viewer. Nothing in the frames or the preview head loads them. Load them in previewHead. See Fonts and fontsMissing.
Vite fails on the Node version. Vite 8 needs Node ^20.19.0 || >=22.12.0. Upgrade Node. See Node.
More act warnings with describe-me than without, in jsdom. On 0.5.1 the recorder waited with React's act flag on. Fixed in 0.5.2. On 0.5.1, upgrade all packages. To compare runs, use the same reporter in both, because minimal hides what passing tests print. See the limitation.
Fewer act warnings with describe-me than without, in jsdom. On 0.5.2 every user-event frame waited one macrotask with React's act flag off. Fixed in 0.5.3. On 0.5.2, upgrade all packages. Compare runs with the same reporter. See the limitation.
Vitest's console output differs with the plugin: no minimal or agent reporter in an AI agent session, no github-actions annotations. On 0.5.1 the plugin replaced Vitest's default reporters. Fixed in 0.5.2. On 0.5.1, name your reporters in the config. See the limitation and Reporters.
include: [] records every test file. On 0.5.1 an empty list meant every file. Fixed in 0.5.2, where it records none and warns. On 0.5.1, use exclude: '**'. See the limitation and Which tests record.

Live #

The Live section of the inspector names how the live page ended up, as the viewer explains. The status table of the live preview says what happened for each status. This one says what to do. After a fix, press Restart.

Status The inspector says What to do
mounted mounted as the test arranged it Nothing. When the component still looks different from its frames, the live page is missing something the test run had. Pass global styles and providers as the test's wrapper, so they mount with the component (Global styles). vi.mock has no effect, so the real module loads, and the notices list each vi.mock and vi.doMock call the page skipped. Timers are real, so a toast that the test holds with fake timers hides after its delay. Errors the component throws after the mount show under Errors.
no-render the test renders no component Open a test that renders a component. A renderHook test, a test that calls skip() or one that renders nothing has nothing to mount.
not-found the test is not in its file The test was renamed, moved or removed since the last run. Run the tests again, so the manifest matches the file.
import-failed the test file does not load in the browser Read the detail in red. Most often the test file, or a module it imports, needs Node, such as node:fs or msw/node. Keep such code out of the test file (What Live runs). A test that imports MSW's server for server.use() needs an alias (MSW in Live). On a static site, describe-me build --live warned about that import. … is not in this build means the manifest is newer than the build, so run describe-me build --live again.
setup-failed a setup file does not load in the browser Read which file the detail names. Most often it needs Node, as MSW's setupServer does. List a browser version of it, such as one with setupWorker (MSW in Live), in live.setupFiles, then start describe-me dev again, because the live preview reads the config once (What Live runs).
failed the arrange phase failed Read the detail in red. A hook, a fixture from test.extend or the body before render threw or took longer than the test's timeout. The detail names a fixture that fails, and an aroundEach or aroundAll hook that settles without calling its run function. Code that needs Node fails here too. Make the arrange phase work in the browser on its own. When MSW failed to register the Service Worker, the live page found no mockServiceWorker.js under its base (MSW in Live).

When the toggle is greyed out

When the live preview does not start, describe-me dev prints the reason on stderr as describe-me: <reason>, and the Live toggle shows it as its tooltip. The viewer runs on without Live. Start describe-me dev again after the fix.

describe-me build --live stops with exit code 1 for the same reasons, and leaves no __live/. In its messages, so describe-me build --live stopped takes the place of so the viewer runs without Live, and an error of the build itself starts with the live build failed:. When that error comes from a plugin whose apply is 'serve', the plugin may need the dev server, which a static site does not have. See the limitation. It also stops without a manifest, which lists the tests to build, and with live: false in the config, which --live contradicts.

Reason What it means and how to fix it
no manifest in … to find the project by, so the viewer runs without Live. Run the tests and start again, or pass --root. The preview finds the project through the manifest, and there is none yet. Run the tests once, or pass --root with the project directory. Check that --data names the directory the reporter writes.
cannot read …/manifest.json (…), so the viewer runs without Live. The manifest is not valid JSON. Run the tests again.
the manifest names the config file …, which is not in …, so the viewer runs without Live. Run the tests again, or pass --root. The config file of the last run is gone, or the manifest comes from another machine. Run the tests again, or pass --root.
cannot find @describe-me/vitest from …, so the viewer runs without Live. Pass --root with the project directory. The CLI loads the preview from the project's own @describe-me/vitest, and only a node_modules in the root or above it counts. Pass --root with the directory of the project that installs it.
the @describe-me/vitest in … predates the live preview, so the viewer runs without Live. The project has an @describe-me/vitest older than the viewer. Install all four packages at one version (one version for all packages).
no Vitest or Vite config file in … With --root, the directory has no vitest.config.* or vite.config.*, so pass the directory that holds the config. Without it, the manifest names no config file and its root has none of them either. Run the tests with a config file.
cannot find vite from … The root has neither Vite nor a Vitest that brings one. Install the project's dependencies, or pass --root with the project directory.
… has no describeMe() plugin The config the preview loads does not call describeMe(). With --root, it may have picked another config than your tests run with. Run the tests with the config that has the plugin and start without --root, so the manifest names that config.
all describe-me packages must be on the same version. The describeMe() plugin in … has live protocol …, expected …. Install @describe-me/core, @describe-me/react, @describe-me/vitest and describe-me at one version. The describeMe() of the config comes from another copy of @describe-me/vitest than the preview, on another release. Install all four packages at one version, with one copy of each.
all describe-me packages must be on the same version. The live preview in … speaks protocol …, this viewer …. The project's @describe-me/vitest and the describe-me that runs the viewer are on different releases. Install all four packages at one version.
Any other message The config threw while the preview loaded it, and the message is its own. The preview loads it in mode test with DESCRIBE_ME_LIVE=1 set (the live preview). Fix the config, or what it imports.

Reporting a bug #

Open an issue on GitHub. These make it quick to reproduce: