executable-stories-formatters 0.4.0 → 0.5.0

package/README.md

@@ -64,8 +64,38 @@ executable-stories format raw-run.json --include "**/*.Story*.cs" --format html
 
 # Exclude test cases by source file glob
 executable-stories format raw-run.json --exclude "**/obj/**" --format markdown
+
+# With run history (flakiness, stability, performance in HTML)
+executable-stories format run.json --format html --history-file .history/runs.json
+
+# Notify on failure (Slack or Teams; env: SLACK_WEBHOOK_URL / TEAMS_WEBHOOK_URL)
+executable-stories format run.json --format html --notify on-failure --report-url "https://ci.example.com/artifacts/report.html"
 ```
 
+### CI detection
+
+When the CLI runs in a CI environment, it auto-detects the provider from environment variables and attaches branch, commit SHA, PR number, build number, and build URL to the run. The HTML report shows this in a **CI** meta block. Supported providers (first match wins): Azure DevOps (`TF_BUILD`), Buildkite, GitHub Actions, GitLab CI, CircleCI, Jenkins, Travis CI; generic fallback when `CI=true`. No flags required—detection is automatic.
+
+### Notifications
+
+After generating reports, the CLI can send a short summary to Slack, Microsoft Teams, or a generic webhook:
+
+- **Slack** — `--slack-webhook <url>` or `SLACK_WEBHOOK_URL` env. Uses an incoming webhook.
+- **Teams** — `--teams-webhook <url>` or `TEAMS_WEBHOOK_URL` env. Uses an incoming webhook connector.
+- **Generic webhook** — `--webhook-url <url>` (repeatable). Optional `--webhook-header "Key: Value"`, `--webhook-method POST|PUT`, and HMAC-SHA256 signing via `--webhook-hmac-secret`, `--webhook-hmac-header`, `--webhook-hmac-timestamp`.
+
+Control when notifications are sent with **`--notify`**: `always`, `on-failure` (default), or `never`. Use **`--report-url`** to pass a public URL for the report so notification messages can link to it. **`--max-failed-tests`** (default 5) limits how many failed tests are listed in the message.
+
+### Run history
+
+Use **`--history-file <path>`** to persist run history to a JSON file. The CLI updates this file after each run and uses it to compute, for the HTML report:
+
+- **Flakiness** — stable / unstable / flaky from pass/fail history
+- **Stability grade** — A–F from recent pass rate
+- **Performance trend** — improving / stable / regressing from duration history
+
+**`--max-history-runs <n>`** (default 10) caps how many runs are kept per test. Omit `--history-file` to disable history (no file is read or written).
+
 ### Filtering by source file
 
 You can limit which test cases appear in reports using **include** and **exclude** glob patterns on `sourceFile`:
@@ -119,7 +149,7 @@ const generator = new ReportGenerator({
 
 | Format | Description | File Extension |
 | --- | --- | --- |
-| `html` | Interactive HTML report with search, screenshots, step parameter highlighting (quoted strings and numbers), syntax-highlighted code blocks, Mermaid diagrams, and Markdown in doc sections | `.html` |
+| `html` | Interactive HTML report with search, screenshots, step parameter highlighting (quoted strings and numbers), syntax-highlighted code blocks, Mermaid diagrams, Markdown in doc sections, optional CI meta block (branch, commit, build link), and run history (flakiness, stability grade, performance trend when `--history-file` is used) | `.html` |
 | `markdown` | Markdown user-story documentation | `.md` |
 | `junit` | JUnit XML for CI integration | `.junit.xml` |
 | `cucumber-json` | Cucumber JSON for tooling compatibility | `.cucumber.json` |
@@ -196,6 +226,13 @@ interface RawTestCase {
 - `normalizeVitestResults(...)` — `adaptVitestRun` + `canonicalizeRun` in one call
 - `normalizePlaywrightResults(...)` — `adaptPlaywrightRun` + `canonicalizeRun` in one call
 
+### CI, history, and notifications (programmatic)
+
+- `detectCI(env?)` — Detect CI environment from `process.env` (or provided object); returns `RawCIInfo` or `undefined`. Used by the CLI; also available for custom pipelines.
+- `toCIInfo(raw?)` / `toRawCIInfo(ci?)` — Convert between `RawCIInfo` (transport) and `CIInfo` (canonical display). Types: `CIInfo`, `CIProvider` from `./types/ci`.
+- `loadHistory(args, deps)` / `saveHistory(args, deps)` / `updateHistory(args)` — Read/write run history JSON. Used by the CLI when `--history-file` is set; also usable from custom tooling.
+- `sendNotifications(args, deps)` — Send Slack, Teams, and/or generic webhook notifications. Types: `NotificationSummary`, `NotifyCondition`, `GenericWebhookNotifierOptions`, `WebhookSignerHmac`. Individual senders: `sendSlackNotification`, `sendTeamsNotification`, `sendWebhookNotification`; `signBody` for HMAC signing.
+
 ### Types
 
 See the TypeScript type exports for `TestRunResult`, `RawRun`, `RawTestCase`, `FormatterOptions`, and more. `FormatterOptions` supports `include` and `exclude` (string arrays of glob patterns) to filter test cases by `sourceFile` before generating reports.

package/dist/adapters.d.cts

@@ -1 +1 @@
-export { J as JestAdapterOptions, i as JestAggregatedResult, j as JestFileResult, k as JestTestResult, P as PlaywrightAdapterOptions, m as PlaywrightAnnotation, n as PlaywrightAttachment, o as PlaywrightError, p as PlaywrightLocation, q as PlaywrightStatus, r as PlaywrightTestCase, s as PlaywrightTestResult, y as StoryFileReport, V as VitestAdapterOptions, z as VitestSerializedError, A as VitestState, B as VitestTestCase, C as VitestTestModule, E as VitestTestResult, e as adaptJestRun, f as adaptPlaywrightRun, g as adaptVitestRun } from './index-DyeUWfYK.cjs';
+export { J as JestAdapterOptions, j as JestAggregatedResult, k as JestFileResult, l as JestTestResult, P as PlaywrightAdapterOptions, n as PlaywrightAnnotation, o as PlaywrightAttachment, p as PlaywrightError, q as PlaywrightLocation, r as PlaywrightStatus, s as PlaywrightTestCase, t as PlaywrightTestResult, z as StoryFileReport, V as VitestAdapterOptions, A as VitestSerializedError, B as VitestState, E as VitestTestCase, F as VitestTestModule, G as VitestTestResult, f as adaptJestRun, g as adaptPlaywrightRun, h as adaptVitestRun } from './index-C4QO-SVT.cjs';

package/dist/adapters.d.ts

@@ -1 +1 @@
-export { J as JestAdapterOptions, i as JestAggregatedResult, j as JestFileResult, k as JestTestResult, P as PlaywrightAdapterOptions, m as PlaywrightAnnotation, n as PlaywrightAttachment, o as PlaywrightError, p as PlaywrightLocation, q as PlaywrightStatus, r as PlaywrightTestCase, s as PlaywrightTestResult, y as StoryFileReport, V as VitestAdapterOptions, z as VitestSerializedError, A as VitestState, B as VitestTestCase, C as VitestTestModule, E as VitestTestResult, e as adaptJestRun, f as adaptPlaywrightRun, g as adaptVitestRun } from './index-DyeUWfYK.js';
+export { J as JestAdapterOptions, j as JestAggregatedResult, k as JestFileResult, l as JestTestResult, P as PlaywrightAdapterOptions, n as PlaywrightAnnotation, o as PlaywrightAttachment, p as PlaywrightError, q as PlaywrightLocation, r as PlaywrightStatus, s as PlaywrightTestCase, t as PlaywrightTestResult, z as StoryFileReport, V as VitestAdapterOptions, A as VitestSerializedError, B as VitestState, E as VitestTestCase, F as VitestTestModule, G as VitestTestResult, f as adaptJestRun, g as adaptPlaywrightRun, h as adaptVitestRun } from './index-C4QO-SVT.js';