@describe-me/vitest 0.2.0 → 0.4.0

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

@@ -0,0 +1,61 @@
+import userEvent from '@testing-library/user-event';
+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 = [
+    'click',
+    'dblClick',
+    'tripleClick',
+    'hover',
+    'unhover',
+    'type',
+    'clear',
+    'keyboard',
+    'tab',
+    'paste',
+    'copy',
+    'cut',
+    'pointer',
+    'selectOptions',
+    'deselectOptions',
+    'upload',
+];
+const PATCHED = Symbol.for('describe-me.patched');
+function labelFor(method, args) {
+    const parts = args.map((arg) => elementLabel(arg) ?? describeArg(arg)).filter(Boolean);
+    return `${method}(${parts.join(', ')})`;
+}
+function patchMethods(target) {
+    for (const method of METHODS) {
+        const original = target[method];
+        if (typeof original !== 'function' || original[PATCHED]) {
+            continue;
+        }
+        const wrapped = (...args) => recordAction(labelFor(method, args), async () => original.apply(target, args));
+        wrapped[PATCHED] = true;
+        target[method] = wrapped;
+    }
+}
+/**
+ * Wrap Testing Library's userEvent in place so each call records a frame.
+ * 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.
+ */
+export function patchTestingLibraryUserEvent() {
+    const direct = userEvent;
+    patchMethods(direct);
+    const originalSetup = direct.setup;
+    if (typeof originalSetup !== 'function' || originalSetup[PATCHED]) {
+        return;
+    }
+    const wrappedSetup = (...args) => {
+        const instance = originalSetup.apply(direct, args);
+        patchMethods(instance);
+        return instance;
+    };
+    wrappedSetup[PATCHED] = true;
+    direct.setup = wrappedSetup;
+}

package/dist/plugin.d.ts

@@ -1,11 +1,32 @@
 import type { ViteUserConfig } from 'vitest/config';
+/** Where the tests run: Vitest browser mode, or a simulated DOM such as jsdom. */
+export type DescribeMeEnvironment = 'browser' | 'dom';
 export interface DescribeMeOptions {
     /** Set to false to run the same tests without recording, e.g. for benchmarks. Default: true. */
     enabled?: boolean;
     /** Which framework adapter replaces the test-library `render`. Default: 'react'. */
     framework?: 'react';
+    /**
+     * Which environment the tests run in. Default: detected, `browser` when
+     * `test.browser.enabled` is set and `dom` otherwise.
+     */
+    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;
 }
 type VitePlugin = NonNullable<ViteUserConfig['plugins']>[number];
 /**
@@ -13,8 +34,9 @@ type VitePlugin = NonNullable<ViteUserConfig['plugins']>[number];
  *
  * Registers the setup file and the reporter, and redirects the framework's
  * `render` import to our adapter so existing tests record frames unchanged.
- * The adapter itself still needs the real module, so imports coming from
- * inside it are left alone.
+ * Works in browser mode and in DOM environments such as jsdom; the adapter
+ * itself still needs the real module, so imports coming from inside it are
+ * left alone.
  */
 export declare function describeMe(options?: DescribeMeOptions): VitePlugin;
 export {};

package/dist/plugin.js

@@ -1,19 +1,75 @@
+import { projectModulePath } from './project-module-path.js';
+import { registerExports } from './register-exports.js';
 import DescribeMeReporter from './reporter.js';
