@describe-me/react 0.5.0-next.1 → 0.5.0-next.3

package/README.md

@@ -24,7 +24,10 @@ 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.
+`cleanup` takes the closing frame before it unmounts. When the render frame is
+taken follows the plugin's
+[`renderFrame`](https://github.com/grzehub/describe-me#render-frame-timing)
+option.
 
 ```tsx
 import { render, step } from '@describe-me/react'

package/dist/cleanup.js

@@ -6,6 +6,7 @@ import { recorder } from '@describe-me/core';
  * state instead of an empty page.
  */
 export function cleanup() {
+    recorder.beforeInteraction();
     void recorder.capture('end', 'end of test', undefined, { settle: false });
     unmountAll();
 }

package/dist/describe-rendered.d.ts

@@ -0,0 +1,9 @@
+import type { ReactElement } from 'react';
+import { type ComponentInfo } from '@describe-me/core';
+/**
+ * Describe what a test rendered: `ui` when the plugin registered its
+ * component, otherwise the first registered component inside it, with the
+ * props that component received. Falls back to `ui` when nothing is found or
+ * React's internals look different. Synchronous and bounded.
+ */
+export declare function describeRendered(ui: ReactElement, container: Element | DocumentFragment, hasWrapper: boolean): ComponentInfo;

package/dist/describe-rendered.js

@@ -0,0 +1,50 @@
+import { describeComponentType, EXPORT_REGISTRY_KEY, serializeValue, } from '@describe-me/core';
+import { describeElement } from './describe-element.js';
+import { firstRegisteredFiber } from './first-registered-fiber.js';
+import { registeredElement } from './registered-element.js';
+import { rootFiber } from './root-fiber.js';
+import { subjectFibers } from './subject-fibers.js';
+/**
+ * Describe what a test rendered: `ui` when the plugin registered its
+ * component, otherwise the first registered component inside it, with the
+ * props that component received. Falls back to `ui` when nothing is found or
+ * React's internals look different. Synchronous and bounded.
+ */
+export function describeRendered(ui, container, hasWrapper) {
+    try {
+        return lookUp(ui, container, hasWrapper) ?? describeElement(ui);
+    }
+    catch {
+        return describeElement(ui);
+    }
+}
+/** The component to name the test after, or null to keep `ui`. */
+function lookUp(ui, container, hasWrapper) {
+    // Without a registry, as with `registerExports: false`, nothing can be found.
+    if (describeComponentType(ui.type).file !== undefined || !hasRegistry()) {
+        return null;
+    }
+    const element = registeredElement(ui);
+    if (element) {
+        return describeElement(element);
+    }
+    const root = rootFiber(container);
+    if (root === null) {
+        return null;
+    }
+    const subjects = subjectFibers(root, ui);
+    // With a wrapper, the root also holds the wrapper's own components.
+    const starts = subjects.length === 0 && !hasWrapper ? [root] : subjects;
+    const fiber = firstRegisteredFiber(starts);
+    return fiber === null ? null : describeFiber(fiber);
+}
+function hasRegistry() {
+    const scope = globalThis;
+    return scope[Symbol.for(EXPORT_REGISTRY_KEY)] !== undefined;
+}
+function describeFiber(fiber) {
+    const byElementType = describeComponentType(fiber.elementType);
+    const identity = byElementType.file === undefined ? describeComponentType(fiber.type) : byElementType;
+    const props = serializeValue(fiber.memoizedProps ?? {});
+    return { ...identity, props };
+}

package/dist/first-registered-fiber.d.ts

@@ -0,0 +1,7 @@
+import type { FiberLike } from './root-fiber.js';
+/**
+ * The first fiber whose component the plugin registered, depth first through
+ * each start fiber and its descendants, or null. The siblings of a start
+ * fiber and the subtrees of `Suspense` fallbacks are not searched.
+ */
+export declare function firstRegisteredFiber(starts: FiberLike[]): FiberLike | null;

package/dist/first-registered-fiber.js

@@ -0,0 +1,55 @@
+import { isValidElement } from 'react';
+import { describeComponentType } from '@describe-me/core';
+const MAX_VISITED = 5000;
+/**
+ * The first fiber whose component the plugin registered, depth first through
+ * each start fiber and its descendants, or null. The siblings of a start
+ * fiber and the subtrees of `Suspense` fallbacks are not searched.
+ */
+export function firstRegisteredFiber(starts) {
+    // React mounts a fallback inside a Fragment fiber whose `memoizedProps` is the fallback itself.
+    const fallbacks = new Set();
+    let visited = 0;
+    for (const start of starts) {
+        const pending = [start];
+        while (pending.length > 0) {
+            if (visited >= MAX_VISITED) {
+                return null;
+            }
+            visited++;
+            const fiber = pending.pop();
+            if (fiber !== start && fiber.sibling) {
+                pending.push(fiber.sibling);
+            }
+            if (fallbacks.has(fiber.memoizedProps)) {
+                continue;
+            }
+            if (isRegistered(fiber)) {
+                return fiber;
+            }
+            rememberFallback(fiber.memoizedProps, fallbacks);
+            if (fiber.child) {
+                pending.push(fiber.child);
+            }
+        }
+    }
+    return null;
+}
+function isRegistered(fiber) {
+    return (describeComponentType(fiber.elementType).file !== undefined ||
+        describeComponentType(fiber.type).file !== undefined);
+}
+/** Text fibers hold a string and the HostRoot holds null, so the shape is checked first. */
+function rememberFallback(props, fallbacks) {
+    if (typeof props !== 'object' || props === null) {
+        return;
+    }
+    const { fallback } = props;
+    if (typeof fallback !== 'object' || fallback === null) {
+        return;
+    }
+    fallbacks.add(fallback);
+    if (isValidElement(fallback)) {
+        fallbacks.add(fallback.props);
+    }
+}

package/dist/record-sync-action.js

@@ -12,6 +12,7 @@ let depth = 0;
  * settling.
  */
 export function recordSyncAction(label, run) {
+    recorder.beforeInteraction();
     depth++;
     let result;
     try {

package/dist/registered-element.d.ts

@@ -0,0 +1,7 @@
+import { type ReactElement } from 'react';
+/**
+ * The first element inside `ui` whose component the plugin registered, or
+ * null. Depth first through `children`, then the other element props. A
+ * `fallback` is skipped, because `Suspense` shows it only while waiting.
+ */
+export declare function registeredElement(ui: ReactElement): ReactElement | null;

package/dist/registered-element.js

@@ -0,0 +1,48 @@
+import { isValidElement } from 'react';
+import { describeComponentType } from '@describe-me/core';
+const MAX_DEPTH = 6;
+const MAX_ELEMENTS = 200;
+/**
+ * The first element inside `ui` whose component the plugin registered, or
+ * null. Depth first through `children`, then the other element props. A
+ * `fallback` is skipped, because `Suspense` shows it only while waiting.
+ */
+export function registeredElement(ui) {
+    return searchInside(ui, 1, { visited: 0 });
+}
+function searchInside(element, depth, budget) {
+    for (const held of heldElements(element)) {
+        if (budget.visited >= MAX_ELEMENTS) {
+            return null;
+        }
+        budget.visited++;
+        if (describeComponentType(held.type).file !== undefined) {
+            return held;
+        }
+        const found = depth < MAX_DEPTH ? searchInside(held, depth + 1, budget) : null;
+        if (found) {
+            return found;
+        }
+    }
+    return null;
+}
+/** The elements in `children` first, then those in every other prop but `fallback`. */
+function heldElements(element) {
+    const props = (element.props ?? {});
+    const held = elementsIn(props.children);
+    for (const [key, value] of Object.entries(props)) {
+        if (key !== 'children' && key !== 'fallback') {
+            held.push(...elementsIn(value));
+        }
+    }
+    return held;
+}
+function elementsIn(value) {
+    if (isValidElement(value)) {
+        return [value];
+    }
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value.flat(Infinity).filter((item) => isValidElement(item));
+}

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

@@ -11,6 +11,8 @@ type RenderResult = ReturnType<typeof baseRender>;
  * 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.
+ * `render`, `rerender` and `unmount` first take a render frame the plugin's
+ * `renderFrame` option deferred.
  *
  * Importing this module hands unmounting to the recorder's teardown rather
  * than to Testing Library's own auto-cleanup, which would run before the

package/dist/render-testing-library.js

@@ -1,7 +1,7 @@
 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 { describeRendered } from './describe-rendered.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.
@@ -15,6 +15,8 @@ recorder.onTeardown(unmountAll);
  * 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.
+ * `render`, `rerender` and `unmount` first take a render frame the plugin's
+ * `renderFrame` option deferred.
  *
  * Importing this module hands unmounting to the recorder's teardown rather
  * than to Testing Library's own auto-cleanup, which would run before the
@@ -22,19 +24,30 @@ recorder.onTeardown(unmountAll);
  * `RTL_SKIP_AUTO_CLEANUP`.
  */
 export function render(ui, options) {
+    recorder.beforeInteraction();
     const result = baseRender(ui, options);
+    // Testing Library keeps the wrapper for `rerender`.
+    const hasWrapper = Boolean(options?.wrapper);
     if (recorder.isActive && isValidElement(ui)) {
-        const info = describeElement(ui);
+        const info = describeRendered(ui, result.container, hasWrapper);
         recorder.setComponent(info);
         void recorder.capture('render', labelFor(info), { props: info.props }, { settle: false });
     }
     const originalRerender = result.rerender;
     result.rerender = (next) => {
+        recorder.beforeInteraction();
         originalRerender(next);
         if (recorder.isActive && isValidElement(next)) {
-            const info = describeElement(next);
+            const info = describeRendered(next, result.container, hasWrapper);
+            recorder.setComponent(info);
             void recorder.capture('render', `rerender ${labelFor(info)}`, { props: info.props }, { settle: false });
         }
     };
+    const originalUnmount = result.unmount;
+    // Without this, a lazy test that ends with `unmount()` documents an empty page.
+    result.unmount = () => {
+        recorder.beforeInteraction();
+        originalUnmount();
+    };
     return result;
 }

package/dist/render.d.ts

@@ -5,7 +5,8 @@ type RenderOptions = Parameters<BaseRender>[1];
 type Screen = Awaited<ReturnType<BaseRender>>;
 /**
  * Drop-in for `render` from vitest-browser-react. Records a frame after mount
- * and after every `rerender`.
+ * and after every `rerender`. `render`, `rerender` and `unmount` first take a
+ * render frame the plugin's `renderFrame` option deferred.
  */
 export declare function render(ui: ReactElement, options?: RenderOptions): Promise<Screen>;
 export {};

package/dist/render.js

@@ -1,27 +1,48 @@
 import { render as baseRender } from 'vitest-browser-react';
 import { isValidElement } from 'react';
 import { recorder } from '@describe-me/core';
-import { describeElement } from './describe-element.js';
+import { describeRendered } from './describe-rendered.js';
 import { labelFor } from './label-for.js';
 /**
  * Drop-in for `render` from vitest-browser-react. Records a frame after mount
- * and after every `rerender`.
+ * and after every `rerender`. `render`, `rerender` and `unmount` first take a
+ * render frame the plugin's `renderFrame` option deferred.
  */
 export async function render(ui, options) {
+    const generation = recorder.generation;
+    recorder.beforeInteraction();
     const screen = await baseRender(ui, options);
-    if (isValidElement(ui)) {
-        const info = describeElement(ui);
+    // vitest-browser-react keeps the wrapper for `rerender`.
+    const hasWrapper = Boolean(options?.wrapper);
+    if (isRecording(generation) && isValidElement(ui)) {
+        const info = describeRendered(ui, screen.container, hasWrapper);
         recorder.setComponent(info);
-        await recorder.capture('render', labelFor(info), { props: info.props });
+        await recorder.capture('render', labelFor(info), { props: info.props }, { generation });
     }
     const originalRerender = screen.rerender.bind(screen);
     screen.rerender = (async (next) => {
+        const rerenderGeneration = recorder.generation;
+        recorder.beforeInteraction();
         const result = await originalRerender(next);
-        if (isValidElement(next)) {
-            const info = describeElement(next);
-            await recorder.capture('render', `rerender ${labelFor(info)}`, { props: info.props });
+        if (isRecording(rerenderGeneration) && isValidElement(next)) {
+            const info = describeRendered(next, screen.container, hasWrapper);
+            recorder.setComponent(info);
+            await recorder.capture('render', `rerender ${labelFor(info)}`, { props: info.props }, { generation: rerenderGeneration });
         }
         return result;
     });
+    const originalUnmount = screen.unmount.bind(screen);
+    // Without this, a lazy test that ends with `unmount()` documents an empty page.
+    screen.unmount = () => {
+        recorder.beforeInteraction();
+        return originalUnmount();
+    };
     return screen;
 }
+/**
+ * Whether the test that began at `generation` is still being recorded. A
+ * render the test did not await can finish after it ended.
+ */
+function isRecording(generation) {
+    return recorder.isActive && recorder.generation === generation;
+}

package/dist/root-fiber.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The fields of a React fiber the naming lookup reads. Structural, because
+ * React does not export its fiber type.
+ */
+export interface FiberLike {
+    elementType?: unknown;
+    type?: unknown;
+    memoizedProps?: unknown;
+    child?: FiberLike | null;
+    sibling?: FiberLike | null;
+    stateNode?: unknown;
+}
+/**
+ * The current HostRoot fiber of the React root mounted into `container`, or
+ * null when there is none.
+ */
+export declare function rootFiber(container: Element | DocumentFragment): FiberLike | null;

package/dist/root-fiber.js

@@ -0,0 +1,16 @@
+// React appends a random suffix, one per copy of React on the page.
+const CONTAINER_KEY_PREFIX = '__reactContainer$';
+/**
+ * The current HostRoot fiber of the React root mounted into `container`, or
+ * null when there is none.
+ */
+export function rootFiber(container) {
+    const key = Object.keys(container).find((name) => name.startsWith(CONTAINER_KEY_PREFIX));
+    if (key === undefined) {
+        return null;
+    }
+    const stored = container[key];
+    // The fiber on the container can be the stale alternate. Its FiberRoot knows the current one.
+    const fiberRoot = stored?.stateNode;
+    return fiberRoot?.current ?? null;
+}

package/dist/subject-fibers.d.ts

@@ -0,0 +1,8 @@
+import { type ReactElement } from 'react';
+import type { FiberLike } from './root-fiber.js';
+/**
+ * The fibers React mounted for `ui` itself, where the naming lookup starts,
+ * so a wrapper's own components are never searched. Empty when none can be
+ * told apart.
+ */
+export declare function subjectFibers(root: FiberLike, ui: ReactElement): FiberLike[];

package/dist/subject-fibers.js

@@ -0,0 +1,51 @@
+import { Fragment, isValidElement } from 'react';
+const MAX_VISITED = 5000;
+/**
+ * The fibers React mounted for `ui` itself, where the naming lookup starts,
+ * so a wrapper's own components are never searched. Empty when none can be
+ * told apart.
+ */
+export function subjectFibers(root, ui) {
+    const subjectProps = propsOfSubject(ui);
+    const byProps = fibersMatching(root, (fiber) => subjectProps.has(fiber.memoizedProps));
+    // Every `div` or fragment would share a host or symbol type, so only component types count.
+    if (byProps.length > 0 || !isComponentType(ui.type)) {
+        return byProps;
+    }
+    return fibersMatching(root, (fiber) => fiber.elementType === ui.type);
+}
+/**
+ * The props objects the fibers of `ui` hold. A fragment's own fiber holds its
+ * children or does not exist, so its direct element children stand in for it.
+ */
+function propsOfSubject(ui) {
+    if (ui.type !== Fragment) {
+        return new Set([ui.props]);
+    }
+    const { children } = ui.props;
+    const items = Array.isArray(children) ? children.flat(Infinity) : [children];
+    return new Set(items.filter((item) => isValidElement(item)).map((element) => element.props));
+}
+/** Depth first from `root`, without descending into a fiber that matches. */
+function fibersMatching(root, matches) {
+    const found = [];
+    const pending = [root];
+    for (let visited = 0; visited < MAX_VISITED && pending.length > 0; visited++) {
+        const fiber = pending.pop();
+        if (fiber.sibling) {
+            pending.push(fiber.sibling);
+        }
+        if (matches(fiber)) {
+            found.push(fiber);
+            continue;
+        }
+        if (fiber.child) {
+            pending.push(fiber.child);
+        }
+    }
+    return found;
+}
+/** Components, `memo`, `forwardRef`, `lazy` and contexts. */
+function isComponentType(type) {
+    return typeof type === 'function' || (typeof type === 'object' && type !== null);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@describe-me/react",
-  "version": "0.5.0-next.1",
+  "version": "0.5.0-next.3",
   "description": "React adapter for describe-me: drop-in render functions that record frames",
   "keywords": [
     "vitest",
@@ -46,7 +46,7 @@
     "./dist/render-testing-library.js"
   ],
   "dependencies": {
-    "@describe-me/core": "^0.5.0-next.1"
+    "@describe-me/core": "^0.5.0-next.3"
   },
   "peerDependencies": {
     "@testing-library/react": "^16.0.0",