@describe-me/vitest 0.3.0 → 0.5.0-next.0

package/dist/file-filter.js

@@ -0,0 +1,23 @@
+function toRegExps(globs) {
+    return globs.map((glob) => new RegExp(glob.source, glob.flags));
+}
+/**
+ * Takes a path relative to the root, with posix separators. Build it once and
+ * reuse the returned function, which memoizes per file name. The test runtime
+ * imports this file, so no Node imports.
+ */
+export function fileFilter(options) {
+    const include = toRegExps(options.include);
+    const exclude = toRegExps(options.exclude);
+    const answers = new Map();
+    return (fileName) => {
+        const known = answers.get(fileName);
+        if (known !== undefined) {
+            return known;
+        }
+        const included = include.length === 0 || include.some((glob) => glob.test(fileName));
+        const answer = included && !exclude.some((glob) => glob.test(fileName));
+        answers.set(fileName, answer);
+        return answer;
+    };
+}

package/dist/is-recorded-test.d.ts

@@ -0,0 +1,6 @@
+import type { FrameKind } from '@describe-me/core/types';
+export declare function isRecordedTest(test: {
+    frames: readonly {
+        kind: FrameKind;
+    }[];
+}): boolean;

package/dist/is-recorded-test.js

@@ -0,0 +1,3 @@
+export function isRecordedTest(test) {
+    return test.frames.some((frame) => frame.kind !== 'end');
+}

package/dist/mirror-react-act-environment.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Set React's `IS_REACT_ACT_ENVIRONMENT` flag for each test file, the way
+ * Testing Library does. `RTL_SKIP_AUTO_CLEANUP` skips its whole setup block,
+ * the flag included, which silences React's act warnings. The flag is set
+ * only under Testing Library's own condition (Vitest globals), so the
+ * warnings match a run without describe-me.
+ */
+export declare function mirrorReactActEnvironment(): void;

package/dist/mirror-react-act-environment.js

@@ -0,0 +1,27 @@
+import { afterAll, beforeAll } from 'vitest';
+/** Testing Library's own test: its auto-cleanup block runs unless the variable is set. */
+function testingLibrarySkippedItsSetup() {
+    return typeof process !== 'undefined' && Boolean(process.env?.RTL_SKIP_AUTO_CLEANUP);
+}
+/**
+ * Set React's `IS_REACT_ACT_ENVIRONMENT` flag for each test file, the way
+ * Testing Library does. `RTL_SKIP_AUTO_CLEANUP` skips its whole setup block,
+ * the flag included, which silences React's act warnings. The flag is set
+ * only under Testing Library's own condition (Vitest globals), so the
+ * warnings match a run without describe-me.
+ */
+export function mirrorReactActEnvironment() {
+    const host = globalThis;
+    const hasGlobalHooks = typeof host.beforeAll === 'function' && typeof host.afterAll === 'function';
+    if (!testingLibrarySkippedItsSetup() || !hasGlobalHooks) {
+        return;
+    }
+    let previous;
+    beforeAll(() => {
+        previous = host.IS_REACT_ACT_ENVIRONMENT;
+        host.IS_REACT_ACT_ENVIRONMENT = true;
+    });
+    afterAll(() => {
+        host.IS_REACT_ACT_ENVIRONMENT = previous;
+    });
+}

package/dist/patch-testing-library-user-event.d.ts

@@ -3,6 +3,7 @@
  * It comes in two shapes, the direct API (`userEvent.click(el)`) and an
  * instance from `userEvent.setup()`, and the first delegates to the second,
  * so both are patched and `recordAction`'s depth guard keeps one gesture to
- * one frame. Safe to call more than once.
+ * one frame. When the optional peer is not installed, there is nothing to
+ * patch. Safe to call more than once.
  */
-export declare function patchTestingLibraryUserEvent(): void;
+export declare function patchTestingLibraryUserEvent(): Promise<void>;

package/dist/patch-testing-library-user-event.js

@@ -1,6 +1,5 @@
-import userEvent from '@testing-library/user-event';
+import { elementLabel } from '@describe-me/core';
 import { describeArg } from './describe-arg.js';
