executable-stories-formatters 0.1.0

package/schemas/examples/pytest.json

@@ -0,0 +1,108 @@
+{
+  "schemaVersion": 1,
+  "projectRoot": "/home/ci/myapp",
+  "startedAtMs": 1706745600000,
+  "finishedAtMs": 1706745614000,
+  "meta": {
+    "framework": "pytest",
+    "pythonVersion": "3.12.1"
+  },
+  "testCases": [
+    {
+      "externalId": "tests/auth/test_login.py::test_successful_login",
+      "title": "Successful login with valid credentials",
+      "titlePath": ["tests", "auth", "test_login", "Successful login with valid credentials"],
+      "sourceFile": "tests/auth/test_login.py",
+      "sourceLine": 15,
+      "status": "pass",
+      "durationMs": 342,
+      "story": {
+        "scenario": "Successful login with valid credentials",
+        "steps": [
+          { "keyword": "Given", "text": "a registered user with email 'alice@example.com'" },
+          { "keyword": "When", "text": "the user submits login with valid credentials" },
+          { "keyword": "Then", "text": "the response status is 200" },
+          { "keyword": "And", "text": "a JWT token is returned" }
+        ],
+        "tags": ["smoke", "auth"],
+        "tickets": ["AUTH-101"],
+        "suitePath": ["tests", "auth", "test_login"],
+        "sourceOrder": 0
+      },
+      "meta": {
+        "framework": "pytest",
+        "frameworkCaseId": "tests/auth/test_login.py::test_successful_login"
+      }
+    },
+    {
+      "externalId": "tests/auth/test_login.py::TestLoginValidation::test_invalid_password",
+      "title": "Login with invalid password shows error",
+      "titlePath": ["tests", "auth", "test_login", "TestLoginValidation", "Login with invalid password shows error"],
+      "sourceFile": "tests/auth/test_login.py",
+      "sourceLine": 42,
+      "status": "fail",
+      "durationMs": 215,
+      "error": {
+        "message": "AssertionError: Expected status 401 but got 500",
+        "stack": "Traceback (most recent call last):\n  File \"tests/auth/test_login.py\", line 58, in test_invalid_password\n    assert response.status_code == 401\nAssertionError: assert 500 == 401"
+      },
+      "meta": {
+        "framework": "pytest",
+        "frameworkCaseId": "tests/auth/test_login.py::TestLoginValidation::test_invalid_password"
+      }
+    },
+    {
+      "externalId": "tests/auth/test_login.py::test_login_rate_limiting",
+      "title": "Login is rate-limited after 5 failed attempts",
+      "titlePath": ["tests", "auth", "test_login", "Login is rate-limited after 5 failed attempts"],
+      "sourceFile": "tests/auth/test_login.py",
+      "sourceLine": 68,
+      "status": "skip",
+      "durationMs": 0,
+      "meta": {
+        "framework": "pytest",
+        "frameworkCaseId": "tests/auth/test_login.py::test_login_rate_limiting",
+        "skipReason": "Rate limit middleware not deployed yet"
+      }
+    },
+    {
+      "externalId": "tests/cart/test_checkout.py::test_checkout_flow",
+      "title": "Complete checkout with credit card",
+      "titlePath": ["tests", "cart", "test_checkout", "Complete checkout with credit card"],
+      "sourceFile": "tests/cart/test_checkout.py",
+      "sourceLine": 10,
+      "status": "pass",
+      "durationMs": 890,
+      "story": {
+        "scenario": "Complete checkout with credit card",
+        "steps": [
+          { "keyword": "Given", "text": "a cart with 2 items totaling $59.98" },
+          { "keyword": "When", "text": "the user submits payment with a test credit card" },
+          { "keyword": "Then", "text": "the order is confirmed" },
+          { "keyword": "And", "text": "a confirmation email is queued" }
+        ],
+        "tags": ["checkout", "payments", "e2e"],
+        "tickets": ["SHOP-200"],
+        "suitePath": ["tests", "cart", "test_checkout"],
+        "sourceOrder": 0
+      },
+      "meta": {
+        "framework": "pytest",
+        "frameworkCaseId": "tests/cart/test_checkout.py::test_checkout_flow"
+      }
+    },
+    {
+      "externalId": "tests/cart/test_checkout.py::test_empty_cart_checkout",
+      "title": "Cannot checkout with an empty cart",
+      "titlePath": ["tests", "cart", "test_checkout", "Cannot checkout with an empty cart"],
+      "sourceFile": "tests/cart/test_checkout.py",
+      "sourceLine": 55,
+      "status": "pass",
+      "durationMs": 32,
+      "meta": {
+        "framework": "pytest",
+        "frameworkCaseId": "tests/cart/test_checkout.py::test_empty_cart_checkout"
+      }
+    }
+  ]
+}

