@donkeylabs/server 2.0.17 → 2.0.18

package/CLAUDE.md

@@ -139,11 +139,31 @@ throw ctx.errors.BadRequest("Invalid input");    // 400
 throw ctx.errors.Unauthorized("Login required"); // 401
 ```
 
+## Testing
+```ts
+// Unit test plugins (no HTTP)
+import { createTestHarness } from "@donkeylabs/server";
+const { manager } = await createTestHarness(myPlugin);
+
+// Integration test with HTTP (parallel-safe, unique ports)
+import { createIntegrationHarness } from "@donkeylabs/server";
+import { createApiClient } from "../lib/api";
+
+const harness = await createIntegrationHarness({
+  routers: [usersRouter],
+  plugins: [usersPlugin],
+});
+const api = harness.createClient(createApiClient); // Fully typed!
+await api.users.create({ name: "Test" });
+await harness.shutdown();
+```
+
 ## Commands
 ```sh
 bun run dev               # Dev server
 bunx donkeylabs generate  # Regen types after changes
 bun --bun tsc --noEmit    # Type check
+bun test                  # Run tests
 ```
 
 ## MCP Tools
@@ -154,4 +174,5 @@ bun --bun tsc --noEmit    # Type check
 - Core: logger, cache, events, cron, jobs, external-jobs, processes, workflows, sse, rate-limiter, errors
 - API: router, handlers, middleware
 - Server: lifecycle-hooks, services (custom services)
-- Infrastructure: database, plugins, testing, sveltekit-adapter, api-client
+- Testing: `createTestHarness` (unit), `createIntegrationHarness` (HTTP)
+- Infrastructure: database, plugins, sveltekit-adapter, api-client

package/docs/testing.md

@@ -1,25 +1,61 @@
 # Testing
 
-This guide covers testing plugins and routes using the built-in test harness.
+This guide covers testing plugins and routes using the built-in test harnesses.
 
 ## Table of Contents
 
-- [Test Harness](#test-harness)
+- [Quick Start](#quick-start)
+- [Test Harnesses](#test-harnesses)
+  - [createTestHarness](#createtestharness) - Unit testing plugins
+  - [createIntegrationHarness](#createintegrationharness) - Full HTTP API testing
 - [Unit Testing Plugins](#unit-testing-plugins)
-- [Integration Testing](#integration-testing)
+- [Integration Testing with HTTP](#integration-testing-with-http)
 - [Testing Routes](#testing-routes)
+- [Parallel Test Execution](#parallel-test-execution)
 - [Mocking Core Services](#mocking-core-services)
 - [Test Organization](#test-organization)
 - [Running Tests](#running-tests)
 
 ---
 
-## Test Harness
+## Quick Start
 
-The test harness creates a fully functional in-memory testing environment with real SQLite, migrations, and all core services.
+```ts
+// Unit test (no HTTP, fast)
+import { createTestHarness } from "@donkeylabs/server";
+const { manager } = await createTestHarness(myPlugin);
+const result = await manager.getServices().myPlugin.doSomething();
+
+// Integration test (full HTTP server)
+import { createIntegrationHarness } from "@donkeylabs/server";
+import { createApiClient } from "../lib/api"; // Your generated client
+
+const harness = await createIntegrationHarness({
+  routers: [myRouter],
+  plugins: [myPlugin],
+});
+const api = harness.createClient(createApiClient);
+const user = await api.users.create({ name: "Test" }); // Fully typed!
+await harness.shutdown();
+```
+
+---
+
+## Test Harnesses
+
+DonkeyLabs provides two test harnesses for different testing needs:
+
+| Harness | Use Case | HTTP Server | Speed |
+|---------|----------|-------------|-------|
+| `createTestHarness` | Unit testing plugins | No | Fast |
+| `createIntegrationHarness` | Full API testing | Yes | Medium |
+
+### createTestHarness
+
+For unit testing plugin services without HTTP overhead. Creates an in-memory environment with SQLite, migrations, and all core services.
 
 ```ts
-import { createTestHarness } from "@donkeylabs/server/harness";
+import { createTestHarness } from "@donkeylabs/server";
 import { myPlugin } from "./plugins/myPlugin";
 
 const { manager, db, core } = await createTestHarness(myPlugin);
@@ -35,12 +71,12 @@ core.logger.info("Test log");
 core.cache.set("key", "value");
 ```
 
-### With Dependencies
+#### With Dependencies
 
 If your plugin depends on other plugins, pass them as the second argument:
 
 ```ts
