bdd-vitest 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mattias Wetterlind
+
+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,180 @@
+# bdd-vitest
+
+Enforced Given/When/Then for Vitest. Tests become documentation. ~200 lines. Zero config.
+
+```ts
+import { unit, feature, expect } from "bdd-vitest";
+
+feature("Checkout", () => {
+  unit("applies discount over 500kr", {
+    given: ["a cart with total 600kr",  () => createCart(600)],
+    when:  ["checking out",             (cart) => checkout(cart)],
+    then:  ["10% discount applied",     (res) => expect(res.discount).toBe(60)],
+  });
+});
+```
+
+Read just the descriptions - you understand the system without opening production code.
+
+## Why
+
+Most test frameworks let you write `it("does something", () => {})` with no structure inside. AI agents skip descriptions. Tired humans skip assertions. Tests pass but prove nothing.
+
+bdd-vitest makes it impossible:
+
+- **Descriptions are required.** Every phase is a `["description", fn]` tuple. TypeScript rejects missing descriptions at compile time.
+- **Levels are required.** No generic `scenario` - you must pick `unit`, `component`, `integration`, or `e2e`. Each has enforced timeouts.
+- **Assertions are required.** `then` is mandatory. No test without a check.
+
+## Install
+
+```bash
+npm install -D bdd-vitest
+```
+
+## Levels
+
+Every test must declare its level. Wrong level => timeout fails the test. Slow for its level => warning nudges you.
+
+```ts
+import { unit, component, integration, e2e } from "bdd-vitest";
+```
+
+| Level | Timeout | What belongs here |
+|-------|---------|-------------------|
+| `unit` | 100ms | Pure functions, calculations, parsing, validation |
+| `component` | 5s | One service with mocked deps (mockServer, mockFetch) |
+| `integration` | 30s | Multiple real services talking to each other |
+| `e2e` | 120s | Full system, browser, real network, real database |
+
+```
+⚠️  [unit] "parse config" took 80ms (warn: 50ms, limit: 100ms). Is this a component test?
+```
+
+Know it's intentionally slow? `slow: true` suppresses the warning (timeout still enforced).
+
+## Phases
+
+`then` is always required. Everything else is optional:
+
+```ts
+unit("full",       { given, when, then });   // setup => action => assert
+unit("no action",  { given, then });          // setup => assert
+unit("no setup",   { when, then });           // action => assert
+unit("assertion",  { then });                 // just assert
+```
+
+No setup code? `given` can be just a description:
+
+```ts
+component("health check", {
+  given: "a running server",
+  when:  ["requesting /health", () => app.request("/health")],
+  then:  ["returns 200",       (res) => expect(res.status).toBe(200)],
+});
+```
+
+Context flows through - `when` receives `given`'s return, `then` receives both:
+
+```ts
+unit("FIFO order", {
+  given: ["a queue with tracker", () => ({ order: [] as number[] })],
+  when:  ["processing tasks",    async (ctx) => {
+    await enqueueAll([1, 2, 3], (n) => { ctx.order.push(n); });
+    return ctx.order;
+  }],
+  then: ["order preserved", (result) => expect(result).toEqual([1, 2, 3])],
+});
+```
+
+Errors show which phase failed:
+
+```
+AssertionError: [given] Database connection failed
+AssertionError: [when] Request timeout
+AssertionError: [then] expected 42 to be 43
+```
+
+## Mock server
+
+No dependencies. Real HTTP server on a random port:
+
+```ts
+import { mockServer } from "bdd-vitest/mock-server";
+
+component("retries on 503", {
+  given: ["an unreliable API", mockServer({
+    "POST /v1/completions": [
+      { status: 503, body: { error: "overloaded" } },
+      { status: 200, body: { result: "ok" } },
+    ],
+  })],
+  when:    ["sending with retry", (server) => fetchWithRetry(`${server.url}/v1/completions`)],
+  then:    ["succeeds",           (res) => expect(res.status).toBe(200)],
+  cleanup: (server) => server.close(),
+});
+```
+
+Response shortcuts:
+
+```ts
+"GET /users":      { name: "Alice" }                                       // => 200 + JSON
+"DELETE /users/1": 204                                                      // => status only
+"POST /submit":    [{ status: 503 }, { status: 200, body: { ok: true } }]  // => sequential
+```
+
+## Mock fetch
+
+Same idea, patches global `fetch` instead of starting a server:
+
+```ts
+import { mockFetch } from "bdd-vitest/mock-fetch";
+
+component("handles 404", {
+  given:   ["github returns 404", mockFetch({ "GET https://api.github.com/users/x": 404 })],
+  when:    ["fetching user",      () => fetch("https://api.github.com/users/x")],
+  then:    ["returns 404",        (res) => expect(res.status).toBe(404)],
+  cleanup: (mock) => mock.restore(),
+});
+```
+
+## Table-driven
+
+```ts
+unit.outline("adds numbers", [
+  { name: "positives",  a: 2,  b: 3, expected: 5 },
+  { name: "negatives",  a: -1, b: 1, expected: 0 },
+], {
+  given: (row) => ({ a: row.a as number, b: row.b as number }),
+  when:  (ctx) => ctx.a + ctx.b,
+  then:  (result, _ctx, row) => expect(result).toBe(row.expected),
+});
+```
+
+## Grouping
+
+```ts
+feature("Auth", () => {
+  rule("valid credentials", () => {
+    unit("grants access", { ... });
+  });
+  rule("expired tokens", () => {
+    component("refreshes automatically", { ... });
+  });
+});
+```
+
+## API
+
+| Export | What |
+|--------|------|
+| `unit` / `component` / `integration` / `e2e` | Test with enforced level + timeout |
+| `.skip` / `.only` / `.group` / `.outline` | Modifiers on any level |
+| `feature(name, fn)` / `rule(name, fn)` | Grouping (describe aliases) |
+| `mockServer(routes)` | Declarative HTTP mock server |
+| `mockFetch(routes)` | Patches global fetch |
+| `expect` | Re-exported from vitest |
+
+## License
+
+MIT

