@describe-me/vitest 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Grzegorz Łotysz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,47 @@
+# @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/`.
+
+## Install
+
+```sh
+pnpm add -D @describe-me/vitest @describe-me/react describe-me
+```
+
+## Usage
+
+One line in the Vitest config registers the setup file and the reporter, and
+redirects `vitest-browser-react` imports to the recording adapter:
+
+```ts
+import { describeMe } from '@describe-me/vitest/plugin'
+
+export default defineConfig({
+  plugins: [react(), describeMe()],
+  test: {
+    browser: { enabled: true, provider: playwright(), instances: [{ browser: 'chromium' }] },
+  },
+})
+```
+
+The pieces can also be wired by hand, in which case tests import `render` from
+`@describe-me/react` themselves:
+
+```ts
+import DescribeMeReporter from '@describe-me/vitest/reporter'
+
+export default defineConfig({
+  test: {
+    setupFiles: ['@describe-me/vitest/setup'],
+    reporters: ['default', new DescribeMeReporter()],
+  },
+})
+```
+
+`typescript` is an optional peer: without it the docs are still generated, only
+the props tables are left out.
+
+See the [root README](https://github.com/grzehub/describe-me#readme) for the
+full picture.

package/dist/action-label.d.ts

@@ -0,0 +1,2 @@
+/** Build the frame label for an interaction, e.g. `click(button "increment")` or `keyboard("{Escape}")`. */
+export declare function actionLabel(method: string, selector: string | undefined, args: unknown[]): string;

package/dist/action-label.js

@@ -0,0 +1,16 @@
+import { describeArg } from './describe-arg.js';
+import { prettySelector } from './pretty-selector.js';
+/** Build the frame label for an interaction, e.g. `click(button "increment")` or `keyboard("{Escape}")`. */
+export function actionLabel(method, selector, args) {
+    const parts = [];
+    if (selector) {
+        parts.push(prettySelector(selector));
+    }
+    for (const arg of args) {
+        const shown = describeArg(arg);
+        if (shown) {
+            parts.push(shown);
+        }
+    }
+    return `${method}(${parts.join(', ')})`;
+}

package/dist/collect-component-docs-safely.d.ts

@@ -0,0 +1,9 @@
+import type { ComponentDoc } from '@describe-me/core/types';
+import type { ComponentEntry } from './collect-component-docs.js';
+/**
+ * Document the rendered components, unless TypeScript is missing. Props are read
+ * with TypeScript's own compiler, which is an optional peer dependency, so the
+ * collector is imported lazily: a JavaScript-only project gets a warning and no
+ * props tables instead of a crashing reporter.
+ */
+export declare function collectComponentDocsSafely(root: string, entries: Iterable<ComponentEntry>): Promise<Record<string, ComponentDoc>>;

package/dist/collect-component-docs-safely.js

@@ -0,0 +1,25 @@
+let warned = false;
+function warnAboutMissingTypeScript() {
+    if (warned) {
+        return;
+    }
+    warned = true;
+    console.warn('describe-me: typescript is not installed, component props will not be documented');
+}
+/**
+ * Document the rendered components, unless TypeScript is missing. Props are read
+ * with TypeScript's own compiler, which is an optional peer dependency, so the
+ * collector is imported lazily: a JavaScript-only project gets a warning and no
+ * props tables instead of a crashing reporter.
+ */
+export async function collectComponentDocsSafely(root, entries) {
+    try {
+        await import('typescript');
+    }
+    catch {
+        warnAboutMissingTypeScript();
+        return {};
+    }
+    const { collectComponentDocs } = await import('./collect-component-docs.js');
+    return collectComponentDocs(root, entries);
+}

package/dist/collect-component-docs.d.ts

@@ -0,0 +1,12 @@
+import type { ComponentDoc } from '@describe-me/core/types';
+/** A component name as the adapter reported it, and the test module that rendered it. */
+export interface ComponentEntry {
+    testFile: string;
+    componentName: string;
+}
+/**
+ * Document every component the tests rendered: find its source file through the
+ * test's imports, then read its props from TypeScript. One program covers all of
+ * them; a component that cannot be found or read is left out of the result.
+ */
+export declare function collectComponentDocs(root: string, entries: Iterable<ComponentEntry>): Record<string, ComponentDoc>;

package/dist/collect-component-docs.js

@@ -0,0 +1,48 @@
+import { relative, sep } from 'node:path';
+import ts from 'typescript';
+import { extractProps } from './extract-props.js';
+import { loadCompilerOptions } from './load-compiler-options.js';
+import { resolveComponentFile } from './resolve-component-file.js';
+/**
+ * Document every component the tests rendered: find its source file through the
+ * test's imports, then read its props from TypeScript. One program covers all of
+ * them; a component that cannot be found or read is left out of the result.
+ */
+export function collectComponentDocs(root, entries) {
+    const options = loadCompilerOptions(root);
+    const resolved = resolveAll(entries, options);
+    if (resolved.size === 0) {
+        return {};
+    }
+    const files = Array.from(new Set(Array.from(resolved.values(), (found) => found.file)));
+    const program = ts.createProgram(files, options);
+    const docs = {};
+    for (const name of Array.from(resolved.keys()).sort()) {
+        const found = resolved.get(name);
+        const props = extractProps(program, found.file, found.exportName);
+        if (!props) {
+            console.warn(`[describe-me] could not read props of ${name} from ${found.file}`);
+            continue;
+        }
+        docs[name] = { name, file: toPosix(relative(root, found.file)), props };
+    }
+    return docs;
+}
+/** One source file per component name; the same component is looked up once. */
+function resolveAll(entries, options) {
+    const resolved = new Map();
+    for (const entry of entries) {
+        if (resolved.has(entry.componentName)) {
+            continue;
+        }
+        const found = resolveComponentFile(entry.testFile, entry.componentName, options);
+        if (found) {
+            resolved.set(entry.componentName, found);
+        }
+    }
+    return resolved;
+}
+/** The manifest is read in a browser, where paths are posix whatever wrote them. */
+function toPosix(path) {
+    return path.split(sep).join('/');
+}

package/dist/component-entries.d.ts

@@ -0,0 +1,4 @@
+import type { ManifestModule } from '@describe-me/core/types';
+import type { ComponentEntry } from './collect-component-docs.js';
+/** Every component the recorded tests rendered, paired with the module that rendered it. */
+export declare function componentEntries(modules: ManifestModule[], root: string): ComponentEntry[];

package/dist/component-entries.js

@@ -0,0 +1,13 @@
+import { resolve } from 'node:path';
+/** Every component the recorded tests rendered, paired with the module that rendered it. */
+export function componentEntries(modules, root) {
+    const entries = [];
+    for (const mod of modules) {
+        for (const test of mod.tests) {
+            if (test.component) {
+                entries.push({ testFile: resolve(root, mod.id), componentName: test.component.name });
+            }
+        }
+    }
+    return entries;
+}

package/dist/describe-arg.d.ts

@@ -0,0 +1,2 @@
+/** Render one argument of a `userEvent.*` call for the frame label. */
+export declare function describeArg(arg: unknown): string;

package/dist/describe-arg.js

@@ -0,0 +1,26 @@
+import { prettySelector } from './pretty-selector.js';
+/** Render one argument of a `userEvent.*` call for the frame label. */
+export function describeArg(arg) {
+    if (arg == null) {
+        return '';
+    }
+    if (typeof arg === 'string') {
+        return JSON.stringify(arg);
+    }
+    if (typeof arg === 'number' || typeof arg === 'boolean') {
+        return String(arg);
+    }
+    if (typeof arg === 'object') {
+        const candidate = arg;
+        if (typeof candidate.selector === 'string') {
+            return prettySelector(candidate.selector);
+        }
+        if (typeof candidate.tagName === 'string') {
+            const text = (candidate.textContent ?? '').trim().slice(0, 24);
+            return `<${candidate.tagName.toLowerCase()}>${text ? ` "${text}"` : ''}`;
+        }
+        const json = JSON.stringify(arg);
+        return json.length <= 32 ? json : '{…}';
+    }
+    return String(arg);
+}

package/dist/extract-props.d.ts

@@ -0,0 +1,8 @@
+import ts from 'typescript';
+import type { PropDoc } from '@describe-me/core/types';
+/**
+ * Read a component's props from its TypeScript type: one PropDoc per own prop,
+ * with the literal choices and the default from the destructuring pattern.
+ * Returns null when the export is not a callable taking a props object.
+ */
+export declare function extractProps(program: ts.Program, file: string, exportName: string): PropDoc[] | null;

package/dist/extract-props.js

@@ -0,0 +1,168 @@
+import ts from 'typescript';
+/** Type names that mean "renderable children" once TypeScript has printed them. */
+const NODE_TYPE_NAMES = ['ReactNode', 'ReactElement', 'Element'];
+/**
+ * Read a component's props from its TypeScript type: one PropDoc per own prop,
+ * with the literal choices and the default from the destructuring pattern.
+ * Returns null when the export is not a callable taking a props object.
+ */
+export function extractProps(program, file, exportName) {
+    const checker = program.getTypeChecker();
+    const sourceFile = program.getSourceFile(file);
+    if (!sourceFile) {
+        return null;
+    }
+    const component = exportedSymbol(checker, sourceFile, exportName);
+    const declaration = component?.declarations?.[0];
+    if (!component || !declaration) {
+        return null;
+    }
+    const signature = componentSignature(checker, component, declaration);
+    if (!signature) {
+        return null;
+    }
+    // A component that takes no props is still a component, with nothing to list.
+    const [parameter] = signature.parameters;
+    if (!parameter) {
+        return [];
+    }
+    const propsType = checker.getTypeOfSymbolAtLocation(parameter, declaration);
+    const defaults = defaultValues(declaration);
+    return propsType
+        .getProperties()
+        .filter(isDeclaredInProject)
+        .map((prop) => toPropDoc(checker, prop, declaration, defaults));
+}
+/** The exported symbol behind `exportName`, with `export { X } from` aliases followed. */
+function exportedSymbol(checker, sourceFile, exportName) {
+    const moduleSymbol = checker.getSymbolAtLocation(sourceFile);
+    if (!moduleSymbol) {
+        return undefined;
+    }
+    const exported = checker.getExportsOfModule(moduleSymbol).find((sym) => sym.name === exportName);
+    if (exported && exported.flags & ts.SymbolFlags.Alias) {
+        return checker.getAliasedSymbol(exported);
+    }
+    return exported;
+}
+/** The first call signature of the export, or null when it is not callable (not a component). */
+function componentSignature(checker, component, declaration) {
+    const type = checker.getTypeOfSymbolAtLocation(component, declaration);
+    const [signature] = type.getCallSignatures();
+    return signature ?? null;
+}
+/**
+ * Drop props inherited from a library type. `Omit<ButtonHTMLAttributes<…>, …>`
+ * would otherwise contribute hundreds of DOM attributes nobody documents.
+ */
+function isDeclaredInProject(prop) {
+    return (prop.declarations ?? []).some((declaration) => {
+        return !declaration.getSourceFile().fileName.includes('/node_modules/');
+    });
+}
+function toPropDoc(checker, prop, location, defaults) {
+    // An optional prop carries `| undefined`, which says nothing the `required`
+    // flag does not already say and makes every printed type noisier.
+    const type = checker.getNonNullableType(checker.getTypeOfSymbolAtLocation(prop, location));
+    const description = ts.displayPartsToString(prop.getDocumentationComment(checker));
+    const shape = classify(checker, type);
+    return {
+        name: prop.name,
+        type: declaredTypeText(prop) ??
+            checker.typeToString(type, undefined, ts.TypeFormatFlags.NoTruncation),
+        required: !(prop.flags & ts.SymbolFlags.Optional),
+        defaultValue: defaults.get(prop.name),
+        kind: shape.kind,
+        values: shape.values,
+        description: description || undefined,
+    };
+}
+/**
+ * The type as the author wrote it (`ReactNode`), when the prop has an
+ * annotation. The checker would otherwise print the expanded alias, which for
+ * ReactNode is a union longer than the table column.
+ */
+function declaredTypeText(prop) {
+    for (const declaration of prop.declarations ?? []) {
+        if (ts.isPropertySignature(declaration) && declaration.type) {
+            return declaration.type.getText();
+        }
+    }
+    return undefined;
+}
+/** What the viewer can do with a prop: pick from a list, toggle, type a value. */
+function classify(checker, type) {
+    const members = type.isUnion() ? type.types : [type];
+    if (type.flags & ts.TypeFlags.Boolean || members.every(isBooleanLiteral)) {
+        return { kind: 'boolean', values: ['true', 'false'] };
+    }
+    if (members.every(isTextualLiteral)) {
+        return { kind: 'literals', values: members.map(literalText) };
+    }
+    if (type.flags & ts.TypeFlags.NumberLike) {
+        return { kind: 'number' };
+    }
+    if (type.flags & ts.TypeFlags.StringLike) {
+        return { kind: 'string' };
+    }
+    if (type.getCallSignatures().length > 0) {
+        return { kind: 'function' };
+    }
+    const printed = checker.typeToString(type);
+    if (NODE_TYPE_NAMES.some((name) => printed.includes(name))) {
+        return { kind: 'node' };
+    }
+    return { kind: 'other' };
+}
+function isBooleanLiteral(type) {
+    return (type.flags & ts.TypeFlags.BooleanLiteral) !== 0;
+}
+function isTextualLiteral(type) {
+    return type.isStringLiteral() || type.isNumberLiteral();
+}
+/** A literal as it would be written in source: `'sm'` for strings, `3` for numbers. */
+function literalText(type) {
+    if (type.isStringLiteral()) {
+        return `'${type.value}'`;
+    }
+    if (type.isNumberLiteral()) {
+        return String(type.value);
+    }
+    return '';
+}
+/**
+ * Defaults live in the destructuring pattern, not in the type, so they are read
+ * from the source text: `{ size = 'md' }` gives `size` → `'md'`.
+ */
+function defaultValues(declaration) {
+    const defaults = new Map();
+    const parameter = functionOf(declaration)?.parameters[0];
+    if (!parameter || !ts.isObjectBindingPattern(parameter.name)) {
+        return defaults;
+    }
+    for (const element of parameter.name.elements) {
+        if (element.initializer) {
+            defaults.set((element.propertyName ?? element.name).getText(), element.initializer.getText());
+        }
+    }
+    return defaults;
+}
+/** The function behind a component declaration, however it was written. */
+function functionOf(declaration) {
+    if (ts.isFunctionDeclaration(declaration) || ts.isFunctionExpression(declaration)) {
+        return declaration;
+    }
+    if (ts.isVariableDeclaration(declaration) && declaration.initializer) {
+        return asFunction(declaration.initializer);
+    }
+    if (ts.isExportAssignment(declaration)) {
+        return asFunction(declaration.expression);
+    }
+    return undefined;
+}
+function asFunction(expression) {
+    if (ts.isArrowFunction(expression) || ts.isFunctionExpression(expression)) {
+        return expression;
+    }
+    return undefined;
+}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { step, recorder } from '@describe-me/core';

package/dist/index.js

@@ -0,0 +1 @@
+export { step, recorder } from '@describe-me/core';

package/dist/load-compiler-options.d.ts

@@ -0,0 +1,6 @@
+import ts from 'typescript';
+/**
+ * The project's own compiler options, so components are read the way the
+ * project reads them (paths, jsx runtime, module resolution).
+ */
+export declare function loadCompilerOptions(root: string): ts.CompilerOptions;

package/dist/load-compiler-options.js

@@ -0,0 +1,30 @@
+import { dirname } from 'node:path';
+import ts from 'typescript';
+/**
+ * Used when the project has no tsconfig.json. Modern React defaults, so a
+ * component still types correctly instead of failing to parse its JSX.
+ */
+const FALLBACK_OPTIONS = {
+    jsx: ts.JsxEmit.ReactJSX,
+    module: ts.ModuleKind.ESNext,
+    moduleResolution: ts.ModuleResolutionKind.Bundler,
+    strict: true,
+    target: ts.ScriptTarget.ES2022,
+    allowJs: true,
+};
+/**
+ * The project's own compiler options, so components are read the way the
+ * project reads them (paths, jsx runtime, module resolution).
+ */
+export function loadCompilerOptions(root) {
+    const configPath = ts.findConfigFile(root, ts.sys.fileExists);
+    if (!configPath) {
+        return FALLBACK_OPTIONS;
+    }
+    const { config, error } = ts.readConfigFile(configPath, ts.sys.readFile);
+    if (error || !config) {
+        return FALLBACK_OPTIONS;
+    }
+    const parsed = ts.parseJsonConfigFileContent(config, ts.sys, dirname(configPath));
+    return parsed.options;
+}

package/dist/patch-locators.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Wrap every action method of Vitest's `Locator` so that
+ * `screen.getByRole('button').click()` records a frame, exactly like
+ * `userEvent.click()` does. Safe to call more than once.
+ */
+export declare function patchLocators(): void;

package/dist/patch-locators.js

@@ -0,0 +1,54 @@
+import { page } from 'vitest/browser';
+import { actionLabel } from './action-label.js';
+import { recordAction } from './record-action.js';
+/** Locator methods that act on the page. Query methods (`getByRole`, `nth`, ...) are left alone. */
+const ACTION_METHODS = [
+    'click',
+    'dblClick',
+    'tripleClick',
+    'wheel',
+    'clear',
+    'hover',
+    'unhover',
+    'fill',
+    'dropTo',
+    'selectOptions',
+    'upload',
+];
+const PATCHED = Symbol.for('describe-me.patched');
+/** Walk the prototype chain and return the first object that defines `name` itself. */
+function findOwner(start, name) {
+    let current = start;
+    while (current && current !== Object.prototype) {
+        if (Object.prototype.hasOwnProperty.call(current, name)) {
+            return current;
+        }
+        current = Object.getPrototypeOf(current);
+    }
+    return null;
+}
+/**
+ * Wrap every action method of Vitest's `Locator` so that
+ * `screen.getByRole('button').click()` records a frame, exactly like
+ * `userEvent.click()` does. Safe to call more than once.
+ */
+export function patchLocators() {
+    const sample = page.elementLocator(document.body);
+    const prototype = Object.getPrototypeOf(sample);
+    for (const method of ACTION_METHODS) {
+        const owner = findOwner(prototype, method);
+        if (!owner || typeof owner[method] !== 'function') {
+            continue;
+        }
+        const original = owner[method];
+        if (original[PATCHED]) {
+            continue;
+        }
+        const wrapped = function (...args) {
+            const label = actionLabel(method, this.selector, args);
+            return recordAction(label, () => original.apply(this, args));
+        };
+        wrapped[PATCHED] = true;
+        owner[method] = wrapped;
+    }
+}

package/dist/patch-user-event.d.ts

@@ -0,0 +1,2 @@
+/** Wrap the keyboard-level `userEvent` methods in place so each call records a frame. Safe to call more than once. */
+export declare function patchUserEvent(): void;

package/dist/patch-user-event.js

@@ -0,0 +1,25 @@
+import { userEvent } from 'vitest/browser';
+import { actionLabel } from './action-label.js';
+import { recordAction } from './record-action.js';
+/**
+ * `userEvent` methods that do not go through a locator. The element-based ones
+ * (`click`, `fill`, ...) delegate to `Locator` and are covered by `patchLocators`.
+ */
+const KEYBOARD_METHODS = ['type', 'tab', 'keyboard', 'copy', 'cut', 'paste'];
+const PATCHED = Symbol.for('describe-me.patched');
+/** Wrap the keyboard-level `userEvent` methods in place so each call records a frame. Safe to call more than once. */
+export function patchUserEvent() {
+    const target = userEvent;
+    for (const method of KEYBOARD_METHODS) {
+        const original = target[method];
+        if (typeof original !== 'function' || original[PATCHED]) {
+            continue;
+        }
+        const wrapped = (...args) => {
+            const label = actionLabel(method, undefined, args);
+            return recordAction(label, () => original.apply(userEvent, args));
+        };
+        wrapped[PATCHED] = true;
+        target[method] = wrapped;
+    }
+}

package/dist/plugin.d.ts

@@ -0,0 +1,20 @@
+import type { ViteUserConfig } from 'vitest/config';
+export interface DescribeMeOptions {
+    /** Set to false to run the same tests without recording, e.g. for benchmarks. Default: true. */
+    enabled?: boolean;
+    /** Which framework adapter replaces the test-library `render`. Default: 'react'. */
+    framework?: 'react';
+    /** Output directory, relative to the Vitest root. Default: `.describe-me`. */
+    outDir?: string;
+}
+type VitePlugin = NonNullable<ViteUserConfig['plugins']>[number];
+/**
+ * One-line integration: `plugins: [describeMe()]`.
+ *
+ * Registers the setup file and the reporter, and redirects the framework's
+ * `render` import to our adapter so existing tests record frames unchanged.
+ * The adapter itself still needs the real module, so imports coming from
+ * inside it are left alone.
+ */
+export declare function describeMe(options?: DescribeMeOptions): VitePlugin;
+export {};

package/dist/plugin.js

@@ -0,0 +1,55 @@
+import DescribeMeReporter from './reporter.js';
+/** For each framework: the render module tests import, and our adapter that wraps it. */
+const RENDER_MODULES = {
+    react: { original: 'vitest-browser-react', adapter: '@describe-me/react' },
+};
+/**
+ * One-line integration: `plugins: [describeMe()]`.
+ *
+ * Registers the setup file and the reporter, and redirects the framework's
+ * `render` import to our adapter so existing tests record frames unchanged.
+ * The adapter itself still needs the real module, so imports coming from
+ * inside it are left alone.
+ */
+export function describeMe(options = {}) {
+    const { enabled = true, framework = 'react', outDir } = options;
+    const { original, adapter } = RENDER_MODULES[framework];
+    return {
+        name: 'describe-me',
+        enforce: 'pre',
+        config(userConfig) {
+            if (!enabled) {
+                return {};
+            }
+            const reporter = new DescribeMeReporter({ outDir });
+            // Vite concatenates arrays when merging, so only add `default` when the
+            // user has not chosen their own reporters; otherwise they would lose it.
+            const reporters = userConfig.test?.reporters ? [reporter] : ['default', reporter];
+            return {
+                // 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: [adapter, original],
+                },
+                test: {
+                    setupFiles: ['@describe-me/vitest/setup'],
+                    reporters,
+                },
+            };
+        },
+        resolveId(source, importer) {
+            if (!enabled || source !== original) {
+                return null;
+            }
+            const fromAdapter = importer !== undefined &&
+                (importer.includes(adapter) || importer.includes('/packages/react/'));
+            if (fromAdapter) {
+                return null;
+            }
+            return this.resolve(adapter, importer, { skipSelf: true });
+        },
+    };
+}

