@describe-me/vitest 0.5.3 → 0.6.0

package/dist/free-live-port.js

@@ -0,0 +1,16 @@
+import { createServer } from 'node:net';
+/**
+ * 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 function freeLivePort() {
+    return new Promise((resolvePort, reject) => {
+        const probe = createServer();
+        probe.once('error', reject);
+        probe.listen(0, 'localhost', () => {
+            const address = probe.address();
+            const port = typeof address === 'object' && address !== null ? address.port : 0;
+            probe.close(() => resolvePort(port));
+        });
+    });
+}

package/dist/import-live-vite.d.ts

@@ -0,0 +1,7 @@
+import type { Vite } from 'vitest/node';
+/**
+ * The project's own Vite, so its plugins run on the version they were made
+ * for. Always the ES module build: `require.resolve('vite')` can pick the
+ * CommonJS one of older majors.
+ */
+export declare function importLiveVite(root: string): Promise<typeof Vite>;

package/dist/import-live-vite.js

@@ -0,0 +1,46 @@
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+/** The `package.json` of the project's Vite, or of the Vite its Vitest runs on. */
+function vitePackageJson(root) {
+    const projectRequire = createRequire(join(root, 'package.json'));
+    try {
+        return projectRequire.resolve('vite/package.json');
+    }
+    catch {
+        // Not a direct dependency of the project. Vitest's own Vite runs the tests.
+    }
+    try {
+        const vitest = projectRequire.resolve('vitest/package.json');
+        return createRequire(vitest).resolve('vite/package.json');
+    }
+    catch {
+        throw new Error(`describe-me: cannot find vite from ${root}`);
+    }
+}
+/** The ES module entry of `exports['.']`: its `import` condition, or the string itself. */
+function esmEntry(target) {
+    if (typeof target === 'string') {
+        return target;
+    }
+    if (typeof target !== 'object' || target === null) {
+        return null;
+    }
+    const conditions = target;
+    return esmEntry(conditions.import ?? conditions.default);
+}
+/**
+ * The project's own Vite, so its plugins run on the version they were made
+ * for. Always the ES module build: `require.resolve('vite')` can pick the
+ * CommonJS one of older majors.
+ */
+export async function importLiveVite(root) {
+    const packageJson = vitePackageJson(root);
+    const { exports } = JSON.parse(readFileSync(packageJson, 'utf8'));
+    const entry = esmEntry(exports?.['.']);
+    if (entry === null) {
+        throw new Error(`describe-me: cannot find the ES module entry of vite in ${packageJson}`);
+    }
+    return (await import(pathToFileURL(join(dirname(packageJson), entry)).href));
+}

package/dist/install-live-globals.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Puts the shimmed globals on `globalThis`, as `test.globals` does. It runs
+ * before the test file imports, so Testing Library finds the hooks too.
+ */
+export declare function installLiveGlobals(): void;

package/dist/install-live-globals.js

@@ -0,0 +1,33 @@
+import { liveExport } from './live-export.js';
+/** The names Vitest puts on `globalThis` with `test.globals`. */
+const GLOBALS = [
+    'suite',
+    'test',
+    'describe',
+    'it',
+    'chai',
+    'expect',
+    'assert',
+    'expectTypeOf',
+    'assertType',
+    'vitest',
+    'vi',
+    'beforeAll',
+    'afterAll',
+    'beforeEach',
+    'afterEach',
+    'onTestFinished',
+    'onTestFailed',
+    'aroundEach',
+    'aroundAll',
+];
+/**
+ * Puts the shimmed globals on `globalThis`, as `test.globals` does. It runs
+ * before the test file imports, so Testing Library finds the hooks too.
+ */
+export function installLiveGlobals() {
+    const scope = globalThis;
+    for (const name of GLOBALS) {
+        scope[name] = liveExport('vitest', name);
+    }
+}

package/dist/is-adapter-module.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Whether a module is one of the adapter's own files, whose imports of the
+ * original module must stay unredirected. `/node_modules/<package>/` is the
+ * fallback for when the project root could not resolve the package.
+ */
+export declare function isAdapterModule(id: string, adapterRoot: string | null, adapterPackage: string): boolean;

