@describe-me/react 0.3.0 → 0.5.0-next.0

package/README.md

@@ -20,8 +20,11 @@ pnpm add -D @describe-me/react
 
 ## Usage
 
-Each entry point re-exports everything its test library offers, with `render`
-swapped for the recording one, so switching an existing test is one import.
+Each entry point re-exports everything its test library offers, with the
+recording functions swapped in, so switching an existing test is one import.
+`@describe-me/react` swaps `render`. The Testing Library entry swaps `render`,
+`fireEvent` and `cleanup`: every `fireEvent` call records a frame, and
+`cleanup` takes the closing frame before it unmounts.
 
 ```tsx
 import { render, step } from '@describe-me/react'

package/dist/cleanup.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Drop-in for `cleanup` from @testing-library/react. Takes the closing frame
+ * before it unmounts, so `afterEach(cleanup)` in a test file records the last
+ * state instead of an empty page.
+ */
+export declare function cleanup(): void;

package/dist/cleanup.js

@@ -0,0 +1,11 @@
+import { cleanup as unmountAll } from '@testing-library/react';
+import { recorder } from '@describe-me/core';
+/**
+ * Drop-in for `cleanup` from @testing-library/react. Takes the closing frame
+ * before it unmounts, so `afterEach(cleanup)` in a test file records the last
+ * state instead of an empty page.
+ */
+export function cleanup() {
+    void recorder.capture('end', 'end of test', undefined, { settle: false });
+    unmountAll();
+}

package/dist/describe-element.d.ts

@@ -1,4 +1,7 @@
 import type { ReactElement } from 'react';
 import { type ComponentInfo } from '@describe-me/core';
-/** Pull the component name and JSON-safe props out of a React element. */
+/**
+ * Pull the component name, its defining file when the plugin registered it,
+ * and JSON-safe props out of a React element.
+ */
 export declare function describeElement(ui: ReactElement): ComponentInfo;

package/dist/describe-element.js

@@ -1,12 +1,10 @@
-import { serializeValue } from '@describe-me/core';
-/** Pull the component name and JSON-safe props out of a React element. */
+import { describeComponentType, serializeValue } from '@describe-me/core';
+/**
+ * Pull the component name, its defining file when the plugin registered it,
+ * and JSON-safe props out of a React element.
+ */
 export function describeElement(ui) {
-    const type = ui.type;
-    const name = typeof type === 'string'
-        ? type
-        : (type?.displayName ??
-            type?.name ??
-            'Anonymous');
+    const identity = describeComponentType(ui.type);
     const props = serializeValue(ui.props ?? {});
-    return { name, props };
+    return { ...identity, props };
 }

package/dist/fire-event-label.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The frame label of one `fireEvent` call, e.g. `click(button "Save")`,
+ * `change(text "Name", "hello")` or `scroll()` for a target that is not an
+ * element, such as `window`.
+ */
+export declare function fireEventLabel(eventName: string, target: unknown, init?: unknown): string;

package/dist/fire-event-label.js

@@ -0,0 +1,22 @@
+import { elementLabel } from '@describe-me/core';
+/**
+ * The frame label of one `fireEvent` call, e.g. `click(button "Save")`,
+ * `change(text "Name", "hello")` or `scroll()` for a target that is not an
+ * element, such as `window`.
+ */
+export function fireEventLabel(eventName, target, init) {
+    const parts = [];
+    const element = elementLabel(target);
+    if (element) {
+        parts.push(element);
+    }
+    const { target: initTarget, key } = (init ?? {});
+    const value = initTarget?.value;
+    if (typeof value === 'string') {
+        parts.push(JSON.stringify(value));
+    }
+    if (typeof key === 'string') {
+        parts.push(JSON.stringify(key));
+    }
+    return `${eventName}(${parts.join(', ')})`;
+}

package/dist/fire-event.d.ts

@@ -0,0 +1,10 @@
+import { fireEvent as baseFireEvent } from '@testing-library/react';
+type FireEvent = typeof baseFireEvent;
+/**
+ * Drop-in for `fireEvent` from @testing-library/react: the function and every
+ * method record one frame per call, labelled like `click(button "Save")`.
+ * The label is read before the event fires, so it names the element the test
+ * targeted, not what the event turned it into.
+ */
+export declare const fireEvent: FireEvent;
+export {};

package/dist/fire-event.js

@@ -0,0 +1,35 @@
+import { fireEvent as baseFireEvent } from '@testing-library/react';
+import { recorder } from '@describe-me/core';
+import { fireEventLabel } from './fire-event-label.js';
+import { recordSyncAction } from './record-sync-action.js';
+/** Fire through Testing Library, recording a frame only while a test is recorded. */
+function fire(label, dispatch) {
+    if (!recorder.isActive) {
+        return dispatch();
+    }
+    return recordSyncAction(label(), dispatch);
+}
+/** `fireEvent(element, event)` is named after the event it dispatches. */
+function eventName(event) {
+    const type = event?.type;
+    return typeof type === 'string' ? type : 'fireEvent';
+}
+/** Testing Library's `fireEvent` with the function and each of its methods wrapped. */
+function recordingFireEvent() {
+    const methods = baseFireEvent;
+    const recording = (element, event) => fire(() => fireEventLabel(eventName(event), element), () => baseFireEvent(element, event));
+    const wrappers = recording;
+    // Composite events such as `mouseEnter` call Testing Library's own object,
+    // not these wrappers, so one call stays one frame.
+    for (const name of Object.keys(baseFireEvent)) {
+        wrappers[name] = (element, init) => fire(() => fireEventLabel(name, element, init), () => methods[name](element, init));
+    }
+    return recording;
+}
+/**
+ * Drop-in for `fireEvent` from @testing-library/react: the function and every
+ * method record one frame per call, labelled like `click(button "Save")`.
+ * The label is read before the event fires, so it names the element the test
+ * targeted, not what the event turned it into.
+ */
+export const fireEvent = recordingFireEvent();

package/dist/record-sync-action.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Run one synchronous interaction and record a frame for it, but only for the
+ * outermost call and only when it returns. Testing Library wraps every event
+ * in `act()`, so the DOM is committed by then and the frame is taken without
+ * settling.
+ */
+export declare function recordSyncAction<T>(label: string, run: () => T): T;

package/dist/record-sync-action.js

@@ -0,0 +1,27 @@
+import { recorder } from '@describe-me/core';
+/**
+ * Nesting depth of synchronous interactions currently running. A handler
+ * that fires another event from inside the first would otherwise record two
+ * frames for one call.
+ */
+let depth = 0;
+/**
+ * Run one synchronous interaction and record a frame for it, but only for the
+ * outermost call and only when it returns. Testing Library wraps every event
+ * in `act()`, so the DOM is committed by then and the frame is taken without
+ * settling.
+ */
+export function recordSyncAction(label, run) {
+    depth++;
+    let result;
+    try {
+        result = run();
+    }
+    finally {
+        depth--;
+    }
+    if (depth === 0) {
+        void recorder.capture('action', label, undefined, { settle: false });
+    }
+    return result;
+}

package/dist/render-testing-library.d.ts

@@ -4,16 +4,18 @@ type RenderOptions = Parameters<typeof baseRender>[1];
 type RenderResult = ReturnType<typeof baseRender>;
 /**
  * Drop-in for `render` from @testing-library/react (jsdom and other DOM
- * environments). Records a frame after mount and after every `rerender`.
+ * environments). Records a frame after mount and after every `rerender`
+ * while a test is being recorded.
  *
  * Synchronous like the original, so `const { asFragment } = render(...)`
  * keeps working. Testing Library wraps mounting in `act()`, which means the DOM
  * is committed when it returns, so frames are captured without settling: the
  * snapshot is taken right here, before the test's next line can change the DOM.
  *
- * Unmounting is handed to the recorder's teardown rather than to Testing
- * Library's own auto-cleanup, which would run before the closing frame is
- * taken. The plugin switches auto-cleanup off with `RTL_SKIP_AUTO_CLEANUP`.
+ * Importing this module hands unmounting to the recorder's teardown rather
+ * than to Testing Library's own auto-cleanup, which would run before the
+ * closing frame is taken. The plugin switches auto-cleanup off with
+ * `RTL_SKIP_AUTO_CLEANUP`.
  */
 export declare function render(ui: ReactElement, options?: RenderOptions): RenderResult;
 export {};

package/dist/render-testing-library.js

@@ -1,25 +1,29 @@
-import { cleanup, render as baseRender } from '@testing-library/react';
+import { cleanup as unmountAll, render as baseRender } from '@testing-library/react';
 import { isValidElement } from 'react';
 import { recorder } from '@describe-me/core';
 import { describeElement } from './describe-element.js';
 import { labelFor } from './label-for.js';
+// On import rather than in `render()`, so a file that only calls `renderHook`
+// is unmounted after each test too.
+recorder.onTeardown(unmountAll);
 /**
  * Drop-in for `render` from @testing-library/react (jsdom and other DOM
- * environments). Records a frame after mount and after every `rerender`.
+ * environments). Records a frame after mount and after every `rerender`
+ * while a test is being recorded.
  *
  * Synchronous like the original, so `const { asFragment } = render(...)`
  * keeps working. Testing Library wraps mounting in `act()`, which means the DOM
  * is committed when it returns, so frames are captured without settling: the
  * snapshot is taken right here, before the test's next line can change the DOM.
  *
- * Unmounting is handed to the recorder's teardown rather than to Testing
- * Library's own auto-cleanup, which would run before the closing frame is
- * taken. The plugin switches auto-cleanup off with `RTL_SKIP_AUTO_CLEANUP`.
+ * Importing this module hands unmounting to the recorder's teardown rather
+ * than to Testing Library's own auto-cleanup, which would run before the
+ * closing frame is taken. The plugin switches auto-cleanup off with
+ * `RTL_SKIP_AUTO_CLEANUP`.
  */
 export function render(ui, options) {
-    recorder.onTeardown(cleanup);
     const result = baseRender(ui, options);
-    if (isValidElement(ui)) {
+    if (recorder.isActive && isValidElement(ui)) {
         const info = describeElement(ui);
         recorder.setComponent(info);
         void recorder.capture('render', labelFor(info), { props: info.props }, { settle: false });
@@ -27,7 +31,7 @@ export function render(ui, options) {
     const originalRerender = result.rerender;
     result.rerender = (next) => {
         originalRerender(next);
-        if (isValidElement(next)) {
+        if (recorder.isActive && isValidElement(next)) {
             const info = describeElement(next);
             void recorder.capture('render', `rerender ${labelFor(info)}`, { props: info.props }, { settle: false });
         }

package/dist/testing-library.d.ts

@@ -1,3 +1,5 @@
 export * from '@testing-library/react';
 export { step } from '@describe-me/core';
+export { cleanup } from './cleanup.js';
+export { fireEvent } from './fire-event.js';
 export { render } from './render-testing-library.js';

package/dist/testing-library.js

@@ -1,4 +1,7 @@
-// Everything @testing-library/react offers, with `render` swapped for the recording one.
+// Everything @testing-library/react offers, with `render`, `fireEvent` and
+// `cleanup` swapped for recording ones.
 export * from '@testing-library/react';
 export { step } from '@describe-me/core';
+export { cleanup } from './cleanup.js';
+export { fireEvent } from './fire-event.js';
 export { render } from './render-testing-library.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@describe-me/react",
-  "version": "0.3.0",
+  "version": "0.5.0-next.0",
   "description": "React adapter for describe-me: drop-in render functions that record frames",
   "keywords": [
     "vitest",
@@ -42,14 +42,16 @@
     "README.md",
     "LICENSE"
   ],
-  "sideEffects": false,
+  "sideEffects": [
+    "./dist/render-testing-library.js"
+  ],
   "dependencies": {
-    "@describe-me/core": "^0.3.0"
+    "@describe-me/core": "^0.5.0-next.0"
   },
   "peerDependencies": {
-    "@testing-library/react": ">=16",
-    "react": ">=18",
-    "vitest-browser-react": ">=2"
+    "@testing-library/react": "^16.0.0",
+    "react": "^18.0.0 || ^19.0.0",
+    "vitest-browser-react": "^2.0.0"
   },
   "peerDependenciesMeta": {
     "@testing-library/react": {