-import { elementLabel } from './element-label.js';
 import { recordAction } from './record-action.js';
 /** Every interaction of user-event 14 that can change what the page shows. */
 const METHODS = [
@@ -42,9 +41,17 @@ function patchMethods(target) {
  * It comes in two shapes, the direct API (`userEvent.click(el)`) and an
  * instance from `userEvent.setup()`, and the first delegates to the second,
  * so both are patched and `recordAction`'s depth guard keeps one gesture to
- * one frame. Safe to call more than once.
+ * one frame. When the optional peer is not installed, there is nothing to
+ * patch. Safe to call more than once.
  */
-export function patchTestingLibraryUserEvent() {
+export async function patchTestingLibraryUserEvent() {
+    let userEvent;
+    try {
+        userEvent = (await import('@testing-library/user-event')).default;
+    }
+    catch {
+        return;
+    }
     const direct = userEvent;
     patchMethods(direct);
     const originalSetup = direct.setup;

package/dist/plugin.d.ts

@@ -13,6 +13,28 @@ export interface DescribeMeOptions {
     environment?: DescribeMeEnvironment;
     /** Output directory, relative to the Vitest root. Default: `.describe-me`. */
     outDir?: string;
+    /**
+     * Register the top-level exports of project modules, so a component is named
+     * after its export (`Button`) even when it is an anonymous `forwardRef`,
+     * `memo` or styled component, and its props are read from the right file.
+     * Default: true.
+     */
+    registerExports?: boolean;
+    /**
+     * DOM environments only. Load the browser build of styled-components (v5+)
+     * instead of the Node one, whose `createGlobalStyle` never inserts its CSS on
+     * the client: global resets and fonts would be missing from every snapshot.
+     * Applied when styled-components is installed. Default: true.
+     */
+    styledComponentsBrowserBuild?: boolean;
+    /**
+     * Test files to record, as globs relative to the Vitest root, matched with
+     * picomatch, dotfiles included. Tests in other files still run, but record
+     * nothing and leave the manifest. Default: every test file.
+     */
+    include?: string | string[];
+    /** Test files never to record, as globs like `include`. Wins over `include`. Default: none. */
+    exclude?: string | string[];
 }
 type VitePlugin = NonNullable<ViteUserConfig['plugins']>[number];
 /**

package/dist/plugin.js

@@ -1,4 +1,10 @@
+import { adapterPackageRoot } from './adapter-package-root.js';
+import { compileGlobs } from './compile-globs.js';
+import { projectModulePath } from './project-module-path.js';
+import { registerExports } from './register-exports.js';
 import DescribeMeReporter from './reporter.js';
+import { RUNTIME_OPTIONS_KEY } from './runtime-options.js';
+import { styledComponentsBrowserBuild } from './styled-components-browser-build.js';
 /** For each framework and environment: the render module tests import, and our adapter that wraps it. */
 const RENDER_MODULES = {
     react: {
@@ -6,8 +12,24 @@ const RENDER_MODULES = {
         dom: { original: '@testing-library/react', adapter: '@describe-me/react/testing-library' },
     },
 };
-/** Paths an adapter's own files live under, published or in this workspace. */
-const ADAPTER_PATHS = ['/@describe-me/react/', '/packages/react/'];
+/**
+ * The package an adapter entry point belongs to, e.g.
+ * `@describe-me/react/testing-library` → `@describe-me/react`.
+ */
+function packageNameOf(specifier) {
+    return specifier.split('/').slice(0, 2).join('/');
+}
+/**
+ * Whether a module is one of the adapter's own files, whose imports of the
+ * original module must stay unredirected. `/node_modules/<package>/` is the
+ * fallback for when the project root could not resolve the package.
+ */
+function isAdapterModule(id, adapterRoot, adapterPackage) {
+    if (adapterRoot !== null && id.startsWith(adapterRoot)) {
+        return true;
+    }
+    return id.includes(`/node_modules/${adapterPackage}/`);
+}
 function detectEnvironment(userConfig) {
     return userConfig.test?.browser?.enabled ? 'browser' : 'dom';
 }
@@ -26,7 +48,8 @@ function browserConfig(renderModule) {
         },
     };
 }
-function domConfig(userTest) {
+function domConfig(userConfig, options) {
+    const userTest = userConfig.test;
     const test = {
         setupFiles: ['@describe-me/vitest/setup-dom'],
         // Testing Library would otherwise unmount in its own afterEach, before the
@@ -41,7 +64,14 @@ function domConfig(userTest) {
     else if (userTest.css === false) {
         console.warn('describe-me: `test.css` is false, so imported stylesheets are stubbed and will be missing from the snapshots.');
     }
-    return { test };
+    const styledComponents = options.styledComponentsBrowserBuild === false
+        ? undefined
+        : styledComponentsBrowserBuild(userConfig.root ?? process.cwd());
+    if (!styledComponents) {
+        return { test };
+    }
+    console.info('describe-me: using the browser build of styled-components, for createGlobalStyle');
+    return { resolve: styledComponents.resolve, test: { ...test, ...styledComponents.test } };
 }
 /**
  * One-line integration: `plugins: [describeMe()]`.
@@ -55,6 +85,13 @@ function domConfig(userTest) {
 export function describeMe(options = {}) {
     const { enabled = true, framework = 'react', outDir } = options;
     let renderModule = RENDER_MODULES[framework].browser;
+    // Known once Vite has resolved its config. Vitest always serves; a production
+    // build that shares the config must not carry the export registration.
+    let root = '';
+    let serving = false;
+    // Where the installed adapter lives, so a user path that merely looks like
+    // it (`packages/react/` in a monorepo) is still redirected.
+    let adapterRoot = null;
     return {
         name: 'describe-me',
         enforce: 'pre',
@@ -64,20 +101,30 @@ export function describeMe(options = {}) {
             }
             const environment = options.environment ?? detectEnvironment(userConfig);
             renderModule = RENDER_MODULES[framework][environment];
-            const reporter = new DescribeMeReporter({ outDir });
+            // Compiled here, so invalid globs fail before any test runs. Vite
+            // deep-merges `provide`, so the user's own keys survive.
+            const runtimeOptions = {
+                include: compileGlobs(options.include),
+                exclude: compileGlobs(options.exclude),
+            };
+            const provide = { [RUNTIME_OPTIONS_KEY]: runtimeOptions };
+            const reporter = new DescribeMeReporter({
+                outDir,
+                include: options.include,
+                exclude: options.exclude,
+            });
             // Vite concatenates arrays when merging, so only add `default` when the
             // user has not chosen their own reporters; otherwise they would lose it.
             const reporters = userConfig.test?.reporters ? [reporter] : ['default', reporter];
-            const config = environment === 'browser' ? browserConfig(renderModule) : domConfig(userConfig.test);
-            return { ...config, test: { ...config.test, reporters } };
+            const config = environment === 'browser' ? browserConfig(renderModule) : domConfig(userConfig, options);
+            return { ...config, test: { ...config.test, reporters, provide } };
         },
         async resolveId(source, importer) {
             if (!enabled || source !== renderModule.original) {
                 return null;
             }
             const fromAdapter = importer !== undefined &&
-                (importer.includes(renderModule.adapter) ||
-                    ADAPTER_PATHS.some((path) => importer.includes(path)));
+                isAdapterModule(importer, adapterRoot, packageNameOf(renderModule.adapter));
             if (fromAdapter) {
                 return null;
             }
@@ -86,9 +133,46 @@ export function describeMe(options = {}) {
             // recording nothing, and in a DOM environment it would also leave every
             // test mounted, because Testing Library's auto-cleanup is switched off.
             if (!resolved) {
-                throw new Error(`describe-me: cannot resolve ${renderModule.adapter} (the recording replacement for ${renderModule.original}). Install ${renderModule.adapter.split('/').slice(0, 2).join('/')}.`);
+                throw new Error(`describe-me: cannot resolve ${renderModule.adapter} (the recording replacement for ${renderModule.original}). Install ${packageNameOf(renderModule.adapter)}.`);
             }
             return resolved;
         },
+        configResolved(config) {
+            root = config.root;
+            serving = config.command === 'serve';
+            adapterRoot = adapterPackageRoot(config.root, packageNameOf(renderModule.adapter));
+        },
+        // Names components after their export (see registerExports). `order: 'post'`
+        // runs it after the TypeScript and JSX transforms, so it parses plain
+        // JavaScript, while the plugin as a whole stays `enforce: 'pre'` for the
+        // render redirect above.
+        transform: {
+            order: 'post',
+            handler(code, id) {
+                if (!enabled || options.registerExports === false || !serving) {
+                    return null;
+                }
+                const file = projectModulePath(id, root);
+                // Without the word `export` there is nothing to register: skip the parse.
+                if (file === null || !code.includes('export')) {
+                    return null;
+                }
+                let snippet;
+                // Parse errors are for the user's own tooling to report, and an older
+                // Vite may lack `this.parse`. This transform must never be the reason a
+                // module fails, so it steps aside instead.
+                try {
+                    snippet = registerExports(this.parse(code), file);
+                }
+                catch {
+                    return null;
+                }
+                if (snippet === null) {
+                    return null;
+                }
+                // Appending moves no code, so the source maps of earlier transforms stay valid.
+                return { code: code + snippet, map: null };
+            },
+        },
     };
 }

package/dist/print-diagnostics.d.ts

@@ -0,0 +1,7 @@
+import type { Manifest } from '@describe-me/core/types';
+/**
+ * Warn, one line per kind, about what the manifest could not document. Prints
+ * nothing when everything is named, documented and loadable. The viewer shows
+ * the same list in its header.
+ */
+export declare function printDiagnostics(manifest: Manifest): void;

package/dist/print-diagnostics.js

@@ -0,0 +1,31 @@
+import { manifestDiagnostics } from '@describe-me/core/diagnostics';
+/** How many names or paths a warning line spells out before summing up the rest. */
+const SHOWN = 5;
+function listed(items) {
+    const shown = items.slice(0, SHOWN).join(', ');
+    const rest = items.length - SHOWN;
+    if (rest > 0) {
+        return `${shown} (+${rest} more)`;
+    }
+    return shown;
+}
+function plural(count, one, many) {
+    return `${count} ${count === 1 ? one : many}`;
+}
+/**
+ * Warn, one line per kind, about what the manifest could not document. Prints
+ * nothing when everything is named, documented and loadable. The viewer shows
+ * the same list in its header.
+ */
+export function printDiagnostics(manifest) {
+    const { anonymous, undocumented, assetsMissing } = manifestDiagnostics(manifest);
+    if (anonymous.length > 0) {
+        console.warn(`describe-me: ${plural(anonymous.length, 'test renders', 'tests render')} an anonymous component; export it from a project module or give it a displayName`);
+    }
+    if (undocumented.length > 0) {
+        console.warn(`describe-me: ${plural(undocumented.length, 'component has', 'components have')} no props docs: ${listed(undocumented.map((component) => component.name))}`);
+    }
+    if (assetsMissing.length > 0) {
+        console.warn(`describe-me: ${plural(assetsMissing.length, 'asset was', 'assets were')} not found in the project and will not load in the viewer: ${listed(assetsMissing)}`);
+    }
+}

package/dist/project-module-path.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The path of a Vite module id relative to the project root, with posix
+ * separators, or null when the module is not the project's own source: a
+ * virtual module (`\0…`), a request with a query (`?raw`, `?worker`), anything
+ * outside the root or in node_modules, a non-script file, or a test file.
+ */
+export declare function projectModulePath(id: string, root: string): string | null;

package/dist/project-module-path.js

@@ -0,0 +1,23 @@
+import { isAbsolute, relative, sep } from 'node:path';
+/** Modules that can export a component: JavaScript and TypeScript, with or without JSX. */
+const SCRIPT_MODULE = /\.[cm]?[jt]sx?$/;
+const TEST_MODULE = /\.(test|spec)\.[cm]?[jt]sx?$/;
+/**
+ * The path of a Vite module id relative to the project root, with posix
+ * separators, or null when the module is not the project's own source: a
+ * virtual module (`\0…`), a request with a query (`?raw`, `?worker`), anything
+ * outside the root or in node_modules, a non-script file, or a test file.
+ */
+export function projectModulePath(id, root) {
+    if (root === '' || id.startsWith('\0') || id.includes('?')) {
+        return null;
+    }
+    if (id.includes('/node_modules/') || !SCRIPT_MODULE.test(id) || TEST_MODULE.test(id)) {
+        return null;
+    }
+    const path = relative(root, id);
+    if (path === '' || path === '..' || path.startsWith(`..${sep}`) || isAbsolute(path)) {
+        return null;
+    }
+    return path.split(sep).join('/');
+}

package/dist/read-runtime-options.d.ts

@@ -0,0 +1,3 @@
+import { type RuntimeOptions } from './runtime-options.js';
+/** Without the plugin nothing is provided, so a hand-wired setup keeps recording every test. */
+export declare function readRuntimeOptions(): RuntimeOptions;

package/dist/read-runtime-options.js

@@ -0,0 +1,6 @@
+import { inject } from 'vitest';
+import { RUNTIME_OPTIONS_KEY } from './runtime-options.js';
+/** Without the plugin nothing is provided, so a hand-wired setup keeps recording every test. */
+export function readRuntimeOptions() {
+    return inject(RUNTIME_OPTIONS_KEY) ?? { include: [], exclude: [] };
+}

package/dist/register-exports.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The part of an ESTree node every node has. Rollup (Vite 6 and 7) and
+ * Rolldown (Vite 8) both parse to ESTree, so structural types fit either
+ * without depending on their AST packages.
+ */
+export interface EstreeNode {
+    type: string;
+}
+/** A parsed module, as `this.parse(code)` returns it in a Vite plugin. */
+export interface EstreeProgram {
+    body: readonly EstreeNode[];
+}
+/**
+ * The code to append to a project module so that each value it exports is
+ * registered under its export name, or null when it exports nothing to
+ * register. A component is then named `Button` even when it is an anonymous
+ * `forwardRef` or a styled component.
+ *
+ * The appended code imports nothing: a user's module cannot always resolve
+ * `@describe-me/core`, and a bundled adapter may carry its own copy of it. It
+ * writes to a `WeakMap` on `globalThis` instead, and the first registration of
+ * a value wins, so the defining module beats a barrel that re-exports it.
+ *
+ * Only local bindings are referenced. Re-exports with `from` are skipped (the
+ * defining module registers the value itself), and so are anonymous default
+ * exports, which have no binding to point at.
+ */
+export declare function registerExports(program: EstreeProgram, file: string): string | null;

package/dist/register-exports.js

@@ -0,0 +1,118 @@
+import { EXPORT_REGISTRY_KEY } from '@describe-me/core/types';
+/**
+ * The code to append to a project module so that each value it exports is
+ * registered under its export name, or null when it exports nothing to
+ * register. A component is then named `Button` even when it is an anonymous
+ * `forwardRef` or a styled component.
+ *
+ * The appended code imports nothing: a user's module cannot always resolve
+ * `@describe-me/core`, and a bundled adapter may carry its own copy of it. It
+ * writes to a `WeakMap` on `globalThis` instead, and the first registration of
+ * a value wins, so the defining module beats a barrel that re-exports it.
+ *
+ * Only local bindings are referenced. Re-exports with `from` are skipped (the
+ * defining module registers the value itself), and so are anonymous default
+ * exports, which have no binding to point at.
+ */
+export function registerExports(program, file) {
+    const registrations = program.body.flatMap(registrationsOf);
+    if (registrations.length === 0) {
+        return null;
+    }
+    return snippetFor(registrations, file);
+}
+function registrationsOf(node) {
+    if (node.type === 'ExportNamedDeclaration') {
+        return namedExports(node);
+    }
+    if (node.type === 'ExportDefaultDeclaration') {
+        return defaultExport(node);
+    }
+    return [];
+}
+/** `export const A = …`, `export function A`, `export class A`, `export { a as A }`. */
+function namedExports(node) {
+    if (node.source) {
+        return [];
+    }
+    if (node.declaration) {
+        return declaredNames(node.declaration).map((name) => ({ name, local: name }));
+    }
+    return (node.specifiers ?? []).flatMap(specifierExport);
+}
+/** Identifiers only: a destructuring pattern would need its own walk for little gain. */
+function declaredNames(declaration) {
+    let ids = [];
+    if (declaration.type === 'VariableDeclaration') {
+        ids = declaration.declarations.map((declarator) => declarator.id);
+    }
+    else if (isFunctionOrClass(declaration)) {
+        ids = [declaration.id];
+    }
+    return ids.map(identifierName).filter((name) => name !== null);
+}
+function specifierExport(specifier) {
+    const local = identifierName(specifier.local);
+    const exported = exportedName(specifier.exported);
+    if (local === null || exported === null) {
+        return [];
+    }
+    // `export { Button as default }` is a default export: its local name says more.
+    const name = exported === 'default' ? local : exported;
+    return [{ name, local }];
+}
+/**
+ * `export default Button` and `export default function Button`, under the local
+ * name. A function or class expression (`export default (function A() {})`)
+ * binds nothing in the module scope, so it is left out like any anonymous one.
+ */
+function defaultExport(node) {
+    const { declaration } = node;
+    const local = identifierName(isFunctionOrClass(declaration) ? declaration.id : declaration);
+    if (local === null) {
+        return [];
+    }
+    return [{ name: local, local }];
+}
+function isFunctionOrClass(node) {
+    return node.type === 'FunctionDeclaration' || node.type === 'ClassDeclaration';
+}
+function identifierName(node) {
+    if (node?.type !== 'Identifier') {
+        return null;
+    }
+    return node.name;
+}
+/** `export { a as A }` or, since ES2022, `export { a as 'A' }`. */
+function exportedName(node) {
+    if (node.type === 'Literal') {
+        const { value } = node;
+        return typeof value === 'string' ? value : null;
+    }
+    return identifierName(node);
+}
+/**
+ * Appended after the module's last line, so no existing code moves and the
+ * source maps from earlier transforms stay valid. Starts on a new line and
+ * with a semicolon, in case the module ends in a comment or an unterminated
+ * expression.
+ */
+function snippetFor(registrations, file) {
+    const entries = registrations
+        .map(({ name, local }) => `[${JSON.stringify(name)}, ${local}]`)
+        .join(', ');
+    return [
+        '',
+        '// describe-me: name components after their export (registerExports option)',
+        ';((key, file, entries) => {',
+        '  const registry = globalThis[key] || (globalThis[key] = new WeakMap())',
+        '  for (const [name, value] of entries) {',
+        "    const isObject = typeof value === 'function' || (typeof value === 'object' && value !== null)",
+        '    if (isObject && !registry.has(value)) {',
+        '      registry.set(value, { name, file })',
+        '    }',
+        '  }',
+        `})(Symbol.for(${JSON.stringify(EXPORT_REGISTRY_KEY)}), ${JSON.stringify(file)}, [${entries}])`,
+        '',
+    ].join('\n');
+}

package/dist/register-recording-hooks.d.ts

@@ -1,6 +1,9 @@
+import type { RuntimeOptions } from './runtime-options.js';
 /**
- * The per-test lifecycle shared by every environment: begin a recording
- * before each test, then take the closing frame, hand the frames to the
- * reporter via task.meta, and only then let adapters unmount.
+ * The per-test lifecycle shared by every environment: begin a recording, take
+ * the closing frame, hand the frames to the reporter via task.meta, and only
+ * then let adapters unmount. Teardown runs for unrecorded tests too, because
+ * Testing Library's auto-cleanup is off in jsdom. Concurrent tests would share
+ * the one recorder, so they are not recorded.
  */
-export declare function registerRecordingHooks(): void;
+export declare function registerRecordingHooks(options: RuntimeOptions): void;

package/dist/register-recording-hooks.js

@@ -1,17 +1,41 @@
 import { afterEach, beforeEach } from 'vitest';
 import { META_KEY, recorder } from '@describe-me/core';
+import { fileFilter } from './file-filter.js';
 /**
- * The per-test lifecycle shared by every environment: begin a recording
- * before each test, then take the closing frame, hand the frames to the
- * reporter via task.meta, and only then let adapters unmount.
+ * The per-test lifecycle shared by every environment: begin a recording, take
+ * the closing frame, hand the frames to the reporter via task.meta, and only
+ * then let adapters unmount. Teardown runs for unrecorded tests too, because
+ * Testing Library's auto-cleanup is off in jsdom. Concurrent tests would share
+ * the one recorder, so they are not recorded.
  */
-export function registerRecordingHooks() {
-    beforeEach(() => {
-        recorder.begin();
+export function registerRecordingHooks(options) {
+    const isRecordedFile = fileFilter(options);
+    let warnedConcurrent = false;
+    beforeEach((context) => {
+        if (context.task.concurrent) {
+            if (!warnedConcurrent) {
+                warnedConcurrent = true;
+                console.warn(`describe-me: concurrent tests are not recorded (${context.task.file.name})`);
+            }
+            return;
+        }
+        if (isRecordedFile(context.task.file.name)) {
+            recorder.begin();
+        }
     });
     afterEach(async (context) => {
-        await recorder.capture('end', 'end of test');
-        context.task.meta[META_KEY] = recorder.end();
-        recorder.teardown();
+        try {
+            if (recorder.isActive) {
+                await recorder.capture('end', 'end of test');
+                const record = recorder.end();
+                if (record.frames.length > 0) {
+                    ;
+                    context.task.meta[META_KEY] = record;
+                }
+            }
+        }
+        finally {
+            recorder.teardown();
+        }
     });
 }

package/dist/reporter.d.ts

@@ -2,22 +2,51 @@ import type { Reporter, TestModule, Vitest } from 'vitest/node';
 export interface DescribeMeReporterOptions {
     /** Output directory, relative to the Vitest root. Default: `.describe-me` */
     outDir?: string;
+    /**
+     * Which test files appear in the manifest: globs relative to the Vitest
+     * root, matched with picomatch, dotfiles included. Default: every test file.
+     */
+    include?: string | string[];
+    /**
+     * Test files to leave out of the manifest, as globs like `include`. Wins over
+     * `include`. Default: none.
+     */
+    exclude?: string | string[];
 }
 export default class DescribeMeReporter implements Reporter {
     private readonly outDirOption;
+    private readonly isRecordedFile;
     private root;
     private outDir;
     private snapshots;
+    private assets;
+    private styles;
     private modules;
     constructor(options?: DescribeMeReporterOptions);
     onInit(vitest: Vitest): void;
+    onTestRunStart(): void;
     /**
      * A filtered run (`vitest run Button.test.tsx`) must not wipe the other
      * modules from the manifest, so start from whatever the last run wrote.
-     * Modules whose file no longer exists are dropped.
+     * Modules whose file is gone or no longer selected by `include` / `exclude`
+     * are dropped, and so are the empty tests that 0.4 still wrote.
      */
     private seedFromPreviousRun;
+    /**
+     * A test skipped in this run keeps its previous entry, so a filtered run does
+     * not erase documentation.
+     */
     onTestModuleEnd(module: TestModule): void;
     onTestRunEnd(): Promise<void>;
+    /** Module ids use the platform's separators. Globs expect posix ones. */
+    private isRecordedModule;
+    /** Decided before any snapshot is written, so a dropped test writes no file. */
+    private manifestTestOf;
     private toManifestTest;
+    /**
+     * Store one frame's DOM, with asset URLs pointing into the asset store and
+     * long stylesheets moved to the style store. Assets go first, so stored CSS
+     * carries asset URLs too.
+     */
+    private writeSnapshot;
 }