@describe-me/react 0.2.0 → 0.3.0

package/README.md

@@ -1,9 +1,16 @@
 # @describe-me/react
 
-The React adapter for [describe-me](https://github.com/grzehub/describe-me): a
-drop-in `render` for `vitest-browser-react` that records a frame after mount and
-after every `rerender`, and reads the component's name and props for the docs.
-This is the only React-specific code in the project.
+The React adapter for [describe-me](https://github.com/grzehub/describe-me):
+drop-in `render` functions that record a frame after mount and after every
+`rerender`, and read the component's name and props for the docs. This is the
+only React-specific code in the project.
+
+| entry point                          | wraps                    | for                      |
+| ------------------------------------ | ------------------------ | ------------------------ |
+| `@describe-me/react`                 | `vitest-browser-react`   | Vitest browser mode      |
+| `@describe-me/react/testing-library` | `@testing-library/react` | jsdom and other DOM envs |
+
+Both test libraries are optional peers: install the one your tests use.
 
 ## Install
 
@@ -13,7 +20,7 @@ pnpm add -D @describe-me/react
 
 ## Usage
 
-The package re-exports everything `vitest-browser-react` offers, with `render`
+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.
 
 ```tsx
@@ -23,9 +30,17 @@ const screen = await render(<Counter initial={1} />)
 await step('increment', () => screen.getByRole('button', { name: 'add' }).click())
 ```
 
+```tsx
+import { render } from '@describe-me/react/testing-library'
+
+// Synchronous, exactly like the original.
+const { getByRole } = render(<Counter initial={1} />)
+```
+
 With `@describe-me/vitest`'s `describeMe()` plugin you do not even need that:
-the plugin redirects `vitest-browser-react` imports to this adapter, so tests
-record frames unchanged.
+the plugin redirects `vitest-browser-react` or `@testing-library/react` imports
+to the matching entry point, including imports made from your own
+`test-utils` wrapper, so tests record frames unchanged.
 
 See the [root README](https://github.com/grzehub/describe-me#readme) for the
 full picture.

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

@@ -0,0 +1,19 @@
+import { render as baseRender } from '@testing-library/react';
+import { type ReactElement } from 'react';
+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`.
+ *
+ * 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`.
+ */
+export declare function render(ui: ReactElement, options?: RenderOptions): RenderResult;
+export {};

package/dist/render-testing-library.js

@@ -0,0 +1,36 @@
+import { cleanup, 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';
+/**
+ * Drop-in for `render` from @testing-library/react (jsdom and other DOM
+ * environments). Records a frame after mount and after every `rerender`.
+ *
+ * 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`.
+ */
+export function render(ui, options) {
+    recorder.onTeardown(cleanup);
+    const result = baseRender(ui, options);
+    if (isValidElement(ui)) {
+        const info = describeElement(ui);
+        recorder.setComponent(info);
+        void recorder.capture('render', labelFor(info), { props: info.props }, { settle: false });
+    }
+    const originalRerender = result.rerender;
+    result.rerender = (next) => {
+        originalRerender(next);
+        if (isValidElement(next)) {
+            const info = describeElement(next);
+            void recorder.capture('render', `rerender ${labelFor(info)}`, { props: info.props }, { settle: false });
+        }
+    };
+    return result;
+}

package/dist/testing-library.d.ts

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

package/dist/testing-library.js

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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@describe-me/react",
-  "version": "0.2.0",
-  "description": "React adapter for describe-me: a drop-in render that records frames",
+  "version": "0.3.0",
+  "description": "React adapter for describe-me: drop-in render functions that record frames",
   "keywords": [
     "vitest",
     "storybook",
@@ -31,6 +31,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./testing-library": {
+      "types": "./dist/testing-library.d.ts",
+      "default": "./dist/testing-library.js"
     }
   },
   "files": [
@@ -40,17 +44,30 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@describe-me/core": "^0.2.0"
+    "@describe-me/core": "^0.3.0"
   },
   "peerDependencies": {
+    "@testing-library/react": ">=16",
     "react": ">=18",
     "vitest-browser-react": ">=2"
   },
+  "peerDependenciesMeta": {
+    "@testing-library/react": {
+      "optional": true
+    },
+    "vitest-browser-react": {
+      "optional": true
+    }
+  },
   "devDependencies": {
+    "@testing-library/dom": "^10.4.0",
+    "@testing-library/react": "^16.3.0",
     "@types/react": "^19",
+    "@types/react-dom": "^19",
     "react": "^19.3.0",
-    "vitest-browser-react": "^2.3.0",
-    "vitest": "^5.0.1"
+    "react-dom": "^19.3.0",
+    "vitest": "^5.0.1",
+    "vitest-browser-react": "^2.3.0"
   },
   "scripts": {
     "build": "rimraf dist && tsc -p tsconfig.json"