package/schemas/examples/rust.json

@@ -0,0 +1,108 @@
+{
+  "schemaVersion": 1,
+  "projectRoot": "/home/ci/myapp",
+  "startedAtMs": 1706745600000,
+  "finishedAtMs": 1706745607000,
+  "meta": {
+    "framework": "rust",
+    "rustVersion": "1.76.0"
+  },
+  "testCases": [
+    {
+      "externalId": "crate::auth::tests::test_successful_login",
+      "title": "Successful login with valid credentials",
+      "titlePath": ["auth", "tests", "Successful login with valid credentials"],
+      "sourceFile": "src/auth.rs",
+      "sourceLine": 120,
+      "status": "pass",
+      "durationMs": 85,
+      "story": {
+        "scenario": "Successful login with valid credentials",
+        "steps": [
+          { "keyword": "Given", "text": "a registered user with email 'alice@example.com'" },
+          { "keyword": "When", "text": "the user submits login with valid credentials" },
+          { "keyword": "Then", "text": "the response status is 200" },
+          { "keyword": "And", "text": "a JWT token is returned" }
+        ],
+        "tags": ["smoke", "auth"],
+        "tickets": ["AUTH-101"],
+        "suitePath": ["auth", "tests"],
+        "sourceOrder": 0
+      },
+      "meta": {
+        "framework": "rust",
+        "frameworkCaseId": "crate::auth::tests::test_successful_login"
+      }
+    },
+    {
+      "externalId": "crate::auth::tests::test_login_invalid_password",
+      "title": "Login with invalid password returns 401",
+      "titlePath": ["auth", "tests", "Login with invalid password returns 401"],
+      "sourceFile": "src/auth.rs",
+      "sourceLine": 145,
+      "status": "fail",
+      "durationMs": 62,
+      "error": {
+        "message": "assertion `left == right` failed\n  left: 500\n right: 401",
+        "stack": "thread 'auth::tests::test_login_invalid_password' panicked at src/auth.rs:158:\nassertion `left == right` failed\n  left: 500\n right: 401\nnote: run with `RUST_BACKTRACE=1` environment variable to display a backtrace"
+      },
+      "meta": {
+        "framework": "rust",
+        "frameworkCaseId": "crate::auth::tests::test_login_invalid_password"
+      }
+    },
+    {
+      "externalId": "crate::auth::tests::test_login_rate_limiting",
+      "title": "Login is rate-limited after 5 failed attempts",
+      "titlePath": ["auth", "tests", "Login is rate-limited after 5 failed attempts"],
+      "sourceFile": "src/auth.rs",
+      "sourceLine": 170,
+      "status": "skip",
+      "durationMs": 0,
+      "meta": {
+        "framework": "rust",
+        "frameworkCaseId": "crate::auth::tests::test_login_rate_limiting",
+        "skipReason": "#[ignore] Rate limit middleware not deployed yet"
+      }
+    },
+    {
+      "externalId": "crate::cart::tests::test_complete_checkout",
+      "title": "Complete checkout with credit card",
+      "titlePath": ["cart", "tests", "Complete checkout with credit card"],
+      "sourceFile": "src/cart.rs",
+      "sourceLine": 88,
+      "status": "pass",
+      "durationMs": 210,
+      "story": {
+        "scenario": "Complete checkout with credit card",
+        "steps": [
+          { "keyword": "Given", "text": "a cart with 2 items totaling $59.98" },
+          { "keyword": "When", "text": "the user submits payment with a test credit card" },
+          { "keyword": "Then", "text": "the order is confirmed" },
+          { "keyword": "And", "text": "a confirmation email is queued" }
+        ],
+        "tags": ["checkout", "payments", "e2e"],
+        "tickets": ["SHOP-200"],
+        "suitePath": ["cart", "tests"],
+        "sourceOrder": 0
+      },
+      "meta": {
+        "framework": "rust",
+        "frameworkCaseId": "crate::cart::tests::test_complete_checkout"
+      }
+    },
+    {
+      "externalId": "crate::cart::tests::test_empty_cart_checkout",
+      "title": "Cannot checkout with an empty cart",
+      "titlePath": ["cart", "tests", "Cannot checkout with an empty cart"],
+      "sourceFile": "src/cart.rs",
+      "sourceLine": 115,
+      "status": "pass",
+      "durationMs": 8,
+      "meta": {
+        "framework": "rust",
+        "frameworkCaseId": "crate::cart::tests::test_empty_cart_checkout"
+      }
+    }
+  ]
+}

