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

package/README.md

@@ -55,6 +55,17 @@ Tests in other files still run, but record nothing. The reporter takes the
 same two options, but on its own it only filters the manifest: without the
 plugin the setup file does not know them.
 
+`describeMe({ previewHead })` takes HTML that the viewer adds to the start of
+every frame's `<head>`, like Storybook's `preview-head.html`: typically the
+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/asset-store.d.ts

@@ -1,12 +1,16 @@
 /**
- * Content-addressed store for the project files snapshots point at (images,
- * fonts, `url()` targets of stylesheets), living in `<outDir>/assets`.
+ * Content-addressed store for the project files that snapshots and the preview
+ * head point at (images, fonts, `url()` targets of stylesheets), living in
+ * `<outDir>/assets`.
  *
  * rrweb makes most URLs absolute against the test page, whose server is gone
- * once the tests finish; a few stay root-relative, which the viewer would
+ * once the tests finish. A few stay root-relative, which the viewer would
  * resolve against itself. `rewrite()` copies each file it finds in the project
  * and swaps its URL for `ASSET_URL_PREFIX` plus the stored name, which the
- * viewer resolves against its own data directory.
+ * viewer resolves against its own data directory. `rewriteHead()` does the
+ * same for the preview head. A CSS file is stored with its own `url()` and
+ * `@import` targets copied too and written as bare sibling names, so it keeps
+ * working from `assets/`.
  */
 export declare class AssetStore {
     private readonly outDir;
@@ -15,11 +19,17 @@ export declare class AssetStore {
     /** Stored name per URL pathname in this run, or null when it is not a project file. */
     private readonly names;
     private readonly notFound;
+    /** Stored name per absolute CSS file path in this run. */
+    private readonly cssNames;
+    /** CSS files being copied right now, so an `@import` cycle ends. */
+    private readonly copying;
     /**
      * Asset names per snapshot or style chunk. Both are content-addressed, so an
      * entry never goes stale.
      */
     private readonly referencesByFile;
+    /** Asset names per stored CSS asset, which is content-addressed too. */
+    private readonly referencesByCssAsset;
     constructor(outDir: string, root: string);
     /** Forget what the previous run found: files may have changed or appeared since. */
     startRun(): void;
@@ -31,21 +41,58 @@ export declare class AssetStore {
      * handled on their own. A `#fragment` is kept, for SVG sprites.
      */
     rewrite(json: string, origin: string | undefined): string;
-    /** Root-relative paths that snapshots in this run pointed at but that do not exist. */
+    /**
+     * Replace every URL in the preview head that points at a project file with
+     * an asset URL. A relative URL counts from the project root, the page the
+     * head is written for.
+     */
+    rewriteHead(html: string): string;
+    /**
+     * Paths that snapshots, the preview head or copied CSS files in this run
+     * pointed at but that do not exist: root-relative inside the project root,
+     * `/@fs/<absolute path>` outside it.
+     */
     missing(): string[];
     /**
-     * Drop the assets no kept snapshot or style chunk refers to. Paths are
-     * relative to the output directory, as the manifest stores them. Every kept
-     * file is scanned, not only the ones written now: snapshots of modules that
-     * were not re-run were rewritten by an earlier run.
+     * Drop the assets that no kept snapshot or style chunk, no inline text such
+     * as the preview head, and no kept CSS asset refers to. Paths are relative
+     * to the output directory, as the manifest stores them. Every kept file is
+     * scanned, not only the ones written now: snapshots of modules that were not
+     * re-run were rewritten by an earlier run.
      */
-    collectGarbage(files: Iterable<string>): void;
+    collectGarbage(files: Iterable<string>, inlineTexts?: Iterable<string>): void;
+    /** Add what each kept CSS asset refers to, and what those refer to in turn. */
+    private keepCssTargets;
+    private cssAssetReferencesOf;
     private referencesIn;
     /** The asset URL for a root-relative URL path, or null when it is not a project file. */
     private assetUrl;
     /** The stored name for a URL pathname, copying the file on first sight in this run. */
     private nameFor;
     private copyIntoStore;
+    /** Store a project file under its content hash, and return its stored name. */
+    private store;
+    /**
+     * Store a CSS file with its `url()` and `@import` targets stored too. They
+     * are written as bare sibling names, which the browser resolves against the
+     * stylesheet's own URL, so the viewer has nothing to substitute. The name is
+     * the hash of the rewritten text.
+     */
+    private storeCss;
+    /**
+     * The stored name, with its fragment, for a target of the CSS file
+     * `cssFile`, or null to leave the target as written: a remote URL, a
+     * file type outside the allowlist, a missing file or a file being copied.
+     */
+    private siblingName;
+    /**
+     * The file behind a target path of a CSS file, reported when missing. A
+     * root-relative path is looked up like a snapshot URL, a relative one next
+     * to the CSS file on disk.
+     */
+    private cssTargetFile;
+    /** How Vite serves a file: root-relative inside the project root, `/@fs/<absolute path>` outside it. */
+    private servedPath;
     /** Where Vite serves a URL pathname from: `/@fs/`, the project root, or its `public/` folder. */
     private fileFor;
 }

package/dist/asset-store.js

@@ -1,7 +1,10 @@
 import { createHash } from 'node:crypto';
-import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, } from 'node:fs';
-import { extname, join, resolve, sep } from 'node:path';
+import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync, } from 'node:fs';
+import { dirname, extname, join, resolve, sep } from 'node:path';
 import { ASSET_URL_PREFIX } from '@describe-me/core/types';
