@mandujs/core 0.22.0 → 0.23.0

package/src/testing/server.ts

@@ -0,0 +1,196 @@
+/**
+ * @mandujs/core/testing/server
+ *
+ * In-process server fixture for integration tests.
+ *
+ * Wraps `startServer()` with an ephemeral port (`0`), a per-test
+ * `ServerRegistry` (so parallel tests cannot stomp each other's handlers),
+ * and a scoped `fetch` helper so callers can write:
+ *
+ * ```ts
+ * import { createTestServer } from "@mandujs/core/testing";
+ *
+ * const server = await createTestServer(manifest, {
+ *   registerHandlers(reg) {
+ *     reg.registerApiHandler("api/health", async () => Response.json({ ok: true }));
+ *   },
+ * });
+ * afterAll(() => server.close());
+ *
+ * const res = await server.fetch("/api/health");
+ * expect(res.status).toBe(200);
+ * ```
+ *
+ * ## Design
+ *
+ * - **Registry isolation** — the fixture always creates its own
+ *   `ServerRegistry` (via `createServerRegistry()`), never touches the default
+ *   global. That lets several fixtures run concurrently in the same test
+ *   process without handler collisions.
+ * - **Port zero** — Bun picks an OS-assigned ephemeral port; the fixture
+ *   exposes the resolved port and a pre-computed `baseUrl` so tests never
+ *   hard-code `:3000`.
+ * - **Scoped `fetch`** — accepts either an absolute URL or a root-relative
+ *   path; the latter is joined to `baseUrl`. This matches the ergonomics
+ *   of `supertest` / Remix `createRoutesStub` without taking a dep on them.
+ * - **Cleanup contract** — `close()` is idempotent; the returned handle is
+ *   also `asyncDispose`-compatible so `using server = await createTestServer(...)`
+ *   works under Bun's Explicit Resource Management.
+ *
+ * @module testing/server
+ */
+
+import type { RoutesManifest } from "../spec/schema";
+import {
+  startServer,
+  createServerRegistry,
+  type ManduServer,
+  type ServerOptions,
+  type ServerRegistry,
+} from "../runtime/server";
+
+/** Options accepted by {@link createTestServer}. */
+export interface CreateTestServerOptions {
+  /**
+   * Optional registration callback. The fixture creates a fresh
+   * `ServerRegistry` and passes it here so tests can attach API handlers,
+   * page loaders, layouts, and so on synchronously before the server starts
+   * listening. Skip when the manifest's handlers are resolved elsewhere.
+   */
+  registerHandlers?: (registry: ServerRegistry) => void | Promise<void>;
+  /**
+   * Host to bind. Default: `"127.0.0.1"` (explicit IPv4 so Windows CI boxes
+   * do not fall through to `::1` and break `fetch` default resolution).
+   */
+  hostname?: string;
+  /**
+   * Extra options forwarded to `startServer()`. The fixture overrides
+   * `port`, `registry`, and `isDev` — those keys are ignored if present.
+   */
+  serverOptions?: Omit<ServerOptions, "port" | "registry" | "isDev" | "hostname">;
+  /** Set to `true` to boot the server in dev mode (HMR, kitchen, etc.). Default: `false`. */
+  isDev?: boolean;
+}
+
+/** The fixture handle returned by {@link createTestServer}. */
+export interface TestServer {
+  /** The underlying `ManduServer` (access `server.server.port` if you need Bun handles). */
+  readonly server: ManduServer;
+  /** The registry the fixture created. Use this to register handlers *after* startup. */
+  readonly registry: ServerRegistry;
+  /** Resolved port (non-zero once `await`ed). */
+  readonly port: number;
+  /** `http://<host>:<port>` with no trailing slash. */
+  readonly baseUrl: string;
+
+  /**
+   * Scoped fetch — accepts a path (`"/api/foo"`) or absolute URL
+   * (`"http://other/..."`). Path-style inputs are joined to `baseUrl`.
+   *
+   * ```ts
+   * await server.fetch("/api/health")
+   * await server.fetch("/api/login", { method: "POST", body: JSON.stringify({...}) })
+   * await server.fetch(new Request("http://localhost/anything"))
+   * ```
+   */
+  fetch(input: string | URL | Request, init?: RequestInit): Promise<Response>;
+
+  /**
+   * Idempotent teardown. Stops the underlying `Bun.serve` instance and
+   * clears the registry so no handler leaks into the next fixture.
+   */
+  close(): void;
+
+  /** Explicit Resource Management support: `using server = await createTestServer(...)`. */
+  [Symbol.asyncDispose](): Promise<void>;
+}
+
+/**
+ * Boot an in-process test server on an ephemeral port.
+ *
+ * Returns once `Bun.serve` is listening — no polling required; Bun binds
+ * synchronously before `fetch` becomes ready.
+ *
+ * @throws if `manifest` is missing required fields (handler resolution errors
+ *   surface on the first `fetch`, not here).
+ */
+export async function createTestServer(
+  manifest: RoutesManifest,
+  options: CreateTestServerOptions = {},
+): Promise<TestServer> {
+  const registry = createServerRegistry();
+
+  if (options.registerHandlers) {
+    await options.registerHandlers(registry);
+  }
+
+  const hostname = options.hostname ?? "127.0.0.1";
+  const server = startServer(manifest, {
+    ...(options.serverOptions ?? {}),
+    port: 0,
+    hostname,
+    isDev: options.isDev ?? false,
+    registry,
+  });
+
+  // Bun.serve always resolves the port synchronously before returning the
+  // handle — `undefined` would only happen on a fully-closed server, which
+  // is impossible here because we just created it. Assert + narrow so
+  // consumers see a plain `number`.
+  if (typeof server.server.port !== "number") {
+    throw new Error(
+      "[testing/server] startServer() returned without a bound port. This is a framework-level bug — please report.",
+    );
+  }
+  const port: number = server.server.port;
+  const baseUrl = `http://${hostname}:${port}`;
+
+  let closed = false;
+  const close = (): void => {
+    if (closed) return;
+    closed = true;
+    try {
+      server.stop();
+    } catch {
+      // stop() is best-effort — swallow so afterEach doesn't mask real test failures.
+    }
+  };
+
+  const fetchImpl = async (
+    input: string | URL | Request,
+    init?: RequestInit,
+  ): Promise<Response> => {
+    if (closed) {
+      throw new Error(
+        "[testing/server] fetch() called after close() — did an afterAll run before this test?",
+      );
+    }
+
+    // Resolve path-style inputs against baseUrl. Absolute URLs and Request
+    // objects pass through untouched so callers keep full control.
+    if (typeof input === "string") {
+      const resolved = input.startsWith("http://") || input.startsWith("https://")
+        ? input
+        : `${baseUrl}${input.startsWith("/") ? "" : "/"}${input}`;
+      return fetch(resolved, init);
+    }
+
+    if (input instanceof URL) {
+      return fetch(input, init);
+    }
+
+    return fetch(input, init);
+  };
+
+  return {
+    server,
+    registry,
+    port,
+    baseUrl,
+    fetch: fetchImpl,
+    close,
+    async [Symbol.asyncDispose]() {
+      close();
+    },
+  };
+}

