@describe-me/core 0.5.0 → 0.5.2

package/README.md

@@ -14,6 +14,9 @@ Most people never install this package directly — `@describe-me/react` and
 pnpm add -D @describe-me/core
 ```
 
+All describe-me packages must be on the same version
+([Add it to your project](https://github.com/grzehub/describe-me#add-it-to-your-project)).
+
 ## Usage
 
 `step()` names a phase of a test. The DOM is captured after the body resolves,

package/dist/manifest-diagnostics.d.ts

@@ -1,8 +1,9 @@
 import { type Manifest, type ManifestDiagnostics } from './types.js';
 /**
  * List what the manifest could not document: anonymous components, named ones
- * without props, assets that will not load, font families that nothing loads
- * and hosts that frames load stylesheets from. The reporter prints it after a
- * run and the viewer shows it in the header, so both agree on what is missing.
+ * without props, assets that will not load, font families that nothing loads,
+ * hosts that frames load stylesheets from and problems in the project's setup.
+ * 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

@@ -5,9 +5,10 @@ function isHostElement(name) {
 }
 /**
  * List what the manifest could not document: anonymous components, named ones
- * without props, assets that will not load, font families that nothing loads
- * and hosts that frames load stylesheets from. The reporter prints it after a
- * run and the viewer shows it in the header, so both agree on what is missing.
+ * without props, assets that will not load, font families that nothing loads,
+ * hosts that frames load stylesheets from and problems in the project's setup.
+ * 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 = [];
@@ -33,5 +34,6 @@ export function manifestDiagnostics(manifest) {
         assetsMissing: manifest.assetsMissing ?? [],
         fontsMissing: manifest.fontsMissing ?? [],
         remoteStylesheets: manifest.remoteStylesheets ?? [],
+        setupWarnings: manifest.setupWarnings ?? [],
     };
 }

package/dist/recorder.d.ts

@@ -7,12 +7,15 @@ type Teardown = () => void;
  * `beforeInteraction()`, `setComponent()` and `onTeardown()`.
  */
 declare class Recorder {
+    /** Which contract this recorder follows, so another copy of core can refuse it. */
+    readonly protocol = 2;
     private slots;
     private currentGeneration;
     private inFlight;
     private deferred;
     private pending;
     private renderFrame;
+    private aroundWait;
     private component?;
     private startedAt;
     private active;
@@ -26,9 +29,10 @@ declare class Recorder {
      */
     get generation(): number;
     /**
-     * Choose when the render frame is taken, from the next render capture on.
-     * The setup files call it with the plugin's options. An invalid `pending`
-     * selector throws.
+     * Choose when the render frame is taken, from the next render capture on,
+     * and what runs around each wait. The setup files call it with the plugin's
+     * options. A `pending` selector the DOM rejects falls back to `'lazy'` with
+     * a warning.
      */
     configure(options: RecorderOptions): void;
     /**
@@ -62,6 +66,7 @@ declare class Recorder {
      */
     private defer;
     private clearDeferred;
+    private waitToSettle;
     private settleThenFill;
     private fill;
 }

package/dist/recorder.js

@@ -5,16 +5,18 @@ import { realTimers } from './real-timers.js';
 import { serializeDocument } from './serialize-document.js';
 import { settle } from './settle.js';
 import { ANONYMOUS_COMPONENT, } from './types.js';
-/** Fails in the setup file rather than in the first test that renders. */
-function assertValidSelector(selector) {
-    if (typeof document === 'undefined') {
-        return;
-    }
+/**
+ * Bump it whenever the contract between the recorder and the adapters or setup
+ * files changes: a method or property added, removed or changed in meaning.
+ */
+const RECORDER_PROTOCOL = 2;
+function isValidSelector(selector) {
     try {
         document.querySelector(selector);
+        return true;
     }
     catch {
-        throw new Error(`describe-me: renderFrame.pending is not a valid CSS selector: "${selector}"`);
+        return false;
     }
 }
 /**
@@ -24,6 +26,8 @@ function assertValidSelector(selector) {
  * `beforeInteraction()`, `setComponent()` and `onTeardown()`.
  */
 class Recorder {
+    /** Which contract this recorder follows, so another copy of core can refuse it. */
+    protocol = RECORDER_PROTOCOL;
     // One per capture, in call order, so a frame sits where it was asked for.
     slots = [];
     currentGeneration = 0;
@@ -32,6 +36,7 @@ class Recorder {
     deferred = null;
     pending = null;
     renderFrame = 'eager';
+    aroundWait = (wait) => wait();
     component;
     startedAt = 0;
     active = false;
@@ -59,14 +64,22 @@ class Recorder {
         return this.currentGeneration;
     }
     /**
-     * Choose when the render frame is taken, from the next render capture on.
-     * The setup files call it with the plugin's options. An invalid `pending`
-     * selector throws.
+     * Choose when the render frame is taken, from the next render capture on,
+     * and what runs around each wait. The setup files call it with the plugin's
+     * options. A `pending` selector the DOM rejects falls back to `'lazy'` with
+     * a warning.
      */
     configure(options) {
         const renderFrame = options.renderFrame ?? 'eager';
-        if (typeof renderFrame === 'object') {
-            assertValidSelector(renderFrame.pending);
+        if (options.aroundWait !== undefined) {
+            this.aroundWait = options.aroundWait;
+        }
+        if (typeof renderFrame === 'object' &&
+            typeof document !== 'undefined' &&
+            !isValidSelector(renderFrame.pending)) {
+            console.warn(`describe-me: renderFrame.pending is not a valid CSS selector: "${renderFrame.pending}". Render frames fall back to 'lazy'.`);
+            this.renderFrame = 'lazy';
+            return;
         }
         this.renderFrame = renderFrame;
     }
@@ -149,7 +162,7 @@ class Recorder {
             return false;
         }
         const generation = this.currentGeneration;
-        await settle();
+        await this.waitToSettle();
         // The test ended, or an interaction took the frame, while this settled.
         if (generation !== this.currentGeneration || this.deferred !== slot) {
             return false;
@@ -207,8 +220,13 @@ class Recorder {
         this.pending?.dispose();
         this.pending = null;
     }
+    // Only the wait runs inside `aroundWait`, so whatever the wrapper changes is
+    // undone before the snapshot and the teardown.
+    waitToSettle() {
+        return this.aroundWait(settle);
+    }
     async settleThenFill(slot, generation) {
-        await settle();
+        await this.waitToSettle();
         if (generation === this.currentGeneration) {
             this.fill(slot);
         }
@@ -227,6 +245,21 @@ class Recorder {
     }
 }
 const RECORDER_KEY = Symbol.for('describe-me.recorder');
+function protocolOf(existing) {
+    if (typeof existing !== 'object' || existing === null) {
+        return undefined;
+    }
+    const candidate = existing;
+    if (typeof candidate.protocol === 'number') {
+        return candidate.protocol;
+    }
+    // 0.5.0 did not stamp its recorder. It is the first version with `flush()`,
+    // and its contract is protocol 1.
+    if (typeof candidate.flush === 'function') {
+        return 1;
+    }
+    return undefined;
+}
 /**
  * The adapter and the setup file may receive two copies of this module: Vite
  * pre-bundles the adapter together with its own copy of core, while a linked
@@ -237,7 +270,16 @@ const RECORDER_KEY = Symbol.for('describe-me.recorder');
  */
 function sharedRecorder() {
     const scope = globalThis;
-    scope[RECORDER_KEY] ??= new Recorder();
-    return scope[RECORDER_KEY];
+    const existing = scope[RECORDER_KEY];
+    if (existing === undefined) {
+        const created = new Recorder();
+        scope[RECORDER_KEY] = created;
+        return created;
+    }
+    const found = protocolOf(existing);
+    if (found !== RECORDER_PROTOCOL) {
+        throw new Error(`describe-me: all describe-me packages must be on the same version. Another copy of @describe-me/core created the test recorder (protocol ${found ?? 'none'}, expected ${RECORDER_PROTOCOL}). Install @describe-me/core, @describe-me/react, @describe-me/vitest and describe-me at one version.`);
+    }
+    return existing;
 }
 export const recorder = sharedRecorder();

package/dist/types.d.ts

@@ -49,10 +49,18 @@ export type RenderFrameMode = 'eager' | 'lazy' | {
     pending: string;
     timeout?: number;
 };
+/** Runs one wait of the recorder. It must call `wait` once and resolve after it. */
+export type AroundWait = (wait: () => Promise<void>) => Promise<void>;
 /** Options for `recorder.configure()`. */
 export interface RecorderOptions {
     /** When the render frame is taken. Default: `'eager'`. */
     renderFrame?: RenderFrameMode;
+    /**
+     * Runs each wait of the recorder. It is kept when omitted, so a later
+     * `configure({ renderFrame })` keeps the setup file's wrapper. By default
+     * it runs `wait` as is.
+     */
+    aroundWait?: AroundWait;
 }
 /** Options for `recorder.capture()`. */
 export interface CaptureOptions {
@@ -157,8 +165,17 @@ export interface ComponentDoc {
     file: string;
     props: PropDoc[];
 }
+/** The package that wrote a manifest. */
+export interface ManifestGenerator {
+    /** The package name, e.g. `@describe-me/vitest`. */
+    name: string;
+    /** Its version, e.g. `0.5.1`. */
+    version: string;
+}
 export interface Manifest {
     version: 1;
+    /** The package and version that wrote the manifest. Absent in manifests written before 0.5.1. */
+    generator?: ManifestGenerator;
     generatedAt: string;
     root: string;
     modules: ManifestModule[];
@@ -186,6 +203,12 @@ export interface Manifest {
      * manifests written before 0.5, which counts as empty.
      */
     remoteStylesheets?: RemoteStylesheet[];
+    /**
+     * Problems the plugin found in the project's setup, one sentence each.
+     * Absent when there are none and in manifests written before 0.5.1, which
+     * counts as empty.
+     */
+    setupWarnings?: string[];
 }
 /** A font family that the captured CSS uses but no `@font-face`, font stylesheet or preview head loads. */
 export interface FontMissing {
@@ -223,4 +246,6 @@ export interface ManifestDiagnostics {
     fontsMissing: FontMissing[];
     /** Hosts that frames load stylesheets from. */
     remoteStylesheets: RemoteStylesheet[];
+    /** Problems in the project's setup that can make tests fail. */
+    setupWarnings: string[];
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@describe-me/core",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "Recorder and manifest types for describe-me: living component docs from your tests",
   "keywords": [
     "vitest",