@beignet/core 0.0.3 → 0.0.4

package/src/testing/index.ts

@@ -1,14 +1,990 @@
-import { type ClockPort, createSystemClock } from "../ports/clock";
+import {
+  createMemoryIdempotencyStore,
+  type MemoryIdempotencyStore,
+} from "../idempotency/index.js";
+import { createMemoryMailer, type MemoryMailerPort } from "../mail/index.js";
+import {
+  createMemoryNotificationPort,
+  type MemoryNotificationPort,
+} from "../notifications/index.js";
+import { createMemoryOutbox, type MemoryOutboxPort } from "../outbox/index.js";
+import {
+  type ActivityActor,
+  type ActivityTenant,
+  type AuditLogPort,
+  createMemoryAuditLog,
+  type MemoryAuditLogPort,
+} from "../ports/audit.js";
+import { type CachePort, createMemoryCache } from "../ports/cache.js";
+import {
+  type ClockPort,
+  createFrozenClock,
+  createSystemClock,
+} from "../ports/clock.js";
+import type { EventBusPort, JobDispatcherPort } from "../ports/events.js";
 import {
   createUuidIdGenerator,
   type IdGeneratorPort,
-} from "../ports/id-generator";
+} from "../ports/id-generator.js";
+import {
+  type AnyPorts,
+  type BoundGate,
+  type BufferedDomainEventRecorder,
+  createGate,
+  createMemoryRateLimiter,
+  createMemoryStorage,
+  createNoopLogger,
+  createNoopUnitOfWork,
+  type GatePort,
+  type LoggerPort,
+  type RateLimitPort,
+  type StoragePort,
+  type UnitOfWorkPort,
+} from "../ports/index.js";
+import {
+  createRecordingEventBus,
+  createRecordingJobDispatcher,
+  createTestActivityContext,
+  createTestSystemActor,
+  createTestUserActor,
+  type RecordedEvent,
+  type RecordedJobDispatch,
+} from "../ports/testing.js";
+import type {
+  AnyServiceProvider,
+  ProviderSetupResult,
+} from "../providers/provider.js";
+import { createAmbientAuditLog } from "../server/audit-context.js";
+import {
+  clearActiveRequestContext,
+  enterActiveRequestContext,
+} from "../server/request-context.js";
 
 /**
  * Value that may be returned synchronously or asynchronously.
  */
 export type MaybePromise<T> = T | Promise<T>;
 