package/src/testing/session.ts

@@ -0,0 +1,190 @@
+/**
+ * @mandujs/core/testing/session
+ *
+ * Pre-baked login state for integration tests.
+ *
+ * Most test scenarios start with "given a logged-in user, when...". This
+ * module returns a ready-to-use set of request headers (specifically,
+ * a `Cookie` header bearing a signed session payload) without going
+ * through the live `/login` flow — which would couple the test to the
+ * app's password, CSRF, and rate-limit policies.
+ *
+ * ```ts
+ * import { createTestSession } from "@mandujs/core/testing";
+ *
+ * const authed = await createTestSession({ userId: "u_42", roles: ["admin"] });
+ *
+ * const res = await server.fetch("/dashboard", {
+ *   headers: authed.headers,
+ * });
+ * expect(res.status).toBe(200);
+ * ```
+ *
+ * ## Contract
+ *
+ * - **Storage compatibility**: the cookie produced here is consumable by the
+ *   same `createCookieSessionStorage()` the app uses in production, as long
+ *   as the shared `secret` matches. Tests typically pass the app's real
+ *   storage instance via `{ storage }`; otherwise the fixture spins up a
+ *   fresh one with a deterministic test secret.
+ * - **No network**: everything happens in-process — no HTTP roundtrip, no
+ *   CSRF token generation, no rate-limit counters incremented.
+ * - **Fully typed**: `userId` is required, `extras` carries arbitrary
+ *   JSON-serializable payload. Cookie attributes (name, path, secure) come
+ *   from the provided storage's options.
+ *
+ * @module testing/session
+ */
+
+import {
+  Session,
+  createCookieSessionStorage,
+  type SessionStorage,
+  type CookieSessionOptions,
+} from "../filling/session";
+import { CookieManager } from "../filling/context";
+
+/** Key under which login helpers persist the user id. Mirrors `auth/login.ts`. */
+const USER_ID_KEY = "userId";
+/** Key under which login helpers persist the login timestamp. Mirrors `auth/login.ts`. */
+const LOGGED_AT_KEY = "loginAt";
+
+/** Default session secret used when the caller does not pass a storage instance. */
+const DEFAULT_TEST_SECRET = "mandu-test-secret-do-not-use-in-production";
+
+/** Options for {@link createTestSession}. */
+export interface CreateTestSessionOptions {
+  /** User id persisted in the session. Required. */
+  userId: string;
+  /** Arbitrary additional session data (JSON-serializable). */
+  extras?: Record<string, unknown>;
+  /**
+   * Login timestamp to persist. Default: `Date.now()` at call time.
+   * Useful for age-sensitive flows (e.g., re-auth prompts).
+   */
+  loggedAt?: number;
+  /**
+   * Storage instance to commit against. When omitted, the fixture spins up
+   * a fresh in-memory cookie-backed storage with {@link DEFAULT_TEST_SECRET}.
+   * Pass your app's real storage (same `secret`) to make the cookie
+   * round-trippable by the server under test.
+   */
+  storage?: SessionStorage;
+  /**
+   * Overrides for the fixture-created storage. Ignored when `storage` is
+   * passed directly.
+   */
+  cookieOptions?: Partial<CookieSessionOptions["cookie"]>;
+}
+
+/** The return shape. */
+export interface TestSession {
+  /** Raw `Set-Cookie` header string produced by committing the session. */
+  readonly setCookie: string;
+  /** `Cookie: ...` value suitable for outbound requests. */
+  readonly cookieHeader: string;
+  /** Headers object with `Cookie` pre-set — spread into `fetch()` directly. */
+  readonly headers: Record<string, string>;
+  /** The storage instance used to commit — re-use for subsequent setup steps. */
+  readonly storage: SessionStorage;
+  /** The `Session` instance that was committed (read-only snapshot view). */
+  readonly session: Session;
+  /** Convenience: the `userId` the fixture was created for. */
+  readonly userId: string;
+}
+
+/**
+ * Build a ready-to-use authenticated session.
+ *
+ * **Why not just POST `/login`?** Because the login endpoint can be behind
+ * CSRF, rate limit, captcha, 2FA, etc. The testing need is to assert
+ * behaviour *given* a logged-in user — not to re-validate the login path.
+ * For login-path tests, call the route directly with `server.fetch("/login", …)`.
+ */
+export async function createTestSession(
+  options: CreateTestSessionOptions,
+): Promise<TestSession> {
+  const { userId, extras, loggedAt, cookieOptions } = options;
+
+  if (typeof userId !== "string" || userId.length === 0) {
+    throw new TypeError(
+      "[testing/session] createTestSession: 'userId' must be a non-empty string.",
+    );
+  }
+
+  const storage =
+    options.storage ??
+    createCookieSessionStorage({
+      cookie: {
+        name: cookieOptions?.name ?? "__session",
+        secrets: cookieOptions?.secrets ?? [DEFAULT_TEST_SECRET],
+        httpOnly: cookieOptions?.httpOnly ?? true,
+        // Tests run over plain HTTP — forcing Secure would make the cookie
+        // invisible to the server under test. Explicit `false` overrides the
+        // production-env default in `createCookieSessionStorage`.
+        secure: cookieOptions?.secure ?? false,
+        sameSite: cookieOptions?.sameSite ?? "lax",
+        maxAge: cookieOptions?.maxAge ?? 86_400,
+        path: cookieOptions?.path ?? "/",
+        domain: cookieOptions?.domain,
+      },
+    });
+
+  const session = new Session();
+  session.set(USER_ID_KEY, userId);
+  session.set(LOGGED_AT_KEY, typeof loggedAt === "number" ? loggedAt : Date.now());
+
+  if (extras) {
+    for (const [key, value] of Object.entries(extras)) {
+      session.set(key, value);
+    }
+  }
+
+  const setCookie = await storage.commitSession(session);
+  const cookieHeader = extractCookieValuePair(setCookie);
+
+  return {
+    setCookie,
+    cookieHeader,
+    headers: { Cookie: cookieHeader },
+    storage,
+    session,
+    userId,
+  };
+}
+
+/**
+ * Given a Set-Cookie string, return the `name=value` segment suitable for
+ * an outgoing `Cookie` request header. Attribute fields (Path, Max-Age,
+ * HttpOnly, SameSite, ...) are stripped.
+ *
+ * The value MUST NOT be URL-decoded — the server-side cookie parser expects
+ * the same encoding that was produced by `commitSession`.
+ *
+ * Exported so tests that build their own Set-Cookie (custom storage) can
+ * share the parsing logic.
+ */
+export function extractCookieValuePair(setCookie: string): string {
+  const end = setCookie.indexOf(";");
+  return end === -1 ? setCookie : setCookie.slice(0, end);
+}
+
+/**
+ * Read the session that `storage.getSession()` would yield for the given
+ * `Cookie:` header. Useful in tests that install their own middleware and
+ * want to assert what the handler would see.
+ *
+ * Thin wrapper that constructs a throwaway `Request` (the form the
+ * production `CookieManager` expects) and delegates to `getSession` —
+ * so tests never have to thread the plumbing themselves.
+ */
+export async function readSession(
+  storage: SessionStorage,
+  cookieHeader: string,
+): Promise<Session> {
+  const request = new Request("http://localhost/__testing/readSession", {
+    headers: { cookie: cookieHeader },
+  });
+  const cookies = new CookieManager(request);
+  return storage.getSession(cookies);
+}