@donkeylabs/server 2.0.16 → 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.16",
+  "version": "2.0.18",
   "type": "module",
   "description": "Type-safe plugin system for building RPC-style APIs with Bun",
   "main": "./src/index.ts",

package/src/generator/index.ts

@@ -300,6 +300,92 @@ export function groupRoutesByPrefix(routes: RouteInfo[]): Map<string, RouteInfo[
   return groups;
 }
 
+/**
+ * Represents a node in the namespace tree
+ */
+interface NamespaceNode {
+  methods: string[]; // Method definitions at this level
+  children: Map<string, NamespaceNode>;
+}
+
+/**
+ * Build a tree structure from route groups to handle multi-level prefixes
+ * e.g., "api.cache" and "api.counter" become:
+ * api -> { cache -> methods, counter -> methods }
+ */
+export function buildNamespaceTree(
+  routeGroups: Map<string, RouteInfo[]>,
+  generateMethod: (route: RouteInfo) => string | null
+): Map<string, NamespaceNode> {
+  const tree = new Map<string, NamespaceNode>();
+
+  for (const [prefix, routes] of routeGroups) {
+    const methods = routes
+      .map(generateMethod)
+      .filter((m): m is string => m !== null);
+
+    if (methods.length === 0) continue;
+
+    if (prefix === "_root") {
+      // Root level methods go directly
+      if (!tree.has("_root")) {
+        tree.set("_root", { methods: [], children: new Map() });
+      }
+      tree.get("_root")!.methods.push(...methods);
+      continue;
+    }
+
+    // Split prefix into parts for nested namespaces
+    const parts = prefix.split(".");
+    let current = tree;
+
+    for (let i = 0; i < parts.length; i++) {
+      const part = parts[i]!;
+      if (!current.has(part)) {
+        current.set(part, { methods: [], children: new Map() });
+      }
+
+      if (i === parts.length - 1) {
+        // Last part - add methods here
+        current.get(part)!.methods.push(...methods);
+      } else {
+        // Intermediate part - continue traversing
+        current = current.get(part)!.children;
+      }
+    }
+  }
+
+  return tree;
+}
+
+/**
+ * Generate nested namespace code from a tree node
+ */
+export function generateNestedNamespaceCode(
+  node: NamespaceNode,
+  indent: string = "    "
+): string {
+  const parts: string[] = [];
+
+  // Add methods at this level with proper indentation
+  for (const method of node.methods) {
+    // Indent each line of the method
+    const indentedMethod = method
+      .split("\n")
+      .map((line, i) => (i === 0 ? `${indent}${line}` : `${indent}  ${line}`))
+      .join("\n");
+    parts.push(indentedMethod);
+  }
+
+  // Add nested namespaces
+  for (const [childName, childNode] of node.children) {
+    const childContent = generateNestedNamespaceCode(childNode, indent + "  ");
+    parts.push(`${indent}${childName}: {\n${childContent}\n${indent}}`);
+  }
+
+  return parts.join(",\n\n");
+}
+
 // ==========================================
 // Client Code Generation
 // ==========================================
