@swedevtools/livedoc-vitest 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2014 dotnetprofessional
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,95 @@
+<div align="center">
+
+# @swedevtools/livedoc-vitest
+
+### Turn your tests into living documentation
+
+[![npm version](https://img.shields.io/npm/v/@swedevtools/livedoc-vitest.svg)](https://www.npmjs.com/package/@swedevtools/livedoc-vitest)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+**Write tests in Gherkin. Get documentation that never goes stale.**
+
+📖 **[Full Documentation →](https://livedoc.swedevtools.com/vitest/learn/getting-started)**
+
+</div>
+
+---
+
+## What is LiveDoc?
+
+LiveDoc brings Behavior-Driven Development to Vitest with full Gherkin syntax — **Feature / Scenario / Given / When / Then**, **Specification / Rule**, **Scenario Outlines**, **Tags & Filtering**, and **beautiful reports**.
+
+## Quick Start
+
+### Install
+
+```bash
+npm install --save-dev vitest @swedevtools/livedoc-vitest
+```
+
+### Create a spec
+
+```ts
+// tests/Calculator.Spec.ts
+import { feature, scenario, given, when, Then as then, and } from '@swedevtools/livedoc-vitest';
+
+feature("Calculator", () => {
+  scenario("Adding two numbers", () => {
+    let result = 0;
+
+    given("I have entered '50' into the calculator", (ctx) => {
+      result = ctx.step.values[0];
+    });
+
+    and("I have entered '70' into the calculator", (ctx) => {
+      result += ctx.step.values[0];
+    });
+
+    when("I press add", () => {
+      // Addition already happened above
+    });
+
+    then("the result should be '120'", (ctx) => {
+      expect(result).toBe(ctx.step.values[0]);
+    });
+  });
+});
+```
+
+> **Why `Then as then`?** ES modules treat `then` as a thenable indicator. We export `Then` (uppercase) and you alias it.
+
+### Configure Vitest
+
+```ts
+// vitest.config.ts
+import { defineConfig } from 'vitest/config';
+import { LiveDocSpecReporter } from '@swedevtools/livedoc-vitest/reporter';
+
+export default defineConfig({
+  test: {
+    globals: true,
+    include: ['**/*.Spec.ts'],
+    reporters: [new LiveDocSpecReporter()],
+  },
+});
+```
+
+### Run
+
+```bash
+npx vitest run
+```
+
+---
+
+## Documentation
+
+📖 **[Full documentation at livedoc.swedevtools.com →](https://livedoc.swedevtools.com/vitest/learn/getting-started)**
+
+Covers getting started, BDD & Specification patterns, data extraction, scenario outlines, tags & filtering, reporters, viewer integration, CI/CD, troubleshooting, and more.
+
+---
+
+## License
+
+MIT

package/dist/RuleContext-BZhuy-zS.d.cts

@@ -0,0 +1,206 @@
+import { Attachment } from '@swedevtools/livedoc-schema';
+
+/**
+ * Global type definitions for LiveDoc-Vitest
+ */
+
+type DataTableRow = any[] | { [key: string]: any };
+
+interface LiveDocMetaTable {
+    name: string;
+    description: string;
+    dataTable: DataTableRow[];
+}
+
+interface LiveDocStepTaskMeta {
+    kind: "step";
+    step: {
+        rawTitle: string;
+        type: string;
+    };
+    scenarioOutline?: {
+        title?: string;
+        description: string;
+        tables: LiveDocMetaTable[];
+        tags: string[];
+        example: {
+            sequence: number;
+            values: Record<string, unknown>;
+        };
+    };
+}
+
+interface LiveDocRuleExampleTaskMeta {
+    kind: "ruleExample";
+    ruleOutline: {
+        title: string;
+        description: string;
+        tables: LiveDocMetaTable[];
+        tags: string[];
+        example: {
+            sequence: number;
+            values: Record<string, unknown>;
+        };
+    };
+}
+
+interface LiveDocRuleTaskMeta {
+    kind: "rule";
+    rule: {
+        title: string;
+        description: string;
+        tags: string[];
+    };
+}
+
+type LiveDocTaskMeta = LiveDocStepTaskMeta | LiveDocRuleExampleTaskMeta | LiveDocRuleTaskMeta;
+
+/**
+ * Extend Vitest's TaskMeta to include LiveDoc context
+ */
+declare module "@vitest/runner" {
+    interface TaskMeta {
+        livedoc?: LiveDocTaskMeta;
+    }
+}
+
+/**
+ * Framework metadata about the current step
+ * READ-ONLY - contains title, parsed values, tables, docStrings
+ * Provides helpers for accessing step data in various formats
+ */
+declare class StepContext {
+    private _table?;
+    private _attachments;
+    title: string;
+    displayTitle: string;
+    dataTable: DataTableRow[];
+    docString: string;
+    type: string;
+    values: any[];
+    valuesRaw: string[];
+    params: Record<string, any>;
+    paramsRaw: Record<string, string>;
+    constructor(attachments?: Attachment[]);
+    /**
+     * Attach arbitrary data (base64-encoded) to this step.
+     */
+    attach(data: string, opts?: {
+        title?: string;
+        mimeType?: string;
+        kind?: 'image' | 'screenshot' | 'file';
+    }): void;
+    /**
+     * Convenience: attach a PNG screenshot.
+     */
+    attachScreenshot(base64: string, title?: string): void;
+    /**
+     * Convenience: attach a JSON payload (e.g., API response).
+     */
+    attachJSON(data: unknown, title?: string): void;
+    /** Attachments collected during step execution. */
+    get attachments(): Attachment[];
+    /**
+     * Parse docString as JSON entity
+     */
+    get docStringAsEntity(): any;
+    /**
+     * Get data table with headers as column names
+     */
+    get table(): DataTableRow[];
+    /**
+     * Convert 2-column table to key-value entity
+     */
+    get tableAsEntity(): DataTableRow | undefined;
+    /**
+     * Get data table as-is (raw array of arrays)
+     */
+    tableAsList(): DataTableRow[];
+    /**
+     * Get first column as single array
+     */
+    get tableAsSingleList(): any[];
+    private convertToTable;
+    private convertDataTableRowToEntity;
+    private coerceValue;
+    private convertToDateIfPossible;
+}
+
+/**
+ * Framework metadata about the scenario
+ * READ-ONLY - contains title/description/tags/step references
+ * NOT for user test data! Use local variables instead.
+ */
+declare class ScenarioContext {
+    title: string;
+    description: string;
+    given?: StepContext;
+    and: StepContext[];
+    tags: string[];
+    /** All steps in this scenario */
+    steps: StepContext[];
+}
+
+/**
+ * Framework metadata about the feature
+ * READ-ONLY - contains file/title/description/tags
+ * NOT for user test data! Use local variables instead.
+ */
+declare class FeatureContext {
+    filename: string;
+    title: string;
+    description: string;
+    tags: string[];
+}
+
+/**
+ * Framework metadata about the background
+ * READ-ONLY - extends ScenarioContext with background-specific data
+ */
+declare class BackgroundContext extends ScenarioContext {
+}
+
+/**
+ * Framework metadata about the specification
+ * READ-ONLY - contains file/title/description/tags
+ * NOT for user test data! Use local variables instead.
+ */
+declare class SpecificationContext {
+    filename: string;
+    title: string;
+    description: string;
+    tags: string[];
+}
+
+/**
+ * Framework metadata about the rule.
+ * Provides title, description, tags, and extracted values/params from the rule title.
+ *
+ * @example
+ * ```typescript
+ * rule("Adding '5' and '3' returns '8'", (ctx) => {
+ *     const [a, b, expected] = ctx.rule.values; // [5, 3, 8]
+ *     expect(a + b).toBe(expected);
+ * });
+ *
+ * rule("Processing <action:login> for <user:alice>", (ctx) => {
+ *     const action = ctx.rule.params.action; // "login"
+ * });
+ * ```
+ */
+declare class RuleContext {
+    title: string;
+    description: string;
+    tags: string[];
+    specification: SpecificationContext;
+    /** Extracted and type-coerced quoted values from the rule title. */
+    values: any[];
+    /** Raw string values before type coercion. */
+    valuesRaw: string[];
+    /** Extracted and type-coerced named parameters from <name:value> patterns. */
+    params: Record<string, any>;
+    /** Raw string named parameters before type coercion. */
+    paramsRaw: Record<string, string>;
+}
+
+export { BackgroundContext as B, type DataTableRow as D, FeatureContext as F, RuleContext as R, ScenarioContext as S, StepContext as a, SpecificationContext as b };

package/dist/RuleContext-BZhuy-zS.d.ts

@@ -0,0 +1,206 @@
+import { Attachment } from '@swedevtools/livedoc-schema';
+
+/**
+ * Global type definitions for LiveDoc-Vitest
+ */
+
+type DataTableRow = any[] | { [key: string]: any };
+
+interface LiveDocMetaTable {
+    name: string;
+    description: string;
+    dataTable: DataTableRow[];
+}
+
+interface LiveDocStepTaskMeta {
+    kind: "step";
+    step: {
+        rawTitle: string;
+        type: string;
+    };
+    scenarioOutline?: {
+        title?: string;
+        description: string;
+        tables: LiveDocMetaTable[];
+        tags: string[];
+        example: {
+            sequence: number;
+            values: Record<string, unknown>;
+        };
+    };
+}
+
+interface LiveDocRuleExampleTaskMeta {
+    kind: "ruleExample";
+    ruleOutline: {
+        title: string;
+        description: string;
+        tables: LiveDocMetaTable[];
+        tags: string[];
+        example: {
+            sequence: number;
+            values: Record<string, unknown>;
+        };
+    };
+}
+
+interface LiveDocRuleTaskMeta {
+    kind: "rule";
+    rule: {
+        title: string;
+        description: string;
+        tags: string[];
+    };
+}
+
+type LiveDocTaskMeta = LiveDocStepTaskMeta | LiveDocRuleExampleTaskMeta | LiveDocRuleTaskMeta;
+
+/**
+ * Extend Vitest's TaskMeta to include LiveDoc context
+ */
+declare module "@vitest/runner" {
+    interface TaskMeta {
+        livedoc?: LiveDocTaskMeta;
+    }
+}
+
+/**
+ * Framework metadata about the current step
+ * READ-ONLY - contains title, parsed values, tables, docStrings
+ * Provides helpers for accessing step data in various formats
+ */
+declare class StepContext {
+    private _table?;
+    private _attachments;
+    title: string;
+    displayTitle: string;
+    dataTable: DataTableRow[];
+    docString: string;
+    type: string;
+    values: any[];
+    valuesRaw: string[];
+    params: Record<string, any>;
+    paramsRaw: Record<string, string>;
+    constructor(attachments?: Attachment[]);
+    /**
+     * Attach arbitrary data (base64-encoded) to this step.
+     */
+    attach(data: string, opts?: {
+        title?: string;
+        mimeType?: string;
+        kind?: 'image' | 'screenshot' | 'file';
+    }): void;
+    /**
+     * Convenience: attach a PNG screenshot.
+     */
+    attachScreenshot(base64: string, title?: string): void;
+    /**
+     * Convenience: attach a JSON payload (e.g., API response).
+     */
+    attachJSON(data: unknown, title?: string): void;
+    /** Attachments collected during step execution. */
+    get attachments(): Attachment[];
+    /**
+     * Parse docString as JSON entity
+     */
+    get docStringAsEntity(): any;
+    /**
+     * Get data table with headers as column names
+     */
+    get table(): DataTableRow[];
+    /**
+     * Convert 2-column table to key-value entity
+     */
+    get tableAsEntity(): DataTableRow | undefined;
+    /**
+     * Get data table as-is (raw array of arrays)
+     */
+    tableAsList(): DataTableRow[];
+    /**
+     * Get first column as single array
+     */
+    get tableAsSingleList(): any[];
+    private convertToTable;
+    private convertDataTableRowToEntity;
+    private coerceValue;
+    private convertToDateIfPossible;
+}
+
+/**
+ * Framework metadata about the scenario
+ * READ-ONLY - contains title/description/tags/step references
+ * NOT for user test data! Use local variables instead.
+ */
+declare class ScenarioContext {
+    title: string;
+    description: string;
+    given?: StepContext;
+    and: StepContext[];
+    tags: string[];
+    /** All steps in this scenario */
+    steps: StepContext[];
+}
+
+/**
+ * Framework metadata about the feature
+ * READ-ONLY - contains file/title/description/tags
+ * NOT for user test data! Use local variables instead.
+ */
+declare class FeatureContext {
+    filename: string;
+    title: string;
+    description: string;
+    tags: string[];
+}
+
+/**
+ * Framework metadata about the background
+ * READ-ONLY - extends ScenarioContext with background-specific data
+ */
+declare class BackgroundContext extends ScenarioContext {
+}
+
+/**
+ * Framework metadata about the specification
+ * READ-ONLY - contains file/title/description/tags
+ * NOT for user test data! Use local variables instead.
+ */
+declare class SpecificationContext {
+    filename: string;
+    title: string;
+    description: string;
+    tags: string[];
+}
+
+/**
+ * Framework metadata about the rule.
+ * Provides title, description, tags, and extracted values/params from the rule title.
+ *
+ * @example
+ * ```typescript
+ * rule("Adding '5' and '3' returns '8'", (ctx) => {
+ *     const [a, b, expected] = ctx.rule.values; // [5, 3, 8]
+ *     expect(a + b).toBe(expected);
+ * });
+ *
+ * rule("Processing <action:login> for <user:alice>", (ctx) => {
+ *     const action = ctx.rule.params.action; // "login"
+ * });
+ * ```
+ */
+declare class RuleContext {
+    title: string;
+    description: string;
+    tags: string[];
+    specification: SpecificationContext;
+    /** Extracted and type-coerced quoted values from the rule title. */
+    values: any[];
+    /** Raw string values before type coercion. */
+    valuesRaw: string[];
+    /** Extracted and type-coerced named parameters from <name:value> patterns. */
+    params: Record<string, any>;
+    /** Raw string named parameters before type coercion. */
+    paramsRaw: Record<string, string>;
+}
+
+export { BackgroundContext as B, type DataTableRow as D, FeatureContext as F, RuleContext as R, ScenarioContext as S, StepContext as a, SpecificationContext as b };

package/dist/globals.cjs

@@ -0,0 +1,2 @@
+'use strict';
+

package/dist/globals.d.cts

@@ -0,0 +1,104 @@
+import { F as FeatureContext, S as ScenarioContext, a as StepContext, B as BackgroundContext, b as SpecificationContext, R as RuleContext } from './RuleContext-BZhuy-zS.cjs';
+import '@swedevtools/livedoc-schema';
+
+/**
+ * The context object passed to all LiveDoc test functions.
+ * Provides access to feature, scenario, step, example, and background contexts.
+ */
+interface LiveDocTestContext {
+    /** Framework metadata about the current feature */
+    feature?: FeatureContext;
+    /** Framework metadata about the current scenario */
+    scenario?: ScenarioContext;
+    /** Framework metadata about the current step */
+    step?: StepContext;
+    /** Framework metadata about the current scenario outline example */
+    example?: ScenarioContext;
+    /** Framework metadata about the background */
+    background?: BackgroundContext;
+}
+
+/**
+ * The context object passed to Specification pattern test functions.
+ */
+interface SpecificationTestContext {
+    /** Framework metadata about the current specification */
+    specification?: SpecificationContext;
+    /** Framework metadata about the current rule */
+    rule?: RuleContext;
+    /** Example data for rule outlines */
+    example?: Record<string, any>;
+}
+
+declare global {
+    /**
+     * Define a Gherkin feature
+     */
+    function feature(title: string, fn: (ctx: LiveDocTestContext) => void): void;
+
+    /**
+     * Define a scenario within a feature
+     */
+    function scenario(title: string, fn: (ctx: LiveDocTestContext) => void | Promise<void>): void;
+
+    /**
+     * Define a scenario outline (data-driven test)
+     * Examples are extracted from the title string by the parser
+     */
+    function scenarioOutline(title: string, fn: (ctx: LiveDocTestContext) => void): void;
+
+    /**
+     * Define background steps that run before each scenario
+     */
+    function background(title: string, fn: (ctx: LiveDocTestContext & {
+        afterBackground: (fn: () => void | Promise<void>) => void;
+    }) => void): void;
+
+    /**
+     * Define a given step (precondition)
+     */
+    function given(title: string, fn?: (ctx: LiveDocTestContext) => void | Promise<void>, passedParam?: object | Function): void;
+
+    /**
+     * Define a when step (action)
+     */
+    function when(title: string, fn?: (ctx: LiveDocTestContext) => void | Promise<void>, passedParam?: object | Function): void;
+
+    /**
+     * Define a then step (assertion)
+     * Available as lowercase global when using globals mode.
+     */
+    function then(title: string, fn?: (ctx: LiveDocTestContext) => void | Promise<void>, passedParam?: object | Function): void;
+
+    /**
+     * Define an and step (continuation)
+     */
+    function and(title: string, fn?: (ctx: LiveDocTestContext) => void | Promise<void>, passedParam?: object | Function): void;
+
+    /**
+     * Define a but step (continuation with contrast)
+     */
+    function but(title: string, fn?: (ctx: LiveDocTestContext) => void | Promise<void>, passedParam?: object | Function): void;
+
+    // ============================================
+    // Specification Pattern Globals
+    // ============================================
+
+    /**
+     * Define a specification (container for rules)
+     */
+    function specification(title: string, fn: (ctx: SpecificationTestContext) => void): void;
+
+    /**
+     * Define a rule within a specification
+     */
+    function rule(title: string, fn: (ctx: SpecificationTestContext) => void | Promise<void>): void;
+
+    /**
+     * Define a rule outline (data-driven rules)
+     * Examples are extracted from the title string by the parser
+     */
+    function ruleOutline(title: string, fn: (ctx: SpecificationTestContext) => void | Promise<void>): void;
+}
+
+export type { LiveDocTestContext, SpecificationTestContext };