-/** For each framework: the render module tests import, and our adapter that wraps it. */
+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: { original: 'vitest-browser-react', adapter: '@describe-me/react' },
+    react: {
+        browser: { original: 'vitest-browser-react', adapter: '@describe-me/react' },
+        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/'];
+function detectEnvironment(userConfig) {
+    return userConfig.test?.browser?.enabled ? 'browser' : 'dom';
+}
+function browserConfig(renderModule) {
+    return {
+        // Vite's dependency scanner runs before our `resolveId` redirect, so it
+        // never sees the adapter. Discovering it mid-run makes Vite re-optimize
+        // and reload, and the test ends up with two copies of the bundled deps
+        // ("Vitest failed to find the runner"). Declaring the adapter up front
+        // keeps a single optimization pass.
+        optimizeDeps: {
+            include: [renderModule.adapter, renderModule.original],
+        },
+        test: {
+            setupFiles: ['@describe-me/vitest/setup'],
+        },
+    };
+}
+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
+        // closing frame is taken. The adapter unmounts through the recorder instead.
+        env: { RTL_SKIP_AUTO_CLEANUP: 'true' },
+    };
+    // Vitest stubs CSS imports by default, which would leave every imported
+    // stylesheet out of the snapshots. An explicit choice by the user wins.
+    if (userTest?.css === undefined) {
+        test.css = true;
+    }
+    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.');
+    }
+    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()]`.
  *
  * Registers the setup file and the reporter, and redirects the framework's
  * `render` import to our adapter so existing tests record frames unchanged.
- * The adapter itself still needs the real module, so imports coming from
- * inside it are left alone.
+ * Works in browser mode and in DOM environments such as jsdom; the adapter
+ * itself still needs the real module, so imports coming from inside it are
+ * left alone.
  */
 export function describeMe(options = {}) {
     const { enabled = true, framework = 'react', outDir } = options;
-    const { original, adapter } = RENDER_MODULES[framework];
+    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;
     return {
         name: 'describe-me',
         enforce: 'pre',
@@ -21,35 +77,69 @@ export function describeMe(options = {}) {
             if (!enabled) {
                 return {};
             }
+            const environment = options.environment ?? detectEnvironment(userConfig);
+            renderModule = RENDER_MODULES[framework][environment];
             const reporter = new DescribeMeReporter({ outDir });
             // 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];
-            return {
-                // Vite's dependency scanner runs before our `resolveId` redirect, so it
-                // never sees the adapter. Discovering it mid-run makes Vite re-optimize
-                // and reload, and the test ends up with two copies of the bundled deps
-                // ("Vitest failed to find the runner"). Declaring the adapter up front
-                // keeps a single optimization pass.
-                optimizeDeps: {
-                    include: [adapter, original],
-                },
-                test: {
-                    setupFiles: ['@describe-me/vitest/setup'],
-                    reporters,
-                },
-            };
+            const config = environment === 'browser' ? browserConfig(renderModule) : domConfig(userConfig, options);
+            return { ...config, test: { ...config.test, reporters } };
         },
-        resolveId(source, importer) {
-            if (!enabled || source !== original) {
+        async resolveId(source, importer) {
+            if (!enabled || source !== renderModule.original) {
                 return null;
             }
             const fromAdapter = importer !== undefined &&
-                (importer.includes(adapter) || importer.includes('/packages/react/'));
+                (importer.includes(renderModule.adapter) ||
+                    ADAPTER_PATHS.some((path) => importer.includes(path)));
             if (fromAdapter) {
                 return null;
             }
-            return this.resolve(adapter, importer, { skipSelf: true });
+            const resolved = await this.resolve(renderModule.adapter, importer, { skipSelf: true });
+            // Falling back to the original module would look like success while
+            // 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('/')}.`);
+            }
+            return resolved;
+        },
+        configResolved(config) {
+            root = config.root;
+            serving = config.command === 'serve';
+        },
+        // 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/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

@@ -0,0 +1,6 @@
+/**
+ * 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.
+ */
+export declare function registerRecordingHooks(): void;

package/dist/register-recording-hooks.js

@@ -0,0 +1,17 @@
+import { afterEach, beforeEach } from 'vitest';
+import { META_KEY, recorder } from '@describe-me/core';
+/**
+ * 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.
+ */
+export function registerRecordingHooks() {
+    beforeEach(() => {
+        recorder.begin();
+    });
+    afterEach(async (context) => {
+        await recorder.capture('end', 'end of test');
+        context.task.meta[META_KEY] = recorder.end();
+        recorder.teardown();
+    });
+}

package/dist/reporter.d.ts