@@ -504,59 +590,60 @@ ${typeEntries.join("\n\n")}
   }`);
     }
 
-    const methodEntries = prefixRoutes
-      .filter((r) => r.handler === "typed")
-      .map((r) => {
-        const inputType = `Routes.${namespaceName}.${toPascalCase(r.routeName)}.Input`;
-        const outputType = `Routes.${namespaceName}.${toPascalCase(r.routeName)}.Output`;
-        return `    ${toCamelCase(r.routeName)}: (input: ${inputType}, options?: RequestOptions): Promise<${outputType}> =>
-      this.request("${r.name}", input, options)`;
-      });
-
-    const rawMethodEntries = prefixRoutes
-      .filter((r) => r.handler === "raw")
-      .map((r) => {
-        return `    ${toCamelCase(r.routeName)}: (init?: RequestInit): Promise<Response> =>
-      this.rawRequest("${r.name}", init)`;
-      });
+  }
 
-    const sseMethodEntries = prefixRoutes
-      .filter((r) => r.handler === "sse")
-      .map((r) => {
-        const inputType = r.inputSource
-          ? `Routes.${namespaceName}.${toPascalCase(r.routeName)}.Input`
-          : "Record<string, any>";
-        const eventsType = `Routes.${namespaceName}.${toPascalCase(r.routeName)}.Events`;
-        return `    ${toCamelCase(r.routeName)}: (input: ${inputType}, options?: Omit<SSEOptions, "endpoint" | "channels">): SSESubscription<${eventsType}> =>
-      this.connectToSSERoute("${r.name}", input, options)`;
-      });
+  // Build namespace tree for proper nesting (handles multi-level prefixes like "api.cache")
+  const generateMethodForRoute = (r: RouteInfo): string | null => {
+    const namespaceName = r.prefix === "_root" ? "Root" : toPascalCase(r.prefix);
 
-    const streamMethodEntries = prefixRoutes
-      .filter((r) => r.handler === "stream" || r.handler === "html")
-      .map((r) => {
-        const inputType = r.inputSource
-          ? `Routes.${namespaceName}.${toPascalCase(r.routeName)}.Input`
-          : "Record<string, any>";
-        return `    ${toCamelCase(r.routeName)}: (input: ${inputType}): Promise<Response> =>
-      this.streamRequest("${r.name}", input)`;
-      });
-
-    const formDataMethodEntries = prefixRoutes
-      .filter((r) => r.handler === "formData")
-      .map((r) => {
-        const inputType = `Routes.${namespaceName}.${toPascalCase(r.routeName)}.Input`;
-        const outputType = `Routes.${namespaceName}.${toPascalCase(r.routeName)}.Output`;
-        return `    ${toCamelCase(r.routeName)}: (fields: ${inputType}, files?: File[]): Promise<${outputType}> =>
-      this.uploadFormData("${r.name}", fields, files)`;
-      });
+    if (r.handler === "typed") {
+      const inputType = `Routes.${namespaceName}.${toPascalCase(r.routeName)}.Input`;
+      const outputType = `Routes.${namespaceName}.${toPascalCase(r.routeName)}.Output`;
+      return `${toCamelCase(r.routeName)}: (input: ${inputType}, options?: RequestOptions): Promise<${outputType}> =>
+        this.request("${r.name}", input, options)`;
+    }
+    if (r.handler === "raw") {
+      return `${toCamelCase(r.routeName)}: (init?: RequestInit): Promise<Response> =>
+        this.rawRequest("${r.name}", init)`;
+    }
+    if (r.handler === "sse") {
+      const inputType = r.inputSource
+        ? `Routes.${namespaceName}.${toPascalCase(r.routeName)}.Input`
+        : "Record<string, any>";
+      const eventsType = `Routes.${namespaceName}.${toPascalCase(r.routeName)}.Events`;
+      return `${toCamelCase(r.routeName)}: (input: ${inputType}, options?: Omit<SSEOptions, "endpoint" | "channels">): SSESubscription<${eventsType}> =>
+        this.connectToSSERoute("${r.name}", input, options)`;
+    }
+    if (r.handler === "stream" || r.handler === "html") {
+      const inputType = r.inputSource
+        ? `Routes.${namespaceName}.${toPascalCase(r.routeName)}.Input`
+        : "Record<string, any>";
+      return `${toCamelCase(r.routeName)}: (input: ${inputType}): Promise<Response> =>
+        this.streamRequest("${r.name}", input)`;
+    }
+    if (r.handler === "formData") {
+      const inputType = `Routes.${namespaceName}.${toPascalCase(r.routeName)}.Input`;
+      const outputType = `Routes.${namespaceName}.${toPascalCase(r.routeName)}.Output`;
+      return `${toCamelCase(r.routeName)}: (fields: ${inputType}, files?: File[]): Promise<${outputType}> =>
+        this.uploadFormData("${r.name}", fields, files)`;
+    }
+    return null;
+  };
 
-    const allMethods = [...methodEntries, ...rawMethodEntries, ...sseMethodEntries, ...streamMethodEntries, ...formDataMethodEntries];
+  const namespaceTree = buildNamespaceTree(routeGroups, generateMethodForRoute);
 
-    if (allMethods.length > 0) {
-      routeNamespaceBlocks.push(`  ${methodName} = {
-${allMethods.join(",\n\n")}
-  };`);
+  // Generate namespace blocks from tree
+  for (const [topLevel, node] of namespaceTree) {
+    if (topLevel === "_root") {
+      // Root level methods become direct class properties
+      for (const method of node.methods) {
+        routeNamespaceBlocks.push(`  ${method.trim().replace(/^\s+/gm, "  ")};`);
+      }
+      continue;
     }
+
+    const content = generateNestedNamespaceCode(node, "    ");
+    routeNamespaceBlocks.push(`  ${topLevel} = {\n${content}\n  };`);
   }
 
   // Generate event types

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";