cypress-reporter-setup

name	cypress-reporter-setup
description	Use when configuring the executable-stories-cypress reporter: wiring the Mocha reporter via --reporter or cypress.config.ts, or using the module API (buildRawRunFromCypressResult, generateReportsFromRawRun) for programmatic report generation.
type	core
library	executable-stories-cypress
library_version	8.4.7
sources	["jagreehal/executable-stories:packages/executable-stories-cypress/src/reporter.ts"]

executable-stories-cypress — Reporter Setup

Setup

Option A: Mocha reporter (CLI)

cypress run \
  --reporter executable-stories-cypress/reporter.cjs \
  --reporter-options "outputDir=docs,outputName=user-stories,formats=markdown"

Mocha's --reporter-options parses key=value pairs into string values only — it has no syntax for array values, so formats can only be set to a single format name this way. To generate multiple formats (e.g. markdown + html + junit), use the Module API instead.

Option B: Module API (programmatic)

// 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",
});

executable-stories-formatters is a bundled dependency (installed automatically with executable-stories-cypress).

CI-pipeline variant of the Module API (guarding on result.status): REFERENCE.md.

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:

// Expecting reporter to auto-generate reports
export default defineConfig({
  e2e: {
    setupNodeEvents(on) {
      registerExecutableStoriesPlugin(on);
    },
  },
  reporter: "executable-stories-cypress/reporter.cjs",
});

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