@describe-me/vitest 0.5.1 → 0.5.2

package/README.md

@@ -26,9 +26,9 @@ 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 and turns it
+  off while the recorder waits, so act warnings match a run without
+  describe-me. It also works without user-event installed.
 
 jsdom has no layout, so positioned popovers show in the top-left corner and
 canvas stays blank
@@ -58,7 +58,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.
 
@@ -73,6 +75,10 @@ test page, and the local files it links are copied into the output directory
 interaction, or `{ pending: '<selector>' }` once a loader is gone. See
 [Render frame timing](https://github.com/grzehub/describe-me#render-frame-timing).
 
+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`,
 `fireEvent` and `cleanup` from `@describe-me/react/testing-library` in jsdom:

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/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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@describe-me/vitest",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "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.2"
   },
   "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.2"
   },
   "peerDependenciesMeta": {
     "typescript": {