+/**
+ * Common Beignet ports created by `createTestPorts(...)`.
+ */
+export interface CommonTestPorts<TxPorts = AnyPorts> {
+  [key: string]: unknown;
+  /**
+   * Ambient-enriched in-memory audit log. Entries recorded through this port
+   * inherit actor, tenant, request ID, and trace ID from the active request
+   * context, matching production server behavior. Use the fixture's `audit`
+   * for entry assertions.
+   */
+  audit: AuditLogPort;
+  /**
+   * In-memory string cache.
+   */
+  cache: CachePort;
+  /**
+   * Mutable deterministic test clock.
+   */
+  clock: ClockPort;
+  /**
+   * Recording event bus.
+   */
+  eventBus: EventBusPort;
+  /**
+   * Authorization gate. Apps with real policies should provide their own gate
+   * through `overrides`.
+   */
+  gate: GatePort<unknown, []>;
+  /**
+   * In-memory idempotency store.
+   */
+  idempotency: MemoryIdempotencyStore;
+  /**
+   * Sequence or UUID generator used by tests.
+   */
+  ids: IdGeneratorPort;
+  /**
+   * Recording job dispatcher.
+   */
+  jobs: JobDispatcherPort;
+  /**
+   * No-op logger.
+   */
+  logger: LoggerPort;
+  /**
+   * In-memory mailer.
+   */
+  mailer: MemoryMailerPort;
+  /**
+   * In-memory notification port.
+   */
+  notifications: MemoryNotificationPort;
+  /**
+   * In-memory outbox.
+   */
+  outbox: MemoryOutboxPort;
+  /**
+   * In-memory rate limiter.
+   */
+  rateLimit: RateLimitPort;
+  /**
+   * In-memory object storage.
+   */
+  storage: StoragePort;
+  /**
+   * No-op Unit of Work over the configured transaction ports.
+   */
+  uow: UnitOfWorkPort<TxPorts>;
+}
+
+/**
+ * Captured state and ports returned by `createTestPorts(...)`.
+ */
+export interface TestPortsFixture<
+  Ports extends AnyPorts = CommonTestPorts,
+  TxPorts = Ports,
+> {
+  /**
+   * App ports to pass into a use-case or route test context.
+   */
+  ports: Ports;
+  /**
+   * Memory audit port, exposed for assertions.
+   */
+  audit: MemoryAuditLogPort;
+  /**
+   * Recording event bus port.
+   */
+  eventBus: EventBusPort;
+  /**
+   * Recorded events published through `eventBus`.
+   */
+  events: RecordedEvent[];
+  /**
+   * Recording job dispatcher port.
+   */
+  jobs: JobDispatcherPort;
+  /**
+   * Jobs dispatched through `jobs`.
+   */
+  dispatchedJobs: RecordedJobDispatch[];
+  /**
+   * Memory mailer, exposed for delivery assertions.
+   */
+  mailer: MemoryMailerPort;
+  /**
+   * Memory notification port, exposed for delivery assertions.
+   */
+  notifications: MemoryNotificationPort;
+  /**
+   * Memory outbox, exposed for durable workflow assertions.
+   */
+  outbox: MemoryOutboxPort;
+  /**
+   * Memory storage port.
+   */
+  storage: StoragePort;
+  /**
+   * Memory idempotency store.
+   */
+  idempotency: MemoryIdempotencyStore;
+  /**
+   * Test cache port.
+   */
+  cache: CachePort;
+  /**
+   * Test rate-limit port.
+   */
+  rateLimit: RateLimitPort;
+  /**
+   * Test logger port.
+   */
+  logger: LoggerPort;
+  /**
+   * Test clock port.
+   */
+  clock: ClockPort;
+  /**
+   * Test ID generator.
+   */
+  ids: IdGeneratorPort;
+  /**
+   * Unit of Work port installed on `ports`.
+   */
+  uow: UnitOfWorkPort<TxPorts>;
+}
+
+/**
+ * Unit of Work behavior for `createTestPorts(...)`.
+ */
+export interface CreateTestPortsTransactionOptions<
+  Ports extends AnyPorts,
+  TxPorts,
+> {
+  /**
+   * Transaction-scoped ports or a function that derives them from final ports.
+   *
+   * Defaults to the final `ports` object.
+   */
+  ports?: TxPorts | ((ports: Ports) => TxPorts);
+  /**
+   * Hook run after the transaction callback resolves.
+   */
+  afterCommit?: (tx: TxPorts) => MaybePromise<void>;
+  /**
+   * Hook run after the transaction callback throws.
+   */
+  afterRollback?: (error: unknown, tx: TxPorts) => MaybePromise<void>;
+  /**
+   * Flush `tx.events` (a buffered domain event recorder) to `ports.eventBus`
+   * after the transaction commits, and clear it after a rollback.
+   *
+   * Requires `transaction.ports` to include an `events` recorder such as
+   * `createDomainEventRecorder()` or `createOutboxEventRecorder(...)`.
+   */
+  outbox?: boolean;
+}
+
+/**
+ * Override shape for one test port.
+ *
+ * Object-valued ports may be supplied one level deep as partials: the missing
+ * members are completed behind a proxy that throws a named error on use.
+ * Function-valued ports must be supplied whole, so the check for functions
+ * happens before the object branch.
+ */
+export type TestPortOverride<Port> = Port extends (...args: never[]) => unknown
+  ? Port
+  : Port extends object
+    ? Partial<Port>
+    : Port;
+
+/**
+ * Typed partial port overrides accepted by `createTestPorts(...)` and
+ * `createTestContext(...)`.
+ */
+export type TestPortsOverrides<Ports extends AnyPorts> = {
+  [K in keyof Ports]?: TestPortOverride<Ports[K]>;
+};
+
+/**
+ * Options for `createTestPorts(...)`.
+ */
+export interface CreateTestPortsOptions<
+  Ports extends AnyPorts,
+  TxPorts = Ports,
+> {
+  /**
+   * App-owned default ports, usually imported from `infra/app-ports`. Common
+   * Beignet test defaults replace matching keys from `base`; use `overrides`
+   * for app ports that should win.
+   *
+   * Values are intentionally loose: boot-time app ports may bind wider types
+   * (or deferred placeholders) than the provider-contributed runtime ports.
+   */
+  base?: { [K in keyof Ports]?: unknown };
+  /**
+   * Test-specific ports that should replace generated defaults or `base`.
+   *
+   * Plain-object ports may be supplied as one-level-deep partials; missing
+   * members throw a named error when called. Function-valued ports, class
+   * instances, and other exotic objects are passed through whole.
+   */
+  overrides?: TestPortsOverrides<Ports>;
+  /**
+   * Clock implementation. Defaults to a frozen clock at the Unix epoch.
+   */
+  clock?: ClockPort;
+  /**
+   * ID generator. Defaults to UUIDs.
+   */
+  ids?: IdGeneratorPort;
+  /**
+   * Unit of Work configuration. A no-op UOW is installed by default.
+   */
+  transaction?: CreateTestPortsTransactionOptions<Ports, TxPorts>;
+}
+
+/**
+ * Create standard memory/fake Beignet ports for tests.
+ *
+ * Use this as the starting point for use-case and route tests, then layer
+ * app-owned repositories or provider fakes through `base` and `overrides`.
+ *
+ * @param options - Optional app ports, overrides, and Unit of Work behavior.
+ * @returns Ports plus captured state for assertions.
+ */
+export function createTestPorts<
+  Ports extends AnyPorts = CommonTestPorts,
+  TxPorts = Ports,
+>(
+  options: CreateTestPortsOptions<Ports, TxPorts> = {},
+): TestPortsFixture<Ports, TxPorts> {
+  const audit = createMemoryAuditLog();
+  const cache = createMemoryCache();
+  const clock = options.clock ?? createFrozenClock();
+  const { bus: eventBus, events } = createRecordingEventBus();
+  const { jobs, dispatchedJobs } = createRecordingJobDispatcher();
+  const idempotency = createMemoryIdempotencyStore();
+  const ids = options.ids ?? createUuidIdGenerator();
+  const logger = createNoopLogger();
+  const mailer = createMemoryMailer();
+  const notifications = createMemoryNotificationPort();
+  const outbox = createMemoryOutbox();
+  const rateLimit = createMemoryRateLimiter();
+  const storage = createMemoryStorage();
+
+  const defaultPorts = {
+    audit: createAmbientAuditLog(audit),
+    cache,
+    clock,
+    eventBus,
+    gate: createGate({ policies: [] }),
+    idempotency,
+    ids,
+    jobs,
+    logger,
+    mailer,
+    notifications,
+    outbox,
+    rateLimit,
+    storage,
+  };
+  const overrides = completeTestPortOverrides(options.overrides);
+  // The kit's one sanctioned cast: boot-time bases and completed partial
+  // overrides are widened to the app's full Ports shape.
+  const portsWithoutUow = {
+    ...options.base,
+    ...defaultPorts,
+    ...overrides,
+  } as unknown as Ports;
+  const transactionOptions = options.transaction;
+  const flushEventsToOutbox = transactionOptions?.outbox === true;
+  const resolveTransactionPorts = (): TxPorts => {
+    const txPorts = transactionOptions?.ports;
+    if (typeof txPorts === "function") {
+      return (txPorts as (ports: Ports) => TxPorts)(portsWithoutUow);
+    }
+
+    return txPorts ?? (portsWithoutUow as unknown as TxPorts);
+  };
+  const generatedUow = createNoopUnitOfWork<TxPorts>(
+    () => {
+      const tx = resolveTransactionPorts();
+      if (flushEventsToOutbox) {
+        // Validate up front so both commit and rollback paths fail loudly.
+        resolveBufferedTransactionEvents(tx);
+      }
+
+      return tx;
+    },
+    {
+      afterCommit: async (tx) => {
+        if (flushEventsToOutbox) {
+          await resolveBufferedTransactionEvents(tx).flush(
+            (portsWithoutUow as unknown as { eventBus: EventBusPort }).eventBus,
+          );
+        }
+        await transactionOptions?.afterCommit?.(tx);
+      },
+      afterRollback: async (error, tx) => {
+        if (flushEventsToOutbox) {
+          resolveBufferedTransactionEvents(tx).clear();
+        }
+        await transactionOptions?.afterRollback?.(error, tx);
+      },
+    },
+  );
+  // The kit consumes `uow` directly, so keep the supplied port's identity
+  // instead of the completed override.
+  const uow =
+    (options.overrides as { uow?: UnitOfWorkPort<TxPorts> } | undefined)?.uow ??
+    generatedUow;
+  const ports = {
+    ...portsWithoutUow,
+    uow,
+  } as Ports;
+
+  return {
+    ports,
+    audit,
+    eventBus,
+    events,
+    jobs,
+    dispatchedJobs,
+    mailer,
+    notifications,
+    outbox,
+    storage,
+    idempotency,
+    cache,
+    rateLimit,
+    logger,
+    clock,
+    ids,
+    uow,
+  };
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  if (value === null || typeof value !== "object") return false;
+  const proto = Object.getPrototypeOf(value);
+
+  return proto === Object.prototype || proto === null;
+}
+
+function createMissingTestPortMember(
+  portKey: string,
+  member: string,
+): () => never {
+  const memberName = `${portKey}.${member}`;
+  const throwMissingMember = () => {
+    throw new Error(
+      `Test port "${memberName}" was called but not provided. Pass it through createTestPorts overrides.`,
+    );
+  };
+  Object.defineProperty(throwMissingMember, "name", {
+    value: memberName,
+    configurable: true,
+  });
+
+  return throwMissingMember;
+}
+
+function completeTestPortOverride(portKey: string, value: unknown): unknown {
+  // Functions are objects: the function check must run first so
+  // function-valued ports pass through whole.
+  if (typeof value === "function") return value;
+  // Class instances (repositories, Maps, gates built from classes) rely on
+  // internal slots or prototype identity, so only plain objects are completed.
+  if (!isPlainObject(value)) return value;
+
+  return new Proxy(value, {
+    get(target, member, receiver) {
+      if (
+        typeof member === "symbol" ||
+        member === "then" ||
+        member === "constructor" ||
+        member in target
+      ) {
+        return Reflect.get(target, member, receiver);
+      }
+
+      return createMissingTestPortMember(portKey, member);
+    },
+  });
+}
+
+function completeTestPortOverrides<Ports extends AnyPorts>(
+  overrides: TestPortsOverrides<Ports> | undefined,
+): Record<string, unknown> {
+  const completed: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(overrides ?? {})) {
+    if (value === undefined) continue;
+    completed[key] = completeTestPortOverride(key, value);
+  }
+
+  return completed;
+}
+
+function resolveBufferedTransactionEvents(
+  tx: unknown,
+): Pick<BufferedDomainEventRecorder, "flush" | "clear"> {
+  const events =
+    tx && typeof tx === "object"
+      ? (tx as { events?: unknown }).events
+      : undefined;
+  const recorder = events as
+    | Partial<Pick<BufferedDomainEventRecorder, "flush" | "clear">>
+    | undefined;
+  if (
+    !recorder ||
+    typeof recorder.flush !== "function" ||
+    typeof recorder.clear !== "function"
+  ) {
+    throw new Error(
+      "createTestPorts transaction.outbox requires tx.events to be a buffered domain event recorder. " +
+        "Add events: createDomainEventRecorder() or createOutboxEventRecorder(...) to transaction.ports.",
+    );
+  }
+
+  return recorder as Pick<BufferedDomainEventRecorder, "flush" | "clear">;
+}
+
+/**
+ * Bound gate type inferred from a ports object.
+ */
+export type TestBoundGateForPorts<Ports extends AnyPorts> = Ports extends {
+  gate?: { bind: (ctx: never) => infer Bound };
+}
+  ? Bound
+  : BoundGate<readonly []>;
+
+/**
+ * Minimal gate shape used by `createTestContextFactory(...)`.
+ */
+type TestGatePort<BoundGateValue = BoundGate<readonly []>> = {
+  /**
+   * Bind the gate to a context.
+   */
+  bind: (ctx: never) => BoundGateValue;
+};
+
+/**
+ * Common app context fields built by `createTestContextFactory(...)`.
+ */
+export type TestContextFields<Ports extends AnyPorts> = {
+  /**
+   * Actor under test.
+   */
+  actor: ActivityActor;
+  /**
+   * Optional tenant under test.
+   */
+  tenant?: ActivityTenant;
+  /**
+   * Stable request ID.
+   */
+  requestId: string;
+  /**
+   * Stable trace ID.
+   */
+  traceId?: string;
+  /**
+   * Optional auth/session value.
+   */
+  auth?: unknown;
+  /**
+   * App ports under test.
+   */
+  ports: Ports;
+  /**
+   * Bound authorization gate when `ports.gate` is available.
+   */
+  gate?: TestBoundGateForPorts<Ports>;
+};
+
+/**
+ * Options for `createTestContextFactory(...)`.
+ */
+export interface CreateTestContextFactoryOptions<Ctx, Ports extends AnyPorts> {
+  /**
+   * Ports or a callback returning ports for each created context.
+   */
+  ports: Ports | (() => Ports);
+  /**
+   * Actor used by default.
+   *
+   * @default createTestUserActor()
+   */
+  actor?: ActivityActor;
+  /**
+   * Tenant used by default. Pass `null` to omit tenant context.
+   */
+  tenant?: ActivityTenant | null;
+  /**
+   * Request ID used by default.
+   */
+  requestId?: string;
+  /**
+   * Trace ID used by default.
+   */
+  traceId?: string;
+  /**
+   * Auth/session value added to the context.
+   */
+  auth?: unknown;
+  /**
+   * Additional app-specific context fields.
+   */
+  extra?: Partial<Ctx> | ((args: TestContextFields<Ports>) => Partial<Ctx>);
+}
+
+/**
+ * Per-call overrides for a test context factory.
+ */
+export type TestContextFactoryOverrides<Ctx, Ports extends AnyPorts> = Partial<
+  Pick<
+    CreateTestContextFactoryOptions<Ctx, Ports>,
+    "actor" | "tenant" | "requestId" | "traceId" | "auth" | "extra"
+  >
+> & {
+  /**
+   * Ports for this context call.
+   */
+  ports?: Ports;
+};
+
+/**
+ * Create a repeatable app context factory for use-case and route tests.
+ *
+ * The factory adds actor, tenant, request ID, trace ID, ports, and auth fields,
+ * and attaches a live `ctx.gate` automatically when `ports.gate` exposes
+ * `bind(...)`. The gate is attached after all `extra` and override fields are
+ * merged, so it always authorizes against the final context identity.
+ *
+ * @param options - Default context values.
+ * @returns A function that creates one app context.
+ */
+export function createTestContextFactory<
+  Ctx extends object,
+  Ports extends AnyPorts,
+>(
+  options: CreateTestContextFactoryOptions<Ctx, Ports>,
+): (overrides?: TestContextFactoryOverrides<Ctx, Ports>) => Ctx {
+  return (overrides = {}) => {
+    const ports = overrides.ports ?? resolvePorts(options.ports);
+    const activity = createTestActivityContext({
+      actor: overrides.actor ?? options.actor ?? createTestUserActor(),
+      tenant:
+        overrides.tenant !== undefined ? overrides.tenant : options.tenant,
+      requestId: overrides.requestId ?? options.requestId,
+      traceId: overrides.traceId ?? options.traceId,
+    });
+    const auth =
+      overrides.auth !== undefined ? overrides.auth : (options.auth ?? null);
+    const base = {
+      ...activity,
+      auth,
+      ports,
+    } as TestContextFields<Ports>;
+    const fields = attachTestGate(ports, base);
+    const extra = resolveExtra(options.extra, fields);
+    const overrideExtra = resolveExtra(overrides.extra, fields);
+    const merged = {
+      ...fields,
+      ...extra,
+      ...overrideExtra,
+    };
+
+    if (Object.hasOwn(merged, "gate")) {
+      return merged as Ctx;
+    }
+
+    return attachTestGate(ports, merged) as Ctx;
+  };
+}
+
+function resolvePorts<Ports extends AnyPorts>(
+  ports: Ports | (() => Ports),
+): Ports {
+  return typeof ports === "function" ? (ports as () => Ports)() : ports;
+}
+
+function resolveExtra<Ctx, Ports extends AnyPorts>(
+  extra:
+    | Partial<Ctx>
+    | ((args: TestContextFields<Ports>) => Partial<Ctx>)
+    | undefined,
+  fields: TestContextFields<Ports>,
+): Partial<Ctx> {
+  return typeof extra === "function" ? extra(fields) : (extra ?? {});
+}
+
+function attachTestGate<Ports extends AnyPorts, Ctx extends object>(
+  ports: Ports,
+  ctx: Ctx,
+): Ctx {
+  const maybeGate = (
+    ports as { gate?: TestGatePort<TestBoundGateForPorts<Ports>> }
+  ).gate;
+  if (!maybeGate) return ctx;
+
+  // Mirror GatePort.attach: a live, non-enumerable getter that re-binds
+  // against the receiver so in-place identity changes are never stale and
+  // spread copies drop the gate loudly.
+  Object.defineProperty(ctx, "gate", {
+    configurable: true,
+    enumerable: false,
+    get() {
+      return maybeGate.bind(this as never);
+    },
+  });
+
+  return ctx;
+}
+
+const disposeSymbol: typeof Symbol.dispose =
+  Symbol.dispose ?? (Symbol.for("Symbol.dispose") as typeof Symbol.dispose);
+
+/**
+ * Options for `createTestContext(...)`.
+ */
+export interface CreateTestContextOptions<Ctx, Ports extends AnyPorts> {
+  /**
+   * Actor under test.
+   *
+   * @default createTestSystemActor("test-system")
+   */
+  actor?: ActivityActor;
+  /**
+   * Tenant under test. Pass `null` to omit tenant context.
+   *
+   * @default createTestTenant()
+   */
+  tenant?: ActivityTenant | null;
+  /**
+   * Request ID exposed on the context.
+   *
+   * @default "test-request"
+   */
+  requestId?: string;
+  /**
+   * Trace ID exposed on the context.
+   *
+   * @default "test-trace"
+   */
+  traceId?: string;
+  /**
+   * Auth/session value added to the context.
+   *
+   * @default null
+   */
+  auth?: unknown;
+  /**
+   * App-owned default ports, usually imported from `infra/app-ports`. Common
+   * Beignet test defaults replace matching keys from `base`; use `ports` for
+   * app ports that should win.
+   */
+  base?: { [K in keyof Ports]?: unknown };
+  /**
+   * Typed partial port overrides that replace generated defaults or `base`.
+   */
+  ports?: TestPortsOverrides<Ports>;
+  /**
+   * Clock implementation. Defaults to a frozen clock at the Unix epoch.
+   */
+  clock?: ClockPort;
+  /**
+   * ID generator. Defaults to UUIDs.
+   */
+  ids?: IdGeneratorPort;
+  /**
+   * Unit of Work configuration. A no-op UOW is installed by default.
+   */
+  transaction?: CreateTestPortsTransactionOptions<Ports, unknown>;
+  /**
+   * Additional app-specific context fields. An explicit `gate` here wins over
+   * the kit-attached gate.
+   */
+  extra?: Partial<Ctx>;
+  /**
+   * Enter the ambient request context with the test actor, tenant, request
+   * ID, and trace ID so ambient enrichment (such as the default audit port)
+   * works like production. Call `dispose()` (or use `using`) to clear it.
+   *
+   * @default true
+   */
+  ambient?: boolean;
+}
+
+/**
+ * Test context fixture returned by `createTestContext(...)`.
+ */
+export interface TestContextFixture<Ctx, Ports extends AnyPorts>
+  extends TestPortsFixture<Ports, unknown> {
+  /**
+   * Assembled app context under test.
+   */
+  ctx: Ctx;
+  /**
+   * Clear the ambient request context entered by this fixture.
+   */
+  dispose(): void;
+  /**
+   * Explicit-resource-management alias for `dispose()`, so fixtures work with
+   * `using`.
+   */
+  [disposeSymbol](): void;
+}
+
+/**
+ * Create a one-call test context fixture for jobs, listeners, schedules,
+ * notifications, tasks, and use-case tests.
+ *
+ * The fixture builds common memory ports through `createTestPorts(...)`,
+ * assembles an app context with actor, tenant, request ID, trace ID, auth,
+ * and a live bound gate, and enters the ambient request context so ambient
+ * enrichment matches production. Reading an app port that is neither a kit
+ * default nor supplied throws a named error on use.
+ *
+ * @example
+ * ```ts
+ * const makeContext = createTestContext<AppContext>();
+ *
+ * using fixture = makeContext({
+ *   ports: { issues: { create: async (input) => issueRecord(input) } },
+ * });
+ * await runCreateIssue(fixture.ctx);
+ * ```
+ *
+ * @returns A factory that creates one disposable test context fixture.
+ */
+export function createTestContext<Ctx extends { ports: AnyPorts }>(): (
+  options?: CreateTestContextOptions<Ctx, Ctx["ports"]>,
+) => TestContextFixture<Ctx, Ctx["ports"]> {
+  return (options = {}) => {
+    const fixture = createTestPorts<Ctx["ports"], unknown>({
+      base: options.base,
+      overrides: options.ports,
+      clock: options.clock,
+      ids: options.ids,
+      transaction: options.transaction,
+    });
+    const ports = createUnboundPortGuard(fixture.ports);
+    const activity = createTestActivityContext({
+      actor: options.actor ?? createTestSystemActor("test-system"),
+      tenant: options.tenant,
+      requestId: options.requestId,
+      traceId: options.traceId,
+    });
+    const auth = options.auth !== undefined ? options.auth : null;
+    const base = {
+      ...activity,
+      auth,
+      ports,
+    } as TestContextFields<Ctx["ports"]>;
+    const fields = attachTestGate(ports, base);
+    const merged = {
+      ...fields,
+      ...(options.extra ?? {}),
+    };
+    const ctx = (Object.hasOwn(merged, "gate")
+      ? merged
+      : attachTestGate(ports, merged)) as unknown as Ctx;
+
+    const ambient = options.ambient ?? true;
+    if (ambient) {
+      enterActiveRequestContext({
+        requestId: activity.requestId,
+        traceId: activity.traceId,
+        actor: activity.actor,
+        tenant: activity.tenant,
+      });
+    }
+    let disposed = false;
+    const dispose = () => {
+      if (!ambient || disposed) return;
+      disposed = true;
+      clearActiveRequestContext();
+    };
+
+    return {
+      ...fixture,
+      ports,
+      ctx,
+      dispose,
+      [disposeSymbol]: dispose,
+    };
+  };
+}
+
+function createUnboundPortGuard<Ports extends AnyPorts>(ports: Ports): Ports {
+  return new Proxy(ports, {
+    get(target, key, receiver) {
+      if (
+        typeof key === "symbol" ||
+        key === "then" ||
+        key === "constructor" ||
+        key in target
+      ) {
+        return Reflect.get(target, key, receiver);
+      }
+
+      throw new Error(
+        `App port "${key}" is not bound in this test context. Pass it through createTestContext ports.`,
+      );
+    },
+  });
+}
+
+/**
+ * Options for `installProviderForTest(...)`.
+ */
+export interface InstallProviderForTestOptions {
+  /**
+   * Base app ports visible to provider setup, such as `{ devtools }`.
+   */
+  ports?: Record<string, unknown>;
+  /**
+   * Config passed to provider setup as-is. The provider config schema is not
+   * run, matching server startup where config is validated before setup.
+   */
+  config?: unknown;
+  /**
+   * Service-context factory passed to setup and lifecycle hooks. The default
+   * factory rejects, mirroring the late-bound runtime factory before all
+   * providers have started.
+   */
+  createServiceContext?: (input?: unknown) => Promise<unknown>;
+}
+
+/**
+ * Installed provider fixture returned by `installProviderForTest(...)`.
+ */
+export interface InstalledProviderFixture {
+  /**
+   * Base ports merged with the ports contributed by provider setup.
+   */
+  ports: Record<string, unknown>;
+  /**
+   * Raw provider setup result, exposed for assertions on contributed ports
+   * and optional lifecycle hooks.
+   */
+  result: ProviderSetupResult<Record<string, unknown>, Record<string, unknown>>;
+  /**
+   * Run the provider `start` hook when the provider declares one.
+   */
+  start(): Promise<void>;
+  /**
+   * Run the provider `stop` hook when the provider declares one.
+   */
+  stop(): Promise<void>;
+}
+
+/**
+ * Run provider setup against test ports and return the merged ports plus
+ * lifecycle runners.
+ *
+ * Use this in provider tests instead of hand-rolling the setup, port merge,
+ * and lifecycle plumbing around `provider.setup(...)`.
+ *
+ * @param provider - Provider under test.
+ * @param options - Base ports, raw config, and service-context factory.
+ * @returns Merged ports, the raw setup result, and start/stop runners.
+ */
+export async function installProviderForTest(
+  provider: AnyServiceProvider,
+  options: InstallProviderForTestOptions = {},
+): Promise<InstalledProviderFixture> {
+  const basePorts: Record<string, unknown> = { ...options.ports };
+  const createServiceContext =
+    options.createServiceContext ??
+    (async () => {
+      throw new Error(
+        `Provider "${provider.name}" called createServiceContext during a test install. ` +
+          "Pass createServiceContext to installProviderForTest(...) when the test needs a service context.",
+      );
+    });
+  const result = await provider.setup({
+    ports: basePorts,
+    config: options.config,
+    createServiceContext,
+  });
+  const ports: Record<string, unknown> = { ...basePorts, ...result.ports };
+  const lifecycleCtx = { ports, createServiceContext };
+
+  return {
+    ports,
+    result,
+    async start() {
+      await result.start?.(lifecycleCtx);
+    },
+    async stop() {
+      await result.stop?.(lifecycleCtx);
+    },
+  };
+}
+
 /**
  * Arguments passed to a factory default builder.
  */
