@describe-me/vitest 0.2.0 → 0.3.0

package/README.md

@@ -13,35 +13,59 @@ pnpm add -D @describe-me/vitest @describe-me/react describe-me
 ## Usage
 
 One line in the Vitest config registers the setup file and the reporter, and
-redirects `vitest-browser-react` imports to the recording adapter:
+redirects the test library's `render` import to the recording adapter. The
+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/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.
 
 ```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' },
+})
 ```
 
+Pass `describeMe({ environment: 'browser' | 'dom' })` to override the detection.
+
 The pieces can also be wired by hand, in which case tests import `render` from
-`@describe-me/react` themselves:
+the adapter themselves (`@describe-me/react` in browser mode,
+`@describe-me/react/testing-library` in jsdom):
 
 ```ts
 import DescribeMeReporter from '@describe-me/vitest/reporter'
 
 export default defineConfig({
   test: {
-    setupFiles: ['@describe-me/vitest/setup'],
+    // 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.
+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.

package/dist/element-label.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 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

@@ -0,0 +1,34 @@
+/** 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);
+}

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

@@ -0,0 +1,8 @@
+/**
+ * Wrap Testing Library's userEvent in place so each call records a frame.
+ * It comes in two shapes, the direct API (`userEvent.click(el)`) and an
+ * instance from `userEvent.setup()`, and the first delegates to the second,
+ * so both are patched and `recordAction`'s depth guard keeps one gesture to
+ * one frame. Safe to call more than once.
+ */
+export declare function patchTestingLibraryUserEvent(): void;

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

@@ -0,0 +1,61 @@
+import userEvent from '@testing-library/user-event';
+import { describeArg } from './describe-arg.js';
+import { elementLabel } from './element-label.js';
+import { recordAction } from './record-action.js';
+/** Every interaction of user-event 14 that can change what the page shows. */
+const METHODS = [
+    'click',
+    'dblClick',
+    'tripleClick',
+    'hover',
+    'unhover',
+    'type',
+    'clear',
+    'keyboard',
+    'tab',
+    'paste',
+    'copy',
+    'cut',
+    'pointer',
+    'selectOptions',
+    'deselectOptions',
+    'upload',
+];
+const PATCHED = Symbol.for('describe-me.patched');
+function labelFor(method, args) {
+    const parts = args.map((arg) => elementLabel(arg) ?? describeArg(arg)).filter(Boolean);
+    return `${method}(${parts.join(', ')})`;
+}
+function patchMethods(target) {
+    for (const method of METHODS) {
+        const original = target[method];
+        if (typeof original !== 'function' || original[PATCHED]) {
+            continue;
+        }
+        const wrapped = (...args) => recordAction(labelFor(method, args), async () => original.apply(target, args));
+        wrapped[PATCHED] = true;
+        target[method] = wrapped;
+    }
+}
+/**
+ * Wrap Testing Library's userEvent in place so each call records a frame.
+ * It comes in two shapes, the direct API (`userEvent.click(el)`) and an
+ * instance from `userEvent.setup()`, and the first delegates to the second,
+ * so both are patched and `recordAction`'s depth guard keeps one gesture to
+ * one frame. Safe to call more than once.
+ */
+export function patchTestingLibraryUserEvent() {
+    const direct = userEvent;
+    patchMethods(direct);
+    const originalSetup = direct.setup;
+    if (typeof originalSetup !== 'function' || originalSetup[PATCHED]) {
+        return;
+    }
+    const wrappedSetup = (...args) => {
+        const instance = originalSetup.apply(direct, args);
+        patchMethods(instance);
+        return instance;
+    };
+    wrappedSetup[PATCHED] = true;
+    direct.setup = wrappedSetup;
+}

package/dist/plugin.d.ts

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

package/dist/plugin.js

@@ -1,19 +1,60 @@
 import DescribeMeReporter from './reporter.js';
-/** For each framework: the render module tests import, and our adapter that wraps it. */
+/** For each framework and environment: the render module tests import, and our adapter that wraps it. */
 const RENDER_MODULES = {
-    react: { original: 'vitest-browser-react', adapter: '@describe-me/react' },
+    react: {
+        browser: { original: 'vitest-browser-react', adapter: '@describe-me/react' },
+        dom: { original: '@testing-library/react', adapter: '@describe-me/react/testing-library' },
+    },
 };
+/** Paths an adapter's own files live under, published or in this workspace. */
+const ADAPTER_PATHS = ['/@describe-me/react/', '/packages/react/'];
+function detectEnvironment(userConfig) {
+    return userConfig.test?.browser?.enabled ? 'browser' : 'dom';
+}
+function browserConfig(renderModule) {
+    return {
+        // Vite's dependency scanner runs before our `resolveId` redirect, so it
+        // never sees the adapter. Discovering it mid-run makes Vite re-optimize
+        // and reload, and the test ends up with two copies of the bundled deps
+        // ("Vitest failed to find the runner"). Declaring the adapter up front
+        // keeps a single optimization pass.
+        optimizeDeps: {
+            include: [renderModule.adapter, renderModule.original],
+        },
+        test: {
+            setupFiles: ['@describe-me/vitest/setup'],
+        },
+    };
+}
+function domConfig(userTest) {
+    const test = {
+        setupFiles: ['@describe-me/vitest/setup-dom'],
+        // Testing Library would otherwise unmount in its own afterEach, before the
+        // closing frame is taken. The adapter unmounts through the recorder instead.
+        env: { RTL_SKIP_AUTO_CLEANUP: 'true' },
+    };
+    // Vitest stubs CSS imports by default, which would leave every imported
+    // stylesheet out of the snapshots. An explicit choice by the user wins.
+    if (userTest?.css === undefined) {
+        test.css = true;
+    }
+    else if (userTest.css === false) {
+        console.warn('describe-me: `test.css` is false, so imported stylesheets are stubbed and will be missing from the snapshots.');
+    }
+    return { test };
+}
 /**
  * One-line integration: `plugins: [describeMe()]`.
  *
  * Registers the setup file and the reporter, and redirects the framework's
  * `render` import to our adapter so existing tests record frames unchanged.
- * The adapter itself still needs the real module, so imports coming from
- * inside it are left alone.
+ * Works in browser mode and in DOM environments such as jsdom; the adapter
+ * itself still needs the real module, so imports coming from inside it are
+ * left alone.
  */
 export function describeMe(options = {}) {
     const { enabled = true, framework = 'react', outDir } = options;
-    const { original, adapter } = RENDER_MODULES[framework];
+    let renderModule = RENDER_MODULES[framework].browser;
     return {
         name: 'describe-me',
         enforce: 'pre',
@@ -21,35 +62,33 @@ export function describeMe(options = {}) {
             if (!enabled) {
                 return {};
             }
+            const environment = options.environment ?? detectEnvironment(userConfig);
+            renderModule = RENDER_MODULES[framework][environment];
             const reporter = new DescribeMeReporter({ outDir });
             // Vite concatenates arrays when merging, so only add `default` when the
             // user has not chosen their own reporters; otherwise they would lose it.
             const reporters = userConfig.test?.reporters ? [reporter] : ['default', reporter];
-            return {
-                // Vite's dependency scanner runs before our `resolveId` redirect, so it
-                // never sees the adapter. Discovering it mid-run makes Vite re-optimize
-                // and reload, and the test ends up with two copies of the bundled deps
-                // ("Vitest failed to find the runner"). Declaring the adapter up front
-                // keeps a single optimization pass.
-                optimizeDeps: {
-                    include: [adapter, original],
-                },
-                test: {
-                    setupFiles: ['@describe-me/vitest/setup'],
-                    reporters,
-                },
-            };
+            const config = environment === 'browser' ? browserConfig(renderModule) : domConfig(userConfig.test);
+            return { ...config, test: { ...config.test, reporters } };
         },
-        resolveId(source, importer) {
-            if (!enabled || source !== original) {
+        async resolveId(source, importer) {
+            if (!enabled || source !== renderModule.original) {
                 return null;
             }
             const fromAdapter = importer !== undefined &&
-                (importer.includes(adapter) || importer.includes('/packages/react/'));
+                (importer.includes(renderModule.adapter) ||
+                    ADAPTER_PATHS.some((path) => importer.includes(path)));
             if (fromAdapter) {
                 return null;
             }
-            return this.resolve(adapter, importer, { skipSelf: true });
+            const resolved = await this.resolve(renderModule.adapter, importer, { skipSelf: true });
+            // Falling back to the original module would look like success while
+            // recording nothing, and in a DOM environment it would also leave every
+            // test mounted, because Testing Library's auto-cleanup is switched off.
+            if (!resolved) {
+                throw new Error(`describe-me: cannot resolve ${renderModule.adapter} (the recording replacement for ${renderModule.original}). Install ${renderModule.adapter.split('/').slice(0, 2).join('/')}.`);
+            }
+            return resolved;
         },
     };
 }

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

@@ -0,0 +1,6 @@
+/**
+ * The per-test lifecycle shared by every environment: begin a recording
+ * before each test, then take the closing frame, hand the frames to the
+ * reporter via task.meta, and only then let adapters unmount.
+ */
+export declare function registerRecordingHooks(): void;

package/dist/register-recording-hooks.js

@@ -0,0 +1,17 @@
+import { afterEach, beforeEach } from 'vitest';
+import { META_KEY, recorder } from '@describe-me/core';
+/**
+ * The per-test lifecycle shared by every environment: begin a recording
+ * before each test, then take the closing frame, hand the frames to the
+ * reporter via task.meta, and only then let adapters unmount.
+ */
+export function registerRecordingHooks() {
+    beforeEach(() => {
+        recorder.begin();
+    });
+    afterEach(async (context) => {
+        await recorder.capture('end', 'end of test');
+        context.task.meta[META_KEY] = recorder.end();
+        recorder.teardown();
+    });
+}

package/dist/setup-dom.d.ts

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

package/dist/setup-dom.js

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

package/dist/setup.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@describe-me/vitest",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Vitest integration for describe-me: plugin, setup file and reporter",
   "keywords": [
     "vitest",
@@ -35,6 +35,10 @@
       "types": "./dist/setup.d.ts",
       "default": "./dist/setup.js"
     },
+    "./setup-dom": {
+      "types": "./dist/setup-dom.d.ts",
+      "default": "./dist/setup-dom.js"
+    },
     "./reporter": {
       "types": "./dist/reporter.d.ts",
       "default": "./dist/reporter.js"
@@ -50,24 +54,31 @@
     "LICENSE"
   ],
   "sideEffects": [
-    "./dist/setup.js"
+    "./dist/setup.js",
+    "./dist/setup-dom.js"
   ],
   "dependencies": {
-    "@describe-me/core": "^0.2.0"
+    "@describe-me/core": "^0.3.0"
   },
   "peerDependencies": {
     "vitest": ">=4",
-    "typescript": ">=5.0"
+    "typescript": ">=5.0",
+    "@testing-library/user-event": ">=14"
   },
   "peerDependenciesMeta": {
     "typescript": {
       "optional": true
+    },
+    "@testing-library/user-event": {
+      "optional": true
     }
   },
   "devDependencies": {
     "vitest": "^5.0.1",
     "@types/node": "^22",
-    "typescript": "^6"
+    "typescript": "^6",
+    "@testing-library/user-event": "^14.6.1",
+    "@testing-library/dom": "^10.4.0"
   },
   "scripts": {
     "build": "rimraf dist && tsc -p tsconfig.json"