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

package/README.md

@@ -61,6 +61,11 @@ font links that the app shell loads and tests never do. It never reaches the
 test page, and the local files it links are copied into the output directory
 ([Fonts](https://github.com/grzehub/describe-me#fonts) in the root README).
 
+`describeMe({ renderFrame })` chooses when the render frame is taken:
+`'eager'` (default) right after mount, `'lazy'` right before the next
+interaction, or `{ pending: '<selector>' }` once a loader is gone. See
+[Render frame timing](https://github.com/grzehub/describe-me#render-frame-timing).
+
 The pieces can also be wired by hand. Tests then import from the adapter
 themselves: `render` from `@describe-me/react` in browser mode, and `render`,
 `fireEvent` and `cleanup` from `@describe-me/react/testing-library` in jsdom:

package/dist/plugin.d.ts

@@ -1,4 +1,5 @@
 import type { ViteUserConfig } from 'vitest/config';
+import type { RenderFrameMode } from '@describe-me/core/types';
 /** Where the tests run: Vitest browser mode, or a simulated DOM such as jsdom. */
 export type DescribeMeEnvironment = 'browser' | 'dom';
 export interface DescribeMeOptions {
@@ -41,6 +42,12 @@ export interface DescribeMeOptions {
      * Project files it links are copied into the output directory. Default: none.
      */
     previewHead?: string;
+    /**
+     * When the render frame is taken: `'eager'` right after mount, `'lazy'`
+     * before the next interaction, `{ pending }` once nothing matches the
+     * selector. Default: `'eager'`.
+     */
+    renderFrame?: RenderFrameMode;
 }
 type VitePlugin = NonNullable<ViteUserConfig['plugins']>[number];
 /**

package/dist/plugin.js

@@ -5,6 +5,7 @@ import { registerExports } from './register-exports.js';
 import DescribeMeReporter from './reporter.js';
 import { RUNTIME_OPTIONS_KEY } from './runtime-options.js';
 import { styledComponentsBrowserBuild } from './styled-components-browser-build.js';
+import { validateRenderFrame } from './validate-render-frame.js';
 /** For each framework and environment: the render module tests import, and our adapter that wraps it. */
 const RENDER_MODULES = {
     react: {
@@ -101,11 +102,12 @@ export function describeMe(options = {}) {
             }
             const environment = options.environment ?? detectEnvironment(userConfig);
             renderModule = RENDER_MODULES[framework][environment];
-            // Compiled here, so invalid globs fail before any test runs. Vite
+            // Checked here, so invalid options fail before any test runs. Vite
             // deep-merges `provide`, so the user's own keys survive.
             const runtimeOptions = {
                 include: compileGlobs(options.include),
                 exclude: compileGlobs(options.exclude),
+                renderFrame: validateRenderFrame(options.renderFrame),
             };
             const provide = { [RUNTIME_OPTIONS_KEY]: runtimeOptions };
             const reporter = new DescribeMeReporter({

package/dist/read-runtime-options.js

@@ -2,5 +2,9 @@ import { inject } from 'vitest';
 import { RUNTIME_OPTIONS_KEY } from './runtime-options.js';
 /** Without the plugin nothing is provided, so a hand-wired setup keeps recording every test. */
 export function readRuntimeOptions() {
-    return inject(RUNTIME_OPTIONS_KEY) ?? { include: [], exclude: [] };
+    return (inject(RUNTIME_OPTIONS_KEY) ?? {
+        include: [],
+        exclude: [],
+        renderFrame: 'eager',
+    });
 }

package/dist/record-action.js

@@ -1,22 +1,32 @@
 import { recorder } from '@describe-me/core';
 /**
- * Nesting depth of interactions currently in flight. `userEvent.click(el)`
- * delegates to `locator.click()`, and `copy()` delegates to `keyboard()`, so
- * without this guard one gesture would produce two frames.
+ * Nesting depth of the interactions in flight, and the test they started in.
+ * `userEvent.click(el)` delegates to `locator.click()`, and `copy()` delegates
+ * to `keyboard()`, so without this guard one gesture would produce two
+ * frames. Keyed to the recorder's generation, so an interaction that an ended
+ * test left running cannot swallow the next test's frame.
  */
-let depth = 0;
+const nesting = { generation: -1, depth: 0 };
 /** Run one user interaction and record a frame for it, but only for the outermost call. */
 export async function recordAction(label, run) {
-    depth++;
+    const generation = recorder.generation;
+    if (generation !== nesting.generation) {
+        nesting.generation = generation;
+        nesting.depth = 0;
+    }
+    recorder.beforeInteraction();
+    nesting.depth++;
     let result;
     try {
         result = await run();
     }
     finally {
-        depth--;
+        if (generation === nesting.generation) {
+            nesting.depth--;
+        }
     }
-    if (depth === 0) {
-        await recorder.capture('action', label);
+    if (generation === nesting.generation && nesting.depth === 0) {
+        await recorder.capture('action', label, undefined, { generation });
     }
     return result;
 }

package/dist/register-recording-hooks.d.ts

@@ -1,9 +1,10 @@
 import type { RuntimeOptions } from './runtime-options.js';
 /**
  * The per-test lifecycle shared by every environment: begin a recording, take
- * the closing frame, hand the frames to the reporter via task.meta, and only
- * then let adapters unmount. Teardown runs for unrecorded tests too, because
- * Testing Library's auto-cleanup is off in jsdom. Concurrent tests would share
- * the one recorder, so they are not recorded.
+ * a deferred render frame or else the closing frame, hand the frames to the
+ * reporter via task.meta, and only then let adapters unmount. Teardown runs
+ * for unrecorded tests too, because Testing Library's auto-cleanup is off in
+ * jsdom. Concurrent tests would share the one recorder, so they are not
+ * recorded.
  */
 export declare function registerRecordingHooks(options: RuntimeOptions): void;

package/dist/register-recording-hooks.js

@@ -3,14 +3,16 @@ import { META_KEY, recorder } from '@describe-me/core';
 import { fileFilter } from './file-filter.js';
 /**
  * The per-test lifecycle shared by every environment: begin a recording, take
- * the closing frame, hand the frames to the reporter via task.meta, and only
- * then let adapters unmount. Teardown runs for unrecorded tests too, because
- * Testing Library's auto-cleanup is off in jsdom. Concurrent tests would share
- * the one recorder, so they are not recorded.
+ * a deferred render frame or else the closing frame, hand the frames to the
+ * reporter via task.meta, and only then let adapters unmount. Teardown runs
+ * for unrecorded tests too, because Testing Library's auto-cleanup is off in
+ * jsdom. Concurrent tests would share the one recorder, so they are not
+ * recorded.
  */
 export function registerRecordingHooks(options) {
     const isRecordedFile = fileFilter(options);
     let warnedConcurrent = false;
+    recorder.configure({ renderFrame: options.renderFrame });
     beforeEach((context) => {
         if (context.task.concurrent) {
             if (!warnedConcurrent) {
@@ -26,7 +28,11 @@ export function registerRecordingHooks(options) {
     afterEach(async (context) => {
         try {
             if (recorder.isActive) {
-                await recorder.capture('end', 'end of test');
+                const tookRender = await recorder.flush();
+                // A render frame taken this late already shows how the test ended.
+                if (!tookRender) {
+                    await recorder.capture('end', 'end of test');
+                }
                 const record = recorder.end();
                 if (record.frames.length > 0) {
                     ;

package/dist/runtime-options.d.ts

@@ -2,8 +2,9 @@
  * Travels from the plugin to the setup files through Vitest's `provide` /
  * `inject`. Keep it plain JSON: the browser receives it serialized, so a
  * RegExp would not survive. The test runtime imports this file, so it imports
- * nothing itself.
+ * only types.
  */
+import type { RenderFrameMode } from '@describe-me/core/types';
 export interface CompiledGlob {
     source: string;
     flags: string;
@@ -13,6 +14,7 @@ export interface RuntimeOptions {
     include: CompiledGlob[];
     /** Wins over `include`. */
     exclude: CompiledGlob[];
+    renderFrame: RenderFrameMode;
 }
 export declare const RUNTIME_OPTIONS_KEY: "describe-me";
 declare module 'vitest' {

package/dist/runtime-options.js

@@ -2,6 +2,6 @@
  * Travels from the plugin to the setup files through Vitest's `provide` /
  * `inject`. Keep it plain JSON: the browser receives it serialized, so a
  * RegExp would not survive. The test runtime imports this file, so it imports
- * nothing itself.
+ * only types.
  */
 export const RUNTIME_OPTIONS_KEY = 'describe-me';

package/dist/setup-dom.js

@@ -3,8 +3,9 @@
  * `setupFiles: ['@describe-me/vitest/setup-dom']`. Patches Testing Library's
  * userEvent, when it is installed, so every interaction records a frame, sets
  * React's act flag where Testing Library would, and registers the recording
- * hooks. Which test files are recorded (`include` / `exclude`) comes from the
- * plugin. Never imports `vitest/browser`, which only exists in browser mode.
+ * hooks. Which test files are recorded (`include` / `exclude`) and when the
+ * render frame is taken (`renderFrame`) come from the plugin. Never imports
+ * `vitest/browser`, which only exists in browser mode.
  */
 import { mirrorReactActEnvironment } from './mirror-react-act-environment.js';
 import { patchTestingLibraryUserEvent } from './patch-testing-library-user-event.js';

package/dist/setup.js

@@ -2,7 +2,8 @@
  * Vitest setup file for browser mode: `setupFiles: ['@describe-me/vitest/setup']`.
  * Patches Vitest's locators and userEvent so every interaction records a
  * frame, and registers the recording hooks. Which test files are recorded
- * (`include` / `exclude`) comes from the plugin. For jsdom use `./setup-dom`.
+ * (`include` / `exclude`) and when the render frame is taken (`renderFrame`)
+ * come from the plugin. For jsdom use `./setup-dom`.
  */
 import { patchLocators } from './patch-locators.js';
 import { patchUserEvent } from './patch-user-event.js';

package/dist/validate-render-frame.d.ts

@@ -0,0 +1,6 @@
+import type { RenderFrameMode } from '@describe-me/core/types';
+/**
+ * The plugin's `renderFrame`, checked before any test runs. Selector syntax is
+ * left to `recorder.configure()` in the test runtime, which has a DOM to parse it.
+ */
+export declare function validateRenderFrame(value: unknown): RenderFrameMode;

package/dist/validate-render-frame.js

@@ -0,0 +1,26 @@
+import { inspect } from 'node:util';
+const ACCEPTED = "'eager', 'lazy' or { pending: string, timeout?: number } with a non-empty selector and a timeout above 0 ms";
+function isPendingMode(value) {
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    const { pending, timeout, ...rest } = value;
+    if (Object.keys(rest).length > 0 || typeof pending !== 'string' || pending === '') {
+        return false;
+    }
+    return (timeout === undefined ||
+        (typeof timeout === 'number' && Number.isFinite(timeout) && timeout > 0));
+}
+/**
+ * The plugin's `renderFrame`, checked before any test runs. Selector syntax is
+ * left to `recorder.configure()` in the test runtime, which has a DOM to parse it.
+ */
+export function validateRenderFrame(value) {
+    if (value === undefined) {
+        return 'eager';
+    }
+    if (value === 'eager' || value === 'lazy' || isPendingMode(value)) {
+        return value;
+    }
+    throw new Error(`describe-me: renderFrame expects ${ACCEPTED}, got ${inspect(value)}`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@describe-me/vitest",
-  "version": "0.5.0-next.1",
+  "version": "0.5.0-next.2",
   "description": "Vitest integration for describe-me: plugin, setup file and reporter",
   "keywords": [
     "vitest",
@@ -59,7 +59,7 @@
   ],
   "dependencies": {
     "picomatch": "^4.0.3",
-    "@describe-me/core": "^0.5.0-next.1"
+    "@describe-me/core": "^0.5.0-next.2"
   },
   "peerDependencies": {
     "vitest": "^4.0.0 || ^5.0.0",