-import { createTestHarness } from "@donkeylabs/server/harness";
+import { createTestHarness } from "@donkeylabs/server";
 import { ordersPlugin } from "./plugins/orders";
 import { usersPlugin } from "./plugins/users";
 
@@ -51,6 +87,65 @@ const orders = manager.getServices().orders;
 const users = manager.getServices().users;
 ```
 
+### createIntegrationHarness
+
+For full HTTP API testing with your generated client. Starts a real HTTP server on a unique port for parallel test execution.
+
+```ts
+import { createIntegrationHarness, type IntegrationHarnessResult } from "@donkeylabs/server";
+import { createApiClient } from "../lib/api"; // Your generated client
+import { usersRouter } from "../server/routes/users";
+import { usersPlugin } from "../server/plugins/users";
+
+describe("Users API", () => {
+  let harness: IntegrationHarnessResult;
+  let api: ReturnType<typeof createApiClient>;
+
+  beforeAll(async () => {
+    harness = await createIntegrationHarness({
+      routers: [usersRouter],
+      plugins: [usersPlugin],
+    });
+    api = harness.createClient(createApiClient);
+  });
+
+  afterAll(async () => {
+    await harness.shutdown();
+  });
+
+  it("should create a user", async () => {
+    const user = await api.users.create({ name: "Test", email: "test@example.com" });
+    expect(user.id).toBeDefined();
+  });
+});
+```
+
+#### Harness Result Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `server` | `AppServer` | The running server instance |
+| `baseUrl` | `string` | Base URL (e.g., `http://localhost:12345`) |
+| `port` | `number` | Actual port the server is running on |
+| `db` | `Kysely<any>` | Database instance for direct queries |
+| `core` | `CoreServices` | Core services (logger, cache, etc.) |
+| `plugins` | `Record<string, any>` | Plugin services |
+| `client` | `TestApiClient` | Untyped client for quick testing |
+| `createClient` | `<T>(factory) => T` | Create typed client from your factory |
+| `shutdown` | `() => Promise<void>` | Cleanup function |
+
+#### Configuration Options
+
+```ts
+interface IntegrationHarnessOptions {
+  routers?: IRouter[];           // Routers to register
+  plugins?: Plugin[];            // Plugins to register
+  port?: number;                 // Starting port (default: random 10000-60000)
+  maxPortAttempts?: number;      // Retry attempts (default: 10)
+  logLevel?: "debug" | "info" | "warn" | "error"; // Default: "error"
+}
+```
+
 ---
 
 ## Unit Testing Plugins
