executable-stories-formatters 0.1.0

package/dist/index-DCJ0NvAp.d.ts

@@ -0,0 +1,378 @@
+/**
+ * Story types — the shared vocabulary for all framework adapters.
+ *
+ * These types were previously in executable-stories-core.
+ * They now live in formatters so every adapter can import them
+ * from the same place that defines RawRun (the output contract).
+ */
+/** BDD step keywords for scenario documentation */
+type StepKeyword = "Given" | "When" | "Then" | "And" | "But";
+/** Step execution mode for docs rendering */
+type StepMode = "normal" | "skip" | "only" | "todo" | "fails" | "concurrent";
+/** Phase tracks when the doc entry was added */
+type DocPhase = "static" | "runtime";
+/** Union type for all documentation entry kinds */
+type DocEntry = {
+    kind: "note";
+    text: string;
+    phase: DocPhase;
+} | {
+    kind: "tag";
+    names: string[];
+    phase: DocPhase;
+} | {
+    kind: "kv";
+    label: string;
+    value: unknown;
+    phase: DocPhase;
+} | {
+    kind: "code";
+    label: string;
+    content: string;
+    lang?: string;
+    phase: DocPhase;
+} | {
+    kind: "table";
+    label: string;
+    columns: string[];
+    rows: string[][];
+    phase: DocPhase;
+} | {
+    kind: "link";
+    label: string;
+    url: string;
+    phase: DocPhase;
+} | {
+    kind: "section";
+    title: string;
+    markdown: string;
+    phase: DocPhase;
+} | {
+    kind: "mermaid";
+    code: string;
+    title?: string;
+    phase: DocPhase;
+} | {
+    kind: "screenshot";
+    path: string;
+    alt?: string;
+    phase: DocPhase;
+} | {
+    kind: "custom";
+    type: string;
+    data: unknown;
+    phase: DocPhase;
+};
+/**
+ * A single step in a scenario with its documentation entries.
+ */
+interface StoryStep {
+    /** Stable internal ID (auto-generated at creation, e.g., "step-0") */
+    id?: string;
+    /** The BDD keyword (Given, When, Then, And, But) */
+    keyword: StepKeyword;
+    /** The step description text */
+    text: string;
+    /** Step execution mode for docs rendering */
+    mode?: StepMode;
+    /** Rich documentation entries attached to this step */
+    docs?: DocEntry[];
+    /** Opt-in step duration in milliseconds */
+    durationMs?: number;
+    /** Whether this step wrapped a function body (step.fn / step.step) vs a text marker */
+    wrapped?: boolean;
+}
+/**
+ * Metadata for a complete scenario, attached to test metadata.
+ * Used by reporters to generate documentation.
+ */
+interface StoryMeta {
+    /** The scenario title (from test name) */
+    scenario: string;
+    /** All steps in this scenario */
+    steps: StoryStep[];
+    /** Tags for filtering and categorization */
+    tags?: string[];
+    /** Ticket/issue references (normalized to array) */
+    tickets?: string[];
+    /** User-defined metadata */
+    meta?: Record<string, unknown>;
+    /** Parent describe/suite names for hierarchical grouping */
+    suitePath?: string[];
+    /** Story-level docs (before any steps) */
+    docs?: DocEntry[];
+    /** Order in which story.init() was called (for source ordering) */
+    sourceOrder?: number;
+}
+/** Key used to store StoryMeta in test metadata */
+declare const STORY_META_KEY = "story";
+
+/**
+ * Raw types for Layer 1: Framework Adapters.
+ *
+ * These types are permissive and gather best-effort data from each framework.
+ * The ACL (Layer 2) will normalize these into strict canonical types.
+ */
+
+/** Permissive status from any framework */
+type RawStatus = "pass" | "fail" | "skip" | "todo" | "pending" | "timeout" | "interrupted" | "unknown";
+/** Raw attachment - don't decide inline vs link yet */
+interface RawAttachment {
+    name: string;
+    mediaType: string;
+    /** File reference (path on disk) */
+    path?: string;
+    /** Inline content */
+    body?: string;
+    /** Content encoding */
+    encoding?: "BASE64" | "IDENTITY";
+    /** Character set (default: "utf-8" when IDENTITY + text) */
+    charset?: string;
+    /** Actual artifact name (distinct from logical label) */
+    fileName?: string;
+    /** Size in bytes (for embed vs link decision) */
+    byteLength?: number;
+    /** Step index (undefined = test-case level) */
+    stepIndex?: number;
+    /** Stable step ID, preferred over stepIndex by converter */
+    stepId?: string;
+}
+/** Raw step event from framework (if available) */
+interface RawStepEvent {
+    index?: number;
+    title?: string;
+    status?: RawStatus;
+    durationMs?: number;
+    errorMessage?: string;
+}
+/** Raw test case - best-effort data gathering */
+interface RawTestCase {
+    /** Framework's test ID */
+    externalId?: string;
+    /** Test title/name */
+    title?: string;
+    /** Full title path (describe blocks + test name) */
+    titlePath?: string[];
+    /** Story metadata from test */
+    story?: StoryMeta;
+    /** Source file path */
+    sourceFile?: string;
+    /** Source line number (1-based) */
+    sourceLine?: number;
+    /** Test status */
+    status: RawStatus;
+    /** Duration in milliseconds */
+    durationMs?: number;
+    /** Error information */
+    error?: {
+        message?: string;
+        stack?: string;
+    };
+    /** Step-level info if framework provides it */
+    stepEvents?: RawStepEvent[];
+    /** Attachments (screenshots, logs, etc.) */
+    attachments?: RawAttachment[];
+    /** Framework-specific metadata (kept for debugging) */
+    meta?: Record<string, unknown>;
+    /** Retry attempt number (0-based) */
+    retry?: number;
+    /** Total retry count configured */
+    retries?: number;
+    /** Playwright project name */
+    projectName?: string;
+}
+/** CI environment info */
+interface RawCIInfo {
+    name: string;
+    url?: string;
+    buildNumber?: string;
+}
+/** Raw run - all framework data gathered */
+interface RawRun {
+    /** All test cases from the run */
+    testCases: RawTestCase[];
+    /** Run start time (epoch ms) */
+    startedAtMs?: number;
+    /** Run finish time (epoch ms) */
+    finishedAtMs?: number;
+    /** Project root directory */
+    projectRoot: string;
+    /** Package version */
+    packageVersion?: string;
+    /** Git commit SHA */
+    gitSha?: string;
+    /** CI environment info */
+    ci?: RawCIInfo;
+}
+
+/**
+ * Jest Adapter - Layer 1.
+ *
+ * Transforms Jest test results and story reports into RawRun.
+ */
+
+/** Jest test result shape (subset of what Jest provides) */
+interface JestTestResult {
+    fullName: string;
+    status: "passed" | "failed" | "pending" | "todo";
+    duration?: number;
+    failureMessages?: string[];
+}
+/** Jest file result shape */
+interface JestFileResult {
+    testFilePath: string;
+    testResults: JestTestResult[];
+}
+/** Jest aggregated result shape */
+interface JestAggregatedResult {
+    testResults: JestFileResult[];
+    startTime?: number;
+}
+/** Story file report written by story.init() */
+interface StoryFileReport {
+    testFilePath: string;
+    scenarios: StoryMeta[];
+}
+/** Options for Jest adapter */
+interface JestAdapterOptions {
+    /** Project root directory */
+    projectRoot?: string;
+    /** Package version */
+    packageVersion?: string;
+    /** Git SHA */
+    gitSha?: string;
+}
+/**
+ * Adapt Jest results and story reports to RawRun.
+ *
+ * @param jestResults - Jest aggregated results
+ * @param storyReports - Story reports from story.init()
+ * @param options - Adapter options
+ * @returns RawRun for ACL processing
+ */
+declare function adaptJestRun(jestResults: JestAggregatedResult, storyReports: StoryFileReport[], options?: JestAdapterOptions): RawRun;
+
+/**
+ * Vitest Adapter - Layer 1.
+ *
+ * Transforms Vitest test results into RawRun.
+ */
+
+/** Vitest test state */
+type VitestState = "passed" | "failed" | "skipped" | "pending";
+/** Vitest serialized error */
+interface VitestSerializedError {
+    message?: string;
+    stack?: string;
+    diff?: string;
+}
+/** Vitest test result shape */
+interface VitestTestResult {
+    state?: VitestState;
+    duration?: number;
+    errors?: VitestSerializedError[];
+}
+/** Vitest test case shape (minimal) */
+interface VitestTestCase {
+    name: string;
+    meta: () => Record<string, unknown>;
+    result: () => VitestTestResult | undefined;
+}
+/** Vitest test module shape (minimal) */
+interface VitestTestModule {
+    moduleId?: string;
+    relativeModuleId?: string;
+    children?: {
+        allTests: () => Iterable<VitestTestCase>;
+    };
+}
+/** Options for Vitest adapter */
+interface VitestAdapterOptions {
+    /** Project root directory */
+    projectRoot?: string;
+    /** Package version */
+    packageVersion?: string;
+    /** Git SHA */
+    gitSha?: string;
+    /** Start time (epoch ms) */
+    startedAtMs?: number;
+}
+/**
+ * Adapt Vitest test modules to RawRun.
+ *
+ * @param testModules - Vitest test modules
+ * @param options - Adapter options
+ * @returns RawRun for ACL processing
+ */
+declare function adaptVitestRun(testModules: ReadonlyArray<VitestTestModule>, options?: VitestAdapterOptions): RawRun;
+
+/**
+ * Playwright Adapter - Layer 1.
+ *
+ * Transforms Playwright test results into RawRun.
+ */
+
+/** Playwright test status */
+type PlaywrightStatus = "passed" | "failed" | "skipped" | "timedOut" | "interrupted";
+/** Playwright test error */
+interface PlaywrightError {
+    message?: string;
+    stack?: string;
+}
+/** Playwright attachment */
+interface PlaywrightAttachment {
+    name: string;
+    contentType: string;
+    path?: string;
+    body?: Buffer;
+}
+/** Playwright test result */
+interface PlaywrightTestResult {
+    status: PlaywrightStatus;
+    duration: number;
+    errors: PlaywrightError[];
+    attachments: PlaywrightAttachment[];
+    retry: number;
+}
+/** Playwright test case annotation */
+interface PlaywrightAnnotation {
+    type: string;
+    description?: string;
+}
+/** Playwright test location */
+interface PlaywrightLocation {
+    file: string;
+    line: number;
+    column: number;
+}
+/** Playwright test case shape (minimal) */
+interface PlaywrightTestCase {
+    title: string;
+    titlePath: () => string[];
+    annotations: PlaywrightAnnotation[];
+    location: PlaywrightLocation;
+    retries: number;
+}
+/** Options for Playwright adapter */
+interface PlaywrightAdapterOptions {
+    /** Project root directory */
+    projectRoot?: string;
+    /** Package version */
+    packageVersion?: string;
+    /** Git SHA */
+    gitSha?: string;
+    /** Start time (epoch ms) */
+    startedAtMs?: number;
+    /** Playwright project name */
+    projectName?: string;
+}
+/**
+ * Adapt Playwright test results to RawRun.
+ *
+ * @param testResults - Array of [testCase, result] tuples
+ * @param options - Adapter options
+ * @returns RawRun for ACL processing
+ */
+declare function adaptPlaywrightRun(testResults: Array<[PlaywrightTestCase, PlaywrightTestResult]>, options?: PlaywrightAdapterOptions): RawRun;
+
+export { type VitestTestCase as A, type VitestTestModule as B, type VitestTestResult as C, type DocEntry as D, type JestAdapterOptions as J, type PlaywrightAdapterOptions as P, type RawStatus as R, type StoryMeta as S, type VitestAdapterOptions as V, type StoryStep as a, type RawAttachment as b, type RawRun as c, type RawCIInfo as d, adaptJestRun as e, adaptPlaywrightRun as f, adaptVitestRun as g, type DocPhase as h, type JestAggregatedResult as i, type JestFileResult as j, type JestTestResult as k, type PlaywrightAnnotation as l, type PlaywrightAttachment as m, type PlaywrightError as n, type PlaywrightLocation as o, type PlaywrightStatus as p, type PlaywrightTestCase as q, type PlaywrightTestResult as r, type RawStepEvent as s, type RawTestCase as t, STORY_META_KEY as u, type StepKeyword as v, type StepMode as w, type StoryFileReport as x, type VitestSerializedError as y, type VitestState as z };