@@ -8,9 +8,11 @@ export default class DescribeMeReporter implements Reporter {
     private root;
     private outDir;
     private snapshots;
+    private assets;
     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.
@@ -20,4 +22,6 @@ export default class DescribeMeReporter implements Reporter {
     onTestModuleEnd(module: TestModule): void;
     onTestRunEnd(): Promise<void>;
     private toManifestTest;
+    /** Store one frame's DOM, with its project asset URLs pointing into the asset store. */
+    private writeSnapshot;
 }

package/dist/reporter.js

@@ -5,8 +5,10 @@
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { join, relative, resolve } from 'node:path';
 import { META_KEY, } from '@describe-me/core/types';
+import { AssetStore } from './asset-store.js';
 import { collectComponentDocsSafely } from './collect-component-docs-safely.js';
 import { componentEntries } from './component-entries.js';
+import { printDiagnostics } from './print-diagnostics.js';
 import { SnapshotStore } from './snapshot-store.js';
 import { testPath } from './test-path.js';
 export default class DescribeMeReporter {
@@ -14,6 +16,7 @@ export default class DescribeMeReporter {
     root = process.cwd();
     outDir = '';
     snapshots;
+    assets;
     modules = new Map();
     constructor(options = {}) {
         this.outDirOption = options.outDir ?? '.describe-me';
@@ -22,8 +25,12 @@ export default class DescribeMeReporter {
         this.root = vitest.config.root;
         this.outDir = resolve(this.root, this.outDirOption);
         this.snapshots = new SnapshotStore(this.outDir);
+        this.assets = new AssetStore(this.outDir, this.root);
         this.seedFromPreviousRun();
     }
+    onTestRunStart() {
+        this.assets.startRun();
+    }
     /**
      * 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.
@@ -54,15 +61,22 @@ export default class DescribeMeReporter {
     async onTestRunEnd() {
         const modules = Array.from(this.modules.values()).sort((left, right) => left.id.localeCompare(right.id));
         const components = await collectComponentDocsSafely(this.root, componentEntries(modules, this.root));
+        // Only what this run found: a filtered run does not know which of the
+        // previous run's missing assets belonged to the modules it skipped.
+        const assetsMissing = this.assets.missing();
         const manifest = {
             version: 1,
             generatedAt: new Date().toISOString(),
             root: this.root,
             modules,
             components,
+            assetsMissing,
         };
-        this.snapshots.collectGarbage(manifest.modules.flatMap((mod) => mod.tests.flatMap((test) => test.frames.map((frame) => frame.snapshot))));
+        const snapshotFiles = manifest.modules.flatMap((mod) => mod.tests.flatMap((test) => test.frames.map((frame) => frame.snapshot)));
+        this.snapshots.collectGarbage(snapshotFiles);
+        this.assets.collectGarbage(snapshotFiles);
         writeFileSync(join(this.outDir, 'manifest.json'), JSON.stringify(manifest, null, 2));
+        printDiagnostics(manifest);
     }
     toManifestTest(tc) {
         const record = tc.meta()[META_KEY];
@@ -73,7 +87,7 @@ export default class DescribeMeReporter {
             label: frame.label,
             at: frame.at,
             meta: frame.meta,
-            snapshot: this.snapshots.write(frame.snapshot),
+            snapshot: this.writeSnapshot(frame.snapshot, record?.origin),
         }));
         return {
             id: tc.id,
@@ -87,4 +101,8 @@ export default class DescribeMeReporter {
             frames,
         };
     }
+    /** Store one frame's DOM, with its project asset URLs pointing into the asset store. */
+    writeSnapshot(snapshot, origin) {
+        return this.snapshots.write(this.assets.rewrite(JSON.stringify(snapshot), origin));
+    }
 }

package/dist/setup-dom.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/setup-dom.js

@@ -0,0 +1,11 @@
+/**
+ * Vitest setup file for DOM environments such as jsdom:
+ * `setupFiles: ['@describe-me/vitest/setup-dom']`. Patches Testing Library's
+ * userEvent so every interaction records a frame, and registers the
+ * recording hooks. Never imports `vitest/browser`, which only exists in
+ * browser mode.
+ */
+import { patchTestingLibraryUserEvent } from './patch-testing-library-user-event.js';
+import { registerRecordingHooks } from './register-recording-hooks.js';
+patchTestingLibraryUserEvent();
+registerRecordingHooks();

package/dist/setup.js

@@ -1,19 +1,11 @@
 /**
- * Vitest setup file: `setupFiles: ['@describe-me/vitest/setup']`.
- * Runs in the browser. Patches Vitest's locators and userEvent so every
- * interaction records a frame, begins a recording before each test, and hands
- * the frames to the reporter via task.meta.
+ * Vitest setup file for browser mode: `setupFiles: ['@describe-me/vitest/setup']`.
+ * Patches Vitest's locators and userEvent so every interaction records a
+ * frame, and registers the recording hooks. For jsdom use `./setup-dom`.
  */
-import { afterEach, beforeEach } from 'vitest';
-import { META_KEY, recorder } from '@describe-me/core';
 import { patchLocators } from './patch-locators.js';
 import { patchUserEvent } from './patch-user-event.js';
+import { registerRecordingHooks } from './register-recording-hooks.js';
 patchLocators();
 patchUserEvent();
-beforeEach(() => {
-    recorder.begin();
-});
-afterEach(async (context) => {
-    await recorder.capture('end', 'end of test');
-    context.task.meta[META_KEY] = recorder.end();
-});
+registerRecordingHooks();