@describe-me/vitest 0.6.1 → 0.7.0

package/dist/check-tags-supported.d.ts

@@ -0,0 +1,7 @@
+import type { StoriesMode } from './stories-mode.js';
+/**
+ * Test tags arrived in Vitest 4.1. Without them `stories: 'tagged'` would
+ * record nothing, so an older Vitest fails before any test runs. A version
+ * that cannot be read passes.
+ */
+export declare function checkTagsSupported(stories: StoriesMode, root: string): void;

package/dist/check-tags-supported.js

@@ -0,0 +1,16 @@
+import { readVitestVersion } from './read-vitest-version.js';
+/**
+ * Test tags arrived in Vitest 4.1. Without them `stories: 'tagged'` would
+ * record nothing, so an older Vitest fails before any test runs. A version
+ * that cannot be read passes.
+ */
+export function checkTagsSupported(stories, root) {
+    if (stories !== 'tagged') {
+        return;
+    }
+    const version = readVitestVersion(root);
+    if (version === null || version.major > 4 || (version.major === 4 && version.minor >= 1)) {
+        return;
+    }
+    throw new Error(`describe-me: stories: 'tagged' needs test tags, which arrived in Vitest 4.1. This project resolves Vitest ${version.major}.${version.minor}.`);
+}

package/dist/docs-tag-definitions.d.ts

@@ -0,0 +1,9 @@
+import type { ViteUserConfig } from 'vitest/config';
+type TagDefinition = NonNullable<NonNullable<ViteUserConfig['test']>['tags']>[number];
+/**
+ * The definitions of `docs` and `no-docs` that the user's config lacks.
+ * Vitest throws on a tag it has no definition for, and Vite concatenates this
+ * list with the user's, so a tag the user defines is left to them.
+ */
+export declare function docsTagDefinitions(userConfig: ViteUserConfig): TagDefinition[];
+export {};

package/dist/docs-tag-definitions.js

@@ -0,0 +1,14 @@
+import { DOCS_TAG, NO_DOCS_TAG } from './stories-mode.js';
+const DEFINITIONS = [
+    { name: DOCS_TAG, description: "describe-me: a story, when stories is 'tagged'" },
+    { name: NO_DOCS_TAG, description: 'describe-me: never a story' },
+];
+/**
+ * The definitions of `docs` and `no-docs` that the user's config lacks.
+ * Vitest throws on a tag it has no definition for, and Vite concatenates this
+ * list with the user's, so a tag the user defines is left to them.
+ */
+export function docsTagDefinitions(userConfig) {
+    const defined = new Set((userConfig.test?.tags ?? []).map((tag) => tag.name));
+    return DEFINITIONS.filter((tag) => !defined.has(tag.name));
+}

package/dist/plugin.d.ts

@@ -1,5 +1,6 @@
 import type { ViteUserConfig } from 'vitest/config';
 import { type RenderFrameMode } from '@describe-me/core/types';