package/dist/is-adapter-module.js

@@ -0,0 +1,11 @@
+/**
+ * Whether a module is one of the adapter's own files, whose imports of the
+ * original module must stay unredirected. `/node_modules/<package>/` is the
+ * fallback for when the project root could not resolve the package.
+ */
+export function isAdapterModule(id, adapterRoot, adapterPackage) {
+    if (adapterRoot !== null && id.startsWith(adapterRoot)) {
+        return true;
+    }
+    return id.includes(`/node_modules/${adapterPackage}/`);
+}

package/dist/live-arg-label.d.ts

@@ -0,0 +1,5 @@
+/**
+ * A short label for one argument of a mock call, such as `"Rename"`,
+ * `click event`, `<button>` or `ƒ onClose`, for the viewer's list of actions.
+ */
+export declare function liveArgLabel(value: unknown): string;

package/dist/live-arg-label.js

@@ -0,0 +1,38 @@
+const MAX_LENGTH = 80;
+function cut(text) {
+    return text.length > MAX_LENGTH ? `${text.slice(0, MAX_LENGTH)}…` : text;
+}
+/** A DOM event, or one of React's synthetic events, which carry the native one. */
+function isEvent(value) {
+    if (value instanceof Event) {
+        return true;
+    }
+    return 'nativeEvent' in value && typeof value.type === 'string';
+}
+/**
+ * A short label for one argument of a mock call, such as `"Rename"`,
+ * `click event`, `<button>` or `ƒ onClose`, for the viewer's list of actions.
+ */
+export function liveArgLabel(value) {
+    if (typeof value === 'string') {
+        return JSON.stringify(cut(value));
+    }
+    if (typeof value === 'function') {
+        return `ƒ ${value.name || 'anonymous'}`;
+    }
+    if (typeof value !== 'object' || value === null) {
+        return String(value);
+    }
+    if (isEvent(value)) {
+        return `${value.type} event`;
+    }
+    if (value instanceof Element) {
+        return `<${value.tagName.toLowerCase()}>`;
+    }
+    try {
+        return cut(JSON.stringify(value));
+    }
+    catch {
+        return Array.isArray(value) ? '[…]' : '{…}';
+    }
+}

package/dist/live-build-plugin.d.ts

@@ -0,0 +1,18 @@
+import type { Vite } from 'vitest/node';
+/** What the plugin of a live build takes from `buildLive()`. */
+export interface LiveBuildPluginOptions {
+    /** How messages name the config file. */
+    configName: string;
+    /** The test files of the map, as paths from the root with `/`. */
+    testFiles: string[];
+    /** Takes the live protocol of the project's describeMe() plugin, once the config is resolved. */
+    onProtocol(protocol: number): void;
+}
+/**
+ * The plugin `buildLive()` adds after the project's own. It runs the checks
+ * of `createLiveServer()` before anything is bundled, loads the map of test
+ * files, and stands in for each import of a project file that does not load
+ * in the browser, such as `node:fs`. A stand-in throws when it runs, so only
+ * the test files and setup files that import it fail, and the build goes on.
+ */
+export declare function liveBuildPlugin(options: LiveBuildPluginOptions): Vite.Plugin;

package/dist/live-build-plugin.js

