@nifrajs/testing 3.5.0 → 4.0.2

package/src/data-conformance.ts

@@ -0,0 +1,297 @@
+/**
+ * Behavioral conformance checks for durable data adapters.
+ *
+ * The framework does not own a SQL dialect or a tenant model. This harness therefore accepts a
+ * small adapter-specific operation map and verifies the guarantees that are portable across
+ * Postgres, SQLite, D1, Durable Objects, and other implementations.
+ */
+
+export interface DataConformanceScope {
+  readonly token: string
+}
+
+export interface DataConformancePage<Row, Cursor = string> {
+  readonly items: readonly Row[]
+  readonly cursor?: Cursor
+}
+
+export interface DataConformanceTransaction<Row> {
+  write(row: Row): Promise<void>
+}
+
+export interface DataAdapterConformanceTarget<Adapter, Row, Snapshot, Cursor = string> {
+  /** Return a fresh adapter handle. Two handles must observe shared durable state. */
+  readonly createAdapter: (instance: string) => Adapter | Promise<Adapter>
+  /** Insert a fixture row under the adapter's tenant/RLS boundary. */
+  readonly seed: (adapter: Adapter, scope: DataConformanceScope, row: Row) => Promise<void>
+  /** Read rows visible to one scope. */
+  readonly read: (adapter: Adapter, scope: DataConformanceScope) => Promise<readonly Row[]>
+  /** Perform one cancellable write. */
+  readonly write: (
+    adapter: Adapter,
+    scope: DataConformanceScope,
+    row: Row,
+    signal: AbortSignal,
+  ) => Promise<void>
+  /** Execute writes atomically; a rejected callback must roll back all writes. */
+  readonly transaction: <T>(
+    adapter: Adapter,
+    scope: DataConformanceScope,
+    run: (transaction: DataConformanceTransaction<Row>) => Promise<T>,
+  ) => Promise<T>
+  /** Return one cursor page. The cursor is adapter-owned and must be treated as opaque. */
+  readonly page: (
+    adapter: Adapter,
+    scope: DataConformanceScope,
+    cursor?: Cursor,
+  ) => Promise<DataConformancePage<Row, Cursor>>
+  /** Capture and restore a durable snapshot for backup/restore testing. */
+  readonly snapshot: (adapter: Adapter) => Promise<Snapshot>
+  readonly restore: (adapter: Adapter, snapshot: Snapshot) => Promise<void>
+  /** Stable row identity used to detect cross-tenant leaks and pagination duplicates. */
+  readonly rowKey: (row: Row) => string
+  /** Optional cleanup for an adapter handle. */
+  readonly close?: (adapter: Adapter) => Promise<void>
+}
+
+export type DataConformanceCheck =
+  | "rls-isolation"
+  | "transaction-rollback"
+  | "cancellation"
+  | "pagination"
+  | "backup-restore"
+  | "multi-instance"
+
+export interface DataConformanceFailure {
+  readonly check: DataConformanceCheck
+  readonly message: string
+}
+
+export interface DataAdapterConformanceReport {
+  readonly ok: boolean
+  readonly checks: Readonly<Record<DataConformanceCheck, "pass" | "fail">>
+  readonly failures: readonly DataConformanceFailure[]
+}
+
+export class DataAdapterConformanceError extends Error {
+  readonly report: DataAdapterConformanceReport
+
+  constructor(report: DataAdapterConformanceReport) {
+    super(
+      `data adapter conformance failed: ${report.failures
+        .map((failure) => `${failure.check}: ${failure.message}`)
+        .join("; ")}`,
+    )
+    this.name = "DataAdapterConformanceError"
+    this.report = report
+  }
+}
+
+const CHECKS: readonly DataConformanceCheck[] = [
+  "rls-isolation",
+  "transaction-rollback",
+  "cancellation",
+  "pagination",
+  "backup-restore",
+  "multi-instance",
+]
+
+const defaultScopes = Object.freeze({
+  left: Object.freeze({ token: "nifra-conformance/tenant-left" }),
+  right: Object.freeze({ token: "nifra-conformance/tenant-right" }),
+})
+
+const defaultRows = Object.freeze({
+  left: Object.freeze({ id: "left" }),
+  right: Object.freeze({ id: "right" }),
+  rollback: Object.freeze({ id: "rollback" }),
+  shared: Object.freeze({ id: "shared" }),
+})
+
+function isAbortLike(error: unknown): boolean {
+  return (
+    (typeof DOMException !== "undefined" &&
+      error instanceof DOMException &&
+      error.name === "AbortError") ||
+    (error instanceof Error && /abort|cancel/i.test(`${error.name} ${error.message}`))
+  )
+}
+
+async function closeAll<Adapter>(
+  target: DataAdapterConformanceTarget<Adapter, unknown, unknown, unknown>,
+  adapters: readonly Adapter[],
+): Promise<void> {
+  if (target.close === undefined) return
+  await Promise.all(adapters.map((adapter) => target.close!(adapter)))
+}
+
+/**
+ * Run the portable data-adapter contract and return machine-readable evidence.
+ *
+ * The harness intentionally uses fresh handles and opaque scope tokens. It does not inspect SQL,
+ * tenant columns, transaction objects, provider errors, or credentials.
+ */
+export async function runDataAdapterConformance<Adapter, Row, Snapshot, Cursor = string>(
+  target: DataAdapterConformanceTarget<Adapter, Row, Snapshot, Cursor>,
+  options: {
+    readonly scopes?: { readonly left: DataConformanceScope; readonly right: DataConformanceScope }
+    readonly rows?: {
+      readonly left: Row
+      readonly right: Row
+      readonly rollback: Row
+      readonly shared: Row
+    }
+  } = {},
+): Promise<DataAdapterConformanceReport> {
+  const scopes = options.scopes ?? defaultScopes
+  const rows =
+    options.rows ??
+    (defaultRows as unknown as {
+      readonly left: Row
+      readonly right: Row
+      readonly rollback: Row
+      readonly shared: Row
+    })
+  const adapters: Adapter[] = []
+  const failures: DataConformanceFailure[] = []
+  const checks: Record<DataConformanceCheck, "pass" | "fail"> = {
+    "rls-isolation": "fail",
+    "transaction-rollback": "fail",
+    cancellation: "fail",
+    pagination: "fail",
+    "backup-restore": "fail",
+    "multi-instance": "fail",
+  }
+
+  const run = async (check: DataConformanceCheck, action: () => Promise<void>): Promise<void> => {
+    try {
+      await action()
+      checks[check] = "pass"
+    } catch {
+      failures.push({
+        check,
+        // Provider errors can contain credentials, SQL, tenant identifiers, or request values.
+        // The portable report is safe to serialize and log, so retain only the stable check name.
+        message: `${check} conformance check failed`,
+      })
+    }
+  }
+
+  try {
+    const primary = await target.createAdapter("primary")
+    const secondary = await target.createAdapter("secondary")
+    adapters.push(primary, secondary)
+
+    await run("rls-isolation", async () => {
+      await target.seed(primary, scopes.left, rows.left)
+      await target.seed(primary, scopes.right, rows.right)
+      const left = await target.read(primary, scopes.left)
+      const right = await target.read(primary, scopes.right)
+      const leftKeys = new Set(left.map(target.rowKey))
+      const rightKeys = new Set(right.map(target.rowKey))
+      if (!leftKeys.has(target.rowKey(rows.left)) || leftKeys.has(target.rowKey(rows.right))) {
+        throw new Error("left scope can read another scope's row")
+      }
+      if (!rightKeys.has(target.rowKey(rows.right)) || rightKeys.has(target.rowKey(rows.left))) {
+        throw new Error("right scope can read another scope's row")
+      }
+    })
+
+    await run("transaction-rollback", async () => {
+      const before = new Set((await target.read(primary, scopes.left)).map(target.rowKey))
+      let rejectedCallback = false
+      try {
+        await target.transaction(primary, scopes.left, async (transaction) => {
+          await transaction.write(rows.rollback)
+          throw new Error("conformance rollback")
+        })
+      } catch {
+        rejectedCallback = true
+      }
+      if (!rejectedCallback) throw new Error("transaction accepted a rejected callback")
+      const after = new Set((await target.read(primary, scopes.left)).map(target.rowKey))
+      if (after.has(target.rowKey(rows.rollback)) || [...after].some((key) => !before.has(key))) {
+        throw new Error("rejected transaction changed durable state")
+      }
+    })
+
+    await run("cancellation", async () => {
+      const controller = new AbortController()
+      controller.abort()
+      try {
+        await target.write(primary, scopes.left, rows.rollback, controller.signal)
+      } catch (error) {
+        if (isAbortLike(error) || controller.signal.aborted) return
+        throw error
+      }
+      throw new Error("cancelled write resolved successfully")
+    })
+
+    await run("pagination", async () => {
+      const seen: string[] = []
+      const cursors = new Set<string>()
+      let cursor: Cursor | undefined
+      for (let pageNumber = 0; pageNumber < 100; pageNumber++) {
+        const page = await target.page(primary, scopes.left, cursor)
+        seen.push(...page.items.map(target.rowKey))
+        if (page.cursor === undefined) break
+        const next = String(page.cursor)
+        if (cursors.has(next)) throw new Error("pagination cursor repeated")
+        cursors.add(next)
+        cursor = page.cursor
+        if (pageNumber === 99) throw new Error("pagination did not terminate")
+      }
+      if (new Set(seen).size !== seen.length) throw new Error("pagination returned a duplicate row")
+    })
+
+    await run("backup-restore", async () => {
+      const snapshot = await target.snapshot(primary)
+      await target.seed(primary, scopes.left, rows.rollback)
+      await target.restore(primary, snapshot)
+      const restored = new Set((await target.read(primary, scopes.left)).map(target.rowKey))
+      if (restored.has(target.rowKey(rows.rollback))) {
+        throw new Error("restore did not remove post-backup data")
+      }
+    })
+
+    await run("multi-instance", async () => {
+      await target.seed(primary, scopes.left, rows.shared)
+      const visible = new Set((await target.read(secondary, scopes.left)).map(target.rowKey))
+      if (!visible.has(target.rowKey(rows.shared))) {
+        throw new Error("a second adapter instance cannot observe committed durable state")
+      }
+    })
+  } catch {
+    failures.push({
+      check: "multi-instance",
+      message: "multi-instance conformance check failed",
+    })
+  } finally {
+    try {
+      await closeAll(
+        target as unknown as DataAdapterConformanceTarget<Adapter, unknown, unknown, unknown>,
+        adapters,
+      )
+    } catch {
+      failures.push({ check: "multi-instance", message: "adapter cleanup failed" })
+    }
+  }
+
+  const failed = new Set(failures.map((failure) => failure.check))
+  for (const check of CHECKS) {
+    if (failed.has(check)) checks[check] = "fail"
+  }
+  return Object.freeze({
+    ok: failures.length === 0,
+    checks: Object.freeze({ ...checks }),
+    failures: Object.freeze([...failures]),
+  })
+}
+
+export async function assertDataAdapterConformance<Adapter, Row, Snapshot, Cursor = string>(
+  target: DataAdapterConformanceTarget<Adapter, Row, Snapshot, Cursor>,
+  options: Parameters<typeof runDataAdapterConformance<Adapter, Row, Snapshot, Cursor>>[1] = {},
+): Promise<void> {
+  const report = await runDataAdapterConformance(target, options)
+  if (!report.ok) throw new DataAdapterConformanceError(report)
+}