+import type { StoriesMode } from './stories-mode.js';
 /** Where the tests run: Vitest browser mode, or a simulated DOM such as jsdom. */
 export type DescribeMeEnvironment = 'browser' | 'dom';
 export interface DescribeMeOptions {
@@ -39,6 +40,13 @@ export interface DescribeMeOptions {
     include?: string | string[];
     /** Test files never to record, as globs like `include`. Wins over `include`. Default: none. */
     exclude?: string | string[];
+    /**
+     * Which tests of the recorded files become stories. `'all'` records every
+     * test, `'tagged'` only those tagged `docs`, on the test, a `describe` or the
+     * file (`@module-tag docs`). A `no-docs` tag leaves a test out in both modes.
+     * The plugin defines both tags, which need Vitest 4.1. Default: `'all'`.
+     */
+    stories?: StoriesMode;
     /**
      * HTML the viewer adds to the start of the `<head>` of every replayed frame,
      * like Storybook's `preview-head.html`. It never reaches the test page.

package/dist/plugin.js

@@ -1,9 +1,12 @@
+import { resolve } from 'node:path';
 import { LIVE_PROTOCOL } from '@describe-me/core/types';
 import { adapterPackageRoot } from './adapter-package-root.js';
+import { checkTagsSupported } from './check-tags-supported.js';
 import { compileGlobs } from './compile-globs.js';
 import { compileInclude } from './compile-include.js';
 import { defaultReporters } from './default-reporters.js';
 import { detectEnvironment } from './detect-environment.js';
+import { docsTagDefinitions } from './docs-tag-definitions.js';
 import { isAdapterModule } from './is-adapter-module.js';
 import { LIVE_ENV } from './live-env.js';
 import { livePlugin } from './live-plugin.js';
@@ -15,6 +18,7 @@ import DescribeMeReporter from './reporter.js';
 import { RUNTIME_OPTIONS_KEY } from './runtime-options.js';
 import { setUpProject } from './set-up-project.js';
 import { validateRenderFrame } from './validate-render-frame.js';
+import { validateStories } from './validate-stories.js';
 /**
  * One-line integration: `plugins: [describeMe()]`.
  *
@@ -58,7 +62,9 @@ export function describeMe(options = {}) {
                 include: compileInclude(options.include),
                 exclude: compileGlobs(options.exclude),
                 renderFrame: validateRenderFrame(options.renderFrame),
+                stories: validateStories(options.stories),
             };
+            checkTagsSupported(runtimeOptions.stories, resolve(userConfig.root ?? process.cwd()));
             const provide = { [RUNTIME_OPTIONS_KEY]: runtimeOptions };
             const profile = await loadProfile(environment);
             renderModule = profile.renderModules[framework];
@@ -68,6 +74,7 @@ export function describeMe(options = {}) {
                 outDir,
                 include: options.include,
                 exclude: options.exclude,
+                stories: runtimeOptions.stories,
                 previewHead: options.previewHead,
                 setupWarnings,
             });
@@ -77,7 +84,13 @@ export function describeMe(options = {}) {
             const reporters = userConfig.test?.reporters ? [reporter] : [...defaultReporters(), reporter];
             return {
                 ...config,
-                test: { setupFiles: [profile.setupFile], ...config.test, reporters, provide },
+                test: {
+                    setupFiles: [profile.setupFile],
+                    ...config.test,
+                    reporters,
+                    provide,
+                    tags: docsTagDefinitions(userConfig),
+                },
             };
         },
         // Runs for every project the plugin's Vite server serves, also those that

package/dist/read-live-vitest-major.d.ts

@@ -1,6 +1,6 @@
 /**
  * The major version of the `vitest` that the root resolves, whose rules the
- * live page names `each` and `for` rows by. Vitest exports its
- * `package.json`. Falls back to 5 when it cannot be read.
+ * live page names `each` and `for` rows by. Falls back to 5 when it cannot be
+ * read.
  */
 export declare function readLiveVitestMajor(root: string): number;

package/dist/read-live-vitest-major.js

@@ -1,20 +1,10 @@
-import { readFileSync } from 'node:fs';
-import { createRequire } from 'node:module';
-import { join } from 'node:path';
+import { readVitestVersion } from './read-vitest-version.js';
 const DEFAULT_MAJOR = 5;
 /**
  * The major version of the `vitest` that the root resolves, whose rules the
- * live page names `each` and `for` rows by. Vitest exports its
- * `package.json`. Falls back to 5 when it cannot be read.
+ * live page names `each` and `for` rows by. Falls back to 5 when it cannot be
+ * read.
  */
 export function readLiveVitestMajor(root) {
-    try {
-        const file = createRequire(join(root, 'package.json')).resolve('vitest/package.json');
-        const { version } = JSON.parse(readFileSync(file, 'utf8'));
-        const major = typeof version === 'string' ? Number.parseInt(version, 10) : Number.NaN;
-        return Number.isInteger(major) && major > 0 ? major : DEFAULT_MAJOR;
-    }
-    catch {
-        return DEFAULT_MAJOR;
-    }
+    return readVitestVersion(root)?.major ?? DEFAULT_MAJOR;
 }

package/dist/read-runtime-options.d.ts

@@ -1,3 +1,6 @@
 import { type RuntimeOptions } from './runtime-options.js';
-/** Without the plugin nothing is provided, so a hand-wired setup keeps recording every test. */
+/**
+ * Without the plugin nothing is provided, so a hand-wired setup keeps recording
+ * every test. The defaults also fill what an older plugin does not provide.
+ */
 export declare function readRuntimeOptions(): RuntimeOptions;

package/dist/read-runtime-options.js

@@ -1,10 +1,16 @@
 import { inject } from 'vitest';
 import { RUNTIME_OPTIONS_KEY } from './runtime-options.js';
-/** Without the plugin nothing is provided, so a hand-wired setup keeps recording every test. */
+const DEFAULTS = {
+    include: null,
+    exclude: [],
+    renderFrame: 'eager',
+    stories: 'all',
+};
+/**
+ * Without the plugin nothing is provided, so a hand-wired setup keeps recording
+ * every test. The defaults also fill what an older plugin does not provide.
+ */
 export function readRuntimeOptions() {
-    return (inject(RUNTIME_OPTIONS_KEY) ?? {
-        include: null,
-        exclude: [],
-        renderFrame: 'eager',
-    });
+    const provided = inject(RUNTIME_OPTIONS_KEY);
+    return { ...DEFAULTS, ...provided };
 }

package/dist/read-vitest-version.d.ts

@@ -0,0 +1,10 @@
+/** A Vitest release, as far as describe-me needs to tell them apart. */
+export interface VitestVersion {
+    major: number;
+    minor: number;
+}
+/**
+ * The version of the `vitest` that the root resolves, or `null` when it cannot
+ * be read. Vitest exports its `package.json`.
+ */
+export declare function readVitestVersion(root: string): VitestVersion | null;

package/dist/read-vitest-version.js

@@ -0,0 +1,21 @@
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { join } from 'node:path';
+/**
+ * The version of the `vitest` that the root resolves, or `null` when it cannot
+ * be read. Vitest exports its `package.json`.
+ */
+export function readVitestVersion(root) {
+    try {
+        const file = createRequire(join(root, 'package.json')).resolve('vitest/package.json');
+        const { version } = JSON.parse(readFileSync(file, 'utf8'));
+        const [major, minor] = typeof version === 'string' ? version.split('.').map(Number) : [];
+        if (!Number.isInteger(major) || major <= 0 || !Number.isInteger(minor)) {
+            return null;
+        }
+        return { major, minor };
+    }
+    catch {
+        return null;
+    }
+}

package/dist/register-recording-hooks.d.ts

@@ -3,7 +3,8 @@ import type { RuntimeOptions } from './runtime-options.js';
 /**
  * The per-test lifecycle shared by every environment: begin a recording, take
  * a deferred render frame or else the closing frame, hand the frames to the
- * reporter via task.meta, and only then let adapters unmount. Teardown runs
+ * reporter via task.meta, and only then let adapters unmount. Which tests
+ * record follows the file globs and then the test's tags. Teardown runs
  * for unrecorded tests too, because Testing Library's auto-cleanup is off in
  * jsdom. Concurrent tests would share the one recorder, so they are not
  * recorded. The hooks destructure the context, because Vitest rejects any

package/dist/register-recording-hooks.js

@@ -1,10 +1,12 @@
 import { afterEach, beforeEach } from 'vitest';
 import { META_KEY, recorder } from '@describe-me/core';
 import { fileFilter } from './file-filter.js';
+import { tagFilter } from './tag-filter.js';
 /**
  * The per-test lifecycle shared by every environment: begin a recording, take
  * a deferred render frame or else the closing frame, hand the frames to the
- * reporter via task.meta, and only then let adapters unmount. Teardown runs
+ * reporter via task.meta, and only then let adapters unmount. Which tests
+ * record follows the file globs and then the test's tags. Teardown runs
  * for unrecorded tests too, because Testing Library's auto-cleanup is off in
  * jsdom. Concurrent tests would share the one recorder, so they are not
  * recorded. The hooks destructure the context, because Vitest rejects any
@@ -12,6 +14,7 @@ import { fileFilter } from './file-filter.js';
  */
 export function registerRecordingHooks(options, aroundWait) {
     const isRecordedFile = fileFilter(options);
+    const isRecordedTags = tagFilter(options.stories);
     let warnedConcurrent = false;
     recorder.configure({ renderFrame: options.renderFrame, aroundWait });
     beforeEach(({ task }) => {
@@ -22,7 +25,8 @@ export function registerRecordingHooks(options, aroundWait) {
             }
             return;
         }
-        if (isRecordedFile(task.file.name)) {
+        // Vitest before 4.1 has no tags, so every test counts as untagged.
+        if (isRecordedFile(task.file.name) && isRecordedTags(task.tags ?? [])) {
             recorder.begin();
         }
     });

package/dist/reporter.d.ts

@@ -1,4 +1,5 @@
 import type { Reporter, TestModule, Vitest } from 'vitest/node';
+import type { StoriesMode } from './stories-mode.js';
 export interface DescribeMeReporterOptions {
     /** Output directory, relative to the Vitest root. Default: `.describe-me` */
     outDir?: string;
@@ -13,6 +14,11 @@ export interface DescribeMeReporterOptions {
      * `include`. Default: none.
      */
     exclude?: string | string[];
+    /**
+     * Which tests appear in the manifest: `'all'`, or only those tagged `docs`.
+     * A test tagged `no-docs` never does. Default: `'all'`.
+     */
+    stories?: StoriesMode;
     /**
      * HTML the viewer adds to the start of the `<head>` of every replayed frame,
      * like Storybook's `preview-head.html`. It never reaches the test page.
@@ -25,6 +31,7 @@ export interface DescribeMeReporterOptions {
 export default class DescribeMeReporter implements Reporter {
     private readonly outDirOption;
     private readonly isRecordedFile;
+    private readonly isRecordedTags;
     private readonly emptyInclude;
     private readonly previewHead;
     private readonly generator;
@@ -44,7 +51,8 @@ export default class DescribeMeReporter implements Reporter {
      * 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 is gone or no longer selected by `include` / `exclude`
-     * are dropped, and so are the empty tests that 0.4 still wrote.
+     * are dropped, and so are tests that `stories` no longer selects and the
+     * empty tests that 0.4 still wrote.
      */
     private seedFromPreviousRun;
     /**
@@ -54,8 +62,8 @@ export default class DescribeMeReporter implements Reporter {
      */
     private withStableIds;
     /**
-     * A test skipped in this run keeps its previous entry, so a filtered run does
-     * not erase documentation.
+     * A test skipped in this run keeps its previous entry with its current tags,
+     * so a filtered run does not erase documentation.
      */
     onTestModuleEnd(module: TestModule): void;
     onTestRunEnd(): Promise<void>;

package/dist/reporter.js

@@ -18,6 +18,7 @@ import { readGenerator } from './read-generator.js';
 import { SnapshotStore } from './snapshot-store.js';
 import { stableTestIds } from './stable-test-ids.js';
 import { StyleStore } from './style-store.js';
+import { tagFilter } from './tag-filter.js';
 import { testPath } from './test-path.js';
 function toPosix(moduleId) {
     return moduleId.split(sep).join('/');
@@ -25,9 +26,16 @@ function toPosix(moduleId) {
 function recordOf(tc) {
     return tc.meta()[META_KEY];
 }
+/** The test's tags for the manifest, where `undefined` leaves them out of the JSON. */
+function tagsOf(tc) {
+    // Vitest before 4.1 has no tags.
+    const tags = tc.tags ?? [];
+    return tags.length > 0 ? tags : undefined;
+}
 export default class DescribeMeReporter {
     outDirOption;
     isRecordedFile;
+    isRecordedTags;
     emptyInclude;
     previewHead;
     generator;
@@ -44,6 +52,7 @@ export default class DescribeMeReporter {
         this.outDirOption = options.outDir ?? '.describe-me';
         const include = compileInclude(options.include);
         this.isRecordedFile = fileFilter({ include, exclude: compileGlobs(options.exclude) });
+        this.isRecordedTags = tagFilter(options.stories ?? 'all');
         this.emptyInclude = include !== null && include.length === 0;
         // A blank head, such as an empty preview-head.html, is the same as none.
         this.previewHead = options.previewHead?.trim() ? options.previewHead : undefined;
@@ -76,7 +85,8 @@ export default class DescribeMeReporter {
      * 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 is gone or no longer selected by `include` / `exclude`
-     * are dropped, and so are the empty tests that 0.4 still wrote.
+     * are dropped, and so are tests that `stories` no longer selects and the
+     * empty tests that 0.4 still wrote.
      */
     seedFromPreviousRun() {
         const file = join(this.outDir, 'manifest.json');
@@ -86,7 +96,7 @@ export default class DescribeMeReporter {
         try {
             const previous = JSON.parse(readFileSync(file, 'utf8'));
             for (const mod of previous.modules ?? []) {
-                const tests = this.withStableIds(mod).filter((test) => isRecordedTest(test));
+                const tests = this.withStableIds(mod).filter((test) => isRecordedTest(test) && this.isRecordedTags(test.tags ?? []));
                 if (tests.length > 0 &&
                     this.isRecordedModule(mod.id) &&
                     existsSync(resolve(this.root, mod.id))) {
@@ -113,8 +123,8 @@ export default class DescribeMeReporter {
         });
     }
     /**
-     * A test skipped in this run keeps its previous entry, so a filtered run does
-     * not erase documentation.
+     * A test skipped in this run keeps its previous entry with its current tags,
+     * so a filtered run does not erase documentation.
      */
     onTestModuleEnd(module) {
         const id = relative(this.root, module.moduleId);
@@ -198,6 +208,11 @@ export default class DescribeMeReporter {
     }
     /** Decided before any snapshot is written, so a dropped test writes no file. */
     manifestTestOf(tc, stableId, previous) {
+        // Before the skipped branch, so a test tagged out since the last run does
+        // not survive a filtered run on its old frames. Vitest before 4.1 has no tags.
+        if (!this.isRecordedTags(tc.tags ?? [])) {
+            return undefined;
+        }
         const record = recordOf(tc);
         if (record && isRecordedTest(record)) {
             return this.toManifestTest(tc, stableId, record);
@@ -205,7 +220,13 @@ export default class DescribeMeReporter {
         if (tc.result().state !== 'skipped') {
             return undefined;
         }
-        return previous?.tests.find((test) => test.id === stableId && isRecordedTest(test));
+        const kept = previous?.tests.find((test) => test.id === stableId && isRecordedTest(test));
+        if (kept === undefined) {
+            return undefined;
+        }
+        // Tags belong to the test, not to the run, and Vitest knows them for a
+        // skipped test too. The viewer shows and filters by them.
+        return { ...kept, tags: tagsOf(tc) };
     }
     toManifestTest(tc, stableId, record) {
         const result = tc.result();
@@ -223,6 +244,7 @@ export default class DescribeMeReporter {
             name: tc.name,
             path: testPath(tc),
             fullName: tc.fullName,
+            tags: tagsOf(tc),
             state: result.state ?? 'pending',
             duration: tc.diagnostic()?.duration,
             errors: result.errors?.map((error) => ({ message: error.message, stack: error.stack })),

package/dist/runtime-options.d.ts

@@ -5,6 +5,7 @@
  * only types.
  */
 import type { RenderFrameMode } from '@describe-me/core/types';
+import type { StoriesMode } from './stories-mode.js';
 export interface CompiledGlob {
     source: string;
     flags: string;
@@ -18,6 +19,7 @@ export interface RuntimeOptions {
     /** Wins over `include`. */
     exclude: CompiledGlob[];
     renderFrame: RenderFrameMode;
+    stories: StoriesMode;
 }
 export declare const RUNTIME_OPTIONS_KEY: "describe-me";
 declare module 'vitest' {

package/dist/stories-mode.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The `stories` option and its two tags. Kept apart from `runtime-options.ts`,
+ * because the public types import this file and must not carry that file's
+ * augmentation of Vitest's `ProvidedContext`. The test runtime imports it, so
+ * no Node imports. The tags live in core, which the viewer reads too.
+ */
+export { DOCS_TAG, NO_DOCS_TAG } from '@describe-me/core/types';
+/** Which tests of the recorded files become stories: every one, or only those tagged `docs`. */
+export type StoriesMode = 'all' | 'tagged';

package/dist/stories-mode.js

@@ -0,0 +1,7 @@
+/**
+ * The `stories` option and its two tags. Kept apart from `runtime-options.ts`,
+ * because the public types import this file and must not carry that file's
+ * augmentation of Vitest's `ProvidedContext`. The test runtime imports it, so
+ * no Node imports. The tags live in core, which the viewer reads too.
+ */
+export { DOCS_TAG, NO_DOCS_TAG } from '@describe-me/core/types';

package/dist/tag-filter.d.ts

@@ -0,0 +1,7 @@
+import { type StoriesMode } from './stories-mode.js';
+/**
+ * Decides from a test's tags, its own and those it inherits from its suites
+ * and its file, whether it becomes a story. `no-docs` wins over `docs`. The
+ * test runtime imports this file, so no Node imports.
+ */
+export declare function tagFilter(stories: StoriesMode): (tags: readonly string[]) => boolean;

package/dist/tag-filter.js

@@ -0,0 +1,14 @@
+import { DOCS_TAG, NO_DOCS_TAG } from './stories-mode.js';
+/**
+ * Decides from a test's tags, its own and those it inherits from its suites
+ * and its file, whether it becomes a story. `no-docs` wins over `docs`. The
+ * test runtime imports this file, so no Node imports.
+ */
+export function tagFilter(stories) {
+    return (tags) => {
+        if (tags.includes(NO_DOCS_TAG)) {
+            return false;
+        }
+        return stories === 'all' || tags.includes(DOCS_TAG);
+    };
+}

package/dist/validate-stories.d.ts

@@ -0,0 +1,3 @@
+import type { StoriesMode } from './stories-mode.js';
+/** The plugin's `stories`, checked before any test runs. */
+export declare function validateStories(value: unknown): StoriesMode;

package/dist/validate-stories.js

@@ -0,0 +1,11 @@
+import { inspect } from 'node:util';
+/** The plugin's `stories`, checked before any test runs. */
+export function validateStories(value) {
+    if (value === undefined) {
+        return 'all';
+    }
+    if (value === 'all' || value === 'tagged') {
+        return value;
+    }
+    throw new Error(`describe-me: stories expects 'all' or 'tagged', got ${inspect(value)}`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@describe-me/vitest",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "description": "Living component documentation from your Vitest tests: the Vitest plugin, setup files and reporter of describe-me",
   "keywords": [
     "vitest",
@@ -71,13 +71,13 @@
   "dependencies": {
     "picomatch": "^4.0.3",
     "std-env": "^4.0.0",
-    "@describe-me/core": "^0.6.1"
+    "@describe-me/core": "^0.7.0"
   },
   "peerDependencies": {
     "vitest": "^4.0.0 || ^5.0.0",
     "typescript": "^5.0.0 || ^6.0.0",
     "@testing-library/user-event": "^14.0.0",
-    "describe-me": "^0.6.1"
+    "describe-me": "^0.7.0"
   },
   "peerDependenciesMeta": {
     "typescript": {