@@ -0,0 +1,89 @@
+import { relative } from 'node:path';
+import { checkLiveEnabled } from './check-live-enabled.js';
+import { LIVE_MODULE_IDS } from './live-module-ids.js';
+import { livePluginProtocol } from './live-plugin-protocol.js';
+import { liveStringLiteral } from './live-string-literal.js';
+import { liveTestFilesSource } from './live-test-files-source.js';
+// The specifier stays in the id and the reason does not, so chunk names stay plain.
+const UNLOADABLE = '\0describe-me-live:unloadable:';
+// Vite's stand-in for a Node module in a browser build.
+const BROWSER_EXTERNAL = '__vite-browser-external';
+const NODE_MODULES = /[\\/]node_modules[\\/]/;
+function isProjectModule(importer) {
+    return importer !== undefined && !importer.startsWith('\0') && !NODE_MODULES.test(importer);
+}
+function firstLine(error) {
+    return (error instanceof Error ? error.message : String(error)).split('\n')[0];
+}
+/** Whether a log is the bundler's note that it shimmed an export of a stand-in. */
+function isShimmedStandIn(log) {
+    const text = `${log.message} ${log.exporter ?? ''} ${log.id ?? ''}`;
+    return /shimmed/i.test(log.message) && text.includes(UNLOADABLE.slice(1));
+}
+/**
+ * The plugin `buildLive()` adds after the project's own. It runs the checks
+ * of `createLiveServer()` before anything is bundled, loads the map of test
+ * files, and stands in for each import of a project file that does not load
+ * in the browser, such as `node:fs`. A stand-in throws when it runs, so only
+ * the test files and setup files that import it fail, and the build goes on.
+ */
+export function liveBuildPlugin(options) {
+    const reasons = new Map();
+    const warned = new Set();
+    let root = '';
+    let logger = null;
+    function warnOnce(importer, specifier, reason) {
+        const key = JSON.stringify([importer, specifier]);
+        if (warned.has(key)) {
+            return;
+        }
+        warned.add(key);
+        logger?.warn(`describe-me: ${relative(root, importer)} imports ${specifier}, which does not load in the browser: ${reason}`);
+    }
+    return {
+        name: 'describe-me:live-build',
+        enforce: 'pre',
+        configResolved(config) {
+            options.onProtocol(livePluginProtocol(config.plugins, options.configName));
+            checkLiveEnabled(config.plugins, options.configName);
+            root = config.root;
+            logger = config.logger;
+        },
+        async resolveId(source, importer, resolveOptions) {
+            if (!isProjectModule(importer)) {
+                return null;
+            }
+            let reason;
+            try {
+                const resolved = await this.resolve(source, importer, { ...resolveOptions, skipSelf: true });
+                if (resolved !== null && !resolved.id.startsWith(BROWSER_EXTERNAL)) {
+                    return resolved;
+                }
+                reason = resolved === null ? 'it cannot be resolved' : 'it is a Node module';
+            }
+            catch (error) {
+                reason = firstLine(error);
+            }
+            const id = `${UNLOADABLE}${source}`;
+            reasons.set(id, reason);
+            warnOnce(importer, source, reason);
+            return id;
+        },
+        load(id) {
+            if (id === LIVE_MODULE_IDS.testFiles) {
+                return liveTestFilesSource(options.testFiles);
+            }
+            const reason = reasons.get(id);
+            if (reason === undefined) {
+                return null;
+            }
+            const message = `${id.slice(UNLOADABLE.length)} does not load in the browser: ${reason}`;
+            return { code: `throw new Error(${liveStringLiteral(message)})\n`, moduleSideEffects: true };
+        },
+        onLog(level, log) {
+            if (level === 'warn' && isShimmedStandIn(log)) {
+                return false;
+            }
+        },
+    };
+}

package/dist/live-each-name.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The name of one row of `each` or `for`, a port of Vitest's `formatTitle`
+ * with its quirks, because the manifest holds the names Vitest gave. Vitest 5
+ * and 4 differ in how they print values, so `vitestMajor` picks the rules.
+ */
+export declare function liveEachName(template: string, items: unknown[], index: number, vitestMajor: number): string;

package/dist/live-each-name.js

