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

package/README.md

@@ -19,10 +19,13 @@ plugin detects where the tests run:
 - **Browser mode** (`test.browser.enabled`): redirects `vitest-browser-react`,
   records a frame after every `Locator` action and keyboard-level `userEvent`.
 - **DOM environments** such as jsdom (anything else): redirects
-  `@testing-library/react`, records a frame after every
+  `@testing-library/react`, records a frame after every `fireEvent` and every
   `@testing-library/user-event` call, turns on `test.css` so imported
   stylesheets reach the snapshots, and sets `RTL_SKIP_AUTO_CLEANUP` so the
-  component is unmounted only after the closing frame.
+  component is unmounted only after the closing frame. The setup file sets
+  React's `IS_REACT_ACT_ENVIRONMENT` where Testing Library would, so act
+  warnings match a run without describe-me. It also works without user-event
+  installed.
 
 ```ts
 import { describeMe } from '@describe-me/vitest/plugin'
@@ -44,9 +47,17 @@ export default defineConfig({
 
 Pass `describeMe({ environment: 'browser' | 'dom' })` to override the detection.
 
-The pieces can also be wired by hand, in which case tests import `render` from
-the adapter themselves (`@describe-me/react` in browser mode,
-`@describe-me/react/testing-library` in jsdom):
+A test that records no frame before the closing one (no recording `render`,
+no interaction, no `step()`) costs no snapshot and is left out of the
+manifest. `describeMe({ include, exclude })` chooses which test files are
+recorded, with picomatch globs relative to the Vitest root. `exclude` wins.
+Tests in other files still run, but record nothing. The reporter takes the
+same two options, but on its own it only filters the manifest: without the
+plugin the setup file does not know them.
+
+The pieces can also be wired by hand. Tests then import from the adapter
+themselves: `render` from `@describe-me/react` in browser mode, and `render`,
+`fireEvent` and `cleanup` from `@describe-me/react/testing-library` in jsdom:
 
 ```ts
 import DescribeMeReporter from '@describe-me/vitest/reporter'

package/dist/adapter-package-root.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The directory of the adapter package the project resolves, e.g.
+ * `/repo/node_modules/@describe-me/react/`, with posix separators and a
+ * trailing slash the way Vite ids look, or null when it cannot be resolved.
+ * It is the real path, so a workspace link points at its source directory.
+ */
+export declare function adapterPackageRoot(root: string, packageName: string): string | null;

package/dist/adapter-package-root.js