package/dist/chunk-3RG5ZIWI.js

@@ -0,0 +1,10 @@
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
+export {
+  __require
+};

package/dist/chunk-R4KYBEVR.js

@@ -0,0 +1,107 @@
+// src/levels.ts
+import { describe, it } from "vitest";
+var LEVELS = {
+  unit: { timeout: 100, warnAt: 50, name: "unit", nextLevel: "component" },
+  component: { timeout: 5e3, warnAt: 2e3, name: "component", nextLevel: "integration" },
+  integration: { timeout: 3e4, warnAt: 15e3, name: "integration", nextLevel: "e2e" },
+  e2e: { timeout: 12e4, warnAt: 6e4, name: "e2e" }
+};
+function createLevelRunner(level) {
+  function run(name, phases) {
+    it(name, { timeout: level.timeout }, async () => {
+      const start = performance.now();
+      let phase = "given";
+      let context = void 0;
+      try {
+        if (phases.given && typeof phases.given !== "string") {
+          context = await phases.given[1]();
+        }
+        phase = "when";
+        const result = phases.when ? await phases.when[1](context) : context;
+        phase = "then";
+        await phases.then[1](result, context);
+      } catch (error) {
+        if (error instanceof Error && !error.message.startsWith("[")) {
+          error.message = `[${phase}] ${error.message}`;
+        }
+        throw error;
+      } finally {
+        if (phases.cleanup) {
+          await phases.cleanup(context);
+        }
+      }
+      const elapsed = performance.now() - start;
+      const warnAt = level.warnAt ?? level.timeout * 0.5;
+      if (!phases.slow && elapsed > warnAt) {
+        const next = level.nextLevel ? ` Is this a ${level.nextLevel} test?` : "";
+        console.warn(
+          `\u26A0\uFE0F  [${level.name}] "${name}" took ${Math.round(elapsed)}ms (warn: ${warnAt}ms, limit: ${level.timeout}ms).${next}`
+        );
+      }
+    });
+  }
+  run.skip = function(name, _phases) {
+    it.skip(name, () => {
+    });
+  };
+  run.only = function(name, phases) {
+    it.only(name, { timeout: level.timeout }, async () => {
+      let phase = "given";
+      let context = void 0;
+      try {
+        if (phases.given && typeof phases.given !== "string") {
+          context = await phases.given[1]();
+        }
+        phase = "when";
+        const result = phases.when ? await phases.when[1](context) : context;
+        phase = "then";
+        await phases.then[1](result, context);
+      } catch (error) {
+        if (error instanceof Error && !error.message.startsWith("[")) {
+          error.message = `[${phase}] ${error.message}`;
+        }
+        throw error;
+      } finally {
+        if (phases.cleanup) {
+          await phases.cleanup(context);
+        }
+      }
+    });
+  };
+  return run;
+}
+function createLevelGroup(level) {
+  return function group(name, fn) {
+    describe(`[${level.name}] ${name}`, fn);
+  };
+}
+function createLevelOutline(level) {
+  return function(name, table, phases) {
+    describe(`[${level.name}] ${name}`, () => {
+      for (const row of table) {
+        it(row.name, { timeout: level.timeout }, async () => {
+          const context = await phases.given(row);
+          const result = await phases.when(context, row);
+          await phases.then(result, context, row);
+        });
+      }
+    });
+  };
+}
+function buildLevel(config) {
+  const runner = createLevelRunner(config);
+  runner.group = createLevelGroup(config);
+  runner.outline = createLevelOutline(config);
+  return runner;
+}
+var unit = buildLevel(LEVELS.unit);
+var component = buildLevel(LEVELS.component);
+var integration = buildLevel(LEVELS.integration);
+var e2e = buildLevel(LEVELS.e2e);
+
+export {
+  unit,
+  component,
+  integration,
+  e2e
+};

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { expect } from 'vitest';
+export { P as Phase, S as Scenario, a as ScenarioWithLifecycle, T as TableRow, component, e2e, f as feature, integration, r as rule, s as scenario, b as scenarioOutline, c as scenarioWithCleanup, unit } from './levels.js';

