@describe-me/core 0.5.0-next.1 → 0.5.0-next.2

package/README.md

@@ -28,6 +28,12 @@ await step('open the menu', () => screen.getByRole('button', { name: 'Menu' }).c
 `elementLabel()` names a DOM element the way frame labels do, e.g.
 `button "Save"`, for adapters that record their own interactions.
 
+Such adapters call `recorder.beforeInteraction()` before they change the page,
+so a deferred render frame is taken first. As the capture's `generation`, they
+pass `recorder.generation`, read when the interaction began, so a capture that
+outlives its test is dropped. `recorder.flush()` waits for the captures in
+flight and takes a deferred render frame.
+
 The manifest types live in `@describe-me/core/types`, for tools that want to
 read `.describe-me/manifest.json` themselves. Stored snapshots point into
 `assets/` and `styles/` through `ASSET_URL_PREFIX` and `STYLE_URL_PREFIX`

package/dist/compact-frames.d.ts

@@ -0,0 +1,19 @@
+import type { Frame, FrameKind } from './types.js';
+/**
+ * The place of one `capture()` call among the test's frames, reserved when it
+ * is called. Unfilled while `snapshot` is undefined.
+ */
+export interface FrameSlot {
+    kind: FrameKind;
+    label: string;
+    meta?: Record<string, unknown>;
+    at?: number;
+    snapshot?: string;
+}
+/**
+ * The frames a test hands over, in the order their captures were called.
+ * Unfilled slots are left out. A closing frame equal to the frame before it
+ * is dropped, and a step equal to the frame before it names that frame
+ * instead. The slots are left unchanged.
+ */
+export declare function compactFrames(slots: readonly FrameSlot[]): Frame[];

package/dist/compact-frames.js

@@ -0,0 +1,38 @@
+/**
+ * The frames a test hands over, in the order their captures were called.
+ * Unfilled slots are left out. A closing frame equal to the frame before it
+ * is dropped, and a step equal to the frame before it names that frame
+ * instead. The slots are left unchanged.
+ */
+export function compactFrames(slots) {
+    const kept = [];
+    for (const slot of slots) {
+        const last = kept.at(-1);
+        // The test went on after `cleanup()`, so its closing frame names the state before it.
+        if (slot.kind !== 'end' && last?.kind === 'end') {
+            last.kind = 'step';
+            last.label = 'before cleanup()';
+        }
+        if (slot.snapshot === undefined) {
+            continue;
+        }
+        if (slot.kind === 'end' && last?.snapshot === slot.snapshot) {
+            continue;
+        }
+        // A step whose body already produced this exact DOM (e.g. via an action) just names that frame.
+        if (slot.kind === 'step' && last?.snapshot === slot.snapshot) {
+            last.label = `${slot.label} · ${last.label}`;
+            last.kind = 'step';
+            continue;
+        }
+        kept.push({
+            id: `f${kept.length}`,
+            kind: slot.kind,
+            label: slot.label,
+            at: slot.at ?? 0,
+            meta: slot.meta,
+            snapshot: slot.snapshot,
+        });
+    }
+    return kept;
+}

package/dist/pending-render.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Watches the page while a render frame waits for its loader to go, and calls
+ * `onReady` once nothing matches `selector` and the page shows content. After
+ * `timeout` ms it stops watching and leaves the frame deferred, so the next
+ * interaction or the end of the test takes it.
+ */
+export declare class PendingRender {
+    private observer;
+    private timer;
+    constructor(selector: string, timeout: number | undefined, onReady: () => void);
+    /**
+     * Whether the frame can be taken: nothing matches `selector` and the page
+     * shows content. The selector goes first, because it is cheap while the
+     * loader is shown.
+     */
+    static isReady(selector: string): boolean;
+    /** Stop watching. Safe to call twice. */
+    dispose(): void;
+}

package/dist/pending-render.js

@@ -0,0 +1,51 @@
+import { pageHasContent } from './page-has-content.js';
+import { realTimers } from './real-timers.js';
+/**
+ * How long to watch for the loader to go, in ms of real time. After that the
+ * frame waits as in `'lazy'`.
+ */
+const DEFAULT_TIMEOUT = 2000;
+const WATCHED = {
+    childList: true,
+    subtree: true,
+    attributes: true,
+    characterData: true,
+};
+/**
+ * Watches the page while a render frame waits for its loader to go, and calls
+ * `onReady` once nothing matches `selector` and the page shows content. After
+ * `timeout` ms it stops watching and leaves the frame deferred, so the next
+ * interaction or the end of the test takes it.
+ */
+export class PendingRender {
+    observer;
+    timer;
+    constructor(selector, timeout, onReady) {
+        this.observer = new MutationObserver(() => {
+            if (!PendingRender.isReady(selector)) {
+                return;
+            }
+            this.dispose();
+            onReady();
+        });
+        this.observer.observe(document, WATCHED);
+        this.timer = realTimers.setTimeout(() => this.dispose(), timeout ?? DEFAULT_TIMEOUT);
+    }
+    /**
+     * Whether the frame can be taken: nothing matches `selector` and the page
+     * shows content. The selector goes first, because it is cheap while the
+     * loader is shown.
+     */
+    static isReady(selector) {
+        return document.querySelector(selector) === null && pageHasContent();
+    }
+    /** Stop watching. Safe to call twice. */
+    dispose() {
+        this.observer?.disconnect();
+        this.observer = null;
+        if (this.timer !== null) {
+            realTimers.clearTimeout(this.timer);
+            this.timer = null;
+        }
+    }
+}

package/dist/real-timers.d.ts

@@ -1,8 +1,10 @@
 /**
- * `setTimeout` and `performance.now()` as they were before any test faked
- * them, so `vi.useFakeTimers()` neither hangs a capture nor skews frame times.
+ * `setTimeout`, `clearTimeout` and `performance.now()` as they were before any
+ * test faked them, so `vi.useFakeTimers()` neither hangs a capture nor skews
+ * frame times.
  */
 export declare const realTimers: {
     setTimeout: typeof setTimeout;
+    clearTimeout: typeof clearTimeout;
     now: () => number;
 };

package/dist/real-timers.js

@@ -3,6 +3,11 @@ function originalSetTimeout() {
     const current = globalThis.setTimeout;
     return current.clock ? current.clock._setTimeout : current;
 }
+/** The global `clearTimeout`, unwrapped the same way. A faked one would not clear a real timer. */
+function originalClearTimeout() {
+    const current = globalThis.clearTimeout;
+    return current.clock ? current.clock._clearTimeout : current;
+}
 /** The global `performance`, unwrapped the same way. */
 function originalPerformance() {
     const current = globalThis.performance;
@@ -11,13 +16,16 @@ function originalPerformance() {
 // Bound, because browsers throw "Illegal invocation" when `setTimeout` is
 // called without its global as `this`.
 const setTimeoutAtLoad = originalSetTimeout().bind(globalThis);
+const clearTimeoutAtLoad = originalClearTimeout().bind(globalThis);
 // Fake timers replace `performance` as a whole object, so this reference stays real.
 const performanceAtLoad = originalPerformance();
 /**
- * `setTimeout` and `performance.now()` as they were before any test faked
- * them, so `vi.useFakeTimers()` neither hangs a capture nor skews frame times.
+ * `setTimeout`, `clearTimeout` and `performance.now()` as they were before any
+ * test faked them, so `vi.useFakeTimers()` neither hangs a capture nor skews
+ * frame times.
  */
 export const realTimers = {
     setTimeout: setTimeoutAtLoad,
+    clearTimeout: clearTimeoutAtLoad,
     now: () => performanceAtLoad.now(),
 };

package/dist/recorder.d.ts

@@ -1,25 +1,48 @@
-import type { CaptureOptions, ComponentInfo, FrameKind, TestRecord } from './types.js';
+import type { CaptureOptions, ComponentInfo, FrameKind, RecorderOptions, TestRecord } from './types.js';
 type Teardown = () => void;
 /**
  * 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()`.
+ * or jsdom. `begin()` in beforeEach. `flush()`, the closing capture, `end()`
+ * then `teardown()` in afterEach. Framework adapters call `capture()`,
+ * `beforeInteraction()`, `setComponent()` and `onTeardown()`.
  */
 declare class Recorder {
-    private frames;
+    private slots;
+    private currentGeneration;
+    private inFlight;
+    private deferred;
+    private pending;
+    private renderFrame;
     private component?;
     private startedAt;
     private active;
     private closed;
-    private lastJson;
-    private seq;
     private teardowns;
     begin(): void;
     get isActive(): boolean;
+    /**
+     * Changes with every test. An interaction reads it when it begins and hands
+     * it to `capture()`.
+     */
+    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.
+     */
+    configure(options: RecorderOptions): void;
     setComponent(info: ComponentInfo): void;
     capture(kind: FrameKind, label: string, meta?: Record<string, unknown>, options?: CaptureOptions): Promise<void>;
-    /** The test went on after `cleanup()`, so the closing frame it took names the state before it. */
-    private reopen;
+    /**
+     * Take a deferred render frame now. Adapters call it before an interaction
+     * changes the page: an event, a `step()` body, another render, an unmount.
+     */
+    beforeInteraction(): void;
+    /**
+     * Wait for the captures in flight, then take a deferred render frame after
+     * one settle. Resolves to whether it took a deferred render frame.
+     */
+    flush(): Promise<boolean>;
     end(): TestRecord;
     /**
      * Register work that must run after the test's frames are handed over, such
@@ -29,6 +52,14 @@ declare class Recorder {
     onTeardown(callback: Teardown): void;
     /** Run the registered teardowns. Called by the runner integration after `end()`. */
     teardown(): void;
+    /**
+     * Hold the render frame back until `mode` allows it. `capture()` already
+     * took any earlier one.
+     */
+    private defer;
+    private clearDeferred;
+    private settleThenFill;
+    private fill;
 }
 export declare const recorder: Recorder;
 export {};

package/dist/recorder.js

@@ -1,34 +1,74 @@
+import { compactFrames } from './compact-frames.js';
 import { pageHasContent } from './page-has-content.js';
+import { PendingRender } from './pending-render.js';
 import { realTimers } from './real-timers.js';
 import { serializeDocument } from './serialize-document.js';
 import { settle } from './settle.js';
+/** Fails in the setup file rather than in the first test that renders. */
+function assertValidSelector(selector) {
+    if (typeof document === 'undefined') {
+        return;
+    }
+    try {
+        document.querySelector(selector);
+    }
+    catch {
+        throw new Error(`describe-me: renderFrame.pending is not a valid CSS selector: "${selector}"`);
+    }
+}
 /**
  * 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()`.
+ * or jsdom. `begin()` in beforeEach. `flush()`, the closing capture, `end()`
+ * then `teardown()` in afterEach. Framework adapters call `capture()`,
+ * `beforeInteraction()`, `setComponent()` and `onTeardown()`.
  */
 class Recorder {
-    frames = [];
+    // One per capture, in call order, so a frame sits where it was asked for.
+    slots = [];
+    currentGeneration = 0;
+    inFlight = new Set();
+    // The render frame `renderFrame` holds back, until an interaction or `flush()` takes it.
+    deferred = null;
+    pending = null;
+    renderFrame = 'eager';
     component;
     startedAt = 0;
     active = false;
     // Once `cleanup()` or the setup file took the closing frame, a second one is skipped.
     closed = false;
-    lastJson = '';
-    seq = 0;
     teardowns = new Set();
     begin() {
-        this.frames = [];
+        this.currentGeneration++;
+        this.slots = [];
+        this.inFlight.clear();
+        this.clearDeferred();
         this.component = undefined;
         this.startedAt = realTimers.now();
         this.active = true;
         this.closed = false;
-        this.lastJson = '';
-        this.seq = 0;
     }
     get isActive() {
         return this.active;
     }
+    /**
+     * Changes with every test. An interaction reads it when it begins and hands
+     * it to `capture()`.
+     */
+    get generation() {
+        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.
+     */
+    configure(options) {
+        const renderFrame = options.renderFrame ?? 'eager';
+        if (typeof renderFrame === 'object') {
+            assertValidSelector(renderFrame.pending);
+        }
+        this.renderFrame = renderFrame;
+    }
     setComponent(info) {
         if (!this.component) {
             this.component = info;
@@ -38,62 +78,85 @@ class Recorder {
         if (!this.active) {
             return;
         }
-        if (kind !== 'end' && this.closed) {
-            this.reopen();
-        }
-        if (kind === 'end' && (this.frames.length === 0 || this.closed)) {
+        const generation = options.generation ?? this.currentGeneration;
+        // The interaction began in a test that has ended.
+        if (generation !== this.currentGeneration) {
             return;
         }
-        if (options.settle !== false) {
-            await settle();
+        // A call site that forgot `beforeInteraction()` still gets its render frame here.
+        this.beforeInteraction();
+        if (kind !== 'end') {
+            this.closed = false;
+        }
+        // Before any `await`, so a test that recorded nothing costs nothing.
+        if (kind === 'end' && (this.slots.length === 0 || this.closed)) {
+            return;
         }
         if (kind === 'end') {
             this.closed = true;
-            // After `cleanup()` or `unmount()` there is nothing left to show.
-            if (!pageHasContent()) {
-                return;
-            }
         }
-        const json = serializeDocument();
-        if (json === null) {
+        const slot = { kind, label, meta };
+        this.slots.push(slot);
+        if (kind === 'render' && this.renderFrame !== 'eager') {
+            this.defer(slot, this.renderFrame);
             return;
         }
-        // The closing frame is only interesting if something changed since the last one.
-        if (kind === 'end' && json === this.lastJson) {
+        // Filled before `capture()` returns: Testing Library frames depend on it.
+        if (options.settle === false) {
+            this.fill(slot);
             return;
         }
-        // A step whose body already produced this exact DOM (e.g. via an action) just names that frame.
-        if (kind === 'step' && json === this.lastJson && this.frames.length) {
-            const last = this.frames[this.frames.length - 1];
-            last.label = `${label} · ${last.label}`;
-            last.kind = 'step';
+        const filling = this.settleThenFill(slot, generation);
+        this.inFlight.add(filling);
+        try {
+            await filling;
+        }
+        finally {
+            this.inFlight.delete(filling);
+        }
+    }
+    /**
+     * Take a deferred render frame now. Adapters call it before an interaction
+     * changes the page: an event, a `step()` body, another render, an unmount.
+     */
+    beforeInteraction() {
+        const slot = this.deferred;
+        if (slot === null) {
             return;
         }
-        this.lastJson = json;
-        this.frames.push({
-            id: `f${this.seq++}`,
-            kind,
-            label,
-            at: Math.round(realTimers.now() - this.startedAt),
-            meta,
-            snapshot: json,
-        });
-    }
-    /** The test went on after `cleanup()`, so the closing frame it took names the state before it. */
-    reopen() {
-        this.closed = false;
-        const last = this.frames[this.frames.length - 1];
-        if (last?.kind === 'end') {
-            last.kind = 'step';
-            last.label = 'before cleanup()';
+        this.clearDeferred();
+        this.fill(slot);
+    }
+    /**
+     * Wait for the captures in flight, then take a deferred render frame after
+     * one settle. Resolves to whether it took a deferred render frame.
+     */
+    async flush() {
+        while (this.inFlight.size > 0) {
+            await Promise.allSettled(this.inFlight);
+        }
+        const slot = this.deferred;
+        // Nothing to settle for, so empty and eager tests stay free.
+        if (slot === null) {
+            return false;
         }
+        const generation = this.currentGeneration;
+        await settle();
+        // The test ended, or an interaction took the frame, while this settled.
+        if (generation !== this.currentGeneration || this.deferred !== slot) {
+            return false;
+        }
+        this.beforeInteraction();
+        return true;
     }
     end() {
         this.active = false;
+        this.currentGeneration++;
+        this.clearDeferred();
         // 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,
+            frames: compactFrames(this.slots),
             component: this.component,
             origin: globalThis.location?.origin,
         };
@@ -112,6 +175,48 @@ class Recorder {
             callback();
         }
     }
+    /**
+     * Hold the render frame back until `mode` allows it. `capture()` already
+     * took any earlier one.
+     */
+    defer(slot, mode) {
+        if (mode === 'lazy') {
+            this.deferred = slot;
+            return;
+        }
+        if (PendingRender.isReady(mode.pending)) {
+            this.fill(slot);
+            return;
+        }
+        this.deferred = slot;
+        // Without an observer the frame waits like in lazy mode.
+        if (typeof MutationObserver !== 'undefined') {
+            this.pending = new PendingRender(mode.pending, mode.timeout, () => this.beforeInteraction());
+        }
+    }
+    clearDeferred() {
+        this.deferred = null;
+        this.pending?.dispose();
+        this.pending = null;
+    }
+    async settleThenFill(slot, generation) {
+        await settle();
+        if (generation === this.currentGeneration) {
+            this.fill(slot);
+        }
+    }
+    fill(slot) {
+        // After `cleanup()` or `unmount()` there is nothing left to show.
+        if (slot.kind === 'end' && !pageHasContent()) {
+            return;
+        }
+        const snapshot = serializeDocument();
+        if (snapshot === null) {
+            return;
+        }
+        slot.snapshot = snapshot;
+        slot.at = Math.round(realTimers.now() - this.startedAt);
+    }
 }
 const RECORDER_KEY = Symbol.for('describe-me.recorder');
 /**

package/dist/step.js

@@ -1,7 +1,9 @@
 import { recorder } from './recorder.js';
 /** Name a phase of the test. The DOM is captured after `fn` resolves. */
 export async function step(label, fn) {
+    const generation = recorder.generation;
+    recorder.beforeInteraction();
     const result = await fn();
-    await recorder.capture('step', label);
+    await recorder.capture('step', label, undefined, { generation });
     return result;
 }

package/dist/types.d.ts

@@ -38,6 +38,22 @@ export declare const ASSET_URL_PREFIX: "describe-me-asset:";
  * the viewer joins them back in order before replaying.
  */
 export declare const STYLE_URL_PREFIX: "describe-me-style:";
+/**
+ * When the render frame is taken. `'eager'`: right after mount. `'lazy'`:
+ * right before the test's next interaction, or at the end of the test.
+ * `{ pending, timeout }`: as soon as nothing matches the CSS selector
+ * `pending` and the page shows content, falling back to `'lazy'` after
+ * `timeout` ms (default 2000) or at an earlier interaction.
+ */
+export type RenderFrameMode = 'eager' | 'lazy' | {
+    pending: string;
+    timeout?: number;
+};
+/** Options for `recorder.configure()`. */
+export interface RecorderOptions {
+    /** When the render frame is taken. Default: `'eager'`. */
+    renderFrame?: RenderFrameMode;
+}
 /** Options for `recorder.capture()`. */
 export interface CaptureOptions {
     /**
@@ -45,16 +61,22 @@ export interface CaptureOptions {
      * 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 and the frame recorded before `capture()`
-     * returns, so the caller can move on without awaiting it.
+     * returns, so the caller can move on without awaiting it. Render frames
+     * follow `renderFrame` (see `RecorderOptions`), which may defer them.
      */
     settle?: boolean;
+    /**
+     * `recorder.generation` as read when the interaction began. A capture from
+     * an earlier test is dropped. Default: the current generation.
+     */
+    generation?: number;
 }
 /** A frame as captured by the recorder. `snapshot` is the DOM, already serialized to JSON. */
 export interface Frame {
     id: string;
     kind: FrameKind;
     label: string;
-    /** ms since the test began */
+    /** when the snapshot was taken, in ms since the test began */
     at: number;
     meta?: Record<string, unknown>;
     /** rrweb serialized document, as JSON text */

package/package.json

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