executable-stories-vitest 8.6.6 → 8.8.0

package/README.md

@@ -153,6 +153,18 @@ story.init(task, {
 
 ## Developer experience
 
+The reporter also maintains canonical state under `<outputDir>/by-file/`, one JSON
+report per test source. Documentation formats render that accumulated suite; JUnit,
+Cucumber, and release manifests contain only the current execution. Vitest name filters
+are detected automatically. A full run may retire scenarios no longer reported, while a
+filtered or incompletely collected file preserves its earlier scenarios and emits a
+warning instead of deleting documentation.
+
+Vitest's live assertion counter is attributed to steps. Marker-style assertions are
+assigned to the current step until the next step or test end, and `story.expect` measures
+its own body. An observable Then/And/But claim with zero assertions is marked in Markdown
+and HTML and grades `none` in Evidence Review.
+
 - **API:** Steps are on the `story` object: `story.given`, `story.when`, `story.then`, `story.and`, `story.but`. There are no top-level `given`/`when`/`then` exports (to avoid `then` being treated as a thenable on the package namespace).
 - **Modifiers:** Use Vitest’s `.skip`, `.only`, `.todo`, `.fails`, `.concurrent` on step calls when needed (e.g. `story.then.skip('...')`). Use `story.skip` / `story.only` for scenario-level modifiers.
 - **Attach story to a plain `it()`:** Call `story.init(task)` inside a normal `it('...', ({ task }) => { ... })` so that test appears in generated docs. Vitest does not export top-level step helpers or `doc`.

package/dist/index.cjs

@@ -38,6 +38,7 @@ __export(src_exports, {
 module.exports = __toCommonJS(src_exports);
 
 // src/story-api.ts
+var import_vitest = require("vitest");
 var import_node_module = require("module");
 var import_otel_detect = require("executable-stories-core/utils/otel-detect");
 var import_doc_builders = require("executable-stories-core/utils/doc-builders");
@@ -202,6 +203,17 @@ function convertStoryDocsToEntries(docs) {
   }
   return entries;
 }
+function feature(input) {
+  declaredFeature = { input };
+}
+var declaredFeature = null;
+function attachFeature(task) {
+  if (!declaredFeature) return;
+  const file = task.file?.name;
+  declaredFeature.file ??= file;
+  if (declaredFeature.file !== file) return;
+  task.meta.storyFeature = { ...declaredFeature.input, sourceFile: file };
+}
 function init(task, options) {
   const meta = {
     scenario: task.name,
@@ -234,6 +246,7 @@ function init(task, options) {
     }
   }
   task.meta.story = meta;
+  attachFeature(task);
   activeContext = {
     meta,
     currentStep: null,
@@ -242,8 +255,41 @@ function init(task, options) {
     attachments: [],
     activeTimers: /* @__PURE__ */ new Map(),
     timerCounter: 0,
-    traceUrlTemplate
+    traceUrlTemplate,
+    pendingStep: null
   };
+  const ctx = activeContext;
+  try {
+    (0, import_vitest.onTestFinished)(() => {
+      flushPendingAssertions(ctx);
+      task.meta.story = ctx.meta;
+    });
+  } catch {
+  }
+}
+function flushPendingAssertions(ctx) {
+  const step = ctx.pendingStep;
+  const before = ctx.pendingFrom;
+  ctx.pendingStep = null;
+  ctx.pendingFrom = void 0;
+  if (!step || before === void 0) return;
+  const after = readAssertionCount();
+  if (after === void 0) return;
+  step.assertions = after - before;
+}
+function readAssertionCount() {
+  try {
+    const state2 = import_vitest.expect.getState?.();
+    return typeof state2?.assertionCalls === "number" ? state2.assertionCalls : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function recordAssertions(step, before) {
+  if (before === void 0) return;
+  const after = readAssertionCount();
+  if (after === void 0) return;
+  step.assertions = after - before;
 }
 function createStepMarker(keyword) {
   function stepMarker(text, docsOrBody) {
@@ -262,8 +308,13 @@ function createStepMarker(keyword) {
       docs: stepDocs,
       ...isCallback ? { wrapped: true } : {}
     };
+    flushPendingAssertions(ctx);
     ctx.meta.steps.push(step);
     ctx.currentStep = step;
+    if (!isCallback) {
+      ctx.pendingStep = step;
+      ctx.pendingFrom = readAssertionCount();
+    }
     syncMetaToTask();
     if (isChildrenArray) {
       const children = docsOrBody;
@@ -283,27 +334,32 @@ function createStepMarker(keyword) {
     if (!isCallback) return;
     const body = docsOrBody;
     const start = performance.now();
+    const assertionsBefore = readAssertionCount();
     try {
       const result = body();
       if (result instanceof Promise) {
         return result.then(
           (val) => {
             step.durationMs = performance.now() - start;
+            recordAssertions(step, assertionsBefore);
             syncMetaToTask();
             return val;
           },
           (err) => {
             step.durationMs = performance.now() - start;
+            recordAssertions(step, assertionsBefore);
             syncMetaToTask();
             throw err;
           }
         );
       }
       step.durationMs = performance.now() - start;
+      recordAssertions(step, assertionsBefore);
       syncMetaToTask();
       return result;
     } catch (err) {
       step.durationMs = performance.now() - start;
+      recordAssertions(step, assertionsBefore);
       syncMetaToTask();
       throw err;
     }
@@ -548,6 +604,7 @@ function attachSpans(spans, options) {
 var story = {
   // Core
   init,
+  feature,
   // BDD step markers
   given: createStepMarker("Given"),
   when: createStepMarker("When"),
@@ -680,6 +737,11 @@ var StoryReporter = class {
   startTime = 0;
   packageVersion;
   gitSha;
+  /**
+   * Left unknown until onInit sees a config. Claiming full coverage without
+   * having looked would let a later merge retire scenarios on a guess.
+   */
+  runScope;
   coverageByFile = {};
   constructor(options = {}) {
     this.options = options;
@@ -688,6 +750,9 @@ var StoryReporter = class {
     this.ctx = ctx;
     this.startTime = Date.now();
     const root = ctx.config?.root ?? process.cwd();
+    if (ctx.config) {
+      this.runScope = ctx.config.testNamePattern != null ? "filtered" : "full";
+    }
     const includeMetadata = this.options.markdown?.includeMetadata ?? true;
     if (includeMetadata) {
       this.packageVersion = (0, import_executable_stories_formatters.readPackageVersion)(root);
@@ -704,14 +769,21 @@ var StoryReporter = class {
     if (reason === "interrupted") return;
     const root = this.ctx?.config?.root ?? process.cwd();
     const rawTestCases = this.collectTestCases(testModules, root);
+    const coveredSourceFiles = this.collectCoveredSourceFiles(testModules, root);
+    const incompleteSourceFiles = this.collectIncompleteSourceFiles(testModules, root);
+    const features = collectFeatures(testModules, root);
     const rawRun = {
       testCases: rawTestCases,
+      ...features.length > 0 ? { features } : {},
       startedAtMs: this.startTime,
       finishedAtMs: Date.now(),
       projectRoot: root,
       packageVersion: this.packageVersion,
       gitSha: this.gitSha,
-      ci: (0, import_executable_stories_formatters.detectCI)()
+      ci: (0, import_executable_stories_formatters.detectCI)(),
+      ...this.runScope ? { runScope: this.runScope } : {},
+      ...coveredSourceFiles.length > 0 ? { coveredSourceFiles } : {},
+      ...incompleteSourceFiles.length > 0 ? { incompleteSourceFiles } : {}
     };
     const rawRunPath = this.options.rawRunPath;
     if (rawRunPath) {
@@ -788,6 +860,58 @@ var StoryReporter = class {
   /**
    * Collect test cases from Vitest test modules.
    */
+  /**
+   * Every module vitest ran, whether or not it produced a story.
+   *
+   * The collected test cases only name modules that produced something, so a
+   * file whose last story was deleted would otherwise look like a file that did
+   * not run and keep its old scenarios for good.
+   */
+  collectCoveredSourceFiles(testModules, root) {
+    const files = /* @__PURE__ */ new Set();
+    for (const mod of testModules) {
+      const moduleId = mod.moduleId ?? mod.relativeModuleId ?? "";
+      if (!moduleId) continue;
+      const absolute = path.isAbsolute(moduleId) ? moduleId : path.resolve(root, moduleId);
+      files.add(toRelativePosix(absolute, root));
+    }
+    return [...files].sort();
+  }
+  /**
+   * Files whose scenarios could not be collected in full.
+   *
+   * A module that errored, or a test that failed without ever declaring a
+   * story, is missing scenarios because the run broke. Treating that as
+   * deletion would throw away documentation at the exact moment the suite is
+   * unhealthy. Checked per test, not per file: one healthy story in a module
+   * does not vouch for its broken siblings.
+   */
+  collectIncompleteSourceFiles(testModules, root) {
+    const incomplete = /* @__PURE__ */ new Set();
+    for (const mod of testModules) {
+      const moduleId = mod.moduleId ?? mod.relativeModuleId ?? "";
+      if (!moduleId) continue;
+      const absolute = path.isAbsolute(moduleId) ? moduleId : path.resolve(root, moduleId);
+      const sourceFile = toRelativePosix(absolute, root);
+      const errors = mod.errors?.() ?? [];
+      const collection = mod.children;
+      if (errors.length > 0 || !collection) {
+        const state2 = mod.state?.();
+        if (errors.length > 0 || state2 === "failed") incomplete.add(sourceFile);
+        continue;
+      }
+      for (const test of collection.allTests()) {
+        const meta = this.getStoryMeta(test);
+        if (meta?.scenario && Array.isArray(meta.steps)) continue;
+        if (test.options?.mode === "todo") continue;
+        if (test.result?.()?.state === "failed") {
+          incomplete.add(sourceFile);
+          break;
+        }
+      }
+    }
+    return [...incomplete].sort();
+  }
   collectTestCases(testModules, root) {
     const testCases = [];
     for (const mod of testModules) {
@@ -909,6 +1033,24 @@ var StoryReporter = class {
 function createStoryReporter(options) {
   return new StoryReporter(options);
 }
+function collectFeatures(testModules, root) {
+  const byFile = /* @__PURE__ */ new Map();
+  for (const mod of testModules) {
+    const collection = mod.children;
+    if (!collection) continue;
+    const moduleId = mod.moduleId ?? mod.relativeModuleId ?? "";
+    const absoluteModuleId = path.isAbsolute(moduleId) ? moduleId : path.resolve(root, moduleId);
+    const sourceFile = toRelativePosix(absoluteModuleId, root);
+    for (const test of collection.allTests()) {
+      const declared = test.meta()?.storyFeature;
+      if (declared?.title) {
+        byFile.set(sourceFile, { ...declared, sourceFile });
+        break;
+      }
+    }
+  }
+  return [...byFile.values()];
+}
 
 // src/index.ts
 var STORY_REPORTER_GUARD_MSG = 'Do not import StoryReporter from "executable-stories-vitest". In vitest.config, import it from "executable-stories-vitest/reporter".';