package/dist/index.js

@@ -0,0 +1,84 @@
+import {
+  component,
+  e2e,
+  integration,
+  unit
+} from "./chunk-R4KYBEVR.js";
+import "./chunk-3RG5ZIWI.js";
+
+// src/index.ts
+import { describe, it } from "vitest";
+import { expect as expect2 } from "vitest";
+function createScenarioRunner(itFn) {
+  return function runScenario(name, phases) {
+    itFn(name, async () => {
+      let phase = "given";
+      try {
+        const context = phases.given ? typeof phases.given === "string" ? void 0 : await phases.given[1]() : void 0;
+        phase = "when";
+        const result = phases.when ? await phases.when[1](context) : context;
+        phase = "then";
+        await phases.then[1](result, context);
+      } catch (error) {
+        if (error instanceof Error && !error.message.startsWith("[")) {
+          error.message = `[${phase}] ${error.message}`;
+        }
+        throw error;
+      }
+    });
+  };
+}
+var _scenario = createScenarioRunner(it);
+var _scenarioOnly = createScenarioRunner(it.only);
+var _scenarioSkip = createScenarioRunner(it.skip);
+function scenario(name, phases) {
+  _scenario(name, phases);
+}
+scenario.only = function(name, phases) {
+  _scenarioOnly(name, phases);
+};
+scenario.skip = function(name, phases) {
+  _scenarioSkip(name, phases);
+};
+function feature(name, fn) {
+  describe(name, fn);
+}
+function rule(name, fn) {
+  describe(name, fn);
+}
+function scenarioWithCleanup(name, phases) {
+  it(name, async () => {
+    const context = phases.given ? typeof phases.given === "string" ? void 0 : await phases.given[1]() : void 0;
+    try {
+      const result = phases.when ? await phases.when[1](context) : context;
+      await phases.then[1](result, context);
+    } finally {
+      if (phases.cleanup) {
+        await phases.cleanup(context);
+      }
+    }
+  });
+}
+function scenarioOutline(name, table, phases) {
+  describe(name, () => {
+    for (const row of table) {
+      it(row.name, async () => {
+        const context = await phases.given(row);
+        const result = await phases.when(context, row);
+        await phases.then(result, context, row);
+      });
+    }
+  });
+}
+export {
+  component,
+  e2e,
+  expect2 as expect,
+  feature,
+  integration,
+  rule,
+  scenario,
+  scenarioOutline,
+  scenarioWithCleanup,
+  unit
+};

package/dist/levels.d.ts

