@describe-me/core 0.2.0 → 0.4.0

package/dist/describe-component-type.d.ts

@@ -0,0 +1,14 @@
+import { type ComponentInfo } from './types.js';
+/** How a component type is shown and where it was defined, when that is known. */
+type ComponentIdentity = Pick<ComponentInfo, 'name' | 'file'>;
+/**
+ * Name a component type (an element's `type`) the way its author would.
+ *
+ * The export it was registered under wins, because an anonymous `forwardRef`
+ * or a styled component has no name of its own. Then an explicit
+ * `displayName`, then the function's name, then the same again for the
+ * component a `memo` or `forwardRef` wraps. Shapes are detected structurally,
+ * so no framework is imported. `Anonymous` when nothing names it.
+ */
+export declare function describeComponentType(type: unknown): ComponentIdentity;
+export {};

package/dist/describe-component-type.js

@@ -0,0 +1,72 @@
+import { ANONYMOUS_COMPONENT, EXPORT_REGISTRY_KEY, } from './types.js';
+/** `memo(forwardRef(memo(…)))` is as deep as real code goes; the bound only guards against cycles. */
+const MAX_UNWRAP_DEPTH = 5;
+/**
+ * Display names styled-components gives when none was set: `styled.p`,
+ * `Styled(Button)`. They say which element is styled, not which component it is.
+ */
+const STYLED_DEFAULT_NAMES = [/^styled\./, /^Styled\(/];
+/**
+ * Name a component type (an element's `type`) the way its author would.
+ *
+ * The export it was registered under wins, because an anonymous `forwardRef`
+ * or a styled component has no name of its own. Then an explicit
+ * `displayName`, then the function's name, then the same again for the
+ * component a `memo` or `forwardRef` wraps. Shapes are detected structurally,
+ * so no framework is imported. `Anonymous` when nothing names it.
+ */
+export function describeComponentType(type) {
+    if (typeof type === 'string') {
+        return { name: type };
+    }
+    return identify(type, 0) ?? { name: ANONYMOUS_COMPONENT };
+}
+function identify(type, depth) {
+    if (!isComponentLike(type)) {
+        return null;
+    }
+    const registered = registeredExport(type);
+    if (registered) {
+        return { name: registered.name, file: registered.file };
+    }
+    const { displayName, name } = type;
+    if (isNonEmptyString(displayName) && !isStyledDefault(displayName)) {
+        return { name: displayName };
+    }
+    if (typeof type === 'function' && isNonEmptyString(name)) {
+        return { name };
+    }
+    // An unregistered styled component: its render function is named after the
+    // library's internals (`forwardRefRender`), so `styled.p` is the best name left.
+    if (isNonEmptyString(displayName)) {
+        return { name: displayName };
+    }
+    if (depth >= MAX_UNWRAP_DEPTH) {
+        return null;
+    }
+    return identify(wrappedType(type), depth + 1);
+}
+/** The component inside `memo(…)` (`.type`) or `forwardRef(…)` (`.render`). */
+function wrappedType(type) {
+    const { type: memoized, render } = type;
+    return memoized ?? render;
+}
+/** What the plugin's appended code registered for this value, if anything. */
+function registeredExport(type) {
+    const registry = globalThis[Symbol.for(EXPORT_REGISTRY_KEY)];
+    // Duck-typed rather than `instanceof`: the map may come from another realm.
+    if (typeof registry?.get !== 'function') {
+        return undefined;
+    }
+    return registry.get(type);
+}
+/** Functions and non-null objects: everything a registry can hold and a component can be. */
+function isComponentLike(value) {
+    return typeof value === 'function' || (typeof value === 'object' && value !== null);
+}
+function isNonEmptyString(value) {
+    return typeof value === 'string' && value !== '';
+}
+function isStyledDefault(displayName) {
+    return STYLED_DEFAULT_NAMES.some((pattern) => pattern.test(displayName));
+}

package/dist/index.d.ts

@@ -1,4 +1,6 @@
 export * from './types.js';
+export { describeComponentType } from './describe-component-type.js';
+export { manifestDiagnostics } from './manifest-diagnostics.js';
 export { recorder } from './recorder.js';
 export { serializeValue } from './serialize-value.js';
 export { step } from './step.js';

package/dist/index.js

@@ -1,4 +1,6 @@
 export * from './types.js';
+export { describeComponentType } from './describe-component-type.js';
+export { manifestDiagnostics } from './manifest-diagnostics.js';
 export { recorder } from './recorder.js';
 export { serializeValue } from './serialize-value.js';
 export { step } from './step.js';

package/dist/manifest-diagnostics.d.ts

@@ -0,0 +1,7 @@
+import { type Manifest, type ManifestDiagnostics } from './types.js';
+/**
+ * List what the manifest could not document: anonymous components, named ones
+ * without props, and assets that will not load. The reporter prints it after a
+ * run and the viewer shows it in the header, so both agree on what is missing.
+ */
+export declare function manifestDiagnostics(manifest: Manifest): ManifestDiagnostics;

package/dist/manifest-diagnostics.js

@@ -0,0 +1,34 @@
+import { ANONYMOUS_COMPONENT } from './types.js';
+/** Host elements such as `div` are rendered as-is and have no props doc to miss. */
+function isHostElement(name) {
+    return /^[a-z]/.test(name);
+}
+/**
+ * List what the manifest could not document: anonymous components, named ones
+ * without props, and assets that will not load. The reporter prints it after a
+ * run and the viewer shows it in the header, so both agree on what is missing.
+ */
+export function manifestDiagnostics(manifest) {
+    const anonymous = [];
+    const undocumented = new Map();
+    for (const mod of manifest.modules) {
+        for (const test of mod.tests) {
+            const name = test.component?.name;
+            if (!name || isHostElement(name)) {
+                continue;
+            }
+            if (name === ANONYMOUS_COMPONENT) {
+                anonymous.push({ testId: test.id, fullName: test.fullName });
+                continue;
+            }
+            if (!manifest.components[name]) {
+                undocumented.set(name, (undocumented.get(name) ?? 0) + 1);
+            }
+        }
+    }
+    return {
+        anonymous,
+        undocumented: Array.from(undocumented, ([name, tests]) => ({ name, tests })).sort((left, right) => left.name.localeCompare(right.name)),
+        assetsMissing: manifest.assetsMissing ?? [],
+    };
+}

package/dist/recorder.d.ts

@@ -1,7 +1,9 @@
-import type { ComponentInfo, FrameKind, TestRecord } from './types.js';
+import type { CaptureOptions, ComponentInfo, FrameKind, TestRecord } from './types.js';
+type Teardown = () => void;
 /**
- * Browser-side recorder. One instance per test iframe; `begin()` in beforeEach,
- * `end()` in afterEach. Framework adapters call `capture()` and `setComponent()`.
+ * Test-side recorder, running wherever the tests run: the browser-mode iframe
+ * or jsdom. `begin()` in beforeEach, `end()` then `teardown()` in afterEach.
+ * Framework adapters call `capture()`, `setComponent()` and `onTeardown()`.
  */
 declare class Recorder {
     private frames;
@@ -10,11 +12,20 @@ declare class Recorder {
     private active;
     private lastHash;
     private seq;
+    private teardowns;
     begin(): void;
     get isActive(): boolean;
     setComponent(info: ComponentInfo): void;
-    capture(kind: FrameKind, label: string, meta?: Record<string, unknown>): Promise<void>;
+    capture(kind: FrameKind, label: string, meta?: Record<string, unknown>, options?: CaptureOptions): Promise<void>;
     end(): TestRecord;
+    /**
+     * Register work that must run after the test's frames are handed over, such
+     * as unmounting. Adapters call this once at import; registering the same
+     * callback again is a no-op.
+     */
+    onTeardown(callback: Teardown): void;
+    /** Run the registered teardowns. Called by the runner integration after `end()`. */
+    teardown(): void;
 }
 export declare const recorder: Recorder;
 export {};

package/dist/recorder.js

@@ -3,8 +3,9 @@ import { materializeAdoptedStyles } from './materialize-adopted-styles.js';
 import { quickHash } from './quick-hash.js';
 import { settle } from './settle.js';
 /**
- * Browser-side recorder. One instance per test iframe; `begin()` in beforeEach,
- * `end()` in afterEach. Framework adapters call `capture()` and `setComponent()`.
+ * Test-side recorder, running wherever the tests run: the browser-mode iframe
+ * or jsdom. `begin()` in beforeEach, `end()` then `teardown()` in afterEach.
+ * Framework adapters call `capture()`, `setComponent()` and `onTeardown()`.
  */
 class Recorder {
     frames = [];
@@ -13,6 +14,7 @@ class Recorder {
     active = false;
     lastHash = '';
     seq = 0;
+    teardowns = new Set();
     begin() {
         this.frames = [];
         this.component = undefined;
@@ -29,11 +31,13 @@ class Recorder {
             this.component = info;
         }
     }
-    async capture(kind, label, meta) {
+    async capture(kind, label, meta, options = {}) {
         if (!this.active) {
             return;
         }
-        await settle();
+        if (options.settle !== false) {
+            await settle();
+        }
         const node = await materializeAdoptedStyles(() => snapshot(document, { mirror: createMirror(), inlineStylesheet: true }));
         if (!node) {
             return;
@@ -63,7 +67,27 @@ class Recorder {
     }
     end() {
         this.active = false;
-        return { frames: this.frames, component: this.component };
+        // The reporter needs the origin rrweb resolved every URL against. Optional
+        // chaining, because a DOM environment is not guaranteed to define `location`.
+        return {
+            frames: this.frames,
+            component: this.component,
+            origin: globalThis.location?.origin,
+        };
+    }
+    /**
+     * Register work that must run after the test's frames are handed over, such
+     * as unmounting. Adapters call this once at import; registering the same
+     * callback again is a no-op.
+     */
+    onTeardown(callback) {
+        this.teardowns.add(callback);
+    }
+    /** Run the registered teardowns. Called by the runner integration after `end()`. */
+    teardown() {
+        for (const callback of this.teardowns) {
+            callback();
+        }
     }
 }
 const RECORDER_KEY = Symbol.for('describe-me.recorder');

package/dist/serialize-value.js

@@ -1,3 +1,4 @@
+import { describeComponentType } from './describe-component-type.js';
 /** Turn arbitrary props into something JSON-safe and readable. */
 export function serializeValue(value, depth = 0) {
     if (depth > 3) {
@@ -23,12 +24,7 @@ export function serializeValue(value, depth = 0) {
         const record = value;
         // React element
         if ('$$typeof' in record && 'type' in record) {
-            const type = record.type;
-            const name = typeof type === 'string'
-                ? type
-                : (type?.displayName ??
-                    type?.name ??
-                    'Anonymous');
+            const { name } = describeComponentType(record.type);
             return `<${name} />`;
         }
         const out = {};

package/dist/types.d.ts

@@ -3,6 +3,43 @@ export type FrameKind = 'render' | 'action' | 'step' | 'end';
 export interface ComponentInfo {
     name: string;
     props: Record<string, unknown>;
+    /**
+     * Source file that defines the component, relative to the project root, when
+     * the plugin registered its module's exports. Lets the reporter read props
+     * without guessing the file from the test's imports.
+     */
+    file?: string;
+}
+/** What the plugin registers for every top-level export of a project module. */
+export interface RegisteredExport {
+    /** The export name in the defining module, e.g. `Button`. */
+    name: string;
+    /** The defining module, relative to the project root, posix separators. */
+    file: string;
+}
+/**
+ * `Symbol.for()` key of the registry on `globalThis`: a
+ * `WeakMap<object, RegisteredExport>` filled by code the plugin appends to
+ * project modules. A global rather than an import, because a user's module
+ * cannot always resolve `@describe-me/core` (pnpm) and a bundled adapter may
+ * carry its own copy of core.
+ */
+export declare const EXPORT_REGISTRY_KEY: "describe-me.exports";
+/**
+ * Prefix of project asset URLs inside stored snapshots, e.g.
+ * `describe-me-asset:3f2a9c1d.svg`. The reporter copies the file to
+ * `<outDir>/assets/` and the viewer resolves the prefix against `__data/assets/`.
+ */
+export declare const ASSET_URL_PREFIX: "describe-me-asset:";
+/** Options for `recorder.capture()`. */
+export interface CaptureOptions {
+    /**
+     * Wait one macrotask for the framework to flush before looking at the DOM.
+     * Default: true. Pass false when the caller knows the DOM is already
+     * committed (e.g. right after Testing Library's `act()`-wrapped `rerender`):
+     * the snapshot is then taken synchronously, before the caller moves on.
+     */
+    settle?: boolean;
 }
 /** A frame as captured in the browser. `snapshot` is an rrweb serialized document. */
 export interface Frame {
@@ -18,6 +55,12 @@ export interface Frame {
 export interface TestRecord {
     frames: Frame[];
     component?: ComponentInfo;
+    /**
+     * `location.origin` of the page the test ran in (`http://localhost:3000` in
+     * jsdom, the Vitest server in browser mode). rrweb makes every URL absolute
+     * against it, so the reporter uses it to find project assets.
+     */
+    origin?: string;
 }
 export declare const META_KEY: "describeMe";
 export type TestState = 'passed' | 'failed' | 'skipped' | 'pending';
@@ -83,4 +126,27 @@ export interface Manifest {
     modules: ManifestModule[];
     /** Keyed by component name, as reported by the framework adapter. */
     components: Record<string, ComponentDoc>;
+    /**
+     * Asset URLs the snapshots point at on the test page's origin that could not
+     * be found in the project, as root-relative paths (`/lib/images/logo.svg`).
+     * They will not load in the viewer. Absent in manifests written before 0.4.
+     */
+    assetsMissing?: string[];
+}
+/** The name adapters fall back to when a component has no usable name. */
+export declare const ANONYMOUS_COMPONENT: "Anonymous";
+/** What keeps a manifest from documenting everything its tests rendered. */
+export interface ManifestDiagnostics {
+    /** Tests whose rendered component has no usable name. */
+    anonymous: {
+        testId: string;
+        fullName: string;
+    }[];
+    /** Named components without a props doc, with how many tests rendered each. */
+    undocumented: {
+        name: string;
+        tests: number;
+    }[];
+    /** Root-relative asset paths that will not load in the viewer. */
+    assetsMissing: string[];
 }

package/dist/types.js

@@ -1,2 +1,18 @@
 /** Shared, JSON-serializable types. Safe to import from Node (no DOM). */
+/**
+ * `Symbol.for()` key of the registry on `globalThis`: a
+ * `WeakMap<object, RegisteredExport>` filled by code the plugin appends to
+ * project modules. A global rather than an import, because a user's module
+ * cannot always resolve `@describe-me/core` (pnpm) and a bundled adapter may
+ * carry its own copy of core.
+ */
+export const EXPORT_REGISTRY_KEY = 'describe-me.exports';
+/**
+ * Prefix of project asset URLs inside stored snapshots, e.g.
+ * `describe-me-asset:3f2a9c1d.svg`. The reporter copies the file to
+ * `<outDir>/assets/` and the viewer resolves the prefix against `__data/assets/`.
+ */
+export const ASSET_URL_PREFIX = 'describe-me-asset:';
 export const META_KEY = 'describeMe';
+/** The name adapters fall back to when a component has no usable name. */
+export const ANONYMOUS_COMPONENT = 'Anonymous';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@describe-me/core",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Recorder and manifest types for describe-me: living component docs from your tests",
   "keywords": [
     "vitest",
@@ -34,6 +34,10 @@
     "./types": {
       "types": "./dist/types.d.ts",
       "default": "./dist/types.js"
+    },
+    "./diagnostics": {
+      "types": "./dist/manifest-diagnostics.d.ts",
+      "default": "./dist/manifest-diagnostics.js"
     }
   },
   "files": [