package/dist/pretty-selector.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Playwright's internal selector, e.g.
+ * `internal:testid=[data-testid="__vitest_0__"s] >> internal:role=button[name="increment"i]`
+ * becomes `button "increment"`.
+ */
+export declare function prettySelector(selector: string): string;

package/dist/pretty-selector.js

@@ -0,0 +1,30 @@
+/**
+ * Playwright's internal selector, e.g.
+ * `internal:testid=[data-testid="__vitest_0__"s] >> internal:role=button[name="increment"i]`
+ * becomes `button "increment"`.
+ */
+export function prettySelector(selector) {
+    const last = selector
+        .split('>>')
+        .map((part) => part.trim())
+        .filter((part) => !part.startsWith('internal:testid'))
+        .pop() ?? selector;
+    const match = /^internal:(\w+)=(.*)$/.exec(last);
+    if (!match) {
+        return last;
+    }
+    const [, kind, rest] = match;
+    const name = /\[name=("[^"]*")[si]?\]/.exec(rest)?.[1];
+    const base = rest.replace(/\[.*$/, '').replace(/[si]$/, '');
+    if (kind === 'role') {
+        return name ? `${base} ${name}` : base;
+    }
+    if (kind === 'text' ||
+        kind === 'label' ||
+        kind === 'placeholder' ||
+        kind === 'alt' ||
+        kind === 'title') {
+        return `${kind} ${base}`;
+    }
+    return last;
+}

package/dist/record-action.d.ts

@@ -0,0 +1,2 @@
+/** Run one user interaction and record a frame for it, but only for the outermost call. */
+export declare function recordAction<T>(label: string, run: () => Promise<T>): Promise<T>;

package/dist/record-action.js

@@ -0,0 +1,22 @@
+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.
+ */
+let 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++;
+    let result;
+    try {
+        result = await run();
+    }
+    finally {
+        depth--;
+    }
+    if (depth === 0) {
+        await recorder.capture('action', label);
+    }
+    return result;
+}

package/dist/reporter.d.ts

@@ -0,0 +1,23 @@
+import type { Reporter, TestModule, Vitest } from 'vitest/node';
+export interface DescribeMeReporterOptions {
+    /** Output directory, relative to the Vitest root. Default: `.describe-me` */
+    outDir?: string;
+}
+export default class DescribeMeReporter implements Reporter {
+    private readonly outDirOption;
+    private root;
+    private outDir;
+    private snapshots;
+    private modules;
+    constructor(options?: DescribeMeReporterOptions);
+    onInit(vitest: Vitest): void;
+    /**
+     * A filtered run (`vitest run Button.test.tsx`) must not wipe the other
+     * modules from the manifest, so start from whatever the last run wrote.
+     * Modules whose file no longer exists are dropped.
+     */
+    private seedFromPreviousRun;
+    onTestModuleEnd(module: TestModule): void;
+    onTestRunEnd(): Promise<void>;
+    private toManifestTest;
+}

package/dist/reporter.js

@@ -0,0 +1,90 @@
+/**
+ * Node-side Vitest reporter. Collects frames from task.meta and writes
+ * `.describe-me/manifest.json` plus one file per snapshot.
+ */
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join, relative, resolve } from 'node:path';
+import { META_KEY, } from '@describe-me/core/types';
+import { collectComponentDocsSafely } from './collect-component-docs-safely.js';
+import { componentEntries } from './component-entries.js';
+import { SnapshotStore } from './snapshot-store.js';
+import { testPath } from './test-path.js';
+export default class DescribeMeReporter {
+    outDirOption;
+    root = process.cwd();
+    outDir = '';
+    snapshots;
+    modules = new Map();
+    constructor(options = {}) {
+        this.outDirOption = options.outDir ?? '.describe-me';
+    }
+    onInit(vitest) {
+        this.root = vitest.config.root;
+        this.outDir = resolve(this.root, this.outDirOption);
+        this.snapshots = new SnapshotStore(this.outDir);
+        this.seedFromPreviousRun();
+    }
+    /**
+     * A filtered run (`vitest run Button.test.tsx`) must not wipe the other
+     * modules from the manifest, so start from whatever the last run wrote.
+     * Modules whose file no longer exists are dropped.
+     */
+    seedFromPreviousRun() {
+        const file = join(this.outDir, 'manifest.json');
+        if (!existsSync(file)) {
+            return;
+        }
+        try {
+            const previous = JSON.parse(readFileSync(file, 'utf8'));
+            for (const mod of previous.modules ?? []) {
+                if (existsSync(resolve(this.root, mod.id))) {
+                    this.modules.set(mod.id, mod);
+                }
+            }
+        }
+        catch {
+            // corrupt or incompatible manifest: start fresh
+        }
+    }
+    onTestModuleEnd(module) {
+        const id = relative(this.root, module.moduleId);
+        const tests = Array.from(module.children.allTests()).map((tc) => this.toManifestTest(tc));
+        this.modules.set(id, { id, tests });
+    }
+    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));
+        const manifest = {
+            version: 1,
+            generatedAt: new Date().toISOString(),
+            root: this.root,
+            modules,
+            components,
+        };
+        this.snapshots.collectGarbage(manifest.modules.flatMap((mod) => mod.tests.flatMap((test) => test.frames.map((frame) => frame.snapshot))));
+        writeFileSync(join(this.outDir, 'manifest.json'), JSON.stringify(manifest, null, 2));
+    }
+    toManifestTest(tc) {
+        const record = tc.meta()[META_KEY];
+        const result = tc.result();
+        const frames = (record?.frames ?? []).map((frame) => ({
+            id: frame.id,
+            kind: frame.kind,
+            label: frame.label,
+            at: frame.at,
+            meta: frame.meta,
+            snapshot: this.snapshots.write(frame.snapshot),
+        }));
+        return {
+            id: tc.id,
+            name: tc.name,
+            path: testPath(tc),
+            fullName: tc.fullName,
+            state: result.state ?? 'pending',
+            duration: tc.diagnostic()?.duration,
+            errors: result.errors?.map((error) => ({ message: error.message, stack: error.stack })),
+            component: record?.component,
+            frames,
+        };
+    }
+}

