@mandujs/core 0.22.1 → 0.24.0

package/src/testing/mocks.ts

@@ -0,0 +1,203 @@
+/**
+ * @mandujs/core/testing/mocks
+ *
+ * Swap-in mocks for the I/O primitives tests typically stub:
+ *
+ * - `mockMail()` → the production `MemoryEmailSender` (Phase 5 email
+ *   primitive), wrapped so tests get a uniform async-dispose cleanup helper.
+ * - `mockStorage()` → an in-memory `S3Client`-shaped handle satisfying the
+ *   public `@mandujs/core/storage/s3` interface without booting `Bun.S3Client`.
+ *
+ * Both return objects that are **drop-in replacements** for their production
+ * counterparts. Pass them to the handler/service under test via whatever
+ * dependency-injection path your code already uses — there is no magic here.
+ *
+ * ```ts
+ * import { mockMail, mockStorage } from "@mandujs/core/testing";
+ *
+ * const mail = mockMail();
+ * const storage = mockStorage();
+ *
+ * await sendWelcomeEmail({ mail }, "u@x.com");
+ * expect(mail.sent[0].subject).toBe("Welcome");
+ *
+ * await uploadAvatar({ storage }, buffer);
+ * expect(await storage.exists("u/avatar.png")).toBe(true);
+ * ```
+ *
+ * @module testing/mocks
+ */
+
+import {
+  createMemoryEmailSender,
+  type EmailMessage,
+  type MemoryEmailSender,
+} from "../email/index";
+import { getContentType, type S3Client, type S3UploadOptions, type S3PresignOptions } from "../storage/s3/index";
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Email mock
+// ═══════════════════════════════════════════════════════════════════════════
+
+/** Handle returned by {@link mockMail}. Extends the production sender 1:1. */
+export interface MockMail extends MemoryEmailSender {
+  /**
+   * Find the most recently sent message whose recipient matches `to`
+   * (single-address equality). Returns `undefined` if none matched.
+   *
+   * Convenience shortcut around a reverse scan of `sent` — the common
+   * assertion in verification / password-reset tests.
+   */
+  lastTo(to: string): (EmailMessage & { id: string; sentAt: number }) | undefined;
+  /** `using mail = mockMail()` — clears the outbox on exit. */
+  [Symbol.dispose](): void;
+}
+
+/**
+ * Create an in-process email sender. Backing store is a plain array —
+ * read via `mail.sent`, clear between cases with `mail.clear()`.
+ *
+ * This is a thin wrapper around the production `createMemoryEmailSender`
+ * so tests do not depend on an implementation detail of the email package.
+ */
+export function mockMail(): MockMail {
+  const inner = createMemoryEmailSender();
+
+  // MemoryEmailSender's `sent` is declared readonly at the type level; the
+  // runtime object exposes .push under the covers. We add the convenience
+  // helper without widening the surface.
+  //
+  // Reverse-iterating by index (vs. `.findLast`) avoids dependency on the
+  // ES2023 `Array.prototype.findLast` lib type — older tsconfig targets
+  // (`"lib": ["ES2022"]`) do not declare it. The runtime has it regardless.
+  return Object.assign(inner, {
+    lastTo(
+      to: string,
+    ): (EmailMessage & { id: string; sentAt: number }) | undefined {
+      for (let i = inner.sent.length - 1; i >= 0; i--) {
+        const m = inner.sent[i];
+        if (Array.isArray(m.to)) {
+          if (m.to.includes(to)) return m;
+        } else if (m.to === to) {
+          return m;
+        }
+      }
+      return undefined;
+    },
+    [Symbol.dispose]() {
+      inner.clear();
+    },
+  }) as MockMail;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Storage (S3-compatible) mock
+// ═══════════════════════════════════════════════════════════════════════════
+
+/** Stored blob + metadata for assertions. */
+export interface MockStoredObject {
+  readonly body: Uint8Array;
+  readonly contentType: string;
+  readonly acl?: "private" | "public-read";
+}
+
+/** Handle returned by {@link mockStorage}. Extends `S3Client` with test-only affordances. */
+export interface MockStorage extends S3Client {
+  /** Every key currently present. */
+  keys(): string[];
+  /** Raw access to a stored object. Returns `undefined` for missing keys. */
+  peek(key: string): MockStoredObject | undefined;
+  /** Wipe all stored objects. */
+  clear(): void;
+  /** `using s = mockStorage()` — clears the store on exit. */
+  [Symbol.dispose](): void;
+}
+
+/**
+ * Convert the production `S3Client` body types into a normalized Uint8Array
+ * so `peek()` returns a stable type regardless of what callers uploaded.
+ */
+function normalizeBody(body: Blob | ArrayBuffer | Uint8Array): Promise<Uint8Array> {
+  if (body instanceof Uint8Array) return Promise.resolve(new Uint8Array(body));
+  if (body instanceof ArrayBuffer) return Promise.resolve(new Uint8Array(body));
+  // Blob → ArrayBuffer → Uint8Array.
+  return body.arrayBuffer().then((ab) => new Uint8Array(ab));
+}
+
+/**
+ * Create an in-memory S3-compatible storage client. Satisfies the full
+ * `S3Client` interface — handlers written against the production API can
+ * be called with this mock unchanged.
+ *
+ * Presigned URLs are synthesized as opaque `mandu-mock://bucket/<key>`
+ * strings. They are not de-serializable back into real uploads — only used
+ * for identity assertions (presign returned? key matches?).
+ */
+export function mockStorage(options?: { bucket?: string }): MockStorage {
+  const bucket = options?.bucket ?? "mandu-test-bucket";
+  const store = new Map<string, MockStoredObject>();
+
+  async function upload(
+    body: Blob | ArrayBuffer | Uint8Array,
+    opts: S3UploadOptions,
+  ): Promise<string> {
+    if (!opts.key) {
+      throw new TypeError(
+        "[testing/mocks] mockStorage.upload: 'key' is required.",
+      );
+    }
+    const contentType = opts.contentType ?? getContentType(opts.key);
+    const bytes = await normalizeBody(body);
+    store.set(opts.key, { body: bytes, contentType, acl: opts.acl });
+    return `mandu-mock://${bucket}/${opts.key}`;
+  }
+
+  async function presign(opts: S3PresignOptions): Promise<string> {
+    if (!opts.key) {
+      throw new TypeError(
+        "[testing/mocks] mockStorage.presign: 'key' is required.",
+      );
+    }
+    const method = opts.method ?? "PUT";
+    const expiresIn = opts.expiresIn ?? 900;
+    return `mandu-mock://${bucket}/${opts.key}?method=${method}&expires=${expiresIn}`;
+  }
+
+  async function deleteObject(key: string): Promise<void> {
+    store.delete(key);
+  }
+
+  async function getReadable(key: string): Promise<ReadableStream> {
+    const obj = store.get(key);
+    if (!obj) {
+      throw new Error(
+        `[testing/mocks] mockStorage.getReadable: key not found: ${JSON.stringify(key)}`,
+      );
+    }
+    return new ReadableStream({
+      start(controller) {
+        controller.enqueue(obj.body);
+        controller.close();
+      },
+    });
+  }
+
+  async function exists(key: string): Promise<boolean> {
+    return store.has(key);
+  }
+
+  const handle: MockStorage = {
+    upload,
+    presign,
+    delete: deleteObject,
+    getReadable,
+    exists,
+    keys: () => [...store.keys()],
+    peek: (key) => store.get(key),
+    clear: () => store.clear(),
+    [Symbol.dispose]() {
+      store.clear();
+    },
+  };
+  return handle;
+}

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);
+}