@@ -138,9 +233,93 @@ describe("usersPlugin", () => {
 
 ---
 
-## Integration Testing
+## Integration Testing with HTTP
+
+Use `createIntegrationHarness` for full end-to-end API testing with your generated client.
+
+### Basic Example
+
+```ts
+import { describe, it, expect, beforeAll, afterAll } from "bun:test";
+import { createIntegrationHarness, type IntegrationHarnessResult } from "@donkeylabs/server";
+import { createApiClient } from "../lib/api";
+import { usersRouter } from "../server/routes/users";
+
+describe("Users API", () => {
+  let harness: IntegrationHarnessResult;
+  let api: ReturnType<typeof createApiClient>;
+
+  beforeAll(async () => {
+    harness = await createIntegrationHarness({
+      routers: [usersRouter],
+    });
+    api = harness.createClient(createApiClient);
+  });
+
+  afterAll(async () => {
+    await harness.shutdown();
+  });
+
+  it("should create and retrieve a user", async () => {
+    // Create
+    const created = await api.users.create({
+      name: "Test User",
+      email: "test@example.com",
+    });
+    expect(created.id).toBeDefined();
+
+    // Retrieve
+    const user = await api.users.get({ id: created.id });
+    expect(user.name).toBe("Test User");
+  });
+
+  it("should list users", async () => {
+    const result = await api.users.list({});
+    expect(result.users.length).toBeGreaterThan(0);
+  });
+});
+```
+
+### With Plugins
+
+```ts
+import { usersPlugin } from "../server/plugins/users";
+import { ordersPlugin } from "../server/plugins/orders";
+import { ordersRouter } from "../server/routes/orders";
+
+const harness = await createIntegrationHarness({
+  routers: [ordersRouter],
+  plugins: [usersPlugin, ordersPlugin],
+});
+```
+
+### Accessing Services Directly
+
+You can access plugin services and core services for test setup:
+
+```ts
+it("should process order for existing user", async () => {
+  // Use plugin service directly to create test data
+  const user = await harness.plugins.users.create({
+    email: "buyer@example.com",
+    name: "Buyer",
+  });
+
+  // Test via API
+  const order = await api.orders.create({
+    userId: user.id,
+    items: [{ productId: 1, quantity: 2 }],
+  });
+
+  expect(order.status).toBe("pending");
+});
+```
+
+---
+
+## Integration Testing (Plugin-Level)
 
-Integration tests verify multiple plugins working together.
+Integration tests verify multiple plugins working together without HTTP.
 
 ```ts
 // tests/checkout.integ.test.ts
@@ -419,12 +598,83 @@ jobs:
 
 ---
 
+## Parallel Test Execution
+
+`createIntegrationHarness` is designed for parallel test execution:
+
+1. **Unique ports** - Each harness gets a random port (10000-60000 range)
+2. **Automatic retry** - If port is in use, tries next port (up to 10 attempts)
+3. **In-memory isolation** - Each test has its own SQLite `:memory:` database
+4. **No file conflicts** - Type generation is disabled during tests
+
+### Example: Parallel Test Suites
+
+```ts
+// users.test.ts
+describe("Users API", () => {
+  let harness: IntegrationHarnessResult;
+
+  beforeAll(async () => {
+    harness = await createIntegrationHarness({ routers: [usersRouter] });
+  });
+  afterAll(() => harness.shutdown());
+
+  it("creates users", async () => {
+    // This test runs on port 12345 (random)
+  });
+});
+
+// orders.test.ts (runs in parallel)
+describe("Orders API", () => {
+  let harness: IntegrationHarnessResult;
+
+  beforeAll(async () => {
+    harness = await createIntegrationHarness({ routers: [ordersRouter] });
+  });
+  afterAll(() => harness.shutdown());
+
+  it("creates orders", async () => {
+    // This test runs on port 54321 (different random port)
+  });
+});
+```
+
+Both test files run simultaneously without conflicts.
+
+### Why Use the Generated Client?
+
+The generated client (`lib/api.ts`) provides:
+- Full TypeScript types for all routes
+- IDE autocomplete while writing tests
+- Compile-time error checking
+
+The client is generated once during development (`bunx donkeylabs generate`) and imported in tests. No regeneration happens at test runtime.
+
+---
+
 ## Best Practices
 
-1. **Use fresh harness per test** - Create a new harness in `beforeEach` to ensure test isolation
-2. **Test the public API** - Focus on testing service methods, not internal implementation
-3. **Use realistic data** - Create test data that resembles production data
-4. **Test edge cases** - Empty inputs, null values, boundary conditions
-5. **Test error cases** - Verify proper error throwing and handling
-6. **Keep tests fast** - In-memory SQLite is fast; avoid unnecessary delays
-7. **Run type checks** - Always run `tsc --noEmit` before committing
+1. **Choose the right harness**:
+   - `createTestHarness` for unit tests (fast, no HTTP)
+   - `createIntegrationHarness` for API tests (full HTTP, typed client)
+
+2. **Use fresh harness per test suite** - Create harness in `beforeAll`, shutdown in `afterAll`
+
+3. **Always call shutdown** - Prevent port leaks and hanging tests:
+   ```ts
+   afterAll(() => harness.shutdown());
+   ```
+
+4. **Use your generated client** - Import from `lib/api.ts` for full type safety
+
+5. **Test the public API** - Focus on testing service methods, not internal implementation
+
+6. **Use realistic data** - Create test data that resembles production data
+
+7. **Test edge cases** - Empty inputs, null values, boundary conditions
+
+8. **Test error cases** - Verify proper error throwing and handling
+
+9. **Keep tests fast** - In-memory SQLite is fast; avoid unnecessary delays
+
+10. **Run type checks** - Always run `tsc --noEmit` before committing

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@donkeylabs/server",
-  "version": "2.0.17",
+  "version": "2.0.18",
   "type": "module",
   "description": "Type-safe plugin system for building RPC-style APIs with Bun",
   "main": "./src/index.ts",

package/src/harness.ts

@@ -20,6 +20,9 @@ import {
   KyselyWorkflowAdapter,
   MemoryAuditAdapter,
 } from "./core/index";
+import { AppServer, type ServerConfig } from "./server";
+import type { IRouter, RouteDefinition } from "./router";
+import { ApiClientBase, type ApiClientOptions } from "./client/base";
 
 /**
  * Creates a fully functional (in-memory) testing environment for a plugin.
@@ -104,3 +107,277 @@ export async function createTestHarness(targetPlugin: Plugin, dependencies: Plug
     core
   };
 }
+
+// =============================================================================
+// INTEGRATION TEST HARNESS
+// =============================================================================
+
+/**
+ * Configuration for the integration test harness.
+ */
+export interface IntegrationHarnessOptions {
+  /** Routers to register with the server */
+  routers?: IRouter[];
+  /** Plugins to register with the server */
+  plugins?: Plugin[];
+  /** Starting port range (default: 10000-60000 random) */
+  port?: number;
+  /** Maximum port retry attempts (default: 10) */
+  maxPortAttempts?: number;
+  /** Logger level (default: "error" for quiet tests) */
+  logLevel?: "debug" | "info" | "warn" | "error";
+}
+
+/**
+ * A dynamic API client built from router definitions.
+ * Provides an untyped but convenient way to call routes.
+ */
+export class TestApiClient extends ApiClientBase {
+  private routeMap: Map<string, RouteDefinition>;
+
+  constructor(baseUrl: string, routers: IRouter[]) {
+    super(baseUrl);
+    this.routeMap = new Map();
+    for (const router of routers) {
+      for (const route of router.getRoutes()) {
+        this.routeMap.set(route.name, route);
+      }
+    }
+  }
+
+  /**
+   * Call any route by name with the given input.
+   * Convenient for quick testing without generated types.
+   *
+   * @example
+   * ```ts
+   * const user = await client.call("users.create", { name: "Test", email: "test@example.com" });
+   * ```
+   */
+  async call<TOutput = any>(route: string, input: any = {}): Promise<TOutput> {
+    const routeDef = this.routeMap.get(route);
+    if (!routeDef) {
+      throw new Error(`Route not found: ${route}. Available routes: ${[...this.routeMap.keys()].join(", ")}`);
+    }
+
+    // Handle different handler types
+    if (routeDef.handler === "typed" || routeDef.handler === "formData") {
+      return this.request(route, input);
+    } else if (routeDef.handler === "stream" || routeDef.handler === "html") {
+      const response = await this.rawRequest(route, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(input),
+      });
+      return response as any;
+    } else if (routeDef.handler === "raw") {
+      const response = await this.rawRequest(route);
+      return response as any;
+    }
+
+    return this.request(route, input);
+  }
+
+  /**
+   * Get a raw Response for stream/file routes.
+   */
+  async stream(route: string, input: any = {}): Promise<Response> {
+    return this.rawRequest(route, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(input),
+    });
+  }
+
+  /**
+   * List all available routes.
+   */
+  routes(): string[] {
+    return [...this.routeMap.keys()];
+  }
+}
+
+/**
+ * Result from createIntegrationHarness.
+ */
+export interface IntegrationHarnessResult {
+  /** The running AppServer instance */
+  server: AppServer;
+  /** Base URL for API calls (e.g., "http://localhost:12345") */
+  baseUrl: string;
+  /** The actual port the server is running on */
+  port: number;
+  /** Database instance */
+  db: Kysely<any>;
+  /** Core services */
+  core: CoreServices;
+  /** Plugin services (after initialization) */
+  plugins: Record<string, any>;
+  /**
+   * Untyped test client for quick testing.
+   * Use `client.call("route.name", input)` to call any route.
+   *
+   * @example
+   * ```ts
+   * const user = await harness.client.call("users.create", { name: "Test" });
+   * ```
+   */
+  client: TestApiClient;
+  /**
+   * Create a typed client using your generated client factory.
+   * Pass your `createApiClient` function to get full type safety.
+   *
+   * @example
+   * ```ts
+   * import { createApiClient } from "../lib/api";
+   * const api = harness.createClient(createApiClient);
+   * const user = await api.users.create({ name: "Test" }); // Fully typed!
+   * ```
+   */
+  createClient: <T>(factory: (config: { baseUrl: string }) => T) => T;
+  /** Shutdown function - call this in afterAll/afterEach */
+  shutdown: () => Promise<void>;
+}
+
+// Track used ports across test files running in parallel
+const usedPorts = new Set<number>();
+
+/**
+ * Get a unique starting port for parallel test execution.
+ * Uses random port in range 10000-60000 and tracks to avoid collisions.
+ */
+function getUniquePort(): number {
+  const minPort = 10000;
+  const maxPort = 60000;
+  let port: number;
+  let attempts = 0;
+  const maxAttempts = 100;
+
+  do {
+    port = minPort + Math.floor(Math.random() * (maxPort - minPort));
+    attempts++;
+  } while (usedPorts.has(port) && attempts < maxAttempts);
+
+  usedPorts.add(port);
+  return port;
+}
+
+/**
+ * Creates a full integration testing environment with a real HTTP server.
+ *
+ * Use this when you need to test API routes end-to-end with the generated
+ * API client. The server runs in-memory (SQLite :memory:) and uses a random
+ * port for parallel test execution.
+ *
+ * @example
+ * ```ts
+ * import { describe, it, expect, beforeAll, afterAll } from "bun:test";
+ * import { createIntegrationHarness } from "@donkeylabs/server";
+ * import { createApiClient } from "../lib/api"; // Your generated client
+ * import { usersRouter } from "../server/routes/users";
+ * import { usersPlugin } from "../server/plugins/users";
+ *
+ * describe("Users API", () => {
+ *   let harness: Awaited<ReturnType<typeof createIntegrationHarness>>;
+ *   let api: ReturnType<typeof createApiClient>;
+ *
+ *   beforeAll(async () => {
+ *     harness = await createIntegrationHarness({
+ *       routers: [usersRouter],
+ *       plugins: [usersPlugin],
+ *     });
+ *     api = createApiClient({ baseUrl: harness.baseUrl });
+ *   });
+ *
+ *   afterAll(async () => {
+ *     await harness.shutdown();
+ *   });
+ *
+ *   it("should create a user", async () => {
+ *     const user = await api.users.create({ name: "Test", email: "test@example.com" });
+ *     expect(user.id).toBeDefined();
+ *   });
+ *
+ *   it("should list users", async () => {
+ *     const result = await api.users.list({});
+ *     expect(result.users.length).toBeGreaterThan(0);
+ *   });
+ * });
+ * ```
+ */
+export async function createIntegrationHarness(
+  options: IntegrationHarnessOptions = {}
+): Promise<IntegrationHarnessResult> {
+  const {
+    routers = [],
+    plugins = [],
+    port = getUniquePort(),
+    maxPortAttempts = 10,
+    logLevel = "error",
+  } = options;
+
+  // 1. Setup In-Memory DB
+  const db = new Kysely<any>({
+    dialect: new BunSqliteDialect({ database: new Database(":memory:") }),
+  });
+
+  // 2. Create server with test configuration
+  const server = new AppServer({
+    db,
+    port,
+    maxPortAttempts,
+    logger: { level: logLevel },
+    // Disable file generation in tests
+    generateTypes: undefined,
+  });
+
+  // 3. Register plugins
+  for (const plugin of plugins) {
+    server.registerPlugin(plugin);
+  }
+
+  // 4. Register routers
+  for (const router of routers) {
+    server.use(router);
+  }
+
+  // 5. Start the server
+  await server.start();
+
+  // Get the actual port (may have changed if initial was in use)
+  const actualPort = (server as any).port as number;
+  const baseUrl = `http://localhost:${actualPort}`;
+
+  // Track this port as used
+  usedPorts.add(actualPort);
+
+  // Get core services and plugins for direct access in tests
+  const core = (server as any).coreServices as CoreServices;
+  const pluginServices = (server as any).manager.getServices();
+
+  // Create untyped test client
+  const client = new TestApiClient(baseUrl, routers);
+
+  // Factory for typed clients
+  const createClient = <T>(factory: (config: { baseUrl: string }) => T): T => {
+    return factory({ baseUrl });
+  };
+
+  // Shutdown function
+  const shutdown = async () => {
+    await server.shutdown();
+    usedPorts.delete(actualPort);
+  };
+
+  return {
+    server,
+    baseUrl,
+    port: actualPort,
+    db,
+    core,
+    plugins: pluginServices,
+    client,
+    createClient,
+    shutdown,
+  };
+}

package/src/index.ts

@@ -121,5 +121,11 @@ export {
   createAdminRouter,
 } from "./admin";
 
-// Test Harness - for plugin testing
-export { createTestHarness } from "./harness";
+// Test Harness - for plugin and integration testing
+export {
+  createTestHarness,
+  createIntegrationHarness,
+  TestApiClient,
+  type IntegrationHarnessOptions,
+  type IntegrationHarnessResult,
+} from "./harness";