@@ -0,0 +1,136 @@
+import 'vitest';
+
+/**
+ * Test levels with enforced constraints.
+ *
+ * Each level has a timeout and rules about what's allowed.
+ * Break the rules → runtime error. No ambiguity.
+ *
+ * Usage:
+ *   import { unit, component, integration } from "bdd-vitest/levels";
+ *
+ *   unit("adds numbers", {
+ *     given: ["two numbers", () => ({ a: 2, b: 3 })],
+ *     when:  ["adding",      (ctx) => ctx.a + ctx.b],
+ *     then:  ["returns sum", (r) => expect(r).toBe(5)],
+ *   });
+ */
+
+interface LevelConfig {
+    /** Max time per scenario (ms) */
+    timeout: number;
+    /** Warn if test takes longer than this (ms). Default: 50% of timeout. */
+    warnAt?: number;
+    /** Level name for error messages */
+    name: string;
+    /** Suggested next level (for warning message) */
+    nextLevel?: string;
+}
+interface LevelScenario<TContext, TResult> {
+    given?: Phase<() => TContext | Promise<TContext>> | string;
+    when?: Phase<(context: TContext) => TResult | Promise<TResult>>;
+    then: Phase<(result: TResult, context: TContext) => void | Promise<void>>;
+    cleanup?: (context: TContext) => void | Promise<void>;
+    /** Suppress slow-test warning. Use when you know the test is intentionally slow for its level. */
+    slow?: boolean;
+}
+interface TableRow$1 {
+    name: string;
+    [key: string]: unknown;
+}
+interface LevelRunner {
+    <TContext, TResult>(name: string, phases: LevelScenario<TContext, TResult>): void;
+    skip: <TContext, TResult>(name: string, phases: LevelScenario<TContext, TResult>) => void;
+    only: <TContext, TResult>(name: string, phases: LevelScenario<TContext, TResult>) => void;
+    group: (name: string, fn: () => void) => void;
+    outline: <TRow extends TableRow$1, TContext, TResult>(name: string, table: TRow[], phases: {
+        given: (row: TRow) => TContext | Promise<TContext>;
+        when: (context: TContext, row: TRow) => TResult | Promise<TResult>;
+        then: (result: TResult, context: TContext, row: TRow) => void | Promise<void>;
+    }) => void;
+}
+/** Pure logic. No I/O, no mocks, no services. <100ms. */
+declare const unit: LevelRunner;
+/** Service in isolation. Mocked dependencies. <5s. */
+declare const component: LevelRunner;
+/** Multiple services together. Real dependencies. <30s. */
+declare const integration: LevelRunner;
+/** Full system, browser, network. <120s. */
+declare const e2e: LevelRunner;
+
+/**
+ * bdd-vitest — Enforced Given/When/Then for Vitest
+ *
+ * Usage:
+ *   import { feature, scenario } from "bdd-vitest";
+ *
+ *   feature("Queue", () => {
+ *     scenario("rejects when full", {
+ *       given: () => createQueue({ maxSize: 50, filled: 50 }),
+ *       when:  (queue) => queue.enqueue(mockRequest()).catch(e => e),
+ *       then:  (error) => expect(error.message).toContain("Queue full"),
+ *     });
+ *   });
+ */
+
+/** Phase: [description, function] tuple — description is enforced */
+type Phase<TFn> = [desc: string, fn: TFn];
+interface Scenario<TContext, TResult> {
+    /** Setup — tuple, description-only string, or omitted */
+    given?: Phase<() => TContext | Promise<TContext>> | string;
+    /** Action — tuple or omitted */
+    when?: Phase<(context: TContext) => TResult | Promise<TResult>>;
+    /** Assertion — required */
+    then: Phase<(result: TResult, context: TContext) => void | Promise<void>>;
+}
+/**
+ * @deprecated Use `unit`, `component`, `integration`, or `e2e` instead.
+ * Choosing a level is required — it enforces timeouts and communicates intent.
+ */
+declare function scenario<TContext, TResult>(name: string, phases: Scenario<TContext, TResult>): void;
+declare namespace scenario {
+    var only: <TContext, TResult>(name: string, phases: Scenario<TContext, TResult>) => void;
+    var skip: <TContext, TResult>(name: string, phases: Scenario<TContext, TResult>) => void;
+}
+/**
+ * Groups related scenarios. Alias for describe with intent.
+ */
+declare function feature(name: string, fn: () => void): void;
+/**
+ * Sub-groups within a feature for related business rules.
+ */
+declare function rule(name: string, fn: () => void): void;
+interface ScenarioWithLifecycle<TContext, TResult> {
+    given?: Phase<() => TContext | Promise<TContext>> | string;
+    when?: Phase<(context: TContext) => TResult | Promise<TResult>>;
+    then: Phase<(result: TResult, context: TContext) => void | Promise<void>>;
+    cleanup?: (context: TContext) => void | Promise<void>;
+}
+/**
+ * Scenario with automatic cleanup after assertion.
+ */
+declare function scenarioWithCleanup<TContext, TResult>(name: string, phases: ScenarioWithLifecycle<TContext, TResult>): void;
+interface TableRow {
+    name: string;
+    [key: string]: unknown;
+}
+/**
+ * Run the same scenario with multiple data rows.
+ *
+ * Usage:
+ *   scenarioOutline("adds numbers", [
+ *     { name: "positive", a: 2, b: 3, expected: 5 },
+ *     { name: "negative", a: -1, b: 1, expected: 0 },
+ *   ], {
+ *     given: (row) => ({ a: row.a as number, b: row.b as number }),
+ *     when:  (ctx) => ctx.a + ctx.b,
+ *     then:  (result, _ctx, row) => expect(result).toBe(row.expected),
+ *   });
+ */
+declare function scenarioOutline<TRow extends TableRow, TContext, TResult>(name: string, table: TRow[], phases: {
+    given: (row: TRow) => TContext | Promise<TContext>;
+    when: (context: TContext, row: TRow) => TResult | Promise<TResult>;
+    then: (result: TResult, context: TContext, row: TRow) => void | Promise<void>;
+}): void;
+
+export { type LevelConfig, type LevelRunner, type LevelScenario, type Phase as P, type Scenario as S, type TableRow as T, type TableRow$1 as TableRow, type ScenarioWithLifecycle as a, scenarioOutline as b, scenarioWithCleanup as c, component, e2e, feature as f, integration, rule as r, scenario as s, unit };