package/dist/resolve-component-file.d.ts

@@ -0,0 +1,15 @@
+import ts from 'typescript';
+/** Where a component lives, and under which name its module exports it. */
+export interface ResolvedComponent {
+    /** Absolute path of the source file. */
+    file: string;
+    /** Exported name, or `default` for a default export. */
+    exportName: string;
+}
+/**
+ * Find the file a test imports a component from. The React adapter only
+ * reports a name, so the test module itself is the index: whichever import
+ * binds that name points at the component. Returns null when no import
+ * matches or the match comes from a library.
+ */
+export declare function resolveComponentFile(testFile: string, componentName: string, options: ts.CompilerOptions): ResolvedComponent | null;

package/dist/resolve-component-file.js

@@ -0,0 +1,85 @@
+import { readFileSync } from 'node:fs';
+import { extname } from 'node:path';
+import ts from 'typescript';
+const SCRIPT_KINDS = {
+    '.ts': ts.ScriptKind.TS,
+    '.tsx': ts.ScriptKind.TSX,
+    '.mts': ts.ScriptKind.TS,
+    '.cts': ts.ScriptKind.TS,
+    '.js': ts.ScriptKind.JS,
+    '.jsx': ts.ScriptKind.JSX,
+    '.mjs': ts.ScriptKind.JS,
+    '.cjs': ts.ScriptKind.JS,
+};
+/**
+ * Find the file a test imports a component from. The React adapter only
+ * reports a name, so the test module itself is the index: whichever import
+ * binds that name points at the component. Returns null when no import
+ * matches or the match comes from a library.
+ */
+export function resolveComponentFile(testFile, componentName, options) {
+    const source = parseModule(testFile);
+    if (!source) {
+        return null;
+    }
+    for (const statement of source.statements) {
+        if (!ts.isImportDeclaration(statement)) {
+            continue;
+        }
+        const exportName = exportNameFor(statement, componentName);
+        if (exportName === null) {
+            continue;
+        }
+        const file = resolveSpecifier(statement, testFile, options);
+        if (file) {
+            return { file, exportName };
+        }
+    }
+    return null;
+}
+/** Parse the test module on its own; a full program would cost far more than reading its imports. */
+function parseModule(testFile) {
+    try {
+        const text = readFileSync(testFile, 'utf8');
+        const kind = SCRIPT_KINDS[extname(testFile)] ?? ts.ScriptKind.TSX;
+        return ts.createSourceFile(testFile, text, ts.ScriptTarget.Latest, true, kind);
+    }
+    catch {
+        return null;
+    }
+}
+/** The exported name this import binds to `componentName`, or null when it binds something else. */
+function exportNameFor(statement, componentName) {
+    const clause = statement.importClause;
+    if (!clause) {
+        return null;
+    }
+    if (clause.name?.text === componentName) {
+        return 'default';
+    }
+    const bindings = clause.namedBindings;
+    if (!bindings || !ts.isNamedImports(bindings)) {
+        return null;
+    }
+    for (const element of bindings.elements) {
+        const original = element.propertyName ?? element.name;
+        // The adapter reports the component's own name: that is the local name,
+        // unless the test aliased the import, in which case it is the exported one.
+        if (element.name.text === componentName || original.text === componentName) {
+            return original.text;
+        }
+    }
+    return null;
+}
+/** Resolve the import specifier to a file in the project, skipping anything from node_modules. */
+function resolveSpecifier(statement, testFile, options) {
+    const specifier = statement.moduleSpecifier;
+    if (!ts.isStringLiteral(specifier)) {
+        return null;
+    }
+    const { resolvedModule } = ts.resolveModuleName(specifier.text, testFile, options, ts.sys);
+    if (!resolvedModule || resolvedModule.isExternalLibraryImport) {
+        return null;
+    }
+    return resolvedModule.resolvedFileName || null;
+}

