@describe-me/vitest 0.5.2 → 0.5.4

package/README.md

@@ -1,106 +1,75 @@
 # @describe-me/vitest
 
-The Vitest integration for [describe-me](https://github.com/grzehub/describe-me):
-a plugin, a setup file that makes every interaction record a frame, and the Node
-reporter that writes `.describe-me/`.
+**Your tests are your stories.** The Vitest plugin, setup files and reporter of
+describe-me: living component documentation generated from the Vitest tests
+you already have.
 
-## Install
+**[Read the docs](https://grzehub.github.io/describe-me/)** · open the viewer
+of the [browser-mode example](https://grzehub.github.io/describe-me/examples/react-browser/)
+or the [jsdom example](https://grzehub.github.io/describe-me/examples/react-jsdom/)
+· [Limitations](https://grzehub.github.io/describe-me/limitations.html)
 
-```sh
-pnpm add -D @describe-me/vitest @describe-me/react describe-me
-```
+describe-me captures the DOM after each step of a test and shows the result as
+a browsable catalog. `describe` blocks become the sidebar, each `it` is a
+story, and each step is a frame you can scrub through. Stories cannot rot,
+because they are tests. If one drifts from the component, CI goes red.
 
-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)).
+Status: prototype. React 18 and 19, Vitest 4 and 5 in browser mode or jsdom,
+static snapshots.
 
-## Usage
+## Which package do I need
 
-One line in the Vitest config registers the setup file and the reporter, and
-redirects the test library's `render` import to the recording adapter. The
-plugin detects where the tests run:
+| Package               | What it is                                         | Install it              |
+| --------------------- | -------------------------------------------------- | ----------------------- |
+| `describe-me`         | the viewer and the `describe-me` CLI               | yes                     |
+| `@describe-me/vitest` | the Vitest plugin, setup files and reporter (this) | yes                     |
+| `@describe-me/react`  | `render` functions that record frames              | yes                     |
+| `@describe-me/core`   | the recorder and the manifest types                | no, the others bring it |
 
-- **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 `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. The setup file sets
-  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.
+## Quick start
 
-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)).
+```sh
+pnpm add -D describe-me @describe-me/vitest @describe-me/react
+```
 
 ```ts
+// vitest.config.ts
 import { describeMe } from '@describe-me/vitest/plugin'
 
-// browser mode
-export default defineConfig({
-  plugins: [react(), describeMe()],
-  test: {
-    browser: { enabled: true, provider: playwright(), instances: [{ browser: 'chromium' }] },
-  },
-})
-
-// jsdom
 export default defineConfig({
   plugins: [react(), describeMe()],
-  test: { environment: 'jsdom' },
+  test: { environment: 'jsdom' }, // or your browser-mode settings
 })
 ```
 
-Pass `describeMe({ environment: 'browser' | 'dom' })` to override the detection.
-
-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. 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.
-
-`describeMe({ previewHead })` takes HTML that the viewer adds to the start of
-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).
-
-`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).
-
-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:
-
-```ts
-import DescribeMeReporter from '@describe-me/vitest/reporter'
-
-export default defineConfig({
-  test: {
-    // browser mode: '@describe-me/vitest/setup'
-    setupFiles: ['@describe-me/vitest/setup-dom'],
-    reporters: ['default', new DescribeMeReporter()],
-    // jsdom only: keep imported CSS and leave unmounting to describe-me
-    css: true,
-    env: { RTL_SKIP_AUTO_CLEANUP: 'true' },
-  },
-})
-```
-
-`typescript` is an optional peer: without it the docs are still generated, only
-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.
+Run your tests, then `describe-me dev` opens the viewer.
+[Getting started](https://grzehub.github.io/describe-me/getting-started.html)
+walks through both environments. Keep all describe-me packages on one version
+([why](https://grzehub.github.io/describe-me/installation.html#lockstep)).
+
+## This package
+
+The plugin is the whole integration. It detects browser mode or a DOM
+environment, registers the setup file and the reporter, and redirects your
+test library's `render` to the recording one, so existing tests record frames
+unchanged.
+[What the plugin changes](https://grzehub.github.io/describe-me/configuration.html#plugin)
+lists every change it makes to your config, and
+[Options](https://grzehub.github.io/describe-me/configuration.html#options)
+every option it takes.
+
+| Entry point                     | What it holds                                                                                         |
+| ------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| `@describe-me/vitest/plugin`    | [`describeMe()`](https://grzehub.github.io/describe-me/api.html#entry-vitest-plugin)                  |
+| `@describe-me/vitest`           | [`step()` and `recorder`](https://grzehub.github.io/describe-me/api.html#entry-vitest)                |
+| `@describe-me/vitest/setup`     | [the browser-mode setup file](https://grzehub.github.io/describe-me/api.html#entry-vitest-setup)      |
+| `@describe-me/vitest/setup-dom` | [the jsdom setup file](https://grzehub.github.io/describe-me/api.html#entry-vitest-setup-dom)         |
+| `@describe-me/vitest/reporter`  | [the reporter, to wire by hand](https://grzehub.github.io/describe-me/api.html#entry-vitest-reporter) |
+
+`typescript` and `@testing-library/user-event` are optional peers. Without
+TypeScript the docs have no props tables. user-event is needed only when your
+jsdom tests use it.
+
+## License
+
+MIT

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/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/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,12 +1,15 @@
 {
   "name": "@describe-me/vitest",
-  "version": "0.5.2",
-  "description": "Vitest integration for describe-me: plugin, setup file and reporter",
+  "version": "0.5.4",
+  "description": "Living component documentation from your Vitest tests: the Vitest plugin, setup files and reporter of describe-me",
   "keywords": [
     "vitest",
+    "react",
     "storybook",
+    "storybook alternative",
     "component documentation",
-    "visual testing",
+    "living documentation",
+    "jsdom",
     "testing"
   ],
   "license": "MIT",
@@ -60,13 +63,13 @@
   "dependencies": {
     "picomatch": "^4.0.3",
     "std-env": "^4.0.0",
-    "@describe-me/core": "^0.5.2"
+    "@describe-me/core": "^0.5.4"
   },
   "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.2"
+    "describe-me": "^0.5.4"
   },
   "peerDependenciesMeta": {
     "typescript": {