@describe-me/vitest 0.5.4 → 0.6.1

package/dist/register-recording-hooks.js

@@ -7,25 +7,26 @@ import { fileFilter } from './file-filter.js';
  * 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.
+ * recorded. The hooks destructure the context, because Vitest rejects any
+ * other first parameter in a test that has `test.extend` fixtures.
  */
 export function registerRecordingHooks(options, aroundWait) {
     const isRecordedFile = fileFilter(options);
     let warnedConcurrent = false;
     recorder.configure({ renderFrame: options.renderFrame, aroundWait });
-    beforeEach((context) => {
-        if (context.task.concurrent) {
+    beforeEach(({ task }) => {
+        if (task.concurrent) {
             if (!warnedConcurrent) {
                 warnedConcurrent = true;
-                console.warn(`describe-me: concurrent tests are not recorded (${context.task.file.name})`);
+                console.warn(`describe-me: concurrent tests are not recorded (${task.file.name})`);
             }
             return;
         }
-        if (isRecordedFile(context.task.file.name)) {
+        if (isRecordedFile(task.file.name)) {
             recorder.begin();
         }
     });
-    afterEach(async (context) => {
+    afterEach(async ({ task }) => {
         try {
             if (recorder.isActive) {
                 const tookRender = await recorder.flush();
@@ -36,7 +37,7 @@ export function registerRecordingHooks(options, aroundWait) {
                 const record = recorder.end();
                 if (record.frames.length > 0) {
                     ;
-                    context.task.meta[META_KEY] = record;
+                    task.meta[META_KEY] = record;
                 }
             }
         }

package/dist/report-live-errors.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Reports what the live component throws while someone uses it. The stop
+ * signal is no error, so it is neither reported nor logged.
+ */
+export declare function reportLiveErrors(): void;

package/dist/report-live-errors.js

@@ -0,0 +1,24 @@
+import { isLiveStop, postLiveMessage } from '@describe-me/core/live';
+function messageOf(reason) {
+    return reason instanceof Error ? String(reason) : `Unhandled rejection: ${String(reason)}`;
+}
+/**
+ * Reports what the live component throws while someone uses it. The stop
+ * signal is no error, so it is neither reported nor logged.
+ */
+export function reportLiveErrors() {
+    window.addEventListener('error', (event) => {
+        if (isLiveStop(event.error)) {
+            event.preventDefault();
+            return;
+        }
+        postLiveMessage({ type: 'error', message: event.message || String(event.error) });
+    });
+    window.addEventListener('unhandledrejection', (event) => {
+        if (isLiveStop(event.reason)) {
+            event.preventDefault();
+            return;
+        }
+        postLiveMessage({ type: 'error', message: messageOf(event.reason) });
+    });
+}

package/dist/reporter.d.ts

@@ -30,6 +30,7 @@ export default class DescribeMeReporter implements Reporter {
     private readonly generator;
     private readonly setupWarnings;
     private root;
+    private configFile;
     private outDir;
     private snapshots;
     private assets;
@@ -60,6 +61,8 @@ export default class DescribeMeReporter implements Reporter {
     onTestRunEnd(): Promise<void>;
     /** A diagnostic must never break the manifest, so a failing audit writes empty lists. */
     private auditFonts;
+    /** The config file of the run, relative to the root, so the live preview loads the same one. */
+    private relativeConfigFile;
     /** Module ids use the platform's separators. Globs expect posix ones. */
     private isRecordedModule;
     /** Decided before any snapshot is written, so a dropped test writes no file. */

package/dist/reporter.js

@@ -33,6 +33,7 @@ export default class DescribeMeReporter {
     generator;
     setupWarnings;
     root = process.cwd();
+    configFile;
     outDir = '';
     snapshots;
     assets;
@@ -51,6 +52,8 @@ export default class DescribeMeReporter {
     }
     onInit(vitest) {
         this.root = vitest.config.root;
+        // A script that calls the reporter directly passes no Vite server, so there is no file to name.
+        this.configFile = this.relativeConfigFile(vitest.vite?.config.configFile);
         this.outDir = resolve(this.root, this.outDirOption);
         this.snapshots = new SnapshotStore(this.outDir);
         this.assets = new AssetStore(this.outDir, this.root);
@@ -150,6 +153,8 @@ export default class DescribeMeReporter {
             generator: this.generator,
             generatedAt: new Date().toISOString(),
             root: this.root,
+            // Always this run's, never the previous manifest's. `undefined` leaves it out of the JSON.
+            configFile: this.configFile,
             modules,
             components,
             assetsMissing,
@@ -183,6 +188,10 @@ export default class DescribeMeReporter {
             manifest.remoteStylesheets = [];
         }
     }
+    /** The config file of the run, relative to the root, so the live preview loads the same one. */
+    relativeConfigFile(configFile) {
+        return configFile === undefined ? undefined : toPosix(relative(this.root, configFile));
+    }
     /** Module ids use the platform's separators. Globs expect posix ones. */
     isRecordedModule(id) {
         return this.isRecordedFile(toPosix(id));

package/dist/run-live-test.d.ts

@@ -0,0 +1,10 @@
+import type { LiveTestMatch } from './find-live-test.js';
+/**
+ * Runs a test's arrange phase the way Vitest runs a test: for each suite from
+ * the root down, its `aroundAll` hooks around its `beforeAll` hooks, then the
+ * `aroundEach` hooks of the path around the `beforeEach` hooks and the body,
+ * each test-scope callback after the fixtures it uses. It stops when the
+ * first render throws the stop signal, so no teardown runs. Unless the render
+ * reported `mounted`, it reports why the page shows nothing.
+ */
+export declare function runLiveTest(match: LiveTestMatch, testTimeout: number): Promise<void>;

package/dist/run-live-test.js

@@ -0,0 +1,118 @@
+import { isLiveStop, liveStatus, reportLiveStatus } from '@describe-me/core/live';
+import { liveErrorDetail } from './live-error-detail.js';
+import { liveFixtureValues } from './live-fixture-values.js';
+import { liveTestContext } from './live-test-context.js';
+const RUN_FUNCTIONS = { aroundAll: 'runSuite', aroundEach: 'runTest' };
+/** The test's own timeout, or the nearest suite's, which Vitest passes on to its tests. */
+function timeoutOf(match, testTimeout) {
+    const innermostFirst = [...match.suites].reverse();
+    const suiteTimeout = innermostFirst.find((suite) => suite.timeout !== undefined)?.timeout;
+    return match.test.timeout ?? suiteTimeout ?? testTimeout;
+}
+/** Computes the fixtures that a test-scope callback uses, then calls it. */
+async function withFixtures(arrange, use, call) {
+    await liveFixtureValues(arrange.match.test.fixtures, use, arrange.context, arrange.computed);
+    await call();
+}
+/**
+ * Runs one around hook. Its run function starts `inner` and returns a
+ * promise that never settles, so the hook's teardown never runs. Settles as
+ * `inner` does, or rejects when the hook fails or settles without calling
+ * its run function.
+ */
+function around(kind, call, inner) {
+    return new Promise((resolve, reject) => {
+        let started = false;
+        const run = () => {
+            if (!started) {
+                started = true;
+                inner().then(resolve, reject);
+            }
+            return new Promise(() => undefined);
+        };
+        new Promise((settle) => settle(call(run))).then(() => {
+            if (!started) {
+                reject(new Error(`${kind} did not call ${RUN_FUNCTIONS[kind]}()`));
+            }
+        }, reject);
+    });
+}
+/** The around hooks nested around `inner`, the first one outermost, as in Vitest. */
+function nested(kind, calls, inner) {
+    return calls.reduceRight((next, call) => () => around(kind, call, next), inner);
+}
+/** The `aroundEach` hooks of every suite on the path, then the `beforeEach` hooks and the body. */
+function testStep(arrange) {
+    const { match, context } = arrange;
+    const inner = async () => {
+        for (const suite of match.suites) {
+            for (const hook of suite.hooks.beforeEach) {
+                await withFixtures(arrange, { callback: hook, index: 0 }, () => hook(context));
+            }
+        }
+        const { body, uses } = match.test;
+        if (body !== undefined) {
+            await withFixtures(arrange, uses, () => body(context));
+        }
+    };
+    const calls = match.suites.flatMap((suite) => suite.hooks.aroundEach.map((hook) => (run) => withFixtures(arrange, { callback: hook, index: 1 }, () => hook(run, context, suite))));
+    return nested('aroundEach', calls, inner);
+}
+/** One suite on the path: its `aroundAll` hooks around its `beforeAll` hooks and everything below. */
+function suiteStep(arrange, depth) {
+    const { match, context } = arrange;
+    const suite = match.suites[depth];
+    if (suite === undefined) {
+        return testStep(arrange);
+    }
+    const inner = async () => {
+        for (const hook of suite.hooks.beforeAll) {
+            await hook(context);
+        }
+        await suiteStep(arrange, depth + 1)();
+    };
+    const calls = suite.hooks.aroundAll.map((hook) => (run) => hook(run, context, suite));
+    return nested('aroundAll', calls, inner);
+}
+function withTimeout(run, timeout, onTimeout) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(() => {
+            onTimeout();
+            resolve({ kind: 'timed-out' });
+        }, timeout);
+        run.then(() => {
+            clearTimeout(timer);
+            resolve({ kind: 'ended' });
+        }, (error) => {
+            clearTimeout(timer);
+            resolve(isLiveStop(error) ? { kind: 'ended' } : { kind: 'failed', error });
+        });
+    });
+}
+/**
+ * Runs a test's arrange phase the way Vitest runs a test: for each suite from
+ * the root down, its `aroundAll` hooks around its `beforeAll` hooks, then the
+ * `aroundEach` hooks of the path around the `beforeEach` hooks and the body,
+ * each test-scope callback after the fixtures it uses. It stops when the
+ * first render throws the stop signal, so no teardown runs. Unless the render
+ * reported `mounted`, it reports why the page shows nothing.
+ */
+export async function runLiveTest(match, testTimeout) {
+    const timeout = timeoutOf(match, testTimeout);
+    const controller = new AbortController();
+    const context = liveTestContext(match, controller.signal);
+    const arrange = { match, context, computed: new Set() };
+    const outcome = await withTimeout(suiteStep(arrange, 0)(), timeout, () => controller.abort());
+    if (liveStatus() !== null) {
+        return;
+    }
+    if (outcome.kind === 'timed-out') {
+        reportLiveStatus('failed', `did not reach its first render within ${timeout} ms`);
+        return;
+    }
+    if (outcome.kind === 'failed') {
+        reportLiveStatus('failed', liveErrorDetail(outcome.error));
+        return;
+    }
+    reportLiveStatus('no-render');
+}

package/dist/set-up-project.d.ts

@@ -0,0 +1,12 @@
+import type { TestProject } from 'vitest/node';
+import type { EnvironmentProfile } from './environment-profile.js';
+/**
+ * Gives a project the profile's setup file, when it lacks it, and the
+ * profile's variables. In Vitest 5 a project that shares the root's Vite
+ * server inherits the root config as it was before the plugin's `config`
+ * hook, so it gets the render redirect but not the setup file, and records
+ * nothing. The file goes last, as in the root config. Only projects with the
+ * setup file get the variables, so one without describe-me keeps Testing
+ * Library's own cleanup.
+ */
+export declare function setUpProject(project: TestProject, profile: EnvironmentProfile): void;

package/dist/set-up-project.js

@@ -0,0 +1,39 @@
+import { realpathSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { join } from 'node:path';
+function resolveFrom(root, specifier) {
+    try {
+        return createRequire(join(root, 'package.json')).resolve(specifier);
+    }
+    catch {
+        return null;
+    }
+}
+function realPathOf(file) {
+    try {
+        return realpathSync(file);
+    }
+    catch {
+        return file;
+    }
+}
+/**
+ * Gives a project the profile's setup file, when it lacks it, and the
+ * profile's variables. In Vitest 5 a project that shares the root's Vite
+ * server inherits the root config as it was before the plugin's `config`
+ * hook, so it gets the render redirect but not the setup file, and records
+ * nothing. The file goes last, as in the root config. Only projects with the
+ * setup file get the variables, so one without describe-me keeps Testing
+ * Library's own cleanup.
+ */
+export function setUpProject(project, profile) {
+    const file = resolveFrom(project.config.root, profile.setupFile);
+    if (file === null) {
+        return;
+    }
+    const real = realPathOf(file);
+    if (!project.config.setupFiles.some((entry) => realPathOf(entry) === real)) {
+        project.config.setupFiles.push(file);
+    }
+    project.config.env = { ...project.config.env, ...profile.env };
+}

package/dist/start-live-page.d.ts

@@ -0,0 +1,29 @@
+/** What the plugin's generated entry hands the live page. */
+export interface LivePageOptions {
+    /**
+     * Imports a test file by its path from the root. The dev server's entry
+     * imports it from the page's own origin, and a static build can pass a map
+     * of lazy imports.
+     */
+    importTest(file: string): Promise<unknown>;
+    /** `test.globals` of the project's config. */
+    globals: boolean;
+    /** How long the arrange phase may take, in ms, when the test sets no timeout of its own. */
+    testTimeout: number;
+    /**
+     * The setup files to import before the test file, in order: each one's
+     * name for messages and its import. Default: none.
+     */
+    setupFiles?: {
+        file: string;
+        load(): Promise<unknown>;
+    }[];
+    /** The major version of the project's Vitest, whose rules name `each` and `for` rows. Default: 5. */
+    vitestMajor?: number;
+}
+/**
+ * Runs the live page: imports the setup files and then the test file that
+ * the URL names, with the shims in place, runs the test's arrange phase and
+ * stops at its first render. The component stays mounted and live.
+ */
+export declare function startLivePage(options: LivePageOptions): Promise<void>;

package/dist/start-live-page.js

@@ -0,0 +1,62 @@
+import { reportLiveStatus } from '@describe-me/core/live';
+import { collectLiveSuites } from './collect-live-suites.js';
+import { findLiveTest } from './find-live-test.js';
+import { installLiveGlobals } from './install-live-globals.js';
+import { liveErrorDetail } from './live-error-detail.js';
+import { liveRegistry } from './live-registry.js';
+import { readLiveParams } from './read-live-params.js';
+import { reportLiveErrors } from './report-live-errors.js';
+import { runLiveTest } from './run-live-test.js';
+/**
+ * Imports the setup files one at a time, as one of the orders Vitest's
+ * parallel default can produce. Reports `setup-failed` and returns false at
+ * the first one that does not load, link or run.
+ */
+async function importSetupFiles(setupFiles) {
+    for (const setupFile of setupFiles ?? []) {
+        try {
+            await setupFile.load();
+        }
+        catch (error) {
+            reportLiveStatus('setup-failed', `${setupFile.file}: ${liveErrorDetail(error)}`);
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * Runs the live page: imports the setup files and then the test file that
+ * the URL names, with the shims in place, runs the test's arrange phase and
+ * stops at its first render. The component stays mounted and live.
+ */
+export async function startLivePage(options) {
+    if (options.globals) {
+        installLiveGlobals();
+    }
+    reportLiveErrors();
+    // Names form while tests register, so the rules must be known before any import.
+    liveRegistry().vitestMajor = options.vitestMajor ?? 5;
+    const params = readLiveParams(window.location);
+    if ('problem' in params) {
+        reportLiveStatus('not-found', params.problem);
+        return;
+    }
+    if (!(await importSetupFiles(options.setupFiles))) {
+        return;
+    }
+    try {
+        await options.importTest(params.file);
+        await collectLiveSuites();
+    }
+    catch (error) {
+        reportLiveStatus('import-failed', liveErrorDetail(error));
+        return;
+    }
+    const match = findLiveTest(params.path, params.occurrence);
+    if (match === null) {
+        const name = params.path.join(' > ');
+        reportLiveStatus('not-found', `no test ${name} (#${params.occurrence}) in ${params.file}`);
+        return;
+    }
+    await runLiveTest(match, options.testTimeout);
+}

package/dist/validate-live-option.d.ts

@@ -0,0 +1,11 @@
+/** The `live` option of `describeMe()`, checked. */
+export interface LiveOption {
+    enabled: boolean;
+    /** `live.setupFiles` as a list, or undefined when the option leaves `test.setupFiles` in place. */
+    setupFiles?: string[];
+}
+/**
+ * Checks the `live` option when the live preview starts, so a typo fails
+ * there instead of falling back to `test.setupFiles` without a word.
+ */
+export declare function validateLiveOption(live: unknown): LiveOption;

package/dist/validate-live-option.js

@@ -0,0 +1,29 @@
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Checks the `live` option when the live preview starts, so a typo fails
+ * there instead of falling back to `test.setupFiles` without a word.
+ */
+export function validateLiveOption(live) {
+    if (live === undefined) {
+        return { enabled: true };
+    }
+    if (live === false) {
+        return { enabled: false };
+    }
+    if (!isPlainObject(live)) {
+        throw new Error('describe-me: live must be false or { setupFiles }');
+    }
+    const { setupFiles } = live;
+    if (setupFiles === undefined) {
+        return { enabled: true };
+    }
+    if (typeof setupFiles === 'string') {
+        return { enabled: true, setupFiles: [setupFiles] };
+    }
+    if (Array.isArray(setupFiles) && setupFiles.every((entry) => typeof entry === 'string')) {
+        return { enabled: true, setupFiles: [...setupFiles] };
+    }
+    throw new Error('describe-me: live.setupFiles must be a string or an array of strings');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@describe-me/vitest",
-  "version": "0.5.4",
+  "version": "0.6.1",
   "description": "Living component documentation from your Vitest tests: the Vitest plugin, setup files and reporter of describe-me",
   "keywords": [
     "vitest",
@@ -49,6 +49,14 @@
     "./plugin": {
       "types": "./dist/plugin.d.ts",
       "default": "./dist/plugin.js"
+    },
+    "./live": {
+      "types": "./dist/live.d.ts",
+      "default": "./dist/live.js"
+    },
+    "./live-runtime": {
+      "types": "./dist/live-runtime.d.ts",
+      "default": "./dist/live-runtime.js"
     }
   },
   "files": [
@@ -63,13 +71,13 @@
   "dependencies": {
     "picomatch": "^4.0.3",
     "std-env": "^4.0.0",
-    "@describe-me/core": "^0.5.4"
+    "@describe-me/core": "^0.6.1"
   },
   "peerDependencies": {
     "vitest": "^4.0.0 || ^5.0.0",
     "typescript": "^5.0.0 || ^6.0.0",
     "@testing-library/user-event": "^14.0.0",
-    "describe-me": "^0.5.4"
+    "describe-me": "^0.6.1"
   },
   "peerDependenciesMeta": {
     "typescript": {