@describe-me/react 0.5.2 → 0.5.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/README.md +50 -38
  2. package/dist/publish-testing-library-act.d.ts +7 -0
  3. package/dist/publish-testing-library-act.js +14 -0
  4. package/dist/render-testing-library.js +3 -1
  5. package/package.json +9 -7
package/README.md CHANGED
@@ -1,55 +1,67 @@
1
1
  # @describe-me/react
2
2
 
3
- The React adapter for [describe-me](https://github.com/grzehub/describe-me):
4
- drop-in `render` functions that record a frame after mount and after every
5
- `rerender`, and read the component's name and props for the docs. This is the
6
- only React-specific code in the project.
3
+ **Your tests are your stories.** The React adapter of describe-me: living
4
+ component documentation generated from the Vitest tests you already have.
7
5
 
8
- | entry point | wraps | for |
9
- | ------------------------------------ | ------------------------ | ------------------------ |
10
- | `@describe-me/react` | `vitest-browser-react` | Vitest browser mode |
11
- | `@describe-me/react/testing-library` | `@testing-library/react` | jsdom and other DOM envs |
6
+ **[Read the docs](https://grzehub.github.io/describe-me/)** · open the viewer
7
+ of the [browser-mode example](https://grzehub.github.io/describe-me/examples/react-browser/)
8
+ or the [jsdom example](https://grzehub.github.io/describe-me/examples/react-jsdom/)
9
+ · [Limitations](https://grzehub.github.io/describe-me/limitations.html)
12
10
 
13
- Both test libraries are optional peers: install the one your tests use.
11
+ describe-me captures the DOM after each step of a test and shows the result as
12
+ a browsable catalog. `describe` blocks become the sidebar, each `it` is a
13
+ story, and each step is a frame you can scrub through. Stories cannot rot,
14
+ because they are tests. If one drifts from the component, CI goes red.
14
15
 
15
- ## Install
16
+ Status: prototype. React 18 and 19, Vitest 4 and 5 in browser mode or jsdom,
17
+ static snapshots.
18
+
19
+ ## Which package do I need
20
+
21
+ | Package | What it is | Install it |
22
+ | --------------------- | -------------------------------------------- | ----------------------- |
23
+ | `describe-me` | the viewer and the `describe-me` CLI | yes |
24
+ | `@describe-me/vitest` | the Vitest plugin, setup files and reporter | yes |
25
+ | `@describe-me/react` | `render` functions that record frames (this) | yes |
26
+ | `@describe-me/core` | the recorder and the manifest types | no, the others bring it |
27
+
28
+ ## Quick start
16
29
 
17
30
  ```sh
18
- pnpm add -D @describe-me/react
31
+ pnpm add -D describe-me @describe-me/vitest @describe-me/react
19
32
  ```
20
33
 
21
- All describe-me packages must be on the same version
22
- ([Add it to your project](https://github.com/grzehub/describe-me#add-it-to-your-project)).
34
+ ```ts
35
+ // vitest.config.ts
36
+ import { describeMe } from '@describe-me/vitest/plugin'
23
37
 
24
- ## Usage
38
+ export default defineConfig({
39
+ plugins: [react(), describeMe()],
40
+ test: { environment: 'jsdom' }, // or your browser-mode settings
41
+ })
42
+ ```
25
43
 
26
- Each entry point re-exports everything its test library offers, with the
27
- recording functions swapped in, so switching an existing test is one import.
28
- `@describe-me/react` swaps `render`. The Testing Library entry swaps `render`,
29
- `fireEvent` and `cleanup`: every `fireEvent` call records a frame, and
30
- `cleanup` takes the closing frame before it unmounts. When the render frame is
31
- taken follows the plugin's
32
- [`renderFrame`](https://github.com/grzehub/describe-me#render-frame-timing)
33
- option.
44
+ Run your tests, then `describe-me dev` opens the viewer.
45
+ [Getting started](https://grzehub.github.io/describe-me/getting-started.html)
46
+ walks through both environments. Keep all describe-me packages on one version
47
+ ([why](https://grzehub.github.io/describe-me/installation.html#lockstep)).
34
48
 
35
- ```tsx
36
- import { render, step } from '@describe-me/react'
49
+ ## This package
37
50
 
38
- const screen = await render(<Counter initial={1} />)
39
- await step('increment', () => screen.getByRole('button', { name: 'add' }).click())
40
- ```
51
+ Drop-in `render` functions that record a frame after mount and after every
52
+ `rerender`, and read the component's name and props for the docs. It is the
53
+ only React-specific code in describe-me.
41
54
 
42
- ```tsx
43
- import { render } from '@describe-me/react/testing-library'
55
+ | Entry point | Wraps | For |
56
+ | ------------------------------------------------------------------------------------------------------------------ | ------------------------ | ------------------- |
57
+ | [`@describe-me/react`](https://grzehub.github.io/describe-me/api.html#entry-react) | `vitest-browser-react` | Vitest browser mode |
58
+ | [`@describe-me/react/testing-library`](https://grzehub.github.io/describe-me/api.html#entry-react-testing-library) | `@testing-library/react` | jsdom |
44
59
 
45
- // Synchronous, exactly like the original.
46
- const { getByRole } = render(<Counter initial={1} />)
47
- ```
60
+ Each entry point re-exports its test library with the recording functions
61
+ swapped in. With the `describeMe()` plugin you never import them yourself: it
62
+ redirects your `render` imports, those in your own `test-utils` included.
63
+ Install the test library your tests use. Both are optional peers.
48
64
 
49
- With `@describe-me/vitest`'s `describeMe()` plugin you do not even need that:
50
- the plugin redirects `vitest-browser-react` or `@testing-library/react` imports
51
- to the matching entry point, including imports made from your own
52
- `test-utils` wrapper, so tests record frames unchanged.
65
+ ## License
53
66
 
54
- See the [root README](https://github.com/grzehub/describe-me#readme) for the
55
- full picture.
67
+ MIT
package/dist/publish-testing-library-act.d.ts ADDED
@@ -0,0 +1,7 @@
1
+ /**
2
+ * Leave a check on `globalThis` that holds while @testing-library/dom keeps the
3
+ * `asyncWrapper` @testing-library/react installed, so a user-event call drains
4
+ * a macrotask before it resolves. A global, because @describe-me/vitest reads it
5
+ * and does not depend on this package.
6
+ */
7
+ export declare function publishTestingLibraryAct(): void;
package/dist/publish-testing-library-act.js ADDED
@@ -0,0 +1,14 @@
1
+ import { getConfig } from '@testing-library/react';
2
+ // `testing-library-wraps-in-act.ts` in @describe-me/vitest reads this key.
3
+ const ACT_CHECK = Symbol.for('describe-me.testing-library-act');
4
+ /**
5
+ * Leave a check on `globalThis` that holds while @testing-library/dom keeps the
6
+ * `asyncWrapper` @testing-library/react installed, so a user-event call drains
7
+ * a macrotask before it resolves. A global, because @describe-me/vitest reads it
8
+ * and does not depend on this package.
9
+ */
10
+ export function publishTestingLibraryAct() {
11
+ const installed = getConfig().asyncWrapper;
12
+ const host = globalThis;
13
+ host[ACT_CHECK] = () => getConfig().asyncWrapper === installed;
14
+ }
package/dist/render-testing-library.js CHANGED
@@ -3,9 +3,11 @@ import { isValidElement } from 'react';
3
3
  import { recorder } from '@describe-me/core';
4
4
  import { describeRendered } from './describe-rendered.js';
5
5
  import { labelFor } from './label-for.js';
6
+ import { publishTestingLibraryAct } from './publish-testing-library-act.js';
6
7
  // On import rather than in `render()`, so a file that only calls `renderHook`
7
- // is unmounted after each test too.
8
+ // is unmounted after each test too, and its user-event frames skip the settle.
8
9
  recorder.onTeardown(unmountAll);
10
+ publishTestingLibraryAct();
9
11
  /**
10
12
  * Drop-in for `render` from @testing-library/react (jsdom and other DOM
11
13
  * environments). Records a frame after mount and after every `rerender`
package/package.json CHANGED
@@ -1,13 +1,15 @@
1
1
  {
2
2
  "name": "@describe-me/react",
3
- "version": "0.5.2",
4
- "description": "React adapter for describe-me: drop-in render functions that record frames",
3
+ "version": "0.5.4",
4
+ "description": "Living component documentation from your Vitest tests: the React adapter of describe-me",
5
5
  "keywords": [
6
6
  "vitest",
7
+ "react",
7
8
  "storybook",
9
+ "storybook alternative",
8
10
  "component documentation",
9
- "visual testing",
10
- "react",
11
+ "living documentation",
12
+ "jsdom",
11
13
  "testing"
12
14
  ],
13
15
  "license": "MIT",
@@ -46,13 +48,13 @@
46
48
  "./dist/render-testing-library.js"
47
49
  ],
48
50
  "dependencies": {
49
- "@describe-me/core": "^0.5.2"
51
+ "@describe-me/core": "^0.5.4"
50
52
  },
51
53
  "peerDependencies": {
52
54
  "@testing-library/react": "^16.0.0",
53
55
  "react": "^18.0.0 || ^19.0.0",
54
56
  "vitest-browser-react": "^2.0.0",
55
- "@describe-me/vitest": "^0.5.2"
57
+ "@describe-me/vitest": "^0.5.4"
56
58
  },
57
59
  "peerDependenciesMeta": {
58
60
  "@testing-library/react": {
@@ -71,7 +73,7 @@
71
73
  "react-dom": "^19.3.0",
72
74
  "vitest": "^5.0.1",
73
75
  "vitest-browser-react": "^2.3.0",
74
- "@describe-me/vitest": "^0.5.2"
76
+ "@describe-me/vitest": "^0.5.4"
75
77
  },
76
78
  "scripts": {
77
79
  "build": "rimraf dist && tsc -p tsconfig.json"