@describe-me/vitest 0.5.1 → 0.5.3

package/README.md

@@ -11,7 +11,7 @@ pnpm add -D @describe-me/vitest @describe-me/react describe-me
 ```
 
 All describe-me packages must be on the same version
-([Add it to your project](https://github.com/grzehub/describe-me#add-it-to-your-project)).
+([One version for all packages](https://grzehub.github.io/describe-me/installation.html#lockstep)).
 
 ## Usage
 
@@ -26,13 +26,16 @@ plugin detects where the tests run:
   `@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. 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.
+  React's `IS_REACT_ACT_ENVIRONMENT` where Testing Library would. With
+  `@testing-library/react`, it takes user-event frames without a wait. The
+  flag is off for the few waits that remain, which can still move an act
+  warning
+  ([jsdom](https://grzehub.github.io/describe-me/environments.html#jsdom)). It
+  also works without user-event installed.
 
 jsdom has no layout, so positioned popovers show in the top-left corner and
 canvas stays blank
-([Limitations in jsdom](https://github.com/grzehub/describe-me#limitations-in-jsdom)).
+([Limitations in jsdom](https://grzehub.github.io/describe-me/environments.html#jsdom-limits)).
 
 ```ts
 import { describeMe } from '@describe-me/vitest/plugin'
@@ -58,7 +61,9 @@ 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
+Tests in other files still run, but record nothing. Leaving `include` out
+records every test file. `include: []` records none and warns, while
+`exclude: '**'` records none without a warning. 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.
 
@@ -66,12 +71,16 @@ plugin the setup file does not know them.
 every frame's `<head>`, like Storybook's `preview-head.html`: typically the
 font links that the app shell loads and tests never do. It never reaches the
 test page, and the local files it links are copied into the output directory
-([Fonts](https://github.com/grzehub/describe-me#fonts) in the root README).
+([Fonts](https://grzehub.github.io/describe-me/styles-and-fonts.html#fonts) in the docs).
 
 `describeMe({ renderFrame })` chooses when the render frame is taken:
 `'eager'` (default) right after mount, `'lazy'` right before the next
 interaction, or `{ pending: '<selector>' }` once a loader is gone. See
-[Render frame timing](https://github.com/grzehub/describe-me#render-frame-timing).
+[Render frame timing](https://grzehub.github.io/describe-me/configuration.html#render-frame).
+
+The plugin adds its reporter to the ones your config names. If it names
+none, the reporter joins the ones Vitest picks on its own, such as `minimal`
+for AI agents and `github-actions` in GitHub Actions.
 
 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`,
@@ -96,5 +105,4 @@ export default defineConfig({
 the props tables are left out. `@testing-library/user-event` is an optional
 peer too, needed only in DOM environments.
 
-See the [root README](https://github.com/grzehub/describe-me#readme) for the
-full picture.
+See the [docs](https://grzehub.github.io/describe-me/) for the full picture.

package/dist/act-neutral-wait.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Run a recorder wait with React's `IS_REACT_ACT_ENVIRONMENT` flag off, as
+ * Testing Library's `asyncWrapper` does for `waitFor` and user-event. Otherwise
+ * an update that lands in the wait logs an act warning that a run without
+ * describe-me never shows.
+ */
+export declare function actNeutralWait(wait: () => Promise<void>): Promise<void>;

package/dist/act-neutral-wait.js

@@ -0,0 +1,30 @@
+/**
+ * Waits can overlap, for example an un-awaited interaction or `flush()` with
+ * captures in flight. The flag from before the first one comes back when the
+ * last one ends.
+ */
+let depth = 0;
+let previous;
+/**
+ * Run a recorder wait with React's `IS_REACT_ACT_ENVIRONMENT` flag off, as
+ * Testing Library's `asyncWrapper` does for `waitFor` and user-event. Otherwise
+ * an update that lands in the wait logs an act warning that a run without
+ * describe-me never shows.
+ */
+export async function actNeutralWait(wait) {
+    const host = globalThis;
+    if (depth === 0) {
+        previous = host.IS_REACT_ACT_ENVIRONMENT;
+        host.IS_REACT_ACT_ENVIRONMENT = false;
+    }
+    depth++;
+    try {
+        await wait();
+    }
+    finally {
+        depth--;
+        if (depth === 0) {
+            host.IS_REACT_ACT_ENVIRONMENT = previous;
+        }
+    }
+}

package/dist/collect-component-docs-safely.js

@@ -13,6 +13,12 @@ function warnAboutMissingTypeScript() {
  * props tables instead of a crashing reporter.
  */
 export async function collectComponentDocsSafely(root, entries) {
+    const rendered = Array.from(entries);
+    // Importing TypeScript takes a few hundred milliseconds, wasted on a run
+    // that recorded no component.
+    if (rendered.length === 0) {
+        return {};
+    }
     try {
         await import('typescript');
     }
@@ -21,5 +27,5 @@ export async function collectComponentDocsSafely(root, entries) {
         return {};
     }
     const { collectComponentDocs } = await import('./collect-component-docs.js');
-    return collectComponentDocs(root, entries);
+    return collectComponentDocs(root, rendered);
 }

package/dist/compile-include.d.ts

@@ -0,0 +1,3 @@
+import type { CompiledGlob } from './runtime-options.js';
+/** Keeps an omitted `include` (`null`, every test file) apart from an empty list (no test file). */
+export declare function compileInclude(patterns: string | string[] | undefined): CompiledGlob[] | null;

package/dist/compile-include.js

@@ -0,0 +1,8 @@
+import { compileGlobs } from './compile-globs.js';
+/** Keeps an omitted `include` (`null`, every test file) apart from an empty list (no test file). */
+export function compileInclude(patterns) {
+    if (patterns === undefined) {
+        return null;
+    }
+    return compileGlobs(patterns);
+}

package/dist/default-reporters.d.ts

@@ -0,0 +1,5 @@
+/**
+ * The reporters the installed Vitest uses when the config names none, such as
+ * `minimal` for AI agents and `github-actions` in GitHub Actions.
+ */
+export declare function defaultReporters(): string[];

package/dist/default-reporters.js

@@ -0,0 +1,35 @@
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { isAgent } from 'std-env';
+import { configDefaults } from 'vitest/config';
+/**
+ * Vitest 4.0 has no `agent` reporter and loads the name as a reporter module,
+ * which fails the run. An unreadable version counts as 4.0.
+ */
+function hasAgentReporter() {
+    try {
+        const manifest = createRequire(import.meta.url).resolve('vitest/package.json');
+        const { version } = JSON.parse(readFileSync(manifest, 'utf8'));
+        const [major, minor] = version.split('.').map(Number);
+        return major > 4 || (major === 4 && minor >= 1);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The reporters the installed Vitest uses when the config names none, such as
+ * `minimal` for AI agents and `github-actions` in GitHub Actions.
+ */
+export function defaultReporters() {
+    // Vitest 5 exports the list. Vitest 4 exports none and fills it while
+    // resolving the config, only when it is still empty, so its rule is rebuilt here.
+    if (configDefaults.reporters.length > 0) {
+        return [...configDefaults.reporters];
+    }
+    const reporters = [isAgent && hasAgentReporter() ? 'agent' : 'default'];
+    if (process.env.GITHUB_ACTIONS === 'true') {
+        reporters.push('github-actions');
+    }
+    return reporters;
+}

package/dist/file-filter.d.ts

@@ -1,6 +1,7 @@
 import type { RuntimeOptions } from './runtime-options.js';
 /**
- * Takes a path relative to the root, with posix separators. Build it once and
+ * Takes a path relative to the root, with posix separators. An `include` of
+ * `null` selects every file, an empty list selects none. Build it once and
  * reuse the returned function, which memoizes per file name. The test runtime
  * imports this file, so no Node imports.
  */

package/dist/file-filter.js

@@ -2,12 +2,13 @@ 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
+ * Takes a path relative to the root, with posix separators. An `include` of
+ * `null` selects every file, an empty list selects none. 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 include = options.include === null ? null : toRegExps(options.include);
     const exclude = toRegExps(options.exclude);
     const answers = new Map();
     return (fileName) => {
@@ -15,7 +16,7 @@ export function fileFilter(options) {
         if (known !== undefined) {
             return known;
         }
-        const included = include.length === 0 || include.some((glob) => glob.test(fileName));
+        const included = include === null || include.some((glob) => glob.test(fileName));
         const answer = included && !exclude.some((glob) => glob.test(fileName));
         answers.set(fileName, answer);
         return answer;

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

@@ -3,7 +3,8 @@
  * 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. When the optional peer is not installed, there is nothing to
- * patch. Safe to call more than once.
+ * one frame. Under @testing-library/react a frame is taken as soon as the
+ * call resolves, otherwise after one settle. When the optional peer is not
+ * installed, there is nothing to patch. Safe to call more than once.
  */
 export declare function patchTestingLibraryUserEvent(): Promise<void>;

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

@@ -1,6 +1,7 @@
 import { elementLabel } from '@describe-me/core';
 import { describeArg } from './describe-arg.js';
 import { recordAction } from './record-action.js';
+import { testingLibraryWrapsInAct } from './testing-library-wraps-in-act.js';
 /** Every interaction of user-event 14 that can change what the page shows. */
 const METHODS = [
     'click',
@@ -31,7 +32,11 @@ function patchMethods(target) {
         if (typeof original !== 'function' || original[PATCHED]) {
             continue;
         }
-        const wrapped = (...args) => recordAction(labelFor(method, args), async () => original.apply(target, args));
+        // Testing Library's wrappers commit the DOM before the call resolves. A settle
+        // would only move React updates into a wait with the act flag off.
+        const wrapped = (...args) => recordAction(labelFor(method, args), async () => original.apply(target, args), {
+            settle: !testingLibraryWrapsInAct(),
+        });
         wrapped[PATCHED] = true;
         target[method] = wrapped;
     }
@@ -41,8 +46,9 @@ 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. When the optional peer is not installed, there is nothing to
- * patch. Safe to call more than once.
+ * one frame. Under @testing-library/react a frame is taken as soon as the
+ * call resolves, otherwise after one settle. When the optional peer is not
+ * installed, there is nothing to patch. Safe to call more than once.
  */
 export async function patchTestingLibraryUserEvent() {
     let userEvent;

package/dist/plugin.d.ts

@@ -33,7 +33,8 @@ export interface DescribeMeOptions {
     /**
      * 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.
+     * nothing and leave the manifest. An empty list records no test file and
+     * warns. Default: every test file.
      */
     include?: string | string[];
     /** Test files never to record, as globs like `include`. Wins over `include`. Default: none. */

package/dist/plugin.js

@@ -1,5 +1,7 @@
 import { adapterPackageRoot } from './adapter-package-root.js';
 import { compileGlobs } from './compile-globs.js';
+import { compileInclude } from './compile-include.js';
+import { defaultReporters } from './default-reporters.js';
 import { projectModulePath } from './project-module-path.js';
 import { registerExports } from './register-exports.js';
 import DescribeMeReporter from './reporter.js';
@@ -110,7 +112,7 @@ export function describeMe(options = {}) {
             // Checked here, so invalid options fail before any test runs. Vite
             // deep-merges `provide`, so the user's own keys survive.
             const runtimeOptions = {
-                include: compileGlobs(options.include),
+                include: compileInclude(options.include),
                 exclude: compileGlobs(options.exclude),
                 renderFrame: validateRenderFrame(options.renderFrame),
             };
@@ -124,9 +126,10 @@ export function describeMe(options = {}) {
                 previewHead: options.previewHead,
                 setupWarnings,
             });
-            // 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];
+            // Vite concatenates our list with the user's. Any list replaces the
+            // reporters Vitest picks on its own, so without one of the user's, ours
+            // joins Vitest's defaults.
+            const reporters = userConfig.test?.reporters ? [reporter] : [...defaultReporters(), reporter];
             const config = environment === 'browser'
                 ? browserConfig(renderModule)
                 : domConfig(userConfig, styledComponents);

package/dist/read-runtime-options.js

@@ -3,7 +3,7 @@ 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: [],
+        include: null,
         exclude: [],
         renderFrame: 'eager',
     });

package/dist/record-action.d.ts

@@ -1,2 +1,6 @@
-/** Run one user interaction and record a frame for it, but only for the outermost call. */
-export declare function recordAction<T>(label: string, run: () => Promise<T>): Promise<T>;
+import type { CaptureOptions } from '@describe-me/core';
+/**
+ * Run one user interaction and record a frame for it, but only for the outermost call.
+ * `settle: false` takes the frame as soon as the interaction resolves, without a wait.
+ */
+export declare function recordAction<T>(label: string, run: () => Promise<T>, options?: Pick<CaptureOptions, 'settle'>): Promise<T>;

package/dist/record-action.js

@@ -7,8 +7,11 @@ import { recorder } from '@describe-me/core';
  * test left running cannot swallow the next test's frame.
  */
 const nesting = { generation: -1, depth: 0 };
-/** Run one user interaction and record a frame for it, but only for the outermost call. */
-export async function recordAction(label, run) {
+/**
+ * Run one user interaction and record a frame for it, but only for the outermost call.
+ * `settle: false` takes the frame as soon as the interaction resolves, without a wait.
+ */
+export async function recordAction(label, run, options = {}) {
     const generation = recorder.generation;
     if (generation !== nesting.generation) {
         nesting.generation = generation;
@@ -26,7 +29,7 @@ export async function recordAction(label, run) {
         }
     }
     if (generation === nesting.generation && nesting.depth === 0) {
-        await recorder.capture('action', label, undefined, { generation });
+        await recorder.capture('action', label, undefined, { generation, settle: options.settle });
     }
     return result;
 }

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

@@ -1,3 +1,4 @@
+import type { AroundWait } from '@describe-me/core';
 import type { RuntimeOptions } from './runtime-options.js';
 /**
  * The per-test lifecycle shared by every environment: begin a recording, take
@@ -7,4 +8,4 @@ import type { RuntimeOptions } from './runtime-options.js';
  * jsdom. Concurrent tests would share the one recorder, so they are not
  * recorded.
  */
-export declare function registerRecordingHooks(options: RuntimeOptions): void;
+export declare function registerRecordingHooks(options: RuntimeOptions, aroundWait?: AroundWait): void;

package/dist/register-recording-hooks.js

@@ -9,10 +9,10 @@ import { fileFilter } from './file-filter.js';
  * jsdom. Concurrent tests would share the one recorder, so they are not
  * recorded.
  */
-export function registerRecordingHooks(options) {
+export function registerRecordingHooks(options, aroundWait) {
     const isRecordedFile = fileFilter(options);
     let warnedConcurrent = false;
-    recorder.configure({ renderFrame: options.renderFrame });
+    recorder.configure({ renderFrame: options.renderFrame, aroundWait });
     beforeEach((context) => {
         if (context.task.concurrent) {
             if (!warnedConcurrent) {

package/dist/reporter.d.ts

@@ -4,7 +4,8 @@ export interface DescribeMeReporterOptions {
     outDir?: string;
     /**
      * Which test files appear in the manifest: globs relative to the Vitest
-     * root, matched with picomatch, dotfiles included. Default: every test file.
+     * root, matched with picomatch, dotfiles included. An empty list leaves every
+     * file out of the manifest and warns. Default: every test file.
      */
     include?: string | string[];
     /**
@@ -24,6 +25,7 @@ export interface DescribeMeReporterOptions {
 export default class DescribeMeReporter implements Reporter {
     private readonly outDirOption;
     private readonly isRecordedFile;
+    private readonly emptyInclude;
     private readonly previewHead;
     private readonly generator;
     private readonly setupWarnings;

package/dist/reporter.js

@@ -8,6 +8,7 @@ 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 { compileInclude } from './compile-include.js';
 import { componentEntries } from './component-entries.js';
 import { fileFilter } from './file-filter.js';
 import { FontAudit } from './font-audit.js';
@@ -27,6 +28,7 @@ function recordOf(tc) {
 export default class DescribeMeReporter {
     outDirOption;
     isRecordedFile;
+    emptyInclude;
     previewHead;
     generator;
     setupWarnings;
@@ -39,10 +41,9 @@ export default class DescribeMeReporter {
     modules = new Map();
     constructor(options = {}) {
         this.outDirOption = options.outDir ?? '.describe-me';
-        this.isRecordedFile = fileFilter({
-            include: compileGlobs(options.include),
-            exclude: compileGlobs(options.exclude),
-        });
+        const include = compileInclude(options.include);
+        this.isRecordedFile = fileFilter({ include, exclude: compileGlobs(options.exclude) });
+        this.emptyInclude = include !== null && include.length === 0;
         // A blank head, such as an empty preview-head.html, is the same as none.
         this.previewHead = options.previewHead?.trim() ? options.previewHead : undefined;
         this.generator = readGenerator();
@@ -59,6 +60,11 @@ export default class DescribeMeReporter {
         if (this.previewHead !== undefined && /<script\b/i.test(this.previewHead)) {
             console.warn('describe-me: previewHead contains a <script>, which the viewer never runs.');
         }
+        // Here and not in the constructor: the plugin builds the reporter in
+        // `config()`, which also runs for a `vite build` that shares the config.
+        if (this.emptyInclude) {
+            console.warn("describe-me: include is an empty list, so no test file is recorded. Leave include out to record every test file, or set exclude: '**' to record none without this warning.");
+        }
     }
     onTestRunStart() {
         this.assets.startRun();

package/dist/runtime-options.d.ts

@@ -10,8 +10,11 @@ export interface CompiledGlob {
     flags: string;
 }
 export interface RuntimeOptions {
-    /** Empty means every test file. */
-    include: CompiledGlob[];
+    /**
+     * `null` means every test file, an empty list means none. `null` survives
+     * `provide` / `inject` and Vite's config merge, `undefined` would not.
+     */
+    include: CompiledGlob[] | null;
     /** Wins over `include`. */
     exclude: CompiledGlob[];
     renderFrame: RenderFrameMode;

package/dist/setup-dom.js

@@ -3,14 +3,16 @@
  * `setupFiles: ['@describe-me/vitest/setup-dom']`. Patches Testing Library's
  * 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`) and when the
+ * hooks. The act flag is off while the recorder waits, as in Testing Library's
+ * own waits. Which test files are recorded (`include` / `exclude`) and when the
  * render frame is taken (`renderFrame`) come from the plugin. Never imports
  * `vitest/browser`, which only exists in browser mode.
  */
+import { actNeutralWait } from './act-neutral-wait.js';
 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';
 await patchTestingLibraryUserEvent();
 mirrorReactActEnvironment();
-registerRecordingHooks(readRuntimeOptions());
+registerRecordingHooks(readRuntimeOptions(), actNeutralWait);

package/dist/testing-library-wraps-in-act.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Whether @testing-library/dom still runs user-event calls through the
+ * `asyncWrapper` that @testing-library/react installed, so the DOM is committed
+ * when a call resolves. False when @describe-me/react/testing-library never loaded.
+ */
+export declare function testingLibraryWrapsInAct(): boolean;

package/dist/testing-library-wraps-in-act.js

@@ -0,0 +1,11 @@
+// `publish-testing-library-act.ts` in @describe-me/react writes this key.
+const ACT_CHECK = Symbol.for('describe-me.testing-library-act');
+/**
+ * Whether @testing-library/dom still runs user-event calls through the
+ * `asyncWrapper` that @testing-library/react installed, so the DOM is committed
+ * when a call resolves. False when @describe-me/react/testing-library never loaded.
+ */
+export function testingLibraryWrapsInAct() {
+    const check = globalThis[ACT_CHECK];
+    return typeof check === 'function' && check() === true;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@describe-me/vitest",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "description": "Vitest integration for describe-me: plugin, setup file and reporter",
   "keywords": [
     "vitest",
@@ -59,13 +59,14 @@
   ],
   "dependencies": {
     "picomatch": "^4.0.3",
-    "@describe-me/core": "^0.5.1"
+    "std-env": "^4.0.0",
+    "@describe-me/core": "^0.5.3"
   },
   "peerDependencies": {
     "vitest": "^4.0.0 || ^5.0.0",
     "typescript": "^5.0.0 || ^6.0.0",
     "@testing-library/user-event": "^14.0.0",
-    "describe-me": "^0.5.1"
+    "describe-me": "^0.5.3"
   },
   "peerDependenciesMeta": {
     "typescript": {