executable-stories-jest 7.0.1 → 8.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "executable-stories-jest",
-  "version": "7.0.1",
+  "version": "8.0.0",
   "description": "BDD-style executable stories for Jest with documentation generation",
   "type": "module",
   "sideEffects": false,
@@ -25,25 +25,27 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "skills",
+    "bin"
   ],
   "peerDependencies": {
-    "jest": ">=30.2.0",
-    "executable-stories-formatters": "^0.6.1"
+    "jest": ">=30.3.0",
+    "executable-stories-formatters": "^0.7.0"
   },
   "dependencies": {
     "fast-glob": "^3.3.3"
   },
   "devDependencies": {
-    "@jest/globals": "^30.2.0",
+    "@jest/globals": "^30.3.0",
     "@opentelemetry/api": "^1.9.0",
     "@types/jest": "^30.0.0",
-    "@types/node": "^25.3.2",
+    "@types/node": "^25.5.0",
     "jest": "^30.2.0",
     "ts-jest": "^29.4.6",
     "tsup": "^8.5.1",
     "typescript": "~5.9.3",
-    "executable-stories-formatters": "0.6.1"
+    "executable-stories-formatters": "0.7.0"
   },
   "repository": {
     "type": "git",
@@ -57,6 +59,9 @@
     "documentation",
     "executable-stories"
   ],
