executable-stories-formatters 1.11.0 → 1.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "executable-stories-formatters",
-  "version": "1.11.0",
+  "version": "1.13.0",
   "description": "Cucumber-compatible report formats (HTML, Markdown, JUnit XML, Cucumber JSON) for executable-stories test results.",
   "author": "Jag Reehal <jag@jagreehal.com>",
   "license": "Apache-2.0",
@@ -62,8 +62,8 @@
     "yaml": "^2.9.0",
     "react": "^19.2.7",
     "react-dom": "^19.2.7",
-    "executable-stories-core": "0.19.0",
-    "executable-stories-react": "0.10.1"
+    "executable-stories-core": "0.21.0",
+    "executable-stories-react": "0.12.0"
   },
   "devDependencies": {
     "@faker-js/faker": "^10.4.0",
@@ -80,6 +80,7 @@
   "scripts": {
     "embed-assets": "node scripts/embed-react-assets.mjs",
     "build": "node scripts/embed-react-assets.mjs && tsup",
+    "lint": "eslint .",
     "test": "node scripts/embed-react-assets.mjs && vitest run",
     "test:watch": "node scripts/embed-react-assets.mjs && vitest",
     "type-check": "node scripts/embed-react-assets.mjs && tsc --noEmit",

package/schemas/README.md

@@ -81,6 +81,9 @@ The full schema is in [`raw-run.schema.json`](raw-run.schema.json). Here are the
 | `gitSha`         | `string`        | No       | Git commit SHA                                               |
 | `ci`             | `RawCIInfo`     | No       | CI environment info (`name`, `url`, `buildNumber`)           |
 | `meta`           | `object`        | No       | Arbitrary metadata (escape hatch)                            |
+| `runScope`       | `full \| filtered` | No    | Whether the adapter knows the run covered whole source files or used a name filter |
+| `coveredSourceFiles` | `string[]` | No       | Every test source executed, including files that produced no scenarios |
+| `incompleteSourceFiles` | `string[]` | No    | Source files whose collection failed and must not retire earlier scenarios |
 
 ### RawTestCase
 
@@ -142,6 +145,7 @@ Emitters/converters should output these RawStatus values. Canonicalization norma
 | `text`    | `string`                                                | Yes      | Step description               |
 | `mode`    | `normal \| skip \| only \| todo \| fails \| concurrent` | No       | Execution mode                 |
 | `docs`    | `DocEntry[]`                                            | No       | Step-level documentation       |
+| `assertions` | `integer >= 0`                                      | No       | Assertions observed or declared for the step; absent means unknown, zero means observed none |
 
 ### DocEntry kinds
 

package/schemas/raw-run.schema.json

@@ -26,6 +26,13 @@
           },
           "description": "All test cases from the run."
         },
+        "features": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/RawFeature"
+          },
+          "description": "Feature declarations from story.feature(...), keyed to their source files."
+        },
         "startedAtMs": {
           "type": "number",
           "minimum": 0,
@@ -55,6 +62,28 @@
         "meta": {
           "type": "object",
           "description": "Arbitrary runner-specific metadata. Escape hatch for data not covered by the schema."
+        },
+        "runScope": {
+          "type": "string",
+          "enum": [
+            "full",
+            "filtered"
+          ],
+          "description": "How much of each source file this run covered. \"full\" means the adapter determined no name filter was applied, so the reported test cases are each file's complete set and a scenario missing from them may be retired. \"filtered\" means a name filter was applied (vitest -t, jest -t, playwright --grep), so the run saw only part of its own files. Omit when the adapter cannot tell: consumers then keep what the run did not report rather than deleting on a guess."
+        },
+        "coveredSourceFiles": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Source files this run executed, whether or not they produced test cases. A run's test cases only name files that produced something, so without this a file whose last scenario was deleted is indistinguishable from one that did not run. Optional."
+        },
+        "incompleteSourceFiles": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Source files whose scenarios could not be collected in full (a hook threw before the story was declared, a collection error, a crash). Such a file looks exactly like one whose scenarios were deleted, so it is never treated as authoritative however complete the rest of the run is."
         }
       },
       "required": [
@@ -295,6 +324,11 @@
           "type": "number",
           "minimum": 0,
           "description": "Step-level duration in milliseconds (from startTimer/endTimer)."
+        },
+        "assertions": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Assertions observed while this step ran. Omit when the adapter cannot observe assertions at all: absent means unknown, 0 means observed none."
         }
       },
       "required": [
@@ -917,6 +951,72 @@
         "name"
       ],
       "additionalProperties": false