package/src/e2e.ts

@@ -0,0 +1,112 @@
+/**
+ * Browser-test glue: an ephemeral server plus typed URLs plus the session handoff - everything
+ * nifra-specific about driving a real browser, and nothing else. This is deliberately NOT a test
+ * runner (bring Playwright or Vitest Browser for the browser itself): API flows already run faster
+ * in-process through {@link testSession}, so this module covers only what in-process cannot - a
+ * real socket, real navigation, real rendering.
+ *
+ * ```ts
+ * import { chromium } from "@playwright/test"
+ * import { e2eUrl, serveTestApp } from "@nifrajs/testing/e2e"
+ * import { testSession } from "@nifrajs/testing"
+ * import { app } from "../src/app"
+ *
+ * const { cookies } = testSession<typeof app>(app)
+ * await api.auth.login.post(credentials) // in-process login; jar captures the session
+ *
+ * const www = await serveTestApp(app)
+ * const browser = await chromium.launch()
+ * const page = await browser.newPage({
+ *   extraHTTPHeaders: { Cookie: cookies.header() }, // the session crosses into the browser
+ * })
+ * await page.goto(e2eUrl<typeof app>(www.baseUrl, "/dashboard")) // typo'd path won't compile
+ * await www.stop()
+ * ```
+ */
+import type { Server } from "@nifrajs/core/server"
+import { isSameOriginPath } from "@nifrajs/core/server"
+import type { NodeServer, ServeOptions } from "@nifrajs/node"
+
+/** The minimal shape a nifra `server()` app satisfies - its own `fetch`. */
+export interface E2EApp {
+  fetch(request: Request): Response | Promise<Response>
+}
+
+/** Every route path the app declares - constrains `e2eUrl`, so a wrong path is a type error. */
+export type E2EPaths<App> = App extends Server<infer R, infer _Ctx> ? keyof R & string : never
+
+export interface ServeTestAppOptions {
+  /** Port to bind. Default `0` (ephemeral - read the real one off {@link ServedTestApp.baseUrl}). */
+  readonly port?: number
+  /** Interface to bind. Default `"127.0.0.1"`. */
+  readonly hostname?: string
+}
+
+export interface ServedTestApp {
+  /** Origin serving the app, e.g. `"http://127.0.0.1:43127"`. Hand it to {@link e2eUrl}. */
+  readonly baseUrl: string
+  /** Stop accepting connections and drain in-flight requests. Idempotent. */
+  readonly stop: () => Promise<void>
+}
+
+/**
+ * Serve an app on an ephemeral port for one browser test. The server is `@nifrajs/node`
+ * (an optional peer - install it in devDependencies); when it is absent this throws a plain
+ * error naming the missing package instead of a module-resolution crash.
+ */
+export async function serveTestApp(
+  app: E2EApp,
+  options: ServeTestAppOptions = {},
+): Promise<ServedTestApp> {
+  let serve: (app: E2EApp, options: ServeOptions) => Promise<NodeServer>
+  try {
+    ;({ serve } = await import("@nifrajs/node"))
+  } catch {
+    throw new Error(
+      "@nifrajs/testing/e2e: serveTestApp needs the @nifrajs/node package - add it to devDependencies",
+    )
+  }
+  const hostname = options.hostname ?? "127.0.0.1"
+  const running = await serve(app, { port: options.port ?? 0, hostname })
+  return {
+    baseUrl: `http://${hostname}:${running.port}`,
+    stop: () => running.stop(),
+  }
+}
+
+/** `path` on the test app's origin, refused unless it is a same-origin absolute path. */
+function onTestAppOrigin(baseUrl: string, path: string, label: string): URL {
+  const base = new URL(baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`)
+  const resolved = new URL(path, base)
+  // The origin compare also holds if the path rule ever admits a form the URL parser re-reads.
+  if (!isSameOriginPath(path) || resolved.origin !== base.origin) {
+    throw new TypeError(`@nifrajs/testing/e2e: ${label} must be a same-origin absolute path`)
+  }
+  return resolved
+}
+
+/**
+ * Join `baseUrl` and a declared route path. The path is checked against the app's registry, so
+ * `page.goto(e2eUrl<typeof app>(www.baseUrl, "/dashbord"))` fails typecheck instead of 404ing
+ * mid-suite - the same guarantee `formFor` gives form fields.
+ */
+export function e2eUrl<App>(baseUrl: string, path: E2EPaths<App>): string {
+  return onTestAppOrigin(baseUrl, path, "path").href
+}
+
+const WEB_SOCKET_BASES: ReadonlySet<string> = new Set(["http:", "https:", "ws:", "wss:"])
+
+/**
+ * Build a real WebSocket URL for an adapter-backed test server. The path uses the same-origin guard as
+ * {@link e2eUrl}; `http`/`https` are translated to `ws`/`wss` so callers cannot accidentally dial an
+ * HTTP URL with a WebSocket client or escape the test server origin.
+ */
+export function e2eWebSocket<App>(baseUrl: string, path: E2EPaths<App>): string {
+  const resolved = onTestAppOrigin(baseUrl, path, "WebSocket path")
+  if (!WEB_SOCKET_BASES.has(resolved.protocol)) {
+    throw new TypeError("@nifrajs/testing/e2e: unsupported WebSocket base URL protocol")
+  }
+  resolved.protocol =
+    resolved.protocol === "https:" || resolved.protocol === "wss:" ? "wss:" : "ws:"
+  return resolved.href
+}

package/src/index.ts

@@ -14,10 +14,12 @@ export {
   type AdversarialContractReport,
   type AdversarialContractResult,
   assertAdversarialContract,
+  type ContractAuthContext,
   type ContractCaseContext,
   type ContractCaseKind,
   type ContractCoverageGap,
   type ContractCoverageGapCode,
+  type ContractExpectedResponse,
   type ContractReplay,
   type ContractRuntime,
   type ContractTarget,
@@ -105,6 +107,18 @@ export {
   runContractLabThroughAdapter,
 } from "./contract-lab.ts"
 export { type CookieJar, cookieJar } from "./cookies.ts"
+export {
+  assertDataAdapterConformance,
+  DataAdapterConformanceError,
+  type DataAdapterConformanceReport,
+  type DataAdapterConformanceTarget,
+  type DataConformanceCheck,
+  type DataConformanceFailure,
+  type DataConformancePage,
+  type DataConformanceScope,
+  type DataConformanceTransaction,
+  runDataAdapterConformance,
+} from "./data-conformance.ts"
 export {
   createFailureLab,
   type FailureDirective,