package/dist/setup.d.ts

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

package/dist/setup.js

@@ -0,0 +1,19 @@
+/**
+ * Vitest setup file: `setupFiles: ['@describe-me/vitest/setup']`.
+ * Runs in the browser. Patches Vitest's locators and userEvent so every
+ * interaction records a frame, begins a recording before each test, and hands
+ * the frames to the reporter via task.meta.
+ */
+import { afterEach, beforeEach } from 'vitest';
+import { META_KEY, recorder } from '@describe-me/core';
+import { patchLocators } from './patch-locators.js';
+import { patchUserEvent } from './patch-user-event.js';
+patchLocators();
+patchUserEvent();
+beforeEach(() => {
+    recorder.begin();
+});
+afterEach(async (context) => {
+    await recorder.capture('end', 'end of test');
+    context.task.meta[META_KEY] = recorder.end();
+});

package/dist/snapshot-store.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Content-addressed store for the serialized DOM of every frame, living in
+ * `<outDir>/snapshots`. Identical DOM across tests or runs is written once.
+ */
+export declare class SnapshotStore {
+    private readonly dir;
+    constructor(outDir: string);
+    /** Write one snapshot and return its path relative to the manifest. */
+    write(snapshot: unknown): string;
+    /** Drop the files no manifest frame points at any more. */
+    collectGarbage(referenced: Iterable<string>): void;
+}