+import { cssAssetReferences } from './css-asset-references.js';
+import { rewriteCssReferences } from './rewrite-css-references.js';
+import { rewriteHeadReferences } from './rewrite-head-references.js';
 /** A URL path inside serialized JSON runs until a quote, whitespace, `)`, `\`, `<` or `>`. */
 const URL_PATH = String.raw `/[^"'\s)\\<>]*`;
 /** A root-relative path: one slash, not the two of a protocol-relative URL. */
@@ -43,12 +46,66 @@ const MODULE_EXTENSIONS = new Set([
     '.vue',
     '.svelte',
 ]);
+/** A URL with a scheme (`https:`, `data:`, `mailto:`, `describe-me-asset:`) is never a project path. */
+const URL_SCHEME = /^[a-z][a-z0-9+.-]*:/i;
+/** The preview head's URLs resolve as if the page were served from the project root. */
+const PROJECT_ROOT_URL = 'http://project-root.invalid/';
+/**
+ * What a copied CSS file may pull into the store: stylesheets, fonts, images
+ * and cursors. Any other target stays as written, so a stylesheet cannot
+ * publish source files or secrets.
+ */
+const CSS_TARGET_EXTENSIONS = new Set([
+    '.css',
+    '.woff2',
+    '.woff',
+    '.ttf',
+    '.otf',
+    '.eot',
+    '.svg',
+    '.png',
+    '.jpg',
+    '.jpeg',
+    '.gif',
+    '.webp',
+    '.avif',
+    '.ico',
+    '.bmp',
+    '.cur',
+]);
 function escapeRegExp(text) {
     return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
 function isFile(path) {
     return existsSync(path) && statSync(path).isFile();
 }
+function contentHash(content) {
+    return createHash('sha1').update(content).digest('hex').slice(0, 16);
+}
+function assetNamesIn(text) {
+    return Array.from(text.matchAll(ASSET_REFERENCE), (match) => match[1]);
+}
+/** Empty values, `#fragment`s, protocol-relative and scheme URLs never name a project file. */
+function isExternalUrl(url) {
+    return url === '' || url.startsWith('#') || url.startsWith('//') || URL_SCHEME.test(url);
+}
+/**
+ * A preview head URL as a root-relative path, or null when it cannot be read
+ * or leaves the project root, as `\\host\x` does.
+ */
+function rootRelativePath(url) {
+    let resolved;
+    try {
+        resolved = new URL(url, PROJECT_ROOT_URL);
+    }
+    catch {
+        return null;
+    }
+    if (!resolved.href.startsWith(PROJECT_ROOT_URL)) {
+        return null;
+    }
+    return resolved.pathname + resolved.search + resolved.hash;
+}
 function decodePath(pathname) {
     try {
         return decodeURIComponent(pathname);
@@ -78,14 +135,18 @@ function fsPathFromUrl(pathname) {
     return /^[A-Za-z]:/.test(path) ? path : `/${path}`;
 }
 /**
- * Content-addressed store for the project files snapshots point at (images,
- * fonts, `url()` targets of stylesheets), living in `<outDir>/assets`.
+ * Content-addressed store for the project files that snapshots and the preview
+ * head point at (images, fonts, `url()` targets of stylesheets), living in
+ * `<outDir>/assets`.
  *
  * rrweb makes most URLs absolute against the test page, whose server is gone
- * once the tests finish; a few stay root-relative, which the viewer would
+ * once the tests finish. A few stay root-relative, which the viewer would
  * resolve against itself. `rewrite()` copies each file it finds in the project
  * and swaps its URL for `ASSET_URL_PREFIX` plus the stored name, which the
- * viewer resolves against its own data directory.
+ * viewer resolves against its own data directory. `rewriteHead()` does the
+ * same for the preview head. A CSS file is stored with its own `url()` and
+ * `@import` targets copied too and written as bare sibling names, so it keeps
+ * working from `assets/`.
  */
 export class AssetStore {
     outDir;
@@ -94,11 +155,17 @@ export class AssetStore {
     /** Stored name per URL pathname in this run, or null when it is not a project file. */
     names = new Map();
     notFound = new Set();
+    /** Stored name per absolute CSS file path in this run. */
+    cssNames = new Map();
+    /** CSS files being copied right now, so an `@import` cycle ends. */
+    copying = new Set();
     /**
      * Asset names per snapshot or style chunk. Both are content-addressed, so an
      * entry never goes stale.
      */
     referencesByFile = new Map();
+    /** Asset names per stored CSS asset, which is content-addressed too. */
+    referencesByCssAsset = new Map();
     constructor(outDir, root) {
         this.outDir = outDir;
         this.dir = join(outDir, 'assets');
@@ -109,6 +176,7 @@ export class AssetStore {
     startRun() {
         this.names.clear();
         this.notFound.clear();
+        this.cssNames.clear();
     }
     /**
      * Replace every URL in a serialized snapshot that points at a project file
@@ -135,17 +203,36 @@ export class AssetStore {
             return asset === null ? poster : `"poster":"${asset}`;
         });
     }
-    /** Root-relative paths that snapshots in this run pointed at but that do not exist. */
+    /**
+     * Replace every URL in the preview head that points at a project file with
+     * an asset URL. A relative URL counts from the project root, the page the
+     * head is written for.
+     */
+    rewriteHead(html) {
+        return rewriteHeadReferences(html, (url) => {
+            if (isExternalUrl(url)) {
+                return null;
+            }
+            const path = rootRelativePath(url);
+            return path === null ? null : this.assetUrl(path);
+        });
+    }
+    /**
+     * Paths that snapshots, the preview head or copied CSS files in this run
+     * pointed at but that do not exist: root-relative inside the project root,
+     * `/@fs/<absolute path>` outside it.
+     */
     missing() {
         return Array.from(this.notFound).sort();
     }
     /**
-     * Drop the assets no kept snapshot or style chunk refers to. Paths are
-     * relative to the output directory, as the manifest stores them. Every kept
-     * file is scanned, not only the ones written now: snapshots of modules that
-     * were not re-run were rewritten by an earlier run.
+     * Drop the assets that no kept snapshot or style chunk, no inline text such
+     * as the preview head, and no kept CSS asset refers to. Paths are relative
+     * to the output directory, as the manifest stores them. Every kept file is
+     * scanned, not only the ones written now: snapshots of modules that were not
+     * re-run were rewritten by an earlier run.
      */
-    collectGarbage(files) {
+    collectGarbage(files, inlineTexts = []) {
         const stored = readdirSync(this.dir);
         if (stored.length === 0) {
             return;
@@ -156,12 +243,45 @@ export class AssetStore {
                 keep.add(name);
             }
         }
+        for (const text of inlineTexts) {
+            for (const name of assetNamesIn(text)) {
+                keep.add(name);
+            }
+        }
+        this.keepCssTargets(keep);
         for (const file of stored) {
             if (!keep.has(file)) {
                 rmSync(join(this.dir, file), { force: true });
             }
         }
     }
+    /** Add what each kept CSS asset refers to, and what those refer to in turn. */
+    keepCssTargets(keep) {
+        const pending = Array.from(keep).filter((name) => name.endsWith('.css'));
+        let name = pending.pop();
+        while (name !== undefined) {
+            for (const target of this.cssAssetReferencesOf(name)) {
+                if (!keep.has(target)) {
+                    keep.add(target);
+                    pending.push(target);
+                }
+            }
+            name = pending.pop();
+        }
+    }
+    cssAssetReferencesOf(name) {
+        const cached = this.referencesByCssAsset.get(name);
+        if (cached) {
+            return cached;
+        }
+        const path = join(this.dir, name);
+        if (!name.endsWith('.css') || !isFile(path)) {
+            return [];
+        }
+        const names = cssAssetReferences(readFileSync(path, 'utf8'));
+        this.referencesByCssAsset.set(name, names);
+        return names;
+    }
     referencesIn(file) {
         const cached = this.referencesByFile.get(file);
         if (cached) {
@@ -171,8 +291,7 @@ export class AssetStore {
         if (!isFile(path)) {
             return [];
         }
-        const text = readFileSync(path, 'utf8');
-        const names = Array.from(text.matchAll(ASSET_REFERENCE), (match) => match[1]);
+        const names = assetNamesIn(readFileSync(path, 'utf8'));
         this.referencesByFile.set(file, names);
         return names;
     }
@@ -208,8 +327,15 @@ export class AssetStore {
             }
             return null;
         }
-        const hash = createHash('sha1').update(readFileSync(file)).digest('hex').slice(0, 16);
+        return this.store(file);
+    }
+    /** Store a project file under its content hash, and return its stored name. */
+    store(file) {
         const extension = extname(file).toLowerCase();
+        if (extension === '.css') {
+            return this.storeCss(file);
+        }
+        const hash = contentHash(readFileSync(file));
         const name = /^\.[a-z0-9]+$/.test(extension) ? `${hash}${extension}` : hash;
         const target = join(this.dir, name);
         if (!existsSync(target)) {
@@ -217,6 +343,80 @@ export class AssetStore {
         }
         return name;
     }
+    /**
+     * Store a CSS file with its `url()` and `@import` targets stored too. They
+     * are written as bare sibling names, which the browser resolves against the
+     * stylesheet's own URL, so the viewer has nothing to substitute. The name is
+     * the hash of the rewritten text.
+     */
+    storeCss(file) {
+        const known = this.cssNames.get(file);
+        if (known !== undefined) {
+            return known;
+        }
+        let css;
+        this.copying.add(file);
+        try {
+            css = rewriteCssReferences(readFileSync(file, 'utf8'), (url) => this.siblingName(url, file));
+        }
+        finally {
+            this.copying.delete(file);
+        }
+        const name = `${contentHash(css)}.css`;
+        const target = join(this.dir, name);
+        if (!existsSync(target)) {
+            writeFileSync(target, css);
+        }
+        this.cssNames.set(file, name);
+        return name;
+    }
+    /**
+     * The stored name, with its fragment, for a target of the CSS file
+     * `cssFile`, or null to leave the target as written: a remote URL, a
+     * file type outside the allowlist, a missing file or a file being copied.
+     */
+    siblingName(url, cssFile) {
+        if (isExternalUrl(url)) {
+            return null;
+        }
+        const { pathname, fragment } = splitUrlPath(url);
+        const path = decodePath(pathname);
+        if (!CSS_TARGET_EXTENSIONS.has(extname(path).toLowerCase())) {
+            return null;
+        }
+        const file = this.cssTargetFile(path, cssFile);
+        if (!file || this.copying.has(file)) {
+            return null;
+        }
+        return `${this.store(file)}${fragment}`;
+    }
+    /**
+     * The file behind a target path of a CSS file, reported when missing. A
+     * root-relative path is looked up like a snapshot URL, a relative one next
+     * to the CSS file on disk.
+     */
+    cssTargetFile(path, cssFile) {
+        if (path.startsWith('/')) {
+            const file = this.fileFor(path);
+            if (!file) {
+                this.notFound.add(path);
+            }
+            return file;
+        }
+        const file = resolve(dirname(cssFile), path);
+        if (!isFile(file)) {
+            this.notFound.add(this.servedPath(file));
+            return undefined;
+        }
+        return file;
+    }
+    /** How Vite serves a file: root-relative inside the project root, `/@fs/<absolute path>` outside it. */
+    servedPath(file) {
+        const path = file.startsWith(this.root + sep)
+            ? file.slice(this.root.length)
+            : `/@fs/${file.replace(/^[\\/]/, '')}`;
+        return path.split(sep).join('/');
+    }
     /** Where Vite serves a URL pathname from: `/@fs/`, the project root, or its `public/` folder. */
     fileFor(pathname) {
         if (pathname.startsWith('/@fs/')) {

package/dist/css-asset-references.d.ts

@@ -0,0 +1,5 @@
+/**
+ * The stored asset names a stored CSS asset refers to. The asset store writes
+ * them as bare sibling names, so garbage collection can follow them.
+ */
+export declare function cssAssetReferences(css: string): string[];

package/dist/css-asset-references.js

@@ -0,0 +1,17 @@
+import { cssReferences } from '@describe-me/core/css-references';
+/** A stored asset's name: a content hash and, when the file has one, its extension. */
+const ASSET_NAME = /^[0-9a-f]{16}(\.[a-z0-9]+)?$/;
+/**
+ * The stored asset names a stored CSS asset refers to. The asset store writes
+ * them as bare sibling names, so garbage collection can follow them.
+ */
+export function cssAssetReferences(css) {
+    const names = [];
+    for (const { url } of cssReferences(css)) {
+        const name = url.split(/[?#]/)[0];
+        if (ASSET_NAME.test(name)) {
+            names.push(name);
+        }
+    }
+    return names;
+}

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 {
@@ -35,6 +36,18 @@ export interface DescribeMeOptions {
     include?: string | string[];
     /** Test files never to record, as globs like `include`. Wins over `include`. Default: none. */
     exclude?: string | string[];
+    /**
+     * HTML the viewer adds to the start of the `<head>` of every replayed frame,
+     * like Storybook's `preview-head.html`. It never reaches the test page.
+     * 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,17 +102,19 @@ 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({
                 outDir,
                 include: options.include,
                 exclude: options.exclude,
+                previewHead: options.previewHead,
             });
             // Vite concatenates arrays when merging, so only add `default` when the
             // user has not chosen their own reporters; otherwise they would lose it.

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/reporter.d.ts

@@ -12,10 +12,17 @@ export interface DescribeMeReporterOptions {
      * `include`. Default: none.
      */
     exclude?: string | string[];
+    /**
+     * HTML the viewer adds to the start of the `<head>` of every replayed frame,
+     * like Storybook's `preview-head.html`. It never reaches the test page.
+     * Project files it links are copied into the output directory. Default: none.
+     */
+    previewHead?: string;
 }
 export default class DescribeMeReporter implements Reporter {
     private readonly outDirOption;
     private readonly isRecordedFile;
+    private readonly previewHead;
     private root;
     private outDir;
     private snapshots;

package/dist/reporter.js

@@ -21,6 +21,7 @@ function recordOf(tc) {
 export default class DescribeMeReporter {
     outDirOption;
     isRecordedFile;
+    previewHead;
     root = process.cwd();
     outDir = '';
     snapshots;
@@ -33,6 +34,8 @@ export default class DescribeMeReporter {
             include: compileGlobs(options.include),
             exclude: compileGlobs(options.exclude),
         });
+        // A blank head, such as an empty preview-head.html, is the same as none.
+        this.previewHead = options.previewHead?.trim() ? options.previewHead : undefined;
     }
     onInit(vitest) {
         this.root = vitest.config.root;
@@ -41,6 +44,9 @@ export default class DescribeMeReporter {
         this.assets = new AssetStore(this.outDir, this.root);
         this.styles = new StyleStore(this.outDir);
         this.seedFromPreviousRun();
+        if (this.previewHead !== undefined && /<script\b/i.test(this.previewHead)) {
+            console.warn('describe-me: previewHead contains a <script>, which the viewer never runs.');
+        }
     }
     onTestRunStart() {
         this.assets.startRun();
@@ -98,6 +104,8 @@ export default class DescribeMeReporter {
     async onTestRunEnd() {
         const modules = Array.from(this.modules.values()).sort((left, right) => left.id.localeCompare(right.id));
         const components = await collectComponentDocsSafely(this.root, componentEntries(modules, this.root));
+        // Before `missing()`, so the files the head links that do not exist are listed too.
+        const head = this.previewHead === undefined ? undefined : this.assets.rewriteHead(this.previewHead);
         // Only what this run found: a filtered run does not know which of the
         // previous run's missing assets belonged to the modules it skipped.
         const assetsMissing = this.assets.missing();
@@ -109,10 +117,13 @@ export default class DescribeMeReporter {
             components,
             assetsMissing,
         };
+        if (head !== undefined) {
+            manifest.head = head;
+        }
         const snapshotFiles = manifest.modules.flatMap((mod) => mod.tests.flatMap((test) => test.frames.map((frame) => frame.snapshot)));
         this.snapshots.collectGarbage(snapshotFiles);
         const styleFiles = this.styles.collectGarbage(snapshotFiles);
-        this.assets.collectGarbage([...snapshotFiles, ...styleFiles]);
+        this.assets.collectGarbage([...snapshotFiles, ...styleFiles], head === undefined ? [] : [head]);
         writeFileSync(join(this.outDir, 'manifest.json'), JSON.stringify(manifest, null, 2));
         printDiagnostics(manifest);
     }

package/dist/rewrite-css-references.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Replace each `url()` and `@import` target in CSS text for which `resolve`
+ * returns a string. Quotes and everything else stay as written.
+ */
+export declare function rewriteCssReferences(css: string, resolve: (url: string) => string | null): string;

package/dist/rewrite-css-references.js

@@ -0,0 +1,18 @@
+import { cssReferences } from '@describe-me/core/css-references';
+/**
+ * Replace each `url()` and `@import` target in CSS text for which `resolve`
+ * returns a string. Quotes and everything else stay as written.
+ */
+export function rewriteCssReferences(css, resolve) {
+    let rewritten = '';
+    let copied = 0;
+    for (const reference of cssReferences(css)) {
+        const replacement = resolve(reference.url);
+        if (replacement === null) {
+            continue;
+        }
+        rewritten += css.slice(copied, reference.start) + replacement;
+        copied = reference.end;
+    }
+    return rewritten + css.slice(copied);
+}

package/dist/rewrite-head-references.d.ts

@@ -0,0 +1,8 @@
+type Resolve = (url: string) => string | null;
+/**
+ * Replace the URLs in HTML meant for a document's `<head>`: `href` and `src`
+ * values, and the `url()` and `@import` targets of `<style>` elements and
+ * `style` attributes, wherever `resolve` returns a string.
+ */
+export declare function rewriteHeadReferences(html: string, resolve: Resolve): string;
+export {};

package/dist/rewrite-head-references.js

@@ -0,0 +1,49 @@
+import { rewriteCssReferences } from './rewrite-css-references.js';
+/**
+ * Comments and `<script>` elements, which stay as written, and `<style>`
+ * elements, whose CSS is rewritten. Tags between them are rewritten attribute
+ * by attribute. End tags and comment ends are matched as loosely as browsers
+ * read them: `</script foo>` and `--!>` count too.
+ */
+const RAW_TEXT = /<!--[\s\S]*?--!?>|<script\b[\s\S]*?<\/script\b[^>]*>|(<style\b[^>]*>)([\s\S]*?)(<\/style\b[^>]*>)/gi;
+/** A start tag, split after its name. Quoted attribute values may contain `>`. */
+const START_TAG = /(<[a-z][^\s/>]*)((?:[^>"']|"[^"]*"|'[^']*')*>)/gi;
+/**
+ * One attribute: its whole name, so `data-src` is never `src`, and its value,
+ * double-quoted, single-quoted or bare.
+ */
+const ATTRIBUTE = /([^\s"'<>/=]+)(?:(\s*=\s*)("[^"]*"|'[^']*'|[^\s"'=<>`]+))?/g;
+/** Attributes whose value is a URL, and `style`, whose value is CSS. */
+const REWRITTEN_ATTRIBUTES = new Set(['href', 'src', 'style']);
+function rewriteAttribute(attribute, name, equals, value, resolve) {
+    const kind = name.toLowerCase();
+    if (equals === undefined || value === undefined || !REWRITTEN_ATTRIBUTES.has(kind)) {
+        return attribute;
+    }
+    const quote = value.startsWith('"') || value.startsWith("'") ? value[0] : '';
+    const text = quote === '' ? value : value.slice(1, -1);
+    const rewritten = kind === 'style' ? rewriteCssReferences(text, resolve) : (resolve(text) ?? text);
+    return `${name}${equals}${quote}${rewritten}${quote}`;
+}
+function rewriteTags(html, resolve) {
+    return html.replace(START_TAG, (_tag, name, attributes) => {
+        const rewritten = attributes.replace(ATTRIBUTE, (attribute, attributeName, equals, value) => rewriteAttribute(attribute, attributeName, equals, value, resolve));
+        return name + rewritten;
+    });
+}
+/**
+ * Replace the URLs in HTML meant for a document's `<head>`: `href` and `src`
+ * values, and the `url()` and `@import` targets of `<style>` elements and
+ * `style` attributes, wherever `resolve` returns a string.
+ */
+export function rewriteHeadReferences(html, resolve) {
+    let rewritten = '';
+    let copied = 0;
+    for (const match of html.matchAll(RAW_TEXT)) {
+        const [text, styleStart, css, styleEnd] = match;
+        const kept = styleStart === undefined ? text : styleStart + rewriteCssReferences(css, resolve) + styleEnd;
+        rewritten += rewriteTags(html.slice(copied, match.index), resolve) + kept;
+        copied = match.index + text.length;
+    }
+    return rewritten + rewriteTags(html.slice(copied), resolve);
+}

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.0",
+  "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.0"
+    "@describe-me/core": "^0.5.0-next.2"
   },
   "peerDependencies": {
     "vitest": "^4.0.0 || ^5.0.0",