executable-stories-cypress 7.0.1 → 7.0.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "executable-stories-cypress",
-  "version": "7.0.1",
+  "version": "7.0.3",
   "description": "BDD-style executable stories for Cypress with documentation generation",
   "type": "module",
   "sideEffects": false,
@@ -30,11 +30,13 @@
   },
   "files": [
     "dist",
-    "reporter.cjs"
+    "skills",
+    "reporter.cjs",
+    "bin"
   ],
   "peerDependencies": {
     "cypress": ">=15.11.0",
-    "executable-stories-formatters": "^0.6.1"
+    "executable-stories-formatters": "^0.6.2"
   },
   "dependencies": {},
   "devDependencies": {
@@ -43,7 +45,7 @@
     "tsup": "^8.5.1",
     "typescript": "~5.9.3",
     "vitest": "^4.0.18",
-    "executable-stories-formatters": "0.6.1"
+    "executable-stories-formatters": "0.6.2"
   },
   "repository": {
     "type": "git",
@@ -57,6 +59,9 @@
     "documentation",
     "executable-stories"
   ],
+  "bin": {
+    "intent": "./bin/intent.js"
+  },
   "scripts": {
     "build": "tsup",
     "type-check": "tsc --noEmit",

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

@@ -0,0 +1,136 @@
+---
+name: cypress-converting-tests
+description: >
+  Incrementally adopt executable-stories in Cypress. Add story.init() and
+  step markers to existing cy.ts spec files. File naming .story.cy.ts.
+  Requires plugin + support file wiring. Progressive enhancement.
+type: lifecycle
+library: executable-stories-cypress
+library_version: "7.0.1"
+requires:
+  - cypress-story-api
+sources:
+  - "jagreehal/executable-stories:packages/executable-stories-cypress/src/index.ts"
+---
+
+This skill builds on cypress-story-api. Read cypress-story-api first.
+
+# Converting Existing Cypress Tests
+
+## Setup
+
+Install and configure the three wiring points:
+
+```bash
+npm install -D executable-stories-cypress executable-stories-formatters
+```
+
+```typescript
+// cypress.config.ts
+import { defineConfig } from "cypress";
+import { registerExecutableStoriesPlugin } from "executable-stories-cypress/plugin";
+
+export default defineConfig({
+  e2e: {
+    setupNodeEvents(on) {
+      registerExecutableStoriesPlugin(on);
+    },
+  },
+});
+```
+
+```typescript
+// cypress/support/e2e.ts
+import "executable-stories-cypress/support";
+```
+
+## Core Patterns
+
+### Step 1: Rename the file
+
+```
+# Before
+cypress/e2e/login.cy.ts
+
+# After
+cypress/e2e/login.story.cy.ts
+```
+
+### Step 2: Add story.init() and step markers
+
+```typescript
+// Before
+describe("Login", () => {
+  it("logs in successfully", () => {
+    cy.visit("/login");
+    cy.get("#email").type("user@example.com");
+    cy.get("#password").type("secret");
+    cy.get("#submit").click();
+    cy.get("h1").should("contain", "Dashboard");
+  });
+});
+```
+
+```typescript
+// After
+import { story } from "executable-stories-cypress";
+
+describe("Login", () => {
+  it("logs in successfully", () => {
+    story.init();
+
+    story.given("the login page is loaded");
+    cy.visit("/login");
+
+    story.when("valid credentials are entered");
+    cy.get("#email").type("user@example.com");
+    cy.get("#password").type("secret");
+    cy.get("#submit").click();
+
+    story.then("the dashboard is shown");
+    cy.get("h1").should("contain", "Dashboard");
+  });
+});
+```
+
+### Step 3: Minimal story
+
+```typescript
+it("loads homepage", () => {
+  story.init();
+  cy.visit("/");
+  cy.title().should("eq", "My App");
+});
+```
+
+### Step 4: Add doc entries
+
+```typescript
+it("shows product details", () => {
+  story.init({ tags: ["e2e", "products"] });
+
+  story.given("the product page is loaded");
+  cy.visit("/products/123");
+
+  story.then("the product details are shown");
+  story.screenshot({ path: "screenshots/product.png", alt: "Product page" });
+  story.json({ label: "Product", value: { id: 123, name: "Widget" } });
+});
+```
+
+## Common Mistakes
+
+### HIGH Using wrong file extension
+
+Wrong: `login.story.test.ts` or `login.story.spec.ts`
+Correct: `login.story.cy.ts`
+
+Cypress convention uses `.cy.ts`. The reporter and file matching expect this extension.
+
+Source: CLAUDE.md — file naming conventions
+
+### CRITICAL Forgetting plugin or support file
+
+Both `registerExecutableStoriesPlugin(on)` in cypress.config.ts AND `import "executable-stories-cypress/support"` in e2e.ts are required. Missing either one causes silent failures — stories record in the browser but never reach the reporter.
+
+Source: packages/executable-stories-cypress/src/plugin.ts, packages/executable-stories-cypress/src/support.ts

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

@@ -0,0 +1,113 @@
+---
+name: cypress-reporter-setup
+description: >
+  Configure Cypress reporter for executable-stories-cypress. Mocha reporter
+  via --reporter flag or cypress.config.ts. Module API for programmatic use
+  with buildRawRunFromCypressResult and generateReportsFromRawRun. Output
+  formats, directory, naming.
+type: core
+library: executable-stories-cypress
+library_version: "7.0.1"
+sources:
+  - "jagreehal/executable-stories:packages/executable-stories-cypress/src/reporter.ts"
+---
+
+# executable-stories-cypress — Reporter Setup
+
+## Setup
+
+### Option A: Mocha reporter (CLI)
+
+```bash
+cypress run \
+  --reporter executable-stories-cypress/reporter \
+  --reporter-options "outputDir=docs,outputName=user-stories,formats=markdown"
+```
+
+### Option B: Module API (programmatic)
+
+```typescript
+// cypress.config.ts
+import { defineConfig } from "cypress";
+import { registerExecutableStoriesPlugin } from "executable-stories-cypress/plugin";
+import {
+  buildRawRunFromCypressResult,
+  generateReportsFromRawRun,
+} from "executable-stories-cypress/reporter";
+
+export default defineConfig({
+  e2e: {
+    setupNodeEvents(on) {
+      registerExecutableStoriesPlugin(on);
+    },
+  },
+});
+
+// After cypress.run() completes:
+const result = await cypress.run();
+const rawRun = buildRawRunFromCypressResult(result, { outputDir: "docs" });
+await generateReportsFromRawRun(rawRun, {
+  formats: ["markdown", "html"],
+  outputDir: "docs",
+  outputName: "user-stories",
+});
+```
+
+Peer dependency: `executable-stories-formatters` must be installed.
+
+## Core Patterns
+
+### Mocha reporter with all options
+
+```bash
+cypress run \
+  --reporter executable-stories-cypress/reporter \
+  --reporter-options "outputDir=reports,outputName=test-results,formats=markdown+html+junit"
+```
+
+### Module API for CI pipelines
+
+```typescript
+import cypress from "cypress";
+import {
+  buildRawRunFromCypressResult,
+  generateReportsFromRawRun,
+} from "executable-stories-cypress/reporter";
+
+const result = await cypress.run({ spec: "cypress/e2e/**/*.story.cy.ts" });
+
+if (result.status === "finished") {
+  const rawRun = buildRawRunFromCypressResult(result);
+  await generateReportsFromRawRun(rawRun, {
+    formats: ["markdown"],
+    outputDir: "docs",
+    outputName: "cypress-stories",
+  });
+}
+```
+
+## Common Mistakes
+
+### CRITICAL Forgetting plugin + support wiring
+
+The reporter only works if both the plugin and support file are configured. Without them, the reporter has no story metadata to process. See cypress-story-api/SKILL.md for the required wiring.
+
+### HIGH Using reporter without Module API in afterRun
+
+Wrong:
+
+```typescript
+// Expecting reporter to auto-generate reports
+export default defineConfig({
+  e2e: {
+    setupNodeEvents(on) {
+      registerExecutableStoriesPlugin(on);
+    },
+  },
+  reporter: "executable-stories-cypress/reporter",
+});
+```
+
+The Mocha reporter approach works for CLI usage (`cypress run --reporter`). For programmatic usage with `cypress.run()`, use the Module API (`buildRawRunFromCypressResult` + `generateReportsFromRawRun`).
+
+Source: packages/executable-stories-cypress/src/reporter.ts

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

@@ -0,0 +1,218 @@
+---
+name: cypress-story-api
+description: >
+  Write BDD stories in Cypress using executable-stories-cypress. story.init()
+  with optional StoryOptions. Steps: story.given, story.when, story.then,
+  story.and, story.but. Doc entries: json, kv, code, table, link, section,
+  mermaid, screenshot, note, tag. Auto-And keyword conversion. Browser-Node
+  bridge via cy.task. Aliases: arrange, act, assert.
+type: core
+library: executable-stories-cypress
+library_version: "7.0.1"
+sources:
+  - "jagreehal/executable-stories:packages/executable-stories-cypress/src/story-api.ts"
+  - "jagreehal/executable-stories:packages/executable-stories-cypress/src/index.ts"
+---
+
+# executable-stories-cypress — Story API
+
+## Setup
+
+Three wiring steps are required:
+
+```typescript
+// 1. cypress.config.ts — register the plugin
+import { defineConfig } from "cypress";
+import { registerExecutableStoriesPlugin } from "executable-stories-cypress/plugin";
+
+export default defineConfig({
+  e2e: {
+    setupNodeEvents(on) {
+      registerExecutableStoriesPlugin(on);
+    },
+  },
+});
+```
+
+```typescript
+// 2. cypress/support/e2e.ts — import the support file
+import "executable-stories-cypress/support";
+```
+
+```typescript
+// 3. cypress/e2e/checkout.story.cy.ts — write a story test
+import { story } from "executable-stories-cypress";
+
+describe("Cart checkout", () => {
+  it("applies discount code", () => {
+    story.init({ tags: ["checkout"], ticket: "CART-42" });
+
+    story.given("a cart with items totaling $100");
+    cy.visit("/cart");
+    cy.get("[data-testid=total]").should("contain", "$100");
+
+    story.when("a 20% discount code is applied");
+    cy.get("#discount-code").type("SAVE20");
+    cy.get("#apply-discount").click();
+
+    story.then("the total is $80");
+    cy.get("[data-testid=total]").should("contain", "$80");
+  });
+});
+```
+
+File naming: `*.story.cy.ts`.
+
+## Core Patterns
+
+### Step markers with Auto-And conversion
+
+```typescript
+it("blocks suspended user login", () => {
+  story.init();
+
+  story.given("the user account exists");        // renders "Given"
+  story.given("the account is suspended");        // renders "And" (auto-converted)
+  story.when("the user submits valid credentials");
+  cy.get("#email").type("user@test.com");
+  cy.get("#submit").click();
+
+  story.then("the user sees an error message");
+  cy.get(".error").should("be.visible");
+
+  story.but("the user is not logged in");         // renders "But" (always)
+  cy.url().should("include", "/login");
+});
+```
+
+### Doc entries
+
+```typescript
+it("processes payment", () => {
+  story.init();
+
+  story.given("a valid payment request");
+  story.json({ label: "Payload", value: { amount: 50, currency: "USD" } });
+
+  story.when("the payment is submitted");
+  cy.get("#pay").click();
+
+  story.then("the order is confirmed");
+  story.table({
+    label: "Order summary",
+    columns: ["Item", "Qty", "Price"],
+    rows: [["Widget", "2", "$25"]],
+  });
+  story.screenshot({ path: "screenshots/confirmation.png", alt: "Confirmation" });
+  story.note("Payment processed in sandbox mode");
+});
+```
+
+### Step wrappers
+
+```typescript
+const result = story.fn("When", "the calculation runs", () => {
+  return calculate(2, 3);
+});
+
+story.expect("the result is correct", () => {
+  expect(result).to.equal(5);
+});
+```
+
+## Common Mistakes
+
+### CRITICAL Missing plugin registration
+
+Wrong:
+
+```typescript
+// cypress.config.ts
+export default defineConfig({
+  e2e: {
+    setupNodeEvents(on) {
+      // No plugin registered
+    },
+  },
+});
+```
+
+Correct:
+
+```typescript
+import { registerExecutableStoriesPlugin } from "executable-stories-cypress/plugin";
+
+export default defineConfig({
+  e2e: {
+    setupNodeEvents(on) {
+      registerExecutableStoriesPlugin(on);
+    },
+  },
+});
+```
+
+The plugin registers `cy.task` handlers for `executableStories:recordMeta`. Without it, the support file's `afterEach` hook fails silently and no story metadata is captured.
+
+Source: packages/executable-stories-cypress/src/plugin.ts
+
+### CRITICAL Missing support file import
+
+Wrong:
+
+```typescript
+// cypress/support/e2e.ts
+// (no executable-stories import)
+```
+
+Correct:
+
+```typescript
+// cypress/support/e2e.ts
+import "executable-stories-cypress/support";
+```
+
+The support file registers an `afterEach` hook that sends story metadata from the browser to Node via `cy.task`. Without it, stories are recorded in the browser but never reach the reporter.
+
+Source: packages/executable-stories-cypress/src/support.ts
+
+### HIGH Using wrong file extension
+
+Wrong:
+
+```
+cypress/e2e/checkout.story.test.ts
+```
+
+Correct:
+
+```
+cypress/e2e/checkout.story.cy.ts
+```
+
+Cypress uses `.cy.ts` file extensions. The reporter expects `.story.cy.ts` for story test files.
+
+Source: CLAUDE.md — "Story test files use .story.cy.ts (cypress)"
+
+### MEDIUM Calling steps before story.init()
+
+Wrong:
+
+```typescript
+it("my test", () => {
+  story.given("something");
+  story.init();
+});
+```
+
+Correct:
+
+```typescript
+it("my test", () => {
+  story.init();
+  story.given("something");
+});
+```
+
+Steps called before `init()` are silently dropped because no story context exists.
+
+Source: packages/executable-stories-cypress/src/story-api.ts