package/dist/snapshot-store.js

@@ -0,0 +1,37 @@
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+/**
+ * Content-addressed store for the serialized DOM of every frame, living in
+ * `<outDir>/snapshots`. Identical DOM across tests or runs is written once.
+ */
+export class SnapshotStore {
+    dir;
+    constructor(outDir) {
+        this.dir = join(outDir, 'snapshots');
+        mkdirSync(this.dir, { recursive: true });
+    }
+    /** Write one snapshot and return its path relative to the manifest. */
+    write(snapshot) {
+        const json = JSON.stringify(snapshot);
+        const hash = createHash('sha1').update(json).digest('hex').slice(0, 16);
+        const file = `${hash}.json`;
+        const abs = join(this.dir, file);
+        if (!existsSync(abs)) {
+            writeFileSync(abs, json);
+        }
+        return `snapshots/${file}`;
+    }
+    /** Drop the files no manifest frame points at any more. */
+    collectGarbage(referenced) {
+        const keep = new Set();
+        for (const path of referenced) {
+            keep.add(path.replace('snapshots/', ''));
+        }
+        for (const file of readdirSync(this.dir)) {
+            if (!keep.has(file)) {
+                rmSync(join(this.dir, file), { force: true });
+            }
+        }
+    }
+}

package/dist/test-path.d.ts