@@ -0,0 +1,146 @@
+import { liveFormatPlaceholder } from './live-format-placeholder.js';
+import { liveInspect } from './live-inspect.js';
+import { liveLoupeInspect } from './live-loupe-inspect.js';
+const PLACEHOLDER = /%[sdjifoOc%]/g;
+const ARRAY_KEY = /^\d+$/;
+// `taskTitleValueFormatTruncate` in Vitest 5, `chaiConfig.truncateThreshold` in Vitest 4.
+const TRUNCATE = 40;
+function isObject(item) {
+    return item !== null && item !== undefined && typeof item === 'object' && !Array.isArray(item);
+}
+function isNegativeNaN(value) {
+    if (!Number.isNaN(value)) {
+        return false;
+    }
+    const float = new Float64Array(1);
+    float[0] = value;
+    return new Uint32Array(float.buffer)[1] >>> 31 === 1;
+}
+/** Vitest's `objectAttr`: a property path such as `a.b` or `a[0]`, or `fallback` where it ends. */
+function objectAttr(source, path, fallback) {
+    const parts = path.replace(/\[(\d+)\]/g, '.$1').split('.');
+    let result = source;
+    for (const part of parts) {
+        result = Object(result)[part];
+        if (result === undefined) {
+            return fallback;
+        }
+    }
+    return result;
+}
+/** Vitest 5's `truncateString`. */
+function truncateString(text, maxLength) {
+    if (text.length <= maxLength) {
+        return text;
+    }
+    let end = maxLength - 1;
+    const before = text[end - 1];
+    if (before >= '\ud800' && before <= '\udbff') {
+        end -= 1;
+    }
+    return `${text.slice(0, end)}…`;
+}
+/** Vitest 4's `objDisplay`: loupe's output, or a summary once it reaches the threshold. */
+function objDisplay(value) {
+    const text = liveLoupeInspect(value, TRUNCATE);
+    if (text.length < TRUNCATE) {
+        return text;
+    }
+    const tag = Object.prototype.toString.call(value);
+    if (tag === '[object Function]') {
+        const { name } = value;
+        return name ? `[Function: ${name}]` : '[Function]';
+    }
+    if (tag === '[object Array]') {
+        return `[ Array(${value.length}) ]`;
+    }
+    if (tag === '[object Object]') {
+        const keys = Object.keys(value);
+        const shown = keys.length > 2 ? `${keys.splice(0, 2).join(', ')}, ...` : keys.join(', ');
+        return `{ Object (${shown}) }`;
+    }
+    return text;
+}
+const VITEST_5 = {
+    key: /\$([$\p{ID_Continue}.]+)/gu,
+    display: (value) => typeof value === 'string' ? truncateString(value, TRUNCATE) : liveInspect(value, TRUNCATE),
+    inspect: (value) => liveInspect(value, TRUNCATE),
+};
+const VITEST_4 = {
+    key: /\$([$\w.]+)/g,
+    display: objDisplay,
+    inspect: (value) => liveLoupeInspect(value, Number.POSITIVE_INFINITY),
+};
+/** `%#` and `%$`, the 0-based and 1-based row index, go in before any value. */
+function withIndex(template, index) {
+    if (!template.includes('%#') && !template.includes('%$')) {
+        return template;
+    }
+    return template
+        .replace(/%%/g, '__vitest_escaped_%__')
+        .replace(/%#/g, `${index}`)
+        .replace(/%\$/g, `${index + 1}`)
+        .replace(/__vitest_escaped_%__/g, '%%');
+}
+/** Vitest puts a `-` before the i-th `%f` when the i-th value, not that `%f`'s own, is -0 or a negative NaN. */
+function withNegativeFloats(template, items) {
+    if (!template.includes('%f')) {
+        return template;
+    }
+    let result = template;
+    const placeholders = template.match(/%f/g) ?? [];
+    placeholders.forEach((_, i) => {
+        if (isNegativeNaN(items[i]) || Object.is(items[i], -0)) {
+            let occurrence = 0;
+            result = result.replace(/%f/g, (match) => {
+                occurrence += 1;
+                return occurrence === i + 1 ? '-%f' : match;
+            });
+        }
+    });
+    return result;
+}
+/** `$key`, `$a.b` and `$0` outside the placeholders. */
+function withKeys(text, items, rules) {
+    const isObjectItem = isObject(items[0]);
+    return text.replace(rules.key, (_, key) => {
+        const isArrayKey = ARRAY_KEY.test(key);
+        if (!isObjectItem && !isArrayKey) {
+            return `$${key}`;
+        }
+        const arrayElement = isArrayKey ? objectAttr(items, key) : undefined;
+        const value = isObjectItem ? objectAttr(items[0], key, arrayElement) : arrayElement;
+        return rules.display(value);
+    });
+}
+/**
+ * The name of one row of `each` or `for`, a port of Vitest's `formatTitle`
+ * with its quirks, because the manifest holds the names Vitest gave. Vitest 5
+ * and 4 differ in how they print values, so `vitestMajor` picks the rules.
+ */
+export function liveEachName(template, items, index, vitestMajor) {
+    const rules = vitestMajor >= 5 ? VITEST_5 : VITEST_4;
+    const indexed = withIndex(template, index);
+    const count = indexed.split('%').length - 1;
+    const named = withNegativeFloats(indexed, items);
+    let output = '';
+    let next = 0;
+    let end = 0;
+    for (const match of named.matchAll(PLACEHOLDER)) {
+        if (end < match.index) {
+            output += withKeys(named.slice(end, match.index), items, rules);
+        }
+        if (next < count) {
+            output += liveFormatPlaceholder(match[0], items[next], rules.inspect);
+            next += 1;
+        }
+        else {
+            output += match[0];
+        }
+        end = match.index + match[0].length;
+    }
+    if (end < named.length) {
+        output += withKeys(named.slice(end), items, rules);
+    }
+    return output;
+}

package/dist/live-entry-source.d.ts

@@ -0,0 +1,9 @@
+import type { LivePageSettings } from './live-page-settings.js';
+/**
+ * The source of the live page's entry. On the dev server the `import()` of
+ * the test file stays here, in a module of the project's server, so it loads
+ * from the server. A build imports it from the map of lazy imports, so the
+ * bundler sees every test file. Setup files are literal imports, so Vite
+ * resolves them and a build bundles them.
+ */
+export declare function liveEntrySource(settings: Pick<LivePageSettings, 'globals' | 'testTimeout' | 'setupFiles' | 'vitestMajor'>, command: 'serve' | 'build'): string;

package/dist/live-entry-source.js

@@ -0,0 +1,46 @@
+import { LIVE_MODULE_IDS } from './live-module-ids.js';
+import { liveStringLiteral } from './live-string-literal.js';
+/**
+ * The `importTest` of the dev server's entry. It imports an absolute URL:
+ * Vite adds `?import` to a path from the root, and the static self-import
+ * that `@vitejs/plugin-react` adds to a file with a component would then load
+ * the test file a second time.
+ */
+const SERVE_IMPORT_TEST = [
+    `  importTest: (file) => import(/* @vite-ignore */ new URL('/' + file, location.origin).href),`,
+];
+/** The `importTest` of a build, which holds only the test files of its map. */
+const BUILD_IMPORT_TEST = [
+    '  importTest: (file) =>',
+    '    Object.hasOwn(testFiles, file)',
+    '      ? testFiles[file]()',
+    '      : Promise.reject(new Error(`${file} is not in this build`)),',
+];
+/**
+ * The source of the live page's entry. On the dev server the `import()` of
+ * the test file stays here, in a module of the project's server, so it loads
+ * from the server. A build imports it from the map of lazy imports, so the
+ * bundler sees every test file. Setup files are literal imports, so Vite
+ * resolves them and a build bundles them.
+ */
+export function liveEntrySource(settings, command) {
+    const setupFiles = settings.setupFiles.map((setupFile) => `    { file: ${liveStringLiteral(setupFile.name)}, load: () => import(${liveStringLiteral(setupFile.specifier)}) },`);
+    const testFilesImport = command === 'build'
+        ? [`import testFiles from ${liveStringLiteral(LIVE_MODULE_IDS.testFiles)}`]
+        : [];
+    return [
+        `import { startLivePage } from '@describe-me/vitest/live-runtime'`,
+        ...testFilesImport,
+        '',
+        'startLivePage({',
+        ...(command === 'build' ? BUILD_IMPORT_TEST : SERVE_IMPORT_TEST),
+        `  globals: ${String(settings.globals)},`,
+        `  testTimeout: ${String(settings.testTimeout)},`,
+        `  vitestMajor: ${String(settings.vitestMajor)},`,
+        '  setupFiles: [',
+        ...setupFiles,
+        '  ],',
+        '})',
+        '',
+    ].join('\n');
+}

package/dist/live-env.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The environment variable that switches `describeMe()` to live mode when it
+ * is `1`. `createLiveServer()` and `buildLive()` set it only while they load
+ * the project's config.
+ */
+export declare const LIVE_ENV = "DESCRIBE_ME_LIVE";

package/dist/live-env.js

@@ -0,0 +1,6 @@
+/**
+ * The environment variable that switches `describeMe()` to live mode when it
+ * is `1`. `createLiveServer()` and `buildLive()` set it only while they load
+ * the project's config.
+ */
+export const LIVE_ENV = 'DESCRIBE_ME_LIVE';

package/dist/live-error-detail.d.ts

@@ -0,0 +1,2 @@
+/** An error's message and the first lines of its stack, for the detail of a status. */
+export declare function liveErrorDetail(error: unknown): string;

package/dist/live-error-detail.js

@@ -0,0 +1,16 @@
+const STACK_LINES = 4;
+/** An error's message and the first lines of its stack, for the detail of a status. */
+export function liveErrorDetail(error) {
+    if (!(error instanceof Error)) {
+        return String(error);
+    }
+    const heading = String(error);
+    const stack = error.stack ?? '';
+    // V8 starts the stack with the heading. Firefox and Safari do not.
+    const frames = (stack.startsWith(heading) ? stack.slice(heading.length) : stack)
+        .split('\n')
+        .map((line) => line.trim())
+        .filter((line) => line !== '')
+        .slice(0, STACK_LINES);
+    return [heading, ...frames].join('\n');
+}

package/dist/live-export.d.ts

@@ -0,0 +1,10 @@
+/** The modules that the live page swaps for shims. */
+type LiveModule = 'vitest' | 'vitest/browser' | '@describe-me/vitest';
+/**
+ * The live page's implementation of one export of a module it swaps for a
+ * shim. The plugin's generated modules call it once per name. A name the shim
+ * does not implement, such as `expect` or one that a newer Vitest adds, gets an
+ * inert value.
+ */
+export declare function liveExport(module: LiveModule, name: string): unknown;
+export {};

package/dist/live-export.js

@@ -0,0 +1,48 @@
+import { liveInert } from '@describe-me/core/live';
+import { liveHook } from './live-hook.js';
+import { liveRegistrar } from './live-registrar.js';
+import { liveStep } from './live-step.js';
+import { liveVi } from './live-vi.js';
+let shims;
+function ignore() {
+    return undefined;
+}
+function createShims() {
+    const describe = liveRegistrar('suite');
+    const it = liveRegistrar('test');
+    const vi = liveVi();
+    return {
+        vitest: {
+            describe,
+            suite: describe,
+            it,
+            test: it,
+            beforeAll: liveHook('beforeAll'),
+            beforeEach: liveHook('beforeEach'),
+            afterEach: liveHook('afterEach'),
+            afterAll: liveHook('afterAll'),
+            aroundEach: liveHook('aroundEach'),
+            aroundAll: liveHook('aroundAll'),
+            onTestFinished: ignore,
+            onTestFailed: ignore,
+            vi,
+            vitest: vi,
+            assertType: ignore,
+            inject: ignore,
+        },
+        // The page never interacts, so all of `vitest/browser` is inert.
+        'vitest/browser': {},
+        '@describe-me/vitest': { step: liveStep },
+    };
+}
+/**
+ * The live page's implementation of one export of a module it swaps for a
+ * shim. The plugin's generated modules call it once per name. A name the shim
+ * does not implement, such as `expect` or one that a newer Vitest adds, gets an
+ * inert value.
+ */
+export function liveExport(module, name) {
+    shims ??= createShims();
+    const shim = shims[module];
+    return Object.hasOwn(shim, name) ? shim[name] : liveInert();
+}

package/dist/live-fixture-props.d.ts

@@ -0,0 +1,12 @@
+/** A callback as written, and which of its parameters destructures the fixtures it uses. */
+export interface LiveFixtureUse {
+    callback: (...args: never[]) => unknown;
+    /** 0 in general, 1 for an `aroundEach` hook and a `for` body. */
+    index: number;
+}
+/**
+ * The fixture names a callback destructures, read from its source the way
+ * Vitest's `getUsedProps` reads them. Throws when the parameter exists but
+ * does not destructure, or uses a rest element, as Vitest does.
+ */
+export declare function liveFixtureProps({ callback, index }: LiveFixtureUse): Set<string>;