@donkeylabs/server 0.3.0 → 0.4.0

package/docs/testing.md

@@ -1,438 +0,0 @@
-# Testing
-
-Testing utilities for @donkeylabs/server plugins and routes.
-
-## Test Harness
-
-The framework provides `createTestHarness` for testing plugins with real services:
-
-```ts
-import { createTestHarness } from "@donkeylabs/server/harness";
-import { myPlugin } from "./plugins/myPlugin";
-import { depPlugin } from "./plugins/depPlugin";
-
-const { manager, db, core } = await createTestHarness(myPlugin, [depPlugin]);
-
-// Access plugin service
-const service = manager.getServices().myPlugin;
-
-// Use real in-memory database
-await db.insertInto("users").values({ name: "Test" }).execute();
-
-// Use real core services
-core.logger.info("Test running");
-await core.cache.set("key", "value");
-```
-
----
-
-## What the Harness Provides
-
-| Component | Description |
-|-----------|-------------|
-| In-memory SQLite | Real Kysely database, auto-runs migrations |
-| Logger | Configured for `warn` level (less verbose) |
-| Cache | Full in-memory cache service |
-| Events | Pub/sub event system |
-| Cron | Scheduled task service |
-| Jobs | Background job queue |
-| SSE | Server-sent events service |
-| RateLimiter | Rate limiting service |
-| Errors | Error factory functions |
-
----
-
-## When to Use
-
-| Scenario | Use Harness | Use Manual Mock |
-|----------|-------------|-----------------|
-| Testing plugin service methods | Yes | |
-| Testing database queries | Yes | |
-| Testing core service integration | Yes | |
-| Unit testing pure functions | | Yes |
-| Testing HTTP endpoints | | Yes (real server) |
-| Testing middleware | | Yes (mock request/response) |
-
----
-
-## Unit Tests
-
-Test plugin services with the harness:
-
-```ts
-import { describe, it, expect } from "bun:test";
-import { createTestHarness } from "@donkeylabs/server/harness";
-import { usersPlugin } from "../plugins/users";
-
-describe("users plugin", () => {
-  it("creates a user", async () => {
-    const { manager, db } = await createTestHarness(usersPlugin);
-    const users = manager.getServices().users;
-
-    const user = await users.create("test@example.com", "Test User");
-
-    expect(user.email).toBe("test@example.com");
-
-    // Verify in database
-    const found = await db.selectFrom("users").selectAll().execute();
-    expect(found).toHaveLength(1);
-  });
-
-  it("finds user by email", async () => {
-    const { manager, db } = await createTestHarness(usersPlugin);
-    const users = manager.getServices().users;
-
-    // Seed data directly
-    await db.insertInto("users").values({
-      email: "existing@example.com",
-      name: "Existing",
-    }).execute();
-
-    const found = await users.findByEmail("existing@example.com");
-
-    expect(found?.name).toBe("Existing");
-  });
-});
-```
-
----
-
-## Testing Plugins with Dependencies
-
-```ts
-import { createTestHarness } from "@donkeylabs/server/harness";
-import { notificationsPlugin } from "../plugins/notifications";
-import { usersPlugin } from "../plugins/users";
-import { emailPlugin } from "../plugins/email";
-
-describe("notifications plugin", () => {
-  it("sends notification to user", async () => {
-    // notificationsPlugin depends on users and email
-    const { manager } = await createTestHarness(notificationsPlugin, [
-      usersPlugin,
-      emailPlugin({ apiKey: "test", fromAddress: "test@test.com", sandbox: true }),
-    ]);
-
-    const notifications = manager.getServices().notifications;
-
-    // Dependencies are resolved and available
-    await notifications.notifyUser(1, "Hello!");
-  });
-});
-```
-
----
-
-## Testing with Events
-
-```ts
-import { createTestHarness } from "@donkeylabs/server/harness";
-import { statsPlugin } from "../plugins/stats";
-
-describe("stats plugin", () => {
-  it("records events", async () => {
-    const { manager, core } = await createTestHarness(statsPlugin);
-    const stats = manager.getServices().stats;
-
-    // Emit event that plugin listens to
-    core.events.emit("request.completed", {
-      route: "users.list",
-      duration: 50,
-    });
-
-    // Give async handlers time to process
-    await new Promise((r) => setTimeout(r, 10));
-
-    const summary = stats.getStats();
-    expect(summary.totalRequests).toBe(1);
-  });
-});
-```
-
----
-
-## Integration Tests
-
-For HTTP endpoint testing, run the actual server:
-
-```ts
-import { describe, it, expect, beforeAll, afterAll } from "bun:test";
-import { spawn } from "bun";
-
-const BASE_URL = "http://localhost:3001";
-let serverProcess: ReturnType<typeof spawn>;
-
-beforeAll(async () => {
-  // Start server on test port
-  serverProcess = spawn({
-    cmd: ["bun", "run", "src/index.ts"],
-    env: { ...process.env, PORT: "3001" },
-  });
-
-  // Wait for server to be ready
-  await new Promise((r) => setTimeout(r, 1000));
-});
-
-afterAll(() => {
-  serverProcess.kill();
-});
-
-describe("users API", () => {
-  it("POST /users.create returns user", async () => {
-    const res = await fetch(`${BASE_URL}/users.create`, {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ email: "test@example.com", name: "Test" }),
-    });
-
-    expect(res.ok).toBe(true);
-    const user = await res.json();
-    expect(user.email).toBe("test@example.com");
-  });
-
-  it("returns validation error for invalid input", async () => {
-    const res = await fetch(`${BASE_URL}/users.create`, {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ email: "not-an-email" }),
-    });
-
-    expect(res.status).toBe(400);
-    const error = await res.json();
-    expect(error.error).toBe("Validation Failed");
-  });
-});
-```
-
----
-
-## Testing Middleware
-
-Test middleware in isolation:
-
-```ts
-import { describe, it, expect, vi } from "bun:test";
-import { authMiddleware } from "./middleware/auth";
-
-describe("auth middleware", () => {
-  it("rejects request without token when required", async () => {
-    const req = new Request("http://test", {
-      method: "POST",
-    });
-
-    const ctx = { user: undefined } as any;
-    const next = vi.fn();
-
-    const response = await authMiddleware.execute(
-      req,
-      ctx,
-      next,
-      { required: true }
-    );
-
-    expect(response.status).toBe(401);
-    expect(next).not.toHaveBeenCalled();
-  });
-
-  it("allows request with valid token", async () => {
-    const req = new Request("http://test", {
-      method: "POST",
-      headers: { Authorization: "Bearer valid-token" },
-    });
-
-    const ctx = { user: undefined } as any;
-    const next = vi.fn().mockResolvedValue(Response.json({ ok: true }));
-
-    // Mock token validation
-    vi.mock("./auth-service", () => ({
-      verifyToken: vi.fn().mockResolvedValue({ id: 1, name: "Test" }),
-    }));
-
-    const response = await authMiddleware.execute(
-      req,
-      ctx,
-      next,
-      { required: true }
-    );
-
-    expect(next).toHaveBeenCalled();
-    expect(ctx.user).toBeDefined();
-  });
-});
-```
-
----
-
-## Testing Handlers
-
-Test custom handlers directly:
-
-```ts
-import { describe, it, expect } from "bun:test";
-import { EchoHandler } from "./handlers/echo";
-
-describe("EchoHandler", () => {
-  it("echoes request body", async () => {
-    const req = new Request("http://test", {
-      method: "POST",
-      body: JSON.stringify({ hello: "world" }),
-    });
-
-    const mockHandle = async (body: any) => ({ echo: body });
-    const ctx = {} as any;
-
-    const response = await EchoHandler.execute(req, {}, mockHandle, ctx);
-    const json = await response.json();
-
-    expect(json).toEqual({ echo: { hello: "world" } });
-  });
-
-  it("handles invalid JSON", async () => {
-    const req = new Request("http://test", {
-      method: "POST",
-      body: "not json",
-    });
-
-    const mockHandle = async () => ({});
-    const ctx = {} as any;
-
-    const response = await EchoHandler.execute(req, {}, mockHandle, ctx);
-
-    expect(response.status).toBe(400);
-  });
-});
-```
-
----
-
-## Route File Organization
-
-The starter project organizes tests alongside route handlers:
-
-```
-routes/<namespace>/<route>/
-├── index.ts           # Route definition
-├── schema.ts          # Zod schemas (Input, Output)
-├── models/
-│   └── model.ts       # Handler class
-└── tests/
-    ├── unit.test.ts   # Unit tests (harness)
-    └── integ.test.ts  # Integration tests (real HTTP)
-```
-
-Example test structure:
-
-```ts
-// routes/health/ping/tests/unit.test.ts
-import { describe, it, expect } from "bun:test";
-import { PingModel } from "../models/model";
-
-describe("PingModel", () => {
-  it("returns pong message", () => {
-    const ctx = {} as any; // Minimal mock
-    const model = new PingModel(ctx);
-
-    const result = model.handle({ message: "ping" });
-
-    expect(result.response).toBe("pong");
-  });
-});
-```
-
-```ts
-// routes/health/ping/tests/integ.test.ts
-import { describe, it, expect } from "bun:test";
-
-describe("health.ping endpoint", () => {
-  it("responds to ping", async () => {
-    const res = await fetch("http://localhost:3000/health.ping", {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ message: "ping" }),
-    });
-
-    expect(res.ok).toBe(true);
-    const data = await res.json();
-    expect(data.response).toBe("pong");
-  });
-});
-```
-
----
-
-## Best Practices
-
-### 1. Use Harness for Plugin Tests
-
-```ts
-// Good - uses harness for real DB
-const { manager, db } = await createTestHarness(usersPlugin);
-const users = manager.getServices().users;
-await users.create("test@test.com", "Test");
-
-// Bad - manual mocking that may miss real behavior
-const mockDb = { insertInto: vi.fn() };
-const users = createUsersService({ db: mockDb });
-```
-
-### 2. Isolate Each Test
-
-```ts
-// Good - each test gets fresh harness
-describe("users", () => {
-  it("test 1", async () => {
-    const { manager } = await createTestHarness(usersPlugin);
-    // ...
-  });
-
-  it("test 2", async () => {
-    const { manager } = await createTestHarness(usersPlugin);
-    // Clean slate, no data from test 1
-  });
-});
-```
-
-### 3. Test Error Cases
-
-```ts
-it("throws on duplicate email", async () => {
-  const { manager, db } = await createTestHarness(usersPlugin);
-  const users = manager.getServices().users;
-
-  await users.create("test@test.com", "First");
-
-  await expect(users.create("test@test.com", "Second"))
-    .rejects.toThrow();
-});
-```
-
-### 4. Use Descriptive Test Names
-
-```ts
-// Good - describes scenario and expectation
-it("returns empty array when no users exist", async () => {});
-it("throws NotFound when user does not exist", async () => {});
-it("updates only provided fields", async () => {});
-
-// Bad - vague
-it("works", async () => {});
-it("handles edge case", async () => {});
-```
-
----
-
-## Running Tests
-
-```sh
-# Run all tests
-bun test
-
-# Run specific test file
-bun test src/plugins/users/tests/unit.test.ts
-
-# Run tests matching pattern
-bun test --filter "users"
-
-# Watch mode
-bun test --watch
-```