@describe-me/vitest 0.5.3 → 0.6.0

package/README.md

@@ -1,108 +1,77 @@
 # @describe-me/vitest
 
-The Vitest integration for [describe-me](https://github.com/grzehub/describe-me):
-a plugin, a setup file that makes every interaction record a frame, and the Node
-reporter that writes `.describe-me/`.
+**Your tests are your stories.** The Vitest plugin, setup files and reporter of
+describe-me: living component documentation generated from the Vitest tests
+you already have.
 
-## Install
+**[Read the docs](https://grzehub.github.io/describe-me/)** · open the viewer
+of the [browser-mode example](https://grzehub.github.io/describe-me/examples/react-browser/)
+or the [jsdom example](https://grzehub.github.io/describe-me/examples/react-jsdom/)
+· [Limitations](https://grzehub.github.io/describe-me/limitations.html)
 
-```sh
-pnpm add -D @describe-me/vitest @describe-me/react describe-me
-```
+describe-me captures the DOM after each step of a test and shows the result as
+a browsable catalog. `describe` blocks become the sidebar, each `it` is a
+story, and each step is a frame you can scrub through. Stories cannot rot,
+because they are tests. If one drifts from the component, CI goes red.
 
-All describe-me packages must be on the same version
-([One version for all packages](https://grzehub.github.io/describe-me/installation.html#lockstep)).
-
-## Usage
-
-One line in the Vitest config registers the setup file and the reporter, and
-redirects the test library's `render` import to the recording adapter. The
-plugin detects where the tests run:
-
-- **Browser mode** (`test.browser.enabled`): redirects `vitest-browser-react`,
-  records a frame after every `Locator` action and keyboard-level `userEvent`.
-- **DOM environments** such as jsdom (anything else): redirects
-  `@testing-library/react`, records a frame after every `fireEvent` and every
-  `@testing-library/user-event` call, turns on `test.css` so imported
-  stylesheets reach the snapshots, and sets `RTL_SKIP_AUTO_CLEANUP` so the
-  component is unmounted only after the closing frame. The setup file sets
-  React's `IS_REACT_ACT_ENVIRONMENT` where Testing Library would. With
-  `@testing-library/react`, it takes user-event frames without a wait. The
-  flag is off for the few waits that remain, which can still move an act
-  warning
-  ([jsdom](https://grzehub.github.io/describe-me/environments.html#jsdom)). It
-  also works without user-event installed.
-
-jsdom has no layout, so positioned popovers show in the top-left corner and
-canvas stays blank
-([Limitations in jsdom](https://grzehub.github.io/describe-me/environments.html#jsdom-limits)).
+Status: prototype. React 18 and 19, Vitest 4 and 5 in browser mode or jsdom,
+recorded frames and Live in the viewer.
 
-```ts
-import { describeMe } from '@describe-me/vitest/plugin'
+## Which package do I need
 
-// browser mode
-export default defineConfig({
-  plugins: [react(), describeMe()],
-  test: {
-    browser: { enabled: true, provider: playwright(), instances: [{ browser: 'chromium' }] },
-  },
-})
+| Package               | What it is                                         | Install it              |
+| --------------------- | -------------------------------------------------- | ----------------------- |
+| `describe-me`         | the viewer and the `describe-me` CLI               | yes                     |
+| `@describe-me/vitest` | the Vitest plugin, setup files and reporter (this) | yes                     |
+| `@describe-me/react`  | `render` functions that record frames              | yes                     |
+| `@describe-me/core`   | the recorder and the manifest types                | no, the others bring it |
 
-// jsdom
-export default defineConfig({
-  plugins: [react(), describeMe()],
-  test: { environment: 'jsdom' },
-})
-```
+## Quick start
 
-Pass `describeMe({ environment: 'browser' | 'dom' })` to override the detection.
-
-A test that records no frame before the closing one (no recording `render`,
-no interaction, no `step()`) costs no snapshot and is left out of the
-manifest. `describeMe({ include, exclude })` chooses which test files are
-recorded, with picomatch globs relative to the Vitest root. `exclude` wins.
-Tests in other files still run, but record nothing. Leaving `include` out
-records every test file. `include: []` records none and warns, while
-`exclude: '**'` records none without a warning. 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://grzehub.github.io/describe-me/styles-and-fonts.html#fonts) in the docs).
-
-`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://grzehub.github.io/describe-me/configuration.html#render-frame).
-
-The plugin adds its reporter to the ones your config names. If it names
-none, the reporter joins the ones Vitest picks on its own, such as `minimal`
-for AI agents and `github-actions` in GitHub Actions.
-
-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:
+```sh
+pnpm add -D describe-me @describe-me/vitest @describe-me/react
+```
 
 ```ts
-import DescribeMeReporter from '@describe-me/vitest/reporter'
+// vitest.config.ts
+import { describeMe } from '@describe-me/vitest/plugin'
 
 export default defineConfig({
-  test: {
-    // browser mode: '@describe-me/vitest/setup'
-    setupFiles: ['@describe-me/vitest/setup-dom'],
-    reporters: ['default', new DescribeMeReporter()],
-    // jsdom only: keep imported CSS and leave unmounting to describe-me
-    css: true,
-    env: { RTL_SKIP_AUTO_CLEANUP: 'true' },
-  },
+  plugins: [react(), describeMe()],
+  test: { environment: 'jsdom' }, // or your browser-mode settings
 })
 ```
 
-`typescript` is an optional peer: without it the docs are still generated, only
-the props tables are left out. `@testing-library/user-event` is an optional
-peer too, needed only in DOM environments.
-
-See the [docs](https://grzehub.github.io/describe-me/) for the full picture.
+Run your tests, then `describe-me dev` opens the viewer.
+[Getting started](https://grzehub.github.io/describe-me/getting-started.html)
+walks through both environments. Keep all describe-me packages on one version
+([why](https://grzehub.github.io/describe-me/installation.html#lockstep)).
+
+## This package
+
+The plugin is the whole integration. It detects browser mode or a DOM
+environment, registers the setup file and the reporter, and redirects your
+test library's `render` to the recording one, so existing tests record frames
+unchanged.
+[What the plugin changes](https://grzehub.github.io/describe-me/configuration.html#plugin)
+lists every change it makes to your config, and
+[Options](https://grzehub.github.io/describe-me/configuration.html#options)
+every option it takes.
+
+| Entry point                        | What it holds                                                                                                           |
+| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `@describe-me/vitest/plugin`       | [`describeMe()`](https://grzehub.github.io/describe-me/api.html#entry-vitest-plugin)                                    |
+| `@describe-me/vitest`              | [`step()` and `recorder`](https://grzehub.github.io/describe-me/api.html#entry-vitest)                                  |
+| `@describe-me/vitest/setup`        | [the browser-mode setup file](https://grzehub.github.io/describe-me/api.html#entry-vitest-setup)                        |
+| `@describe-me/vitest/setup-dom`    | [the jsdom setup file](https://grzehub.github.io/describe-me/api.html#entry-vitest-setup-dom)                           |
+| `@describe-me/vitest/reporter`     | [the reporter, to wire by hand](https://grzehub.github.io/describe-me/api.html#entry-vitest-reporter)                   |
+| `@describe-me/vitest/live`         | [`createLiveServer()` and `buildLive()`, for the CLI](https://grzehub.github.io/describe-me/api.html#entry-vitest-live) |
+| `@describe-me/vitest/live-runtime` | [the runtime of the live page](https://grzehub.github.io/describe-me/api.html#entry-vitest-live-runtime)                |
+
+`typescript` and `@testing-library/user-event` are optional peers. Without
+TypeScript the docs have no props tables. user-event is needed only when your
+jsdom tests use it.
+
+## License
+
+MIT

package/dist/browser-profile.d.ts

@@ -0,0 +1,3 @@
+import type { EnvironmentProfile } from './environment-profile.js';
+/** Vitest browser mode, where tests render in a real browser. */
+export declare const browserProfile: EnvironmentProfile;

package/dist/browser-profile.js

@@ -0,0 +1,26 @@
+/** Vitest browser mode, where tests render in a real browser. */
+export const browserProfile = {
+    renderModules: {
+        react: {
+            original: 'vitest-browser-react',
+            adapter: '@describe-me/react',
+            live: '@describe-me/react/live',
+        },
+    },
+    setupFile: '@describe-me/vitest/setup',
+    configFor({ renderModule }) {
+        return {
+            config: {
+                // Vite's dependency scanner runs before our `resolveId` redirect, so it
+                // never sees the adapter. Discovering it mid-run makes Vite re-optimize
+                // and reload, and the test ends up with two copies of the bundled deps
+                // ("Vitest failed to find the runner"). Declaring the adapter up front
+                // keeps a single optimization pass.
+                optimizeDeps: {
+                    include: [renderModule.adapter, renderModule.original],
+                },
+            },
+            setupWarnings: [],
+        };
+    },
+};

package/dist/build-live.d.ts

@@ -0,0 +1,26 @@
+/** What `buildLive()` builds, and where it writes the page. */
+export interface LiveBuildOptions {
+    /** The project root. */
+    root: string;
+    /** The Vitest config file, relative to `root` or absolute. Default: the one Vitest picks. */
+    configFile?: string;
+    /** Where the live page goes, relative to the current directory or absolute. Emptied first. */
+    outDir: string;
+    /** The test files the page can import: module ids of the manifest, paths relative to `root`. */
+    testFiles: string[];
+}
+/** A finished live build. */
+export interface LiveBuild {
+    /** `api.live.protocol` of the project's describeMe() plugin. */
+    protocol: number;
+}
+/**
+ * Builds the live preview into `outDir` as static files: `live.html`, the
+ * setup files and a lazy import of each test file, with a relative base, so
+ * it works under any path of a static host. It loads the project's config
+ * the way `createLiveServer()` does, with the project's own Vite, and builds
+ * the page the dev server serves. When the project's describeMe() has
+ * `live: false`, it writes nothing and rejects with an error whose `code` is
+ * `DESCRIBE_ME_LIVE_OFF`.
+ */
+export declare function buildLive(options: LiveBuildOptions): Promise<LiveBuild>;

package/dist/build-live.js

@@ -0,0 +1,106 @@
+import { existsSync, realpathSync } from 'node:fs';
+import { isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { findLiveConfigFile } from './find-live-config-file.js';
+import { importLiveVite } from './import-live-vite.js';
+import { liveBuildPlugin } from './live-build-plugin.js';
+import { liveProjectPlugins } from './live-project-plugins.js';
+import { loadLiveConfig } from './load-live-config.js';
+function isInRoot(file, root) {
+    const fromRoot = relative(root, file);
+    return fromRoot !== '' && fromRoot.split(sep)[0] !== '..' && !isAbsolute(fromRoot);
+}
+/** The test files with `/` separators, without those that are not under the root, which it names once. */
+function liveTestFiles(testFiles, root) {
+    const kept = new Set();
+    const missing = [];
+    for (const file of testFiles.map((testFile) => testFile.replaceAll('\\', '/'))) {
+        const path = resolve(root, file);
+        if (isInRoot(path, root) && existsSync(path)) {
+            kept.add(file);
+        }
+        else {
+            missing.push(file);
+        }
+    }
+    if (missing.length > 0) {
+        console.warn(`describe-me: the live build leaves out test files that are not in ${root}: ${missing.join(', ')}`);
+    }
+    return [...kept];
+}
+function liveBuildOptions(viteVersion, root, outDir) {
+    // Vite 8 does not resolve a relative input against the root.
+    const bundlerOptions = { input: join(root, 'live.html'), shimMissingExports: true };
+    // Vite 8 bundles with Rolldown and older majors with Rollup, each under its own key.
+    const bundler = Number.parseInt(viteVersion, 10) >= 8
+        ? { rolldownOptions: bundlerOptions }
+        : { rollupOptions: bundlerOptions };
+    return {
+        outDir: resolve(outDir),
+        // Vite empties an outDir outside the root only when asked.
+        emptyOutDir: true,
+        // Suite and test names come from `fn.name`, as in Vitest. A minifier would rename
+        // `describe(Button, …)` and `%s` rows of functions, so the page would not find tests that
+        // dev mounts. Dev allows top-level await, which Vite 6's default target rejects.
+        minify: false,
+        target: 'esnext',
+        // Unminified, React's development build alone is above Vite's default limit.
+        chunkSizeWarningLimit: 10_000,
+        ...bundler,
+    };
+}
+/** Runs `build` with `NODE_ENV=development`, as on the dev server, and puts back what was there. */
+async function inDevelopment(build) {
+    const previous = process.env.NODE_ENV;
+    process.env.NODE_ENV = 'development';
+    try {
+        return await build();
+    }
+    finally {
+        if (previous === undefined) {
+            delete process.env.NODE_ENV;
+        }
+        else {
+            process.env.NODE_ENV = previous;
+        }
+    }
+}
+/**
+ * Builds the live preview into `outDir` as static files: `live.html`, the
+ * setup files and a lazy import of each test file, with a relative base, so
+ * it works under any path of a static host. It loads the project's config
+ * the way `createLiveServer()` does, with the project's own Vite, and builds
+ * the page the dev server serves. When the project's describeMe() has
+ * `live: false`, it writes nothing and rejects with an error whose `code` is
+ * `DESCRIBE_ME_LIVE_OFF`.
+ */
+export async function buildLive(options) {
+    // Vite 8 takes the real path of the root, and the page must lie under it to land in outDir.
+    const root = realpathSync(resolve(options.root));
+    const configFile = options.configFile === undefined ? findLiveConfigFile(root) : resolve(root, options.configFile);
+    const testFiles = liveTestFiles(options.testFiles, root);
+    const vite = await importLiveVite(root);
+    const loaded = await loadLiveConfig(vite, configFile, root);
+    const configName = relative(root, configFile) || configFile;
+    let protocol = 0;
+    const config = vite.mergeConfig(loaded.config, {
+        root,
+        mode: 'test',
+        base: './',
+        logLevel: 'warn',
+        clearScreen: false,
+    });
+    // Dev never reads the project's build section, nor runs its build-only plugins.
+    config.build = liveBuildOptions(vite.version, root, options.outDir);
+    config.plugins = [
+        ...(await liveProjectPlugins(loaded.config.plugins)),
+        liveBuildPlugin({
+            configName,
+            testFiles,
+            onProtocol: (value) => {
+                protocol = value;
+            },
+        }),
+    ];
+    await inDevelopment(() => vite.build({ ...config, configFile: false }));
+    return { protocol };
+}

package/dist/check-live-enabled.d.ts

@@ -0,0 +1,3 @@
+import type { Vite } from 'vitest/node';
+/** Throws with the code `DESCRIBE_ME_LIVE_OFF` when the project's describeMe() has `live: false`. */
+export declare function checkLiveEnabled(plugins: readonly Vite.Plugin[], configName: string): void;

package/dist/check-live-enabled.js

@@ -0,0 +1,10 @@
+/** The code of the error for a project whose describeMe() has `live: false`. */
+const LIVE_OFF = 'DESCRIBE_ME_LIVE_OFF';
+/** Throws with the code `DESCRIBE_ME_LIVE_OFF` when the project's describeMe() has `live: false`. */
+export function checkLiveEnabled(plugins, configName) {
+    const plugin = plugins.find((candidate) => candidate.name === 'describe-me');
+    if (plugin?.api?.live?.enabled !== false) {
+        return;
+    }
+    throw Object.assign(new Error(`describe-me: live: false in ${configName} switches the live preview off`), { code: LIVE_OFF });
+}

package/dist/collect-live-suites.d.ts

@@ -0,0 +1,7 @@
+import type { LiveSuite } from './live-suite.js';
+/**
+ * Runs the factories of the registered suites once the test file has
+ * imported, as Vitest collects: depth first in registration order, each one
+ * awaited. A factory's own `describe` calls are collected after it returns.
+ */
+export declare function collectLiveSuites(suite?: LiveSuite): Promise<void>;

package/dist/collect-live-suites.js

@@ -0,0 +1,25 @@
+import { liveRegistry } from './live-registry.js';
+/**
+ * Runs the factories of the registered suites once the test file has
+ * imported, as Vitest collects: depth first in registration order, each one
+ * awaited. A factory's own `describe` calls are collected after it returns.
+ */
+export async function collectLiveSuites(suite = liveRegistry().root) {
+    const registry = liveRegistry();
+    for (const child of suite.children) {
+        if (child.kind !== 'suite') {
+            continue;
+        }
+        if (child.factory !== undefined) {
+            const previous = registry.current;
+            registry.current = child;
+            try {
+                await child.factory();
+            }
+            finally {
+                registry.current = previous;
+            }
+        }
+        await collectLiveSuites(child);
+    }
+}

package/dist/create-live-server.d.ts

@@ -0,0 +1,29 @@
+/** Where the live preview finds the project. */
+export interface LiveServerOptions {
+    /** The project root. */
+    root: string;
+    /**
+     * The Vitest config file, relative to `root` or absolute. Default: the one
+     * Vitest picks, the first `vitest.config.*`, then `vite.config.*`.
+     */
+    configFile?: string;
+    /** The port on localhost. Default: a free one. */
+    port?: number;
+}
+/** A running live preview server. */
+export interface LiveServer {
+    /** The URL the live page is under, such as `http://localhost:5173/__describe-me/`. */
+    base: string;
+    /** `api.live.protocol` of the project's describeMe() plugin. */
+    protocol: number;
+    /** Stops the server. */
+    close(): Promise<void>;
+}
+/**
+ * Starts the live preview: a second Vite dev server on the project's own
+ * config, in mode `test` and on localhost only, whose page mounts one test
+ * at a time. A change to the config file takes a new server. When the
+ * project's describeMe() has `live: false`, it closes the server and rejects
+ * with an error whose `code` is `DESCRIBE_ME_LIVE_OFF`.
+ */
+export declare function createLiveServer(options: LiveServerOptions): Promise<LiveServer>;

package/dist/create-live-server.js

@@ -0,0 +1,55 @@
+import { relative, resolve } from 'node:path';
+import { checkLiveEnabled } from './check-live-enabled.js';
+import { findLiveConfigFile } from './find-live-config-file.js';
+import { freeLivePort } from './free-live-port.js';
+import { importLiveVite } from './import-live-vite.js';
+import { livePluginProtocol } from './live-plugin-protocol.js';
+import { loadLiveConfig } from './load-live-config.js';
+/** Closes the server when `run` throws, so a failed start leaves no server behind. */
+async function closingOnError(server, run) {
+    try {
+        return await run();
+    }
+    catch (error) {
+        await server.close();
+        throw error;
+    }
+}
+/**
+ * Starts the live preview: a second Vite dev server on the project's own
+ * config, in mode `test` and on localhost only, whose page mounts one test
+ * at a time. A change to the config file takes a new server. When the
+ * project's describeMe() has `live: false`, it closes the server and rejects
+ * with an error whose `code` is `DESCRIBE_ME_LIVE_OFF`.
+ */
+export async function createLiveServer(options) {
+    const root = resolve(options.root);
+    const configFile = options.configFile === undefined ? findLiveConfigFile(root) : resolve(root, options.configFile);
+    const vite = await importLiveVite(root);
+    const loaded = await loadLiveConfig(vite, configFile, root);
+    const port = options.port ?? (await freeLivePort());
+    // With `configFile: false` Vite does not watch the config. An edit would
+    // restart the server and run the config again without the flag, in recording mode.
+    const server = await vite.createServer({
+        ...vite.mergeConfig(loaded.config, {
+            root,
+            mode: 'test',
+            base: '/',
+            clearScreen: false,
+            logLevel: 'warn',
+            server: { host: 'localhost', port, strictPort: true, open: false },
+        }),
+        configFile: false,
+    });
+    const configName = relative(root, configFile) || configFile;
+    const { plugins } = server.config;
+    const protocol = await closingOnError(server, () => livePluginProtocol(plugins, configName));
+    await closingOnError(server, () => checkLiveEnabled(plugins, configName));
+    await closingOnError(server, () => server.listen());
+    const local = server.resolvedUrls?.local[0] ?? `http://localhost:${port}/`;
+    return {
+        base: new URL('__describe-me/', local).href,
+        protocol,
+        close: () => server.close(),
+    };
+}

package/dist/detect-environment.d.ts

@@ -0,0 +1,4 @@
+import type { ViteUserConfig } from 'vitest/config';
+import type { DescribeMeEnvironment } from './plugin.js';
+/** The environment the tests run in, when the `environment` option does not say. */
+export declare function detectEnvironment(userConfig: ViteUserConfig): DescribeMeEnvironment;

package/dist/detect-environment.js

@@ -0,0 +1,4 @@
+/** The environment the tests run in, when the `environment` option does not say. */
+export function detectEnvironment(userConfig) {
+    return userConfig.test?.browser?.enabled ? 'browser' : 'dom';
+}

package/dist/dom-profile.d.ts

@@ -0,0 +1,3 @@
+import type { EnvironmentProfile } from './environment-profile.js';
+/** DOM environments such as jsdom, where tests render through Testing Library. */
+export declare const domProfile: EnvironmentProfile;

package/dist/dom-profile.js

@@ -0,0 +1,39 @@
+import { styledComponentsBrowserBuild } from './styled-components-browser-build.js';
+/** DOM environments such as jsdom, where tests render through Testing Library. */
+export const domProfile = {
+    renderModules: {
+        react: {
+            original: '@testing-library/react',
+            adapter: '@describe-me/react/testing-library',
+            live: '@describe-me/react/live-testing-library',
+        },
+    },
+    setupFile: '@describe-me/vitest/setup-dom',
+    configFor({ userConfig, options }) {
+        const build = options.styledComponentsBrowserBuild === false
+            ? undefined
+            : styledComponentsBrowserBuild(userConfig.root ?? process.cwd());
+        const userTest = userConfig.test;
+        const test = {
+            // Testing Library would otherwise unmount in its own afterEach, before the
+            // closing frame is taken. The adapter unmounts through the recorder instead.
+            env: { RTL_SKIP_AUTO_CLEANUP: 'true' },
+        };
+        // Vitest stubs CSS imports by default, which would leave every imported
+        // stylesheet out of the snapshots. An explicit choice by the user wins.
+        if (userTest?.css === undefined) {
+            test.css = true;
+        }
+        else if (userTest.css === false) {
+            console.warn('describe-me: `test.css` is false, so imported stylesheets are stubbed and will be missing from the snapshots.');
+        }
+        if (!build) {
+            return { config: { test }, setupWarnings: [] };
+        }
+        console.info('describe-me: using the browser build of styled-components, for createGlobalStyle');
+        return {
+            config: { resolve: build.config.resolve, test: { ...test, ...build.config.test } },
+            setupWarnings: build.warning ? [build.warning] : [],
+        };
+    },
+};

package/dist/environment-profile.d.ts

@@ -0,0 +1,35 @@
+import type { ViteUserConfig } from 'vitest/config';
+import type { DescribeMeOptions } from './plugin.js';
+/** The render module tests import, and the modules that replace it. */
+export interface RenderModule {
+    /** The module tests import `render` from. */
+    original: string;
+    /** Our recording adapter for it. */
+    adapter: string;
+    /** The live preview's stand-in for it, which mounts at the first render and stops the test. */
+    live: string;
+}
+/** What the plugin hands a profile when it asks for its config. */
+export interface ProfileContext {
+    userConfig: ViteUserConfig;
+    options: DescribeMeOptions;
+    renderModule: RenderModule;
+}
+/** One environment's config, and the setup problems found while building it. */
+export interface ProfileConfig {
+    config: ViteUserConfig;
+    /** Handed to the reporter, which writes them to the manifest. */
+    setupWarnings: string[];
+}
+/**
+ * Everything describe-me does differently in one environment. The plugin
+ * picks a profile and adds what every environment shares.
+ */
+export interface EnvironmentProfile {
+    /** For each framework, the render module tests import and our adapter for it. */
+    renderModules: Record<NonNullable<DescribeMeOptions['framework']>, RenderModule>;
+    /** The setup file that patches interactions and registers the recording hooks. */
+    setupFile: string;
+    /** The rest of the environment's config, built in the plugin's `config` hook. */
+    configFor(context: ProfileContext): ProfileConfig;
+}

package/dist/environment-profile.js

@@ -0,0 +1 @@
+export {};

package/dist/find-live-config-file.d.ts

@@ -0,0 +1,2 @@
+/** The config file Vitest picks in `root` when none is named: `vitest.config.*`, then `vite.config.*`. */
+export declare function findLiveConfigFile(root: string): string;

package/dist/find-live-config-file.js

@@ -0,0 +1,16 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+const NAMES = ['vitest.config', 'vite.config'];
+const EXTENSIONS = ['ts', 'mts', 'cts', 'js', 'mjs', 'cjs'];
+/** The config file Vitest picks in `root` when none is named: `vitest.config.*`, then `vite.config.*`. */
+export function findLiveConfigFile(root) {
+    for (const name of NAMES) {
+        for (const extension of EXTENSIONS) {
+            const file = join(root, `${name}.${extension}`);
+            if (existsSync(file)) {
+                return file;
+            }
+        }
+    }
+    throw new Error(`describe-me: no Vitest or Vite config file in ${root}`);
+}

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

@@ -0,0 +1,13 @@
+import type { LiveSuite, LiveTest } from './live-suite.js';
+/** A registered test, with the suites around it from the root down. */
+export interface LiveTestMatch {
+    test: LiveTest;
+    suites: LiveSuite[];
+    /** The suite names, outermost first, then the test name. The root has no name. */
+    path: string[];
+}
+/**
+ * The `occurrence`-th test whose suite path and name equal `path`, counted
+ * 1-based over the whole file like the stable test id, or null.
+ */
+export declare function findLiveTest(path: string[], occurrence: number): LiveTestMatch | null;

package/dist/find-live-test.js

@@ -0,0 +1,31 @@
+import { liveRegistry } from './live-registry.js';
+/** Every test, depth first in registration order, the order Vitest reports them in. */
+function* testsIn(suite, suites, names) {
+    for (const child of suite.children) {
+        if (child.kind === 'test') {
+            yield { test: child, suites, path: [...names, child.name] };
+        }
+        else {
+            yield* testsIn(child, [...suites, child], [...names, child.name]);
+        }
+    }
+}
+/**
+ * The `occurrence`-th test whose suite path and name equal `path`, counted
+ * 1-based over the whole file like the stable test id, or null.
+ */
+export function findLiveTest(path, occurrence) {
+    const root = liveRegistry().root;
+    const wanted = JSON.stringify(path);
+    let seen = 0;
+    for (const match of testsIn(root, [root], [])) {
+        if (JSON.stringify(match.path) !== wanted) {
+            continue;
+        }
+        seen += 1;
+        if (seen === occurrence) {
+            return match;
+        }
+    }
+    return null;
+}

package/dist/free-live-port.d.ts

@@ -0,0 +1,5 @@
+/**
+ * A port that is free on localhost right now. Older Vite majors keep `port: 0`
+ * in their resolved config, which breaks the address HMR falls back to.
+ */
+export declare function freeLivePort(): Promise<number>;