@@ -50,7 +1026,7 @@ export type FactoryOverrides<
 /**
  * Options for declaring a test data factory.
  */
-export interface DefineFactoryOptions<
+export interface CreateFactoryOptions<
   Name extends string,
   Value extends object,
   Ctx = unknown,
@@ -175,6 +1151,96 @@ export interface RunSeedsOptions<Ctx> {
   seeds: readonly SeedDef<Ctx>[];
 }
 
+/**
+ * Options for creating a database test harness.
+ */
+export interface CreateDatabaseTestHarnessOptions<Database, Ctx> {
+  /**
+   * Create an isolated app-owned database fixture.
+   */
+  create(): MaybePromise<Database>;
+  /**
+   * Build the context passed to factories and seeds from the database fixture.
+   */
+  ctx(database: Database): Ctx;
+  /**
+   * Reset the database fixture, when supported by the app.
+   */
+  reset?(database: Database): MaybePromise<void>;
+  /**
+   * Close and dispose the database fixture.
+   */
+  close?(database: Database): MaybePromise<void>;
+  /**
+   * Factories whose sequences should reset before each setup and reset.
+   */
+  factories?: readonly Pick<FactoryDef, "resetSequence">[];
+  /**
+   * Default seeds available to `setup({ seed: true })` and `session.runSeeds()`.
+   */
+  seeds?: readonly SeedDef<Ctx>[];
+}
+
+/**
+ * Options for setting up one database test session.
+ */
+export interface DatabaseTestSetupOptions<Ctx> {
+  /**
+   * Run seeds after creating the database session.
+   *
+   * Pass `true` to use the harness default seeds, or pass an explicit seed
+   * list for this setup.
+   */
+  seed?: boolean | readonly SeedDef<Ctx>[];
+}
+
+/**
+ * Active database fixture created by `createDatabaseTestHarness(...)`.
+ */
+export interface DatabaseTestSession<Database, Ctx> {
+  /**
+   * App-owned database fixture returned by the harness `create` function.
+   */
+  readonly database: Database;
+  /**
+   * Context built from the database fixture for factories and seeds.
+   */
+  readonly ctx: Ctx;
+  /**
+   * Run the default harness seeds or an explicit seed list.
+   */
+  runSeeds(seeds?: readonly SeedDef<Ctx>[]): Promise<void>;
+  /**
+   * Reset factory sequences and the database fixture.
+   */
+  reset(): Promise<void>;
+  /**
+   * Close and dispose this session.
+   */
+  close(): Promise<void>;
+}
+
+/**
+ * Database test harness that coordinates app-owned database fixtures with
+ * Beignet factories and seeds.
+ */
+export interface DatabaseTestHarness<Database, Ctx> {
+  /**
+   * Create one isolated database test session.
+   */
+  setup(
+    options?: DatabaseTestSetupOptions<Ctx>,
+  ): Promise<DatabaseTestSession<Database, Ctx>>;
+  /**
+   * Reset all configured factory sequences.
+   */
+  resetFactories(): void;
+  /**
+   * Close all sessions that have not already been closed.
+   */
+  cleanup(): Promise<void>;
+}
+
 /**
  * Error thrown when a seed fails.
  */