package/dist/levels.js

@@ -0,0 +1,13 @@
+import {
+  component,
+  e2e,
+  integration,
+  unit
+} from "./chunk-R4KYBEVR.js";
+import "./chunk-3RG5ZIWI.js";
+export {
+  component,
+  e2e,
+  integration,
+  unit
+};

package/dist/mock-ai.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Mock AI provider for testing — never calls real APIs.
+ *
+ * Usage:
+ *   import { createMockProvider, createMockAuthProfiles } from "bdd-vitest/mock-ai";
+ */
+interface MockProviderOptions {
+    /** Simulated response latency in ms (default: 10) */
+    latencyMs?: number;
+    /** Default response text */
+    response?: string;
+    /** Simulate failure after N requests */
+    failAfter?: number;
+    /** Error message on failure */
+    errorMessage?: string;
+}
+interface MockProviderStats {
+    totalRequests: number;
+    activeRequests: number;
+    maxConcurrent: number;
+    requestLog: Array<{
+        model: string;
+        timestamp: number;
+        durationMs: number;
+    }>;
+}
+declare function createMockProvider(options?: MockProviderOptions): {
+    complete: (model: string, _messages: unknown[]) => Promise<{
+        id: string;
+        object: "chat.completion";
+        created: number;
+        model: string;
+        choices: {
+            index: number;
+            message: {
+                role: "assistant";
+                content: string;
+            };
+            finish_reason: "stop";
+        }[];
+        usage: {
+            prompt_tokens: number;
+            completion_tokens: number;
+            total_tokens: number;
+        };
+    }>;
+    stats: MockProviderStats;
+    reset: () => void;
+};
+interface MockAuthProfile {
+    type: string;
+    provider: string;
+    access: string;
+    refresh: string;
+    expires: number;
+}
+/**
+ * Creates a mock auth-profiles.json structure.
+ * Tokens are obviously fake — never hit real APIs.
+ */
+declare function createMockAuthProfiles(providers?: string[]): Record<string, MockAuthProfile>;
+/**
+ * Creates expired mock credentials for testing refresh flows.
+ */
+declare function createExpiredMockAuthProfiles(providers?: string[]): Record<string, MockAuthProfile>;
+
+export { type MockAuthProfile, type MockProviderOptions, type MockProviderStats, createExpiredMockAuthProfiles, createMockAuthProfiles, createMockProvider };