@@ -0,0 +1,40 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join, sep } from 'node:path';
+/** The `name` in a directory's package.json, if it has a readable one. */
+function packageNameIn(directory) {
+    const manifest = join(directory, 'package.json');
+    if (!existsSync(manifest)) {
+        return undefined;
+    }
+    try {
+        return JSON.parse(readFileSync(manifest, 'utf8')).name;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The directory of the adapter package the project resolves, e.g.
+ * `/repo/node_modules/@describe-me/react/`, with posix separators and a
+ * trailing slash the way Vite ids look, or null when it cannot be resolved.
+ * It is the real path, so a workspace link points at its source directory.
+ */
+export function adapterPackageRoot(root, packageName) {
+    let entry;
+    // The package does not export `./package.json`, so resolve its entry and walk up.
+    try {
+        entry = createRequire(join(root, 'package.json')).resolve(packageName);
+    }
+    catch {
+        return null;
+    }
+    let directory = dirname(entry);
+    while (directory !== dirname(directory)) {
+        if (packageNameIn(directory) === packageName) {
+            return `${directory.split(sep).join('/')}/`;
+        }
+        directory = dirname(directory);
+    }
+    return null;
+}

package/dist/asset-store.d.ts

@@ -15,8 +15,11 @@ export declare class AssetStore {
     /** Stored name per URL pathname in this run, or null when it is not a project file. */
     private readonly names;
     private readonly notFound;
-    /** Asset names per snapshot file. Snapshots are content-addressed, so an entry never goes stale. */
-    private readonly referencesBySnapshot;
+    /**
+     * Asset names per snapshot or style chunk. Both are content-addressed, so an
+     * entry never goes stale.
+     */
+    private readonly referencesByFile;
     constructor(outDir: string, root: string);
     /** Forget what the previous run found: files may have changed or appeared since. */
     startRun(): void;
@@ -31,12 +34,12 @@ export declare class AssetStore {
     /** Root-relative paths that snapshots in this run pointed at but that do not exist. */
     missing(): string[];
     /**
-     * Drop the assets no kept snapshot refers to. Paths are relative to the
-     * output directory, as the manifest stores them. Every kept file is scanned,
-     * not only the ones written now: snapshots of modules that were not re-run
-     * were rewritten by an earlier run.
+     * Drop the assets no kept snapshot or style chunk refers to. Paths are
+     * relative to the output directory, as the manifest stores them. Every kept
+     * file is scanned, not only the ones written now: snapshots of modules that
+     * were not re-run were rewritten by an earlier run.
      */
-    collectGarbage(snapshotFiles: Iterable<string>): void;
+    collectGarbage(files: Iterable<string>): void;
     private referencesIn;
     /** The asset URL for a root-relative URL path, or null when it is not a project file. */
     private assetUrl;

package/dist/asset-store.js

@@ -94,8 +94,11 @@ export class AssetStore {
     /** Stored name per URL pathname in this run, or null when it is not a project file. */
     names = new Map();
     notFound = new Set();
-    /** Asset names per snapshot file. Snapshots are content-addressed, so an entry never goes stale. */
-    referencesBySnapshot = new Map();
+    /**
+     * Asset names per snapshot or style chunk. Both are content-addressed, so an
+     * entry never goes stale.
+     */
+    referencesByFile = new Map();
     constructor(outDir, root) {
         this.outDir = outDir;
         this.dir = join(outDir, 'assets');
@@ -137,19 +140,19 @@ export class AssetStore {
         return Array.from(this.notFound).sort();
     }
     /**
-     * Drop the assets no kept snapshot refers to. Paths are relative to the
-     * output directory, as the manifest stores them. Every kept file is scanned,
-     * not only the ones written now: snapshots of modules that were not re-run
-     * were rewritten by an earlier run.
+     * Drop the assets no kept snapshot or style chunk refers to. Paths are
+     * relative to the output directory, as the manifest stores them. Every kept
+     * file is scanned, not only the ones written now: snapshots of modules that
+     * were not re-run were rewritten by an earlier run.
      */
-    collectGarbage(snapshotFiles) {
+    collectGarbage(files) {
         const stored = readdirSync(this.dir);
         if (stored.length === 0) {
             return;
         }
         const keep = new Set();
-        for (const snapshotFile of snapshotFiles) {
-            for (const name of this.referencesIn(snapshotFile)) {
+        for (const file of files) {
+            for (const name of this.referencesIn(file)) {
                 keep.add(name);
             }
         }
@@ -159,18 +162,18 @@ export class AssetStore {
             }
         }
     }
-    referencesIn(snapshotFile) {
-        const cached = this.referencesBySnapshot.get(snapshotFile);
+    referencesIn(file) {
+        const cached = this.referencesByFile.get(file);
         if (cached) {
             return cached;
         }
-        const path = join(this.outDir, snapshotFile);
+        const path = join(this.outDir, file);
         if (!isFile(path)) {
             return [];
         }
-        const json = readFileSync(path, 'utf8');
-        const names = Array.from(json.matchAll(ASSET_REFERENCE), (match) => match[1]);
-        this.referencesBySnapshot.set(snapshotFile, names);
+        const text = readFileSync(path, 'utf8');
+        const names = Array.from(text.matchAll(ASSET_REFERENCE), (match) => match[1]);
+        this.referencesByFile.set(file, names);
         return names;
     }
     /** The asset URL for a root-relative URL path, or null when it is not a project file. */

package/dist/compile-globs.d.ts

@@ -0,0 +1,6 @@
+import type { CompiledGlob } from './runtime-options.js';
+/**
+ * Plain `{ source, flags }` pairs, because the globs travel to the test
+ * runtime as JSON. Invalid input fails here, before any test runs.
+ */
+export declare function compileGlobs(patterns: string | string[] | undefined): CompiledGlob[];

package/dist/compile-globs.js

@@ -0,0 +1,20 @@
+import { inspect } from 'node:util';
+import picomatch from 'picomatch';
+/**
+ * Plain `{ source, flags }` pairs, because the globs travel to the test
+ * runtime as JSON. Invalid input fails here, before any test runs.
+ */
+export function compileGlobs(patterns) {
+    if (patterns === undefined) {
+        return [];
+    }
+    const list = Array.isArray(patterns) ? patterns : [patterns];
+    return list.map((pattern) => {
+        // picomatch throws its own unprefixed TypeError for an empty string.
+        if (typeof pattern !== 'string' || pattern === '') {
+            throw new Error(`describe-me: include and exclude expect non-empty glob strings, got ${inspect(pattern)}`);
+        }
+        const regExp = picomatch.makeRe(pattern, { dot: true, windows: false });
+        return { source: regExp.source, flags: regExp.flags };
+    });
+}

package/dist/file-filter.d.ts

@@ -0,0 +1,7 @@
+import type { RuntimeOptions } from './runtime-options.js';
+/**
+ * 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 declare function fileFilter(options: Pick<RuntimeOptions, 'include' | 'exclude'>): (fileName: string) => boolean;

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

@@ -27,6 +27,14 @@ export interface DescribeMeOptions {
      * 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,6 +1,9 @@
+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 = {
@@ -9,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';
 }
@@ -70,6 +89,9 @@ export function describeMe(options = {}) {
     // 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',
@@ -79,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, options);
-            return { ...config, test: { ...config.test, reporters } };
+            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;
             }
@@ -101,13 +133,14 @@ 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

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-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,13 +2,25 @@ 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;
@@ -16,12 +28,25 @@ export default class DescribeMeReporter implements Reporter {
     /**
      * 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 its project asset URLs pointing into the asset store. */
+    /**
+     * 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;
 }

package/dist/reporter.js

@@ -1,31 +1,45 @@
 /**
  * Node-side Vitest reporter. Collects frames from task.meta and writes
- * `.describe-me/manifest.json` plus one file per snapshot.
+ * `.describe-me/`: `manifest.json`, `snapshots/`, `styles/` and `assets/`.
  */
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
-import { join, relative, resolve } from 'node:path';
+import { join, relative, resolve, sep } 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 { compileGlobs } from './compile-globs.js';
 import { componentEntries } from './component-entries.js';
+import { fileFilter } from './file-filter.js';
+import { isRecordedTest } from './is-recorded-test.js';
 import { printDiagnostics } from './print-diagnostics.js';
 import { SnapshotStore } from './snapshot-store.js';
+import { StyleStore } from './style-store.js';
 import { testPath } from './test-path.js';
+function recordOf(tc) {
+    return tc.meta()[META_KEY];
+}
 export default class DescribeMeReporter {
     outDirOption;
+    isRecordedFile;
     root = process.cwd();
     outDir = '';
     snapshots;
     assets;
+    styles;
     modules = new Map();
     constructor(options = {}) {
         this.outDirOption = options.outDir ?? '.describe-me';
+        this.isRecordedFile = fileFilter({
+            include: compileGlobs(options.include),
+            exclude: compileGlobs(options.exclude),
+        });
     }
     onInit(vitest) {
         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.styles = new StyleStore(this.outDir);
         this.seedFromPreviousRun();
     }
     onTestRunStart() {
@@ -34,7 +48,8 @@ export default class DescribeMeReporter {
     /**
      * 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.
      */
     seedFromPreviousRun() {
         const file = join(this.outDir, 'manifest.json');
@@ -44,8 +59,11 @@ export default class DescribeMeReporter {
         try {
             const previous = JSON.parse(readFileSync(file, 'utf8'));
             for (const mod of previous.modules ?? []) {
-                if (existsSync(resolve(this.root, mod.id))) {
-                    this.modules.set(mod.id, mod);
+                const tests = mod.tests.filter((test) => isRecordedTest(test));
+                if (tests.length > 0 &&
+                    this.isRecordedModule(mod.id) &&
+                    existsSync(resolve(this.root, mod.id))) {
+                    this.modules.set(mod.id, { ...mod, tests });
                 }
             }
         }
@@ -53,9 +71,28 @@ export default class DescribeMeReporter {
             // corrupt or incompatible manifest: start fresh
         }
     }
+    /**
+     * A test skipped in this run keeps its previous entry, so a filtered run does
+     * not erase documentation.
+     */
     onTestModuleEnd(module) {
         const id = relative(this.root, module.moduleId);
-        const tests = Array.from(module.children.allTests()).map((tc) => this.toManifestTest(tc));
+        if (!this.isRecordedModule(id)) {
+            this.modules.delete(id);
+            return;
+        }
+        const previous = this.modules.get(id);
+        const tests = [];
+        for (const tc of module.children.allTests()) {
+            const test = this.manifestTestOf(tc, previous);
+            if (test) {
+                tests.push(test);
+            }
+        }
+        if (tests.length === 0) {
+            this.modules.delete(id);
+            return;
+        }
         this.modules.set(id, { id, tests });
     }
     async onTestRunEnd() {
@@ -74,20 +111,35 @@ export default class DescribeMeReporter {
         };
         const snapshotFiles = manifest.modules.flatMap((mod) => mod.tests.flatMap((test) => test.frames.map((frame) => frame.snapshot)));
         this.snapshots.collectGarbage(snapshotFiles);
-        this.assets.collectGarbage(snapshotFiles);
+        const styleFiles = this.styles.collectGarbage(snapshotFiles);
+        this.assets.collectGarbage([...snapshotFiles, ...styleFiles]);
         writeFileSync(join(this.outDir, 'manifest.json'), JSON.stringify(manifest, null, 2));
         printDiagnostics(manifest);
     }
-    toManifestTest(tc) {
-        const record = tc.meta()[META_KEY];
+    /** Module ids use the platform's separators. Globs expect posix ones. */
+    isRecordedModule(id) {
+        return this.isRecordedFile(id.split(sep).join('/'));
+    }
+    /** Decided before any snapshot is written, so a dropped test writes no file. */
+    manifestTestOf(tc, previous) {
+        const record = recordOf(tc);
+        if (record && isRecordedTest(record)) {
+            return this.toManifestTest(tc, record);
+        }
+        if (tc.result().state !== 'skipped') {
+            return undefined;
+        }
+        return previous?.tests.find((test) => test.id === tc.id && test.fullName === tc.fullName && isRecordedTest(test));
+    }
+    toManifestTest(tc, record) {
         const result = tc.result();
-        const frames = (record?.frames ?? []).map((frame) => ({
+        const frames = record.frames.map((frame) => ({
             id: frame.id,
             kind: frame.kind,
             label: frame.label,
             at: frame.at,
             meta: frame.meta,
-            snapshot: this.writeSnapshot(frame.snapshot, record?.origin),
+            snapshot: this.writeSnapshot(frame.snapshot, record.origin),
         }));
         return {
             id: tc.id,
@@ -97,12 +149,18 @@ export default class DescribeMeReporter {
             state: result.state ?? 'pending',
             duration: tc.diagnostic()?.duration,
             errors: result.errors?.map((error) => ({ message: error.message, stack: error.stack })),
-            component: record?.component,
+            component: record.component,
             frames,
         };
     }
-    /** Store one frame's DOM, with its project asset URLs pointing into the asset store. */
+    /**
+     * 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.
+     */
     writeSnapshot(snapshot, origin) {
-        return this.snapshots.write(this.assets.rewrite(JSON.stringify(snapshot), origin));
+        // A mixed install, where an older core created the global recorder, still hands over objects.
+        const json = typeof snapshot === 'string' ? snapshot : JSON.stringify(snapshot);
+        return this.snapshots.write(this.styles.extract(this.assets.rewrite(json, origin)));
     }
 }

package/dist/runtime-options.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Travels from the plugin to the setup files through Vitest's `provide` /
+ * `inject`. Keep it plain JSON: the browser receives it serialized, so a
+ * RegExp would not survive. The test runtime imports this file, so it imports
+ * nothing itself.
+ */
+export interface CompiledGlob {
+    source: string;
+    flags: string;
+}
+export interface RuntimeOptions {
+    /** Empty means every test file. */
+    include: CompiledGlob[];
+    /** Wins over `include`. */
+    exclude: CompiledGlob[];
+}
+export declare const RUNTIME_OPTIONS_KEY: "describe-me";
+declare module 'vitest' {
+    interface ProvidedContext {
+        'describe-me': RuntimeOptions;
+    }
+}

package/dist/runtime-options.js

@@ -0,0 +1,7 @@
+/**
+ * Travels from the plugin to the setup files through Vitest's `provide` /
+ * `inject`. Keep it plain JSON: the browser receives it serialized, so a
+ * RegExp would not survive. The test runtime imports this file, so it imports
+ * nothing itself.
+ */
+export const RUNTIME_OPTIONS_KEY = 'describe-me';

package/dist/setup-dom.js

@@ -1,11 +1,15 @@
 /**
  * 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.
+ * userEvent, when it is installed, so every interaction records a frame, sets
+ * React's act flag where Testing Library would, and registers the recording
+ * hooks. Which test files are recorded (`include` / `exclude`) comes from the
+ * plugin. Never imports `vitest/browser`, which only exists in browser mode.
  */
+import { mirrorReactActEnvironment } from './mirror-react-act-environment.js';
 import { patchTestingLibraryUserEvent } from './patch-testing-library-user-event.js';
+import { readRuntimeOptions } from './read-runtime-options.js';
 import { registerRecordingHooks } from './register-recording-hooks.js';
-patchTestingLibraryUserEvent();
-registerRecordingHooks();
+await patchTestingLibraryUserEvent();
+mirrorReactActEnvironment();
+registerRecordingHooks(readRuntimeOptions());

package/dist/setup.js

@@ -1,11 +1,13 @@
 /**
  * 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`.
+ * frame, and registers the recording hooks. Which test files are recorded
+ * (`include` / `exclude`) comes from the plugin. For jsdom use `./setup-dom`.
  */
 import { patchLocators } from './patch-locators.js';
 import { patchUserEvent } from './patch-user-event.js';
+import { readRuntimeOptions } from './read-runtime-options.js';
 import { registerRecordingHooks } from './register-recording-hooks.js';
 patchLocators();
 patchUserEvent();
-registerRecordingHooks();
+registerRecordingHooks(readRuntimeOptions());

package/dist/split-stylesheet.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Split a stylesheet into chunks of about 4 KB, cut between top-level rules
+ * where their content decides, so a sheet that grows from test to test keeps
+ * most of its chunks. `chunks.join('')` is always the input, even for
+ * malformed CSS.
+ */
+export declare function splitStylesheet(css: string): string[];

package/dist/split-stylesheet.js

@@ -0,0 +1,114 @@
+/** A chunk is never closed below this length, so small rules do not end up in tiny files. */
+const MIN_CHUNK = 1024;
+/**
+ * A chunk is closed once it reaches this length. Only its last rule can take it
+ * past the limit, because a rule is never split.
+ */
+const MAX_CHUNK = 16384;
+/**
+ * Past `MIN_CHUNK`, a rule of `n` characters ends its chunk with a probability
+ * of about `n / BOUNDARY_SPACING`, decided by a hash of its text. Chunks then
+ * average about 4 KB, and where they end depends on content, not on offsets.
+ */
+const BOUNDARY_SPACING = 3072;
+/** Boundaries only need a cheap, stable hash, not sha1. */
+function fnv1a32(text) {
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < text.length; i++) {
+        hash = Math.imul(hash ^ text.charCodeAt(i), 0x01000193);
+    }
+    return hash >>> 0;
+}
+function isBoundary(piece) {
+    return fnv1a32(piece) % BOUNDARY_SPACING < piece.length;
+}
+function endOfComment(css, start) {
+    const close = css.indexOf('*/', start + 2);
+    return close === -1 ? css.length : close + 2;
+}
+function endOfString(css, start) {
+    const quote = css[start];
+    let i = start + 1;
+    while (i < css.length) {
+        if (css[i] === '\\') {
+            i += 2;
+        }
+        else if (css[i] === quote) {
+            return i + 1;
+        }
+        else {
+            i++;
+        }
+    }
+    return css.length;
+}
+/**
+ * Cut a stylesheet after every top-level rule: after the `}` that closes a
+ * top-level block, or after a semicolon at depth 0 (`@import`). Strings,
+ * comments and escapes are skipped and nothing in parentheses counts, so
+ * `content: "}"` or an unquoted font URL with semicolons never ends a rule.
+ */
+function topLevelPieces(css) {
+    const pieces = [];
+    let start = 0;
+    let braces = 0;
+    let parens = 0;
+    let i = 0;
+    while (i < css.length) {
+        const char = css[i];
+        if (char === '\\') {
+            i += 2;
+            continue;
+        }
+        if (char === '/' && css[i + 1] === '*') {
+            i = endOfComment(css, i);
+            continue;
+        }
+        if (char === '"' || char === "'") {
+            i = endOfString(css, i);
+            continue;
+        }
+        if (char === '(') {
+            parens++;
+        }
+        else if (char === ')') {
+            parens = Math.max(0, parens - 1);
+        }
+        else if (parens === 0 && char === '{') {
+            braces++;
+        }
+        else if (parens === 0 && char === '}') {
+            braces = Math.max(0, braces - 1);
+        }
+        i++;
+        if (parens === 0 && braces === 0 && (char === '}' || char === ';')) {
+            pieces.push(css.slice(start, i));
+            start = i;
+        }
+    }
+    if (start < css.length) {
+        pieces.push(css.slice(start));
+    }
+    return pieces;
+}
+/**
+ * Split a stylesheet into chunks of about 4 KB, cut between top-level rules
+ * where their content decides, so a sheet that grows from test to test keeps
+ * most of its chunks. `chunks.join('')` is always the input, even for
+ * malformed CSS.
+ */
+export function splitStylesheet(css) {
+    const chunks = [];
+    let current = '';
+    for (const piece of topLevelPieces(css)) {
+        current += piece;
+        if (current.length >= MAX_CHUNK || (current.length >= MIN_CHUNK && isBoundary(piece))) {
+            chunks.push(current);
+            current = '';
+        }
+    }
+    if (current !== '') {
+        chunks.push(current);
+    }
+    return chunks;
+}

package/dist/style-store.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Content-addressed store for the stylesheets rrweb copies into every capture,
+ * living in `<outDir>/styles`. A sheet is stored once, in chunks, so one that
+ * grows from test to test shares most of them.
+ */
+export declare class StyleStore {
+    private readonly outDir;
+    private readonly dir;
+    /** Snapshots are content-addressed, so a cached entry never goes stale. */
+    private readonly referencesBySnapshot;
+    constructor(outDir: string);
+    /**
+     * Replace each long `_cssText` in a serialized snapshot with a reference to
+     * its chunks, writing the ones not stored yet. Idempotent.
+     */
+    extract(json: string): string;
+    /**
+     * Drop the chunks no kept snapshot refers to, and return the kept ones as
+     * sorted `styles/<hash>.css` paths for the asset store. Paths are relative to
+     * the output directory, as the manifest stores them.
+     */
+    collectGarbage(snapshotFiles: Iterable<string>): string[];
+    private write;
+    private referencesIn;
+}

package/dist/style-store.js

@@ -0,0 +1,90 @@
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync, } from 'node:fs';
+import { join } from 'node:path';
+import { STYLE_URL_PREFIX } from '@describe-me/core/types';
+import { splitStylesheet } from './split-stylesheet.js';
+/** Shorter sheets stay inline, where they cost less than a reference and a file of their own. */
+const MIN_EXTRACTED_LENGTH = 256;
+/**
+ * Inside a JSON string every `"` is escaped, so only a real `_cssText` key
+ * matches. Unrolled, because `(?:[^"\\]|\\.)*` is much slower on
+ * megabyte-long sheets.
+ */
+const CSS_TEXT_MEMBER = /"_cssText":"([^"\\]*(?:\\.[^"\\]*)*)"/g;
+const STYLE_REFERENCE = new RegExp(`${STYLE_URL_PREFIX}([0-9a-f]{16}(?:\\+[0-9a-f]{16})*)`, 'g');
+/**
+ * Content-addressed store for the stylesheets rrweb copies into every capture,
+ * living in `<outDir>/styles`. A sheet is stored once, in chunks, so one that
+ * grows from test to test shares most of them.
+ */
+export class StyleStore {
+    outDir;
+    dir;
+    /** Snapshots are content-addressed, so a cached entry never goes stale. */
+    referencesBySnapshot = new Map();
+    constructor(outDir) {
+        this.outDir = outDir;
+        this.dir = join(outDir, 'styles');
+        mkdirSync(this.dir, { recursive: true });
+    }
+    /**
+     * Replace each long `_cssText` in a serialized snapshot with a reference to
+     * its chunks, writing the ones not stored yet. Idempotent.
+     */
+    extract(json) {
+        return json.replace(CSS_TEXT_MEMBER, (member, escaped) => {
+            const css = JSON.parse(`"${escaped}"`);
+            if (css.length < MIN_EXTRACTED_LENGTH || css.startsWith(STYLE_URL_PREFIX)) {
+                return member;
+            }
+            const hashes = splitStylesheet(css).map((chunk) => this.write(chunk));
+            return `"_cssText":"${STYLE_URL_PREFIX}${hashes.join('+')}"`;
+        });
+    }
+    /**
+     * Drop the chunks no kept snapshot refers to, and return the kept ones as
+     * sorted `styles/<hash>.css` paths for the asset store. Paths are relative to
+     * the output directory, as the manifest stores them.
+     */
+    collectGarbage(snapshotFiles) {
+        const keep = new Set();
+        for (const snapshotFile of snapshotFiles) {
+            for (const hash of this.referencesIn(snapshotFile)) {
+                keep.add(`${hash}.css`);
+            }
+        }
+        const kept = [];
+        for (const file of readdirSync(this.dir)) {
+            if (keep.has(file)) {
+                kept.push(`styles/${file}`);
+            }
+            else {
+                rmSync(join(this.dir, file), { force: true });
+            }
+        }
+        return kept.sort();
+    }
+    write(chunk) {
+        const hash = createHash('sha1').update(chunk).digest('hex').slice(0, 16);
+        const file = join(this.dir, `${hash}.css`);
+        // Not remembered in memory: in watch mode, GC can delete the file between runs.
+        if (!existsSync(file)) {
+            writeFileSync(file, chunk);
+        }
+        return hash;
+    }
+    referencesIn(snapshotFile) {
+        const cached = this.referencesBySnapshot.get(snapshotFile);
+        if (cached) {
+            return cached;
+        }
+        const path = join(this.outDir, snapshotFile);
+        if (!statSync(path, { throwIfNoEntry: false })?.isFile()) {
+            return [];
+        }
+        const json = readFileSync(path, 'utf8');
+        const hashes = Array.from(json.matchAll(STYLE_REFERENCE), (match) => match[1].split('+')).flat();
+        this.referencesBySnapshot.set(snapshotFile, hashes);
+        return hashes;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@describe-me/vitest",
-  "version": "0.4.0",
+  "version": "0.5.0-next.0",
   "description": "Vitest integration for describe-me: plugin, setup file and reporter",
   "keywords": [
     "vitest",
@@ -58,12 +58,13 @@
     "./dist/setup-dom.js"
   ],
   "dependencies": {
-    "@describe-me/core": "^0.4.0"
+    "picomatch": "^4.0.3",
+    "@describe-me/core": "^0.5.0-next.0"
   },
   "peerDependencies": {
-    "vitest": ">=4",
-    "typescript": ">=5.0",
-    "@testing-library/user-event": ">=14"
+    "vitest": "^4.0.0 || ^5.0.0",
+    "typescript": "^5.0.0 || ^6.0.0",
+    "@testing-library/user-event": "^14.0.0"
   },
   "peerDependenciesMeta": {
     "typescript": {
@@ -78,7 +79,8 @@
     "@types/node": "^22",
     "typescript": "^6",
     "@testing-library/user-event": "^14.6.1",
-    "@testing-library/dom": "^10.4.0"
+    "@testing-library/dom": "^10.4.0",
+    "@types/picomatch": "^4.0.3"
   },
   "scripts": {
     "build": "rimraf dist && tsc -p tsconfig.json"

package/dist/element-label.d.ts

@@ -1,6 +0,0 @@
-/**
- * A readable target for a frame label, e.g. `button "show details"`.
- * Testing Library hands interactions a real `Element` rather than a Vitest
- * locator, so the label is read off the element instead of a selector string.
- */
-export declare function elementLabel(target: unknown): string | undefined;

package/dist/element-label.js

@@ -1,34 +0,0 @@
-/** Attributes that name an element better than its text, in order of preference. */
-const NAME_ATTRIBUTES = ['aria-label', 'name', 'placeholder', 'title'];
-function roleOf(element) {
-    const explicit = element.getAttribute('role');
-    if (explicit) {
-        return explicit;
-    }
-    const tag = element.tagName.toLowerCase();
-    if (tag === 'input') {
-        return element.getAttribute('type') ?? 'input';
-    }
-    return tag;
-}
-function nameOf(element) {
-    for (const attribute of NAME_ATTRIBUTES) {
-        const value = element.getAttribute(attribute);
-        if (value) {
-            return value;
-        }
-    }
-    return (element.textContent ?? '').trim().slice(0, 40);
-}
-/**
- * A readable target for a frame label, e.g. `button "show details"`.
- * Testing Library hands interactions a real `Element` rather than a Vitest
- * locator, so the label is read off the element instead of a selector string.
- */
-export function elementLabel(target) {
-    if (typeof Element === 'undefined' || !(target instanceof Element)) {
-        return undefined;
-    }
-    const name = nameOf(target);
-    return name ? `${roleOf(target)} "${name}"` : roleOf(target);
-}