@@ -0,0 +1,3 @@
+import type { TestCase } from 'vitest/node';
+/** Suite names of a test case, from outermost to innermost. */
+export declare function testPath(tc: TestCase): string[];

package/dist/test-path.js

@@ -0,0 +1,10 @@
+/** Suite names of a test case, from outermost to innermost. */
+export function testPath(tc) {
+    const path = [];
+    let parent = tc.parent;
+    while (parent && parent.type === 'suite') {
+        path.unshift(parent.name);
+        parent = parent.parent;
+    }
+    return path;
+}

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@describe-me/vitest",
+  "version": "0.1.0",
+  "description": "Vitest integration for describe-me: plugin, setup file and reporter",
+  "keywords": [
+    "vitest",
+    "storybook",
+    "component documentation",
+    "visual testing",
+    "testing"
+  ],
+  "license": "MIT",
+  "author": "Grzegorz Łotysz",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/grzehub/describe-me.git",
+    "directory": "packages/vitest"
+  },
+  "homepage": "https://grzehub.github.io/describe-me/",
+  "bugs": "https://github.com/grzehub/describe-me/issues",
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./setup": {
+      "types": "./dist/setup.d.ts",
+      "default": "./dist/setup.js"
+    },
+    "./reporter": {
+      "types": "./dist/reporter.d.ts",
+      "default": "./dist/reporter.js"
+    },
+    "./plugin": {
+      "types": "./dist/plugin.d.ts",
+      "default": "./dist/plugin.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": [
+    "./dist/setup.js"
+  ],
+  "dependencies": {
+    "@describe-me/core": "^0.1.0"
+  },
+  "peerDependencies": {
+    "vitest": ">=4",
+    "typescript": ">=5.0"
+  },
+  "peerDependenciesMeta": {
+    "typescript": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "vitest": "^5.0.1",
+    "@types/node": "^22",
+    "typescript": "^6"
+  },
+  "scripts": {
+    "build": "rimraf dist && tsc -p tsconfig.json"
+  }
+}