@@ -243,16 +1309,16 @@ function assertCount(kind: "buildList" | "createList", count: number): void {
 }
 
 /**
- * Define a typed test data factory with deterministic sequence support.
+ * Create a typed test data factory with deterministic sequence support.
  */
-export function defineFactory<
+export function createFactory<
   const Name extends string,
   Value extends object,
   Ctx = unknown,
   Created = Value,
 >(
   name: Name,
-  options: DefineFactoryOptions<Name, Value, Ctx, Created>,
+  options: CreateFactoryOptions<Name, Value, Ctx, Created>,
 ): FactoryDef<Name, Value, Ctx, Created> {
   const start = options.start ?? 1;
   const ids = options.ids ?? createUuidIdGenerator();
@@ -346,3 +1412,73 @@ export async function runSeeds<Ctx>(
     }
   }
 }
+
+/**
+ * Create a database test harness for app-owned database fixtures.
+ *
+ * The harness does not know about an ORM or database provider. Apps provide
+ * creation, reset, close, and context mapping functions, while Beignet handles
+ * the repetitive test lifecycle around factory sequences and seed execution.
+ */
+export function createDatabaseTestHarness<Database, Ctx>(
+  options: CreateDatabaseTestHarnessOptions<Database, Ctx>,
+): DatabaseTestHarness<Database, Ctx> {
+  const sessions = new Set<DatabaseTestSession<Database, Ctx>>();
+
+  function resetFactorySequences(): void {
+    resetFactories(...(options.factories ?? []));
+  }
+
+  function defaultSeeds(): readonly SeedDef<Ctx>[] {
+    return options.seeds ?? [];
+  }
+
+  async function closeSession(
+    session: DatabaseTestSession<Database, Ctx>,
+  ): Promise<void> {
+    if (!sessions.delete(session)) return;
+    await options.close?.(session.database);
+  }
+
+  return {
+    async setup(setupOptions = {}) {
+      resetFactorySequences();
+
+      const database = await options.create();
+      const ctx = options.ctx(database);
+      const session: DatabaseTestSession<Database, Ctx> = {
+        database,
+        ctx,
+        async runSeeds(seeds = defaultSeeds()) {
+          await runSeeds({ ctx, seeds });
+        },
+        async reset() {
+          resetFactorySequences();
+          await options.reset?.(database);
+        },
+        async close() {
+          await closeSession(session);
+        },
+      };
+
+      sessions.add(session);
+
+      try {
+        if (setupOptions.seed) {
+          const seeds =
+            setupOptions.seed === true ? defaultSeeds() : setupOptions.seed;
+          await session.runSeeds(seeds);
+        }
+      } catch (error) {
+        await session.close();
+        throw error;
+      }
+
+      return session;
+    },
+    resetFactories: resetFactorySequences,
+    async cleanup() {
+      await Promise.all(Array.from(sessions, (session) => session.close()));
+    },
+  };
+}