+    },
+    "RawFeature": {
+      "type": "object",
+      "description": "A feature declared in a test file: what it is for, in the words the business uses.",
+      "properties": {
+        "sourceFile": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Source file the declaration was made in. Declarations without one are dropped."
+        },
+        "title": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Heading for the feature."
+        },
+        "kind": {
+          "type": "string",
+          "enum": [
+            "feature",
+            "ability",
+            "business-need"
+          ],
+          "description": "How to introduce the feature. Defaults to feature."
+        },
+        "narrative": {
+          "type": "string",
+          "description": "Markdown explaining why the feature exists and who it serves."
+        },
+        "tags": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Tags applied to every scenario in the file."
+        },
+        "glossary": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/RawGlossaryTerm"
+          },
+          "description": "Terms this feature defines."
+        }
+      },
+      "required": [
+        "title"
+      ],
+      "additionalProperties": false
+    },
+    "RawGlossaryTerm": {
+      "type": "object",
+      "description": "One glossary entry: a term the scenarios use and what it means.",
+      "properties": {
+        "term": {
+          "type": "string",
+          "minLength": 1
+        },
+        "definition": {
+          "type": "string",
+          "minLength": 1
+        }
+      },
+      "required": [
+        "term",
+        "definition"
+      ],
+      "additionalProperties": false
     }
   }
 }

package/templates/astro-thin/executable-stories.config.mjs

@@ -5,12 +5,17 @@ import { defineExecutableStories } from 'executable-stories-astro';
  * astro.config.mjs (route injection, nav, theme) and src/content.config.ts
  * (the loaders) — so everything lives in one place.
  *
- * `source` points at the run JSON your test adapter writes. Emit it by setting
- * `rawRunPath: "reports/raw-run.json"` in your StoryReporter config, then run
- * your tests in watch mode + `astro dev` to hot-reload these pages.
+ * `source` points at the directory of per-file reports your test run writes,
+ * one per test source file. Pointing at the directory rather than a single run
+ * JSON is what keeps the site showing your whole suite when you have only run
+ * part of it. Run your tests in watch mode + `astro dev` to hot-reload these
+ * pages; new test files appear without a restart.
+ *
+ * A single run JSON still works if you want only the last run:
+ * `source: '../reports/raw-run.json'`.
  */
 export default defineExecutableStories({
-  source: process.env.ES_RUN_JSON ?? '../reports/raw-run.json',
+  source: process.env.ES_RUN_JSON ?? '../reports/by-file',
 
   // Shown only until your tests emit the run JSON above, so `astro dev` is
   // populated on first run instead of empty. Replaced automatically the moment
@@ -28,8 +33,8 @@ export default defineExecutableStories({
 
   // Combine several test suites in one site (optional):
   // sources: [
-  //   { name: 'web', label: 'Web app', source: '../apps/web/reports/raw-run.json' },
-  //   { name: 'api', label: 'API',     source: '../apps/api/reports/raw-run.json' },
+  //   { name: 'web', label: 'Web app', source: '../apps/web/reports/by-file' },
+  //   { name: 'api', label: 'API',     source: '../apps/api/reports/by-file' },
   // ],
 
   // Audience lenses (optional): each view mounts a filtered, re-grouped index

package/templates/astro-thin/src/content/docs/index.mdx

@@ -13,7 +13,7 @@ pages are never written to disk, so they can't drift into a lie. Everything unde
 Run two things side by side and leave them running:
 
 ```bash
-# Terminal 1 — your tests in watch mode (rewrites reports/raw-run.json on every run)
+# Terminal 1 — your tests in watch mode (rewrites reports/by-file/ on every run)
 pnpm test --watch        # or: vitest, jest --watch, playwright --ui, …
 
 # Terminal 2 — this docs site
@@ -46,6 +46,6 @@ Your own pages can embed scenarios as live evidence too — see
 ## Wiring (one-time)
 
 The site reads the run JSON your test adapter writes. Point `source` in
-`executable-stories.config.mjs` at it (default `../reports/raw-run.json`), and set
+`executable-stories.config.mjs` at it (default `../reports/by-file`), and set
 the matching `rawRunPath` in your StoryReporter config. That's the only wiring —
 no per-test setup.