executable-stories-vitest 2.0.0

package/dist/index.d.ts

@@ -0,0 +1,447 @@
+import { StepKeyword } from 'executable-stories-formatters';
+export { ColocatedStyle, DocEntry, DocPhase, FormatterOptions, OutputFormat, OutputMode, OutputRule, STORY_META_KEY, StepKeyword, StepMode, StoryMeta, StoryStep } from 'executable-stories-formatters';
+export { StoryReporterOptions } from './reporter.js';
+import 'vitest/node';
+
+/**
+ * Type definitions for executable-stories-vitest.
+ *
+ * Shared story types (StepKeyword, DocEntry, StoryStep, StoryMeta, etc.)
+ * are imported from executable-stories-formatters — the single source of truth.
+ * This module re-exports them and adds Vitest-specific types.
+ */
+
+/**
+ * Inline documentation options for step markers.
+ * Pass to story.given(), story.when(), story.then() as second argument.
+ *
+ * @example
+ * ```ts
+ * story.given('valid credentials', {
+ *   json: { label: 'Credentials', value: { email: 'test@example.com', password: '***' } },
+ *   note: 'Password is masked for security'
+ * });
+ * ```
+ */
+interface StoryDocs {
+    /** Add a free-text note */
+    note?: string;
+    /** Add tag(s) for categorization */
+    tag?: string | string[];
+    /** Add key-value pairs */
+    kv?: Record<string, unknown>;
+    /** Add a code block with label and optional language */
+    code?: {
+        label: string;
+        content: string;
+        lang?: string;
+    };
+    /** Add a JSON data block with label */
+    json?: {
+        label: string;
+        value: unknown;
+    };
+    /** Add a markdown table with label */
+    table?: {
+        label: string;
+        columns: string[];
+        rows: string[][];
+    };
+    /** Add a hyperlink */
+    link?: {
+        label: string;
+        url: string;
+    };
+    /** Add a titled section with markdown content */
+    section?: {
+        title: string;
+        markdown: string;
+    };
+    /** Add a Mermaid diagram with optional title */
+    mermaid?: {
+        code: string;
+        title?: string;
+    };
+    /** Add a screenshot reference */
+    screenshot?: {
+        path: string;
+        alt?: string;
+    };
+    /** Add a custom documentation entry */
+    custom?: {
+        type: string;
+        data: unknown;
+    };
+}
+/**
+ * Options for configuring a story via story.init().
+ *
+ * @example
+ * ```ts
+ * it('admin deletes user', ({ task }) => {
+ *   story.init(task, {
+ *     tags: ['admin', 'destructive'],
+ *     ticket: 'JIRA-456'
+ *   });
+ * });
+ * ```
+ */
+interface StoryOptions {
+    /** Tags for filtering and categorizing stories */
+    tags?: string[];
+    /** Ticket/issue reference(s) for requirements traceability */
+    ticket?: string | string[];
+    /** Arbitrary user-defined metadata */
+    meta?: Record<string, unknown>;
+}
+/** Minimal Vitest suite interface for suite path extraction */
+interface VitestSuite {
+    /** Suite name */
+    name?: string;
+    /** Parent suite (optional) */
+    suite?: VitestSuite;
+}
+/**
+ * Minimal Vitest task interface for story.init().
+ * This is the { task } from it('name', ({ task }) => { ... }).
+ *
+ * Uses generic type parameter to be compatible with Vitest's actual TaskMeta type.
+ */
+interface VitestTask<TMeta = Record<string, unknown>> {
+    /** The test/task name */
+    name: string;
+    /** Task metadata object where we store story data */
+    meta: TMeta;
+    /** Parent suite (optional) */
+    suite?: VitestSuite;
+    /** The test file (optional) */
+    file?: {
+        name?: string;
+    };
+}
+
+/**
+ * story.* API for executable-stories-vitest.
+ *
+ * Uses native Vitest describe/it/test with opt-in documentation:
+ *
+ * @example
+ * ```ts
+ * import { describe, it, expect } from 'vitest';
+ * import { story } from 'executable-stories-vitest';
+ *
+ * describe('Calculator', () => {
+ *   it('adds two numbers', ({ task }) => {
+ *     story.init(task);
+ *
+ *     story.given('two numbers 5 and 3');
+ *     const a = 5;
+ *     const b = 3;
+ *
+ *     story.when('I add them together');
+ *     const result = a + b;
+ *
+ *     story.then('the result is 8');
+ *     expect(result).toBe(8);
+ *   });
+ * });
+ * ```
+ */
+
+/**
+ * Minimal task interface compatible with Vitest's Test type.
+ * The meta property accepts any object type to be compatible with Vitest's TaskMeta.
+ */
+interface TaskLike {
+    name: string;
+    meta: any;
+    suite?: VitestSuite;
+    file?: {
+        name?: string;
+    };
+}
+/** Attachment options for story.attach() */
+interface AttachmentOptions {
+    name: string;
+    mediaType: string;
+    path?: string;
+    body?: string;
+    encoding?: "BASE64" | "IDENTITY";
+    charset?: string;
+    fileName?: string;
+}
+/**
+ * Initialize a story for the current test.
+ * Must be called at the start of each test that wants documentation.
+ *
+ * @param task - The Vitest task object from ({ task }) => { ... }
+ * @param options - Optional story configuration (tags, ticket, meta)
+ *
+ * @example
+ * ```ts
+ * it('adds two numbers', ({ task }) => {
+ *   story.init(task);
+ *   // ... rest of test
+ * });
+ *
+ * // With options:
+ * it('admin deletes user', ({ task }) => {
+ *   story.init(task, {
+ *     tags: ['admin', 'destructive'],
+ *     ticket: 'JIRA-456'
+ *   });
+ * });
+ * ```
+ */
+declare function init(task: TaskLike, options?: StoryOptions): void;
+/**
+ * Add a free-text note to the current step or story-level if before any step.
+ */
+declare function note(text: string): void;
+/** Options for kv() - key-value pair */
+interface KvOptions {
+    label: string;
+    value: unknown;
+}
+/** Options for json() - JSON code block */
+interface JsonOptions {
+    label: string;
+    value: unknown;
+}
+/** Options for code() - code block with optional language */
+interface CodeOptions {
+    label: string;
+    content: string;
+    lang?: string;
+}
+/** Options for table() - markdown table */
+interface TableOptions {
+    label: string;
+    columns: string[];
+    rows: string[][];
+}
+/** Options for link() - hyperlink */
+interface LinkOptions {
+    label: string;
+    url: string;
+}
+/** Options for section() - titled markdown section */
+interface SectionOptions {
+    title: string;
+    markdown: string;
+}
+/** Options for mermaid() - Mermaid diagram */
+interface MermaidOptions {
+    code: string;
+    title?: string;
+}
+/** Options for screenshot() - screenshot reference */
+interface ScreenshotOptions {
+    path: string;
+    alt?: string;
+}
+/** Options for custom() - custom doc entry */
+interface CustomOptions {
+    type: string;
+    data: unknown;
+}
+/**
+ * Add a key-value pair to the current step or story-level.
+ * @example story.kv({ label: 'Payment ID', value: 'pay_123' })
+ */
+declare function kv(options: KvOptions): void;
+/**
+ * Add a JSON code block to the current step or story-level.
+ * @example story.json({ label: 'Order', value: { id: 123 } })
+ */
+declare function json(options: JsonOptions): void;
+/**
+ * Add a code block with optional language to the current step or story-level.
+ * @example story.code({ label: 'Config', content: 'port: 3000', lang: 'yaml' })
+ */
+declare function code(options: CodeOptions): void;
+/**
+ * Add a markdown table to the current step or story-level.
+ * @example story.table({ label: 'Users', columns: ['Name', 'Role'], rows: [['Alice', 'Admin']] })
+ */
+declare function table(options: TableOptions): void;
+/**
+ * Add a hyperlink to the current step or story-level.
+ * @example story.link({ label: 'API Docs', url: 'https://docs.example.com' })
+ */
+declare function link(options: LinkOptions): void;
+/**
+ * Add a titled section with markdown content to the current step or story-level.
+ * @example story.section({ title: 'Details', markdown: 'This is **important**' })
+ */
+declare function section(options: SectionOptions): void;
+/**
+ * Add a Mermaid diagram to the current step or story-level.
+ * @example story.mermaid({ code: 'graph LR; A-->B', title: 'Flow' })
+ */
+declare function mermaid(options: MermaidOptions): void;
+/**
+ * Add a screenshot reference to the current step or story-level.
+ * @example story.screenshot({ path: '/screenshots/result.png', alt: 'Final result' })
+ */
+declare function screenshot(options: ScreenshotOptions): void;
+/**
+ * Add tag(s) to the current step or story-level.
+ * @example story.tag('admin') or story.tag(['admin', 'security'])
+ */
+declare function tag(name: string | string[]): void;
+/**
+ * Add a custom documentation entry for use with custom renderers.
+ * @example story.custom({ type: 'myType', data: { foo: 'bar' } })
+ */
+declare function custom(options: CustomOptions): void;
+/**
+ * Attach a file or inline content to the current step or test case.
+ * @example story.attach({ name: 'screenshot', mediaType: 'image/png', path: '/tmp/screenshot.png' })
+ */
+declare function attach(options: AttachmentOptions): void;
+/**
+ * Start a timer for the current step. Returns a token to pass to endTimer().
+ */
+declare function startTimer(): number;
+/**
+ * End a timer and record duration on the step that was active when startTimer() was called.
+ */
+declare function endTimer(token: number): void;
+/**
+ * Wrap a function body as a step. Records the step with timing and `wrapped: true`.
+ * Supports both sync and async functions. Returns whatever the function returns.
+ *
+ * @param keyword - The BDD keyword (Given, When, Then, And, But)
+ * @param text - Step description
+ * @param body - The function to execute
+ * @returns The return value of body (or a Promise of it if body is async)
+ *
+ * @example
+ * ```ts
+ * const data = story.fn('Given', 'setup data', () => ({ a: 5, b: 3 }));
+ * const result = await story.fn('When', 'call API', async () => fetch('/api'));
+ * ```
+ */
+declare function fn<T>(keyword: StepKeyword, text: string, body: () => T): T;
+/**
+ * Wrap an assertion as a Then step. Shorthand for `story.fn('Then', text, body)`.
+ *
+ * @param text - Step description
+ * @param body - The assertion function to execute
+ *
+ * @example
+ * ```ts
+ * story.expect('the result is 8', () => { expect(result).toBe(8); });
+ * await story.expect('async check', async () => { ... });
+ * ```
+ */
+declare function storyExpect<T>(text: string, body: () => T): T;
+/**
+ * The main story API object.
+ *
+ * Use with native Vitest describe/it/test for full IDE support:
+ *
+ * @example
+ * ```ts
+ * import { describe, it, expect } from 'vitest';
+ * import { story } from 'executable-stories-vitest';
+ *
+ * describe('Calculator', () => {
+ *   it('adds two numbers', ({ task }) => {
+ *     story.init(task);
+ *
+ *     story.given('two numbers 5 and 3');
+ *     const a = 5, b = 3;
+ *
+ *     story.when('I add them together');
+ *     const result = a + b;
+ *
+ *     story.then('the result is 8');
+ *     expect(result).toBe(8);
+ *   });
+ * });
+ * ```
+ */
+declare const story: {
+    init: typeof init;
+    given: (text: string, docs?: StoryDocs) => void;
+    when: (text: string, docs?: StoryDocs) => void;
+    then: (text: string, docs?: StoryDocs) => void;
+    and: (text: string, docs?: StoryDocs) => void;
+    but: (text: string, docs?: StoryDocs) => void;
+    arrange: (text: string, docs?: StoryDocs) => void;
+    act: (text: string, docs?: StoryDocs) => void;
+    assert: (text: string, docs?: StoryDocs) => void;
+    setup: (text: string, docs?: StoryDocs) => void;
+    context: (text: string, docs?: StoryDocs) => void;
+    execute: (text: string, docs?: StoryDocs) => void;
+    action: (text: string, docs?: StoryDocs) => void;
+    verify: (text: string, docs?: StoryDocs) => void;
+    note: typeof note;
+    kv: typeof kv;
+    json: typeof json;
+    code: typeof code;
+    table: typeof table;
+    link: typeof link;
+    section: typeof section;
+    mermaid: typeof mermaid;
+    screenshot: typeof screenshot;
+    tag: typeof tag;
+    custom: typeof custom;
+    attach: typeof attach;
+    fn: typeof fn;
+    expect: typeof storyExpect;
+    startTimer: typeof startTimer;
+    endTimer: typeof endTimer;
+};
+type Story = typeof story;
+
+/**
+ * executable-stories-vitest: Native Vitest story/given/when/then with Markdown doc generation.
+ *
+ * Uses native Vitest describe/it/test for full IDE support:
+ *
+ * @example
+ * ```ts
+ * import { describe, it, expect } from 'vitest';
+ * import { story } from 'executable-stories-vitest';
+ *
+ * describe('Calculator', () => {
+ *   it('adds two numbers', ({ task }) => {
+ *     story.init(task);
+ *
+ *     story.given('two numbers 5 and 3');
+ *     const a = 5, b = 3;
+ *
+ *     story.when('I add them together');
+ *     const result = a + b;
+ *
+ *     story.then('the result is 8');
+ *     expect(result).toBe(8);
+ *   });
+ * });
+ * ```
+ *
+ * In vitest.config, import StoryReporter from "executable-stories-vitest/reporter":
+ *
+ * @example
+ * ```ts
+ * import { defineConfig } from "vitest/config";
+ * import { StoryReporter } from "executable-stories-vitest/reporter";
+ *
+ * export default defineConfig({
+ *   test: {
+ *     reporters: ["default", new StoryReporter()],
+ *   },
+ * });
+ * ```
+ */
+
+/** @internal Guard: throws if used. Import StoryReporter from "executable-stories-vitest/reporter" in vitest.config. */
+declare class StoryReporter {
+    static __isGuard: boolean;
+    constructor();
+}
+
+export { type Story, type StoryDocs, type StoryOptions, StoryReporter, type VitestSuite, type VitestTask, story };