+  "bin": {
+    "intent": "./bin/intent.js"
+  },
   "scripts": {
     "build": "tsup",
     "type-check": "tsc --noEmit",

package/skills/jest-converting-tests/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: jest-converting-tests
+description: >
+  Incrementally adopt executable-stories in Jest. Add story.init() and
+  top-level step imports to existing test blocks. No task argument needed.
+  File naming .story.test.ts. Progressive enhancement without rewriting.
+type: lifecycle
+library: executable-stories-jest
+library_version: "7.0.1"
+requires:
+  - jest-story-api
+sources:
+  - "jagreehal/executable-stories:apps/docs-site/src/content/docs/guides/converting-jest.md"
+---
+
+This skill builds on jest-story-api. Read jest-story-api first.
+
+# Converting Existing Jest Tests
+
+## Setup
+
+Install the packages and configure:
+
+```bash
+npm install -D executable-stories-jest executable-stories-formatters
+```
+
+```javascript
+// jest.config.mjs
+export default {
+  setupFilesAfterEnv: ["executable-stories-jest/setup"],
+  reporters: [
+    "default",
+    ["executable-stories-jest/reporter", { formats: ["markdown"] }],
+  ],
+};
+```
+
+## Core Patterns
+
+### Step 1: Rename the file
+
+```
+# Before
+test/calculator.test.ts
+
+# After
+test/calculator.story.test.ts
+```
+
+### Step 2: Add story.init() and step markers
+
+```typescript
+// Before
+import { describe, expect, it } from "@jest/globals";
+
+describe("Calculator", () => {
+  it("adds two numbers", () => {
+    const result = add(2, 3);
+    expect(result).toBe(5);
+  });
+});
+```
+
+```typescript
+// After
+import { describe, expect, it } from "@jest/globals";
+import { story, given, when, then } from "executable-stories-jest";
+
+describe("Calculator", () => {
+  it("adds two numbers", () => {
+    story.init();
+
+    given("two numbers 2 and 3");
+    const a = 2, b = 3;
+
+    when("they are added");
+    const result = add(a, b);
+
+    then("the result is 5");
+    expect(result).toBe(5);
+  });
+});
+```
+
+Key difference from Vitest: no `({ task })` needed. `story.init()` takes no arguments.
+
+### Step 3: Minimal story
+
+```typescript
+it("subtracts two numbers", () => {
+  story.init();
+  expect(subtract(10, 4)).toBe(6);
+});
+```
+
+### Step 4: Add doc entries
+
+```typescript
+it("handles division by zero", () => {
+  story.init({ tags: ["edge-case"] });
+
+  given("a divisor of zero");
+  story.note("This tests the error handling path");
+
+  when("division is attempted");
+  const fn = () => divide(10, 0);
+
+  then("an error is thrown");
+  expect(fn).toThrow("Division by zero");
+});
+```
+
+## Common Mistakes
+
+### HIGH Adding ({ task }) like Vitest
+
+Wrong:
+
+```typescript
+it("my test", ({ task }) => {
+  story.init(task);
+});
+```
+
+Correct:
+
+```typescript
+it("my test", () => {
+  story.init();
+});
+```
+
+Jest does not provide a `task` object. `story.init()` reads the test name from `expect.getState().currentTestName`.
+
+Source: packages/executable-stories-jest/src/story-api.ts
+
+### HIGH Forgetting setupFilesAfterEnv
+
+Without `setupFilesAfterEnv: ["executable-stories-jest/setup"]` in jest.config, stories are never flushed to disk and the reporter produces empty output.
+
+Source: packages/executable-stories-jest/src/reporter.ts

package/skills/jest-reporter-setup/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: jest-reporter-setup
+description: >
+  Configure Jest custom reporter for executable-stories-jest. jest.config
+  reporters array with options. setupFilesAfterEnv for story flushing.
+  Output formats, directory, naming. Aggregated and colocated modes.
+type: core
+library: executable-stories-jest
+library_version: "7.0.1"
+sources:
+  - "jagreehal/executable-stories:packages/executable-stories-jest/src/reporter.ts"
+---
+
+# executable-stories-jest — Reporter Setup
+
+## Setup
+
+```javascript
+// jest.config.mjs
+export default {
+  setupFilesAfterEnv: ["executable-stories-jest/setup"],
+  reporters: [
+    "default",
+    [
+      "executable-stories-jest/reporter",
+      {
+        formats: ["markdown", "html"],
+        outputDir: "docs",
+        outputName: "user-stories",
+      },
+    ],
+  ],
+};
+```
+
+Both the `setup` file and the `reporter` entry are required. Peer dependency: `executable-stories-formatters` must be installed.
+
+## Core Patterns
+
+### Minimal config
+
+```javascript
+export default {
+  setupFilesAfterEnv: ["executable-stories-jest/setup"],
+  reporters: [
+    "default",
+    ["executable-stories-jest/reporter", { formats: ["markdown"] }],
+  ],
+};
+```
+
+### Full options
+
+```javascript
+export default {
+  setupFilesAfterEnv: ["executable-stories-jest/setup"],
+  reporters: [
+    "default",
+    [
+      "executable-stories-jest/reporter",
+      {
+        formats: ["markdown", "html", "junit", "cucumber-json"],
+        outputDir: "reports",
+        outputName: "test-results",
+        output: {
+          mode: "aggregated",
+          // mode: "colocated",
+          // colocatedStyle: "mirrored",
+        },
+        markdown: {
+          title: "User Stories",
+          includeStatusIcons: true,
+          includeErrors: true,
+          includeMetadata: true,
+          sortScenarios: "source",
+          ticketUrlTemplate: "https://jira.example.com/browse/{ticket}",
+        },
+        html: {
+          title: "Test Report",
+          darkMode: true,
+          searchable: true,
+        },
+        rawRunPath: "reports/raw-run.json",
+      },
+    ],
+  ],
+};
+```
+
+### File-based communication
+
+Jest uses worker processes. Stories are written to `.jest-executable-stories/worker-{id}/*.json` during execution. The reporter aggregates these files in `onRunComplete`. The `JEST_STORY_DOCS_DIR` env var overrides the temp directory.
+
+## Common Mistakes
+
+### CRITICAL Missing setupFilesAfterEnv entry
+
+Wrong:
+
+```javascript
+export default {
+  reporters: [
+    "default",
+    ["executable-stories-jest/reporter", { formats: ["markdown"] }],
+  ],
+};
+```
+
+Correct:
+
+```javascript
+export default {
+  setupFilesAfterEnv: ["executable-stories-jest/setup"],
+  reporters: [
+    "default",
+    ["executable-stories-jest/reporter", { formats: ["markdown"] }],
+  ],
+};
+```
+
+The setup file registers an `afterAll` hook that flushes story metadata to disk at the end of each test file. Without it, the reporter receives no data and produces empty output.
+
+Source: packages/executable-stories-jest/src/reporter.ts
+
+### HIGH Using the reporter path as a string instead of tuple
+
+Wrong:
+
+```javascript
+reporters: ["default", "executable-stories-jest/reporter"]
+```
+
+Correct:
+
+```javascript
+reporters: [
+  "default",
+  ["executable-stories-jest/reporter", { formats: ["markdown"] }],
+]
+```
+
+Without options, the default format is `["cucumber-json"]`. Use the tuple form `[path, options]` to specify formats and output directory.
+
+Source: packages/executable-stories-jest/src/reporter.ts
+
+### MEDIUM Default format is cucumber-json, not markdown
+
+The default `formats` is `["cucumber-json"]`. Always specify `formats: ["markdown"]` (or other desired formats) explicitly.
+
+Source: packages/executable-stories-jest/src/reporter.ts

package/skills/jest-story-api/SKILL.md

@@ -0,0 +1,225 @@
+---
+name: jest-story-api
+description: >
+  Write BDD stories in Jest using executable-stories-jest. Top-level exports:
+  import { given, when, then, and, but } from executable-stories-jest.
+  story.init() takes no arguments. Auto-And keyword conversion. Suite path
+  from expect.getState().currentTestName. Aliases: arrange, act, assert.
+  Doc entries: json, kv, code, table, link, section, mermaid, note, tag.
+type: core
+library: executable-stories-jest
+library_version: "7.0.1"
+sources:
+  - "jagreehal/executable-stories:packages/executable-stories-jest/src/index.ts"
+  - "jagreehal/executable-stories:packages/executable-stories-jest/src/story-api.ts"
+---
+
+# executable-stories-jest — Story API
+
+## Setup
+
+```typescript
+import { describe, expect, it } from "@jest/globals";
+import { story, given, when, then } from "executable-stories-jest";
+
+describe("Cart checkout", () => {
+  it("applies discount code", () => {
+    story.init({ tags: ["checkout"], ticket: "CART-42" });
+
+    given("a cart with items totaling $100");
+    const cart = createCart([{ name: "Shirt", price: 100 }]);
+
+    when("a 20% discount code is applied");
+    applyDiscount(cart, "SAVE20");
+
+    then("the total is $80");
+    expect(cart.total).toBe(80);
+  });
+});
+```
+
+File naming: `*.story.test.ts`.
+
+Jest uses top-level step exports. `story.init()` takes no arguments — the test name is derived from `expect.getState().currentTestName`.
+
+## Core Patterns
+
+### Top-level step exports
+
+```typescript
+import { story, given, when, then, and, but } from "executable-stories-jest";
+
+it("blocks suspended user login", () => {
+  story.init();
+
+  given("the user account exists");         // renders "Given"
+  given("the account is suspended");         // renders "And" (auto-converted)
+  when("the user submits valid credentials");
+  then("the user sees an error message");
+  but("the user is not logged in");          // renders "But" (always)
+});
+```
+
+### Doc entries
+
+```typescript
+import { story, given, when, then } from "executable-stories-jest";
+
+it("processes payment", () => {
+  story.init();
+
+  given("a valid payment request");
+  story.json({ label: "Payload", value: { amount: 50, currency: "USD" } });
+
+  when("the payment is submitted");
+  story.code({ label: "Response", content: '{ "status": "ok" }', lang: "json" });
+
+  then("the order is confirmed");
+  story.table({
+    label: "Order summary",
+    columns: ["Item", "Qty", "Price"],
+    rows: [["Widget", "2", "$25"]],
+  });
+  story.note("Payment processed in sandbox mode");
+});
+```
+
+### Step wrappers with timing
+
+```typescript
+const profile = await story.fn("When", "the profile is fetched", async () => {
+  return fetchProfile(userId);
+});
+
+await story.expect("the profile contains the correct name", () => {
+  expect(profile.name).toBe("Alice");
+});
+```
+
+### Inline docs via second argument
+
+```typescript
+given("valid credentials", {
+  json: { label: "Credentials", value: { user: "alice", role: "admin" } },
+  note: "Password masked for security",
+});
+```
+
+## Common Mistakes
+
+### CRITICAL Calling story.init() with a task argument
+
+Wrong:
+
+```typescript
+it("my test", ({ task }) => {
+  story.init(task);  // Jest does not provide task
+});
+```
+
+Correct:
+
+```typescript
+it("my test", () => {
+  story.init();  // No arguments needed
+});
+```
+
+Jest's `story.init()` takes no arguments. It reads the test name from `expect.getState().currentTestName`. Passing an argument is a Vitest pattern that does not apply to Jest.
+
+Source: packages/executable-stories-jest/src/story-api.ts
+
+### HIGH Suite path not detected in docs
+
+Wrong assumption:
+
+```typescript
+// Expecting "Calculator" to appear as a ## heading in docs
+describe("Calculator", () => {
+  it("adds numbers", () => {
+    story.init();
+    // ...
+  });
+});
+// Jest's currentTestName format is "Calculator adds numbers" (space-separated)
+// Suite path is usually undefined → docs are flat
+```
+
+This is a known limitation. Jest's `expect.getState().currentTestName` uses space-separated format (`"Describe title test name"`), not `" > "` separated. Suite path extraction only works when `" > "` is present. In the default Jest setup, docs are flat without `## Suite name` headings.
+
+Source: CLAUDE.md — "Doc heading and describe in generated docs"
+
+### HIGH Missing setup file in jest.config
+
+Wrong:
+
+```javascript
+// jest.config.mjs
+export default {
+  reporters: ["default", "executable-stories-jest/reporter"],
+};
+```
+
+Correct:
+
+```javascript
+// jest.config.mjs
+export default {
+  setupFilesAfterEnv: ["executable-stories-jest/setup"],
+  reporters: ["default", "executable-stories-jest/reporter"],
+};
+```
+
+The setup file registers an `afterAll` hook that flushes story metadata to disk. Without it, the reporter has no data to process.
+
+Source: packages/executable-stories-jest/src/reporter.ts
+
+### MEDIUM Calling steps before story.init()
+
+Wrong:
+
+```typescript
+it("my test", () => {
+  given("something");
+  story.init();
+});
+```
+
+Correct:
+
+```typescript
+it("my test", () => {
+  story.init();
+  given("something");
+});
+```
+
+Steps called before `init()` are silently dropped because no story context exists.
+
+Source: packages/eslint-plugin-executable-stories-jest/src/rules/require-story-context-for-steps.ts
+
+## Parameterized Scenarios (Scenario Outline equivalent)
+
+Use Jest's `it.each` with `story()` to produce one scenario per data row — the framework-native replacement for Cucumber's Scenario Outline + Examples.
+
+```ts
+import { story, given, when, then } from "executable-stories-jest";
+
+const cases = [
+  { input: 1, expected: 2 },
+  { input: 2, expected: 4 },
+  { input: 3, expected: 6 },
+];
+
+describe("Doubling", () => {
+  it.each(cases)("doubles $input to $expected", ({ input, expected }) => {
+    story(`Doubles ${input} to ${expected}`);
+    given(`the input is ${input}`);
+    when("the doubler runs");
+    then(`the result is ${expected}`);
+    expect(input * 2).toBe(expected);
+  });
+});
+```
+
+Each iteration produces a separate scenario in the generated report. Use interpolated titles so each scenario has a distinct, descriptive name.