package/schemas/raw-run.schema.json

@@ -0,0 +1,437 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://executable-stories.dev/schemas/raw-run.schema.json",
+  "title": "RawRun",
+  "description": "Raw test run data from any test framework. Feed this to the executable-stories CLI to generate HTML, Markdown, JUnit XML, and Cucumber JSON reports.",
+  "type": "object",
+  "$ref": "#/$defs/RawRun",
+  "$defs": {
+    "RawRun": {
+      "type": "object",
+      "description": "Top-level raw run containing all test cases and run metadata.",
+      "properties": {
+        "schemaVersion": {
+          "type": "integer",
+          "const": 1,
+          "description": "Schema version for forward compatibility. Must be 1."
+        },
+        "testCases": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/RawTestCase" },
+          "description": "All test cases from the run."
+        },
+        "startedAtMs": {
+          "type": "number",
+          "minimum": 0,
+          "description": "Run start time as Unix epoch milliseconds."
+        },
+        "finishedAtMs": {
+          "type": "number",
+          "minimum": 0,
+          "description": "Run finish time as Unix epoch milliseconds."
+        },
+        "projectRoot": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Absolute path to the project root directory. Used for resolving relative attachment paths."
+        },
+        "packageVersion": {
+          "type": "string",
+          "description": "Version of the package under test."
+        },
+        "gitSha": {
+          "type": "string",
+          "description": "Git commit SHA at the time of the run."
+        },
+        "ci": {
+          "$ref": "#/$defs/RawCIInfo"
+        },
+        "meta": {
+          "type": "object",
+          "description": "Arbitrary runner-specific metadata. Escape hatch for data not covered by the schema."
+        }
+      },
+      "required": ["schemaVersion", "testCases", "projectRoot"],
+      "additionalProperties": false
+    },
+    "RawTestCase": {
+      "type": "object",
+      "description": "A single test case result. Only 'status' is required — everything else is optional to support plain unit tests without BDD metadata.",
+      "properties": {
+        "externalId": {
+          "type": "string",
+          "description": "Framework's native test ID (e.g., Jest test path, Playwright test ID)."
+        },
+        "title": {
+          "type": "string",
+          "description": "Human-readable test title/name."
+        },
+        "titlePath": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Full title path from describe/suite blocks down to the test name."
+        },
+        "story": {
+          "$ref": "#/$defs/StoryMeta"
+        },
+        "sourceFile": {
+          "type": "string",
+          "description": "Path to the source file containing this test (relative to projectRoot or absolute)."
+        },
+        "sourceLine": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Line number in the source file (1-based)."
+        },
+        "status": {
+          "$ref": "#/$defs/RawStatus"
+        },
+        "durationMs": {
+          "type": "number",
+          "minimum": 0,
+          "description": "Test duration in milliseconds."
+        },
+        "error": {
+          "type": "object",
+          "description": "Error information if the test failed.",
+          "properties": {
+            "message": {
+              "type": "string",
+              "description": "Error message."
+            },
+            "stack": {
+              "type": "string",
+              "description": "Error stack trace."
+            }
+          },
+          "additionalProperties": false
+        },
+        "stepEvents": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/RawStepEvent" },
+          "description": "Step-level execution events from the framework (if available)."
+        },
+        "attachments": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/RawAttachment" },
+          "description": "Attachments such as screenshots, logs, or other artifacts."
+        },
+        "meta": {
+          "type": "object",
+          "description": "Arbitrary framework-specific metadata. Escape hatch for data not covered by the schema."
+        },
+        "retry": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Retry attempt number (0-based). 0 means first attempt."
+        },
+        "retries": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Total number of retries configured for this test."
+        },
+        "projectName": {
+          "type": "string",
+          "description": "Project name (e.g., Playwright project like 'chromium', 'firefox')."
+        }
+      },
+      "required": ["status"],
+      "additionalProperties": false
+    },
+    "RawStatus": {
+      "type": "string",
+      "enum": ["pass", "fail", "skip", "todo", "pending", "timeout", "interrupted", "unknown"],
+      "description": "Permissive test status from any framework. Mapped to canonical status (passed/failed/skipped/pending) during canonicalization."
+    },
+    "StoryMeta": {
+      "type": "object",
+      "description": "BDD story metadata for a test case. Contains the scenario title, steps, tags, and documentation.",
+      "properties": {
+        "scenario": {
+          "type": "string",
+          "minLength": 1,
+          "description": "The scenario title (typically the test name)."
+        },
+        "steps": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/StoryStep" },
+          "description": "BDD steps in this scenario. Can be empty or omitted for progressive enrichment."
+        },
+        "tags": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Tags for filtering and categorization (e.g., ['smoke', 'auth'])."
+        },
+        "tickets": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Ticket/issue references for requirements traceability (e.g., ['JIRA-123'])."
+        },
+        "meta": {
+          "type": "object",
+          "description": "User-defined metadata for this story."
+        },
+        "suitePath": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Parent describe/suite names for hierarchical grouping."
+        },
+        "docs": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/DocEntry" },
+          "description": "Story-level documentation entries (before any steps)."
+        },
+        "sourceOrder": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Order in which the story was defined in source (for stable sorting)."
+        }
+      },
+      "required": ["scenario"],
+      "additionalProperties": false
+    },
+    "StoryStep": {
+      "type": "object",
+      "description": "A single BDD step in a scenario.",
+      "properties": {
+        "keyword": {
+          "$ref": "#/$defs/StepKeyword"
+        },
+        "text": {
+          "type": "string",
+          "description": "The step description text."
+        },
+        "mode": {
+          "$ref": "#/$defs/StepMode"
+        },
+        "docs": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/DocEntry" },
+          "description": "Rich documentation entries attached to this step."
+        }
+      },
+      "required": ["keyword", "text"],
+      "additionalProperties": false
+    },
+    "StepKeyword": {
+      "type": "string",
+      "description": "BDD step keyword. Case-insensitive — 'given' and 'Given' are both accepted. Normalized to title case during processing.",
+      "pattern": "^[Gg]iven$|^[Ww]hen$|^[Tt]hen$|^[Aa]nd$|^[Bb]ut$"
+    },
+    "StepMode": {
+      "type": "string",
+      "enum": ["normal", "skip", "only", "todo", "fails", "concurrent"],
+      "description": "Step execution mode for documentation rendering."
+    },
+    "DocPhase": {
+      "type": "string",
+      "enum": ["static", "runtime"],
+      "description": "When the doc entry was added — 'static' at definition time, 'runtime' during execution."
+    },
+    "DocEntry": {
+      "description": "A documentation entry attached to a story or step. Discriminated union on the 'kind' field.",
+      "oneOf": [
+        {
+          "type": "object",
+          "description": "Free-text note.",
+          "properties": {
+            "kind": { "const": "note" },
+            "text": { "type": "string" },
+            "phase": { "$ref": "#/$defs/DocPhase" }
+          },
+          "required": ["kind", "text", "phase"],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "description": "Tag(s) for categorization.",
+          "properties": {
+            "kind": { "const": "tag" },
+            "names": {
+              "type": "array",
+              "items": { "type": "string" }
+            },
+            "phase": { "$ref": "#/$defs/DocPhase" }
+          },
+          "required": ["kind", "names", "phase"],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "description": "Key-value pair.",
+          "properties": {
+            "kind": { "const": "kv" },
+            "label": { "type": "string" },
+            "value": {},
+            "phase": { "$ref": "#/$defs/DocPhase" }
+          },
+          "required": ["kind", "label", "value", "phase"],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "description": "Code block with optional language.",
+          "properties": {
+            "kind": { "const": "code" },
+            "label": { "type": "string" },
+            "content": { "type": "string" },
+            "lang": { "type": "string" },
+            "phase": { "$ref": "#/$defs/DocPhase" }
+          },
+          "required": ["kind", "label", "content", "phase"],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "description": "Markdown table.",
+          "properties": {
+            "kind": { "const": "table" },
+            "label": { "type": "string" },
+            "columns": {
+              "type": "array",
+              "items": { "type": "string" }
+            },
+            "rows": {
+              "type": "array",
+              "items": {
+                "type": "array",
+                "items": { "type": "string" }
+              }
+            },
+            "phase": { "$ref": "#/$defs/DocPhase" }
+          },
+          "required": ["kind", "label", "columns", "rows", "phase"],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "description": "Hyperlink.",
+          "properties": {
+            "kind": { "const": "link" },
+            "label": { "type": "string" },
+            "url": { "type": "string" },
+            "phase": { "$ref": "#/$defs/DocPhase" }
+          },
+          "required": ["kind", "label", "url", "phase"],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "description": "Titled section with markdown content.",
+          "properties": {
+            "kind": { "const": "section" },
+            "title": { "type": "string" },
+            "markdown": { "type": "string" },
+            "phase": { "$ref": "#/$defs/DocPhase" }
+          },
+          "required": ["kind", "title", "markdown", "phase"],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "description": "Mermaid diagram.",
+          "properties": {
+            "kind": { "const": "mermaid" },
+            "code": { "type": "string" },
+            "title": { "type": "string" },
+            "phase": { "$ref": "#/$defs/DocPhase" }
+          },
+          "required": ["kind", "code", "phase"],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "description": "Screenshot reference.",
+          "properties": {
+            "kind": { "const": "screenshot" },
+            "path": { "type": "string" },
+            "alt": { "type": "string" },
+            "phase": { "$ref": "#/$defs/DocPhase" }
+          },
+          "required": ["kind", "path", "phase"],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "description": "Custom documentation entry with arbitrary data.",
+          "properties": {
+            "kind": { "const": "custom" },
+            "type": { "type": "string" },
+            "data": {},
+            "phase": { "$ref": "#/$defs/DocPhase" }
+          },
+          "required": ["kind", "type", "data", "phase"],
+          "additionalProperties": false
+        }
+      ]
+    },
+    "RawAttachment": {
+      "type": "object",
+      "description": "A test attachment (screenshot, log, artifact). In the MVP schema, only path-based attachments are supported (no inline base64).",
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "Human-readable name for the attachment."
+        },
+        "mediaType": {
+          "type": "string",
+          "description": "MIME type (e.g., 'image/png', 'text/plain', 'application/json')."
+        },
+        "path": {
+          "type": "string",
+          "description": "File path (relative to projectRoot or absolute)."
+        }
+      },
+      "required": ["name", "mediaType", "path"],
+      "additionalProperties": false
+    },
+    "RawStepEvent": {
+      "type": "object",
+      "description": "Step-level execution event from the framework. Optional — most frameworks don't provide step-level data.",
+      "properties": {
+        "index": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Step index (0-based)."
+        },
+        "title": {
+          "type": "string",
+          "description": "Step title/description."
+        },
+        "status": {
+          "$ref": "#/$defs/RawStatus"
+        },
+        "durationMs": {
+          "type": "number",
+          "minimum": 0,
+          "description": "Step duration in milliseconds."
+        },
+        "errorMessage": {
+          "type": "string",
+          "description": "Error message if the step failed."
+        }
+      },
+      "additionalProperties": false
+    },
+    "RawCIInfo": {
+      "type": "object",
+      "description": "CI environment information.",
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "CI provider name (e.g., 'GitHub Actions', 'Jenkins', 'CircleCI')."
+        },
+        "url": {
+          "type": "string",
+          "description": "URL to the CI build/run."
+        },
+        "buildNumber": {
+          "type": "string",
+          "description": "CI build number or run ID."
+        }
+      },
+      "required": ["name"],
+      "additionalProperties": false
+    }
+  }
+}