bdd-vitest 0.1.1 → 1.0.0

package/README.md

@@ -1,6 +1,6 @@
 # bdd-vitest
 
-Enforced Given/When/Then for Vitest. Tests become documentation. ~200 lines. Zero config.
+Enforced Given/When/Then for Vitest. Tests become documentation. Zero config.
 
 ```ts
 import { unit, feature, expect } from "bdd-vitest";
@@ -14,7 +14,7 @@ feature("Checkout", () => {
 });
 ```
 
-Read just the descriptions - you understand the system without opening production code.
+Read just the descriptions. You understand the system without opening production code.
 
 ## Why
 
@@ -23,7 +23,7 @@ Most test frameworks let you write `it("does something", () => {})` with no stru
 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.
+- **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
@@ -44,7 +44,7 @@ import { unit, component, integration, e2e } from "bdd-vitest";
 |-------|---------|-------------------|
 | `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 |
+| `integration` | 30s | Real services, real files, real I/O |
 | `e2e` | 120s | Full system, browser, real network, real database |
 
 ```
@@ -74,7 +74,7 @@ component("health check", {
 });
 ```
 
-Context flows through - `when` receives `given`'s return, `then` receives both:
+`when` receives `given`'s return. `then` receives both:
 
 ```ts
 unit("FIFO order", {
@@ -138,6 +138,25 @@ component("handles 404", {
 });
 ```
 
+## Database tests
+
+No special API needed. `given` sets up, `cleanup` tears down:
+
+```ts
+integration("finds user by email", {
+  given: ["a seeded database", async () => {
+    const db = await createTestDb();
+    await db.users.insert({ email: "alice@test.com", name: "Alice" });
+    return db;
+  }],
+  when:    ["querying", (db) => db.users.findBy({ email: "alice@test.com" })],
+  then:    ["returns Alice", (user) => expect(user.name).toBe("Alice")],
+  cleanup: (db) => db.destroy(),
+});
+```
+
+Works with any database library. Bring your own setup.
+
 ## Table-driven
 
 ```ts
@@ -164,6 +183,70 @@ feature("Auth", () => {
 });
 ```
 
+## Real world example
+
+```ts
+import { unit, component, integration, feature, rule, expect } from "bdd-vitest";
+import { mockServer } from "bdd-vitest/mock-server";
+
+feature("Ship AI", () => {
+  rule("airlock access", () => {
+    unit("denies crew without clearance", {
+      given: ["a crew member with no override", () => ({ crew: "Kai", clearance: 0 })],
+      when:  ["requesting airlock",              (ctx) => shipAI.evaluateRequest(ctx)],
+      then:  ["denies the request",              (res) => {
+        expect(res.granted).toBe(false);
+        expect(res.reason).toContain("insufficient clearance");
+      }],
+    });
+
+    unit.outline("clearance levels", [
+      { name: "cadet: denied",     clearance: 0, expected: false },
+      { name: "engineer: denied",  clearance: 1, expected: false },
+      { name: "commander: granted", clearance: 9, expected: true },
+    ], {
+      given: (row) => ({ crew: "Kai", clearance: row.clearance as number }),
+      when:  (ctx) => shipAI.evaluateRequest(ctx),
+      then:  (res, _ctx, row) => expect(res.granted).toBe(row.expected),
+    });
+  });
+
+  rule("crew monitoring API", () => {
+    component("reports life signs", {
+      given: ["a sensor API", mockServer({
+        "GET /crew/kai/vitals": { heartRate: 72, o2: 98, status: "nominal" },
+      })],
+      when:    ["checking vitals", (server) => shipAI.checkCrew("kai", server.url)],
+      then:    ["reports nominal",  (report) => expect(report.status).toBe("nominal")],
+      cleanup: (server) => server.close(),
+    });
+
+    component("handles sensor failure", {
+      given: ["a failing sensor API", mockServer({
+        "GET /crew/kai/vitals": 503,
+      })],
+      when:    ["checking vitals", (server) => shipAI.checkCrew("kai", server.url)],
+      then:    ["triggers alert",  (report) => expect(report.status).toBe("sensor_failure")],
+      cleanup: (server) => server.close(),
+    });
+  });
+
+  rule("mission log", () => {
+    integration("logs all crew requests", {
+      given: ["a mission database", async () => {
+        const db = await createMissionDb();
+        await shipAI.logRequest(db, { crew: "Kai", action: "open_airlock" });
+        await shipAI.logRequest(db, { crew: "Yara", action: "check_antenna" });
+        return db;
+      }],
+      when:    ["querying the log",   (db) => db.logs.findAll()],
+      then:    ["contains both entries", (logs) => expect(logs).toHaveLength(2)],
+      cleanup: (db) => db.destroy(),
+    });
+  });
+});
+```
+
 ## API
 
 | Export | What |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bdd-vitest",
-  "version": "0.1.1",
+  "version": "1.0.0",
   "type": "module",
   "description": "Enforced Given/When/Then for Vitest. ~200 lines. Zero config.",
   "license": "MIT",