@zerotal/testing 1.0.0

package/src/index.ts

@@ -0,0 +1,30 @@
+export { createTestApp, TestApp } from "./TestApp.ts";
+export type { TestFileInput, TestFormValue } from "./TestApp.ts";
+export { TestResponse } from "./TestResponse.ts";
+export type { SessionDecoder, TestResponseContext, InertiaPage } from "./TestResponse.ts";
+export { withDatabase } from "./withDatabase.ts";
+export { refreshDatabase } from "./refreshDatabase.ts";
+export type { RefreshDatabaseOptions } from "./refreshDatabase.ts";
+export { migrateDatabase } from "./migrateDatabase.ts";
+export type { MigrateDatabaseOptions } from "./migrateDatabase.ts";
+export { resetTestState } from "./resetTestState.ts";
+export { assertDatabaseHas, assertDatabaseMissing, assertDatabaseCount } from "./assertions.ts";
+export { assertStoredFile, assertMissingFile } from "./storageAssertions.ts";
+export { Factory, FactoryBatch } from "./factory.ts";
+export type { FactoryPayload } from "./factory.ts";
+export { fake } from "./fake.ts";
+export { fakeFile } from "./fakeFile.ts";
+export type { FakeFile } from "./fakeFile.ts";
+
+// Testing fakes. Each one lives with the subsystem it stands in for; the ones
+// whose package this already depends on are re-exported here so a test does not
+// have to know which package a given fake ships in. The two that would pull a
+// new dependency in are reached through their own facades instead:
+// `Broadcast.fake()` from @zerotal/broadcasting and `Social.fake()` from
+// @zerotal/auth.
+export { EventFake } from "@zerotal/core";
+export { Http } from "@zerotal/core/http";
+export { QueueFake } from "@zerotal/queue";
+export { NotificationFake } from "@zerotal/notifications";
+export { FakeDisk } from "@zerotal/core/storage";
+export type { FakeStoredFile } from "@zerotal/core/storage";

package/src/migrateDatabase.ts

@@ -0,0 +1,66 @@
+import {
+  MigrationRunner,
+  currentOrmContext,
+  _getModelConnection,
+  _setBaseModelConnection,
+  _setDbConnection,
+  _getDbConnectionOverride,
+  type SQLInstance,
+} from "@zerotal/orm";
+
+export interface MigrateDatabaseOptions {
+  /**
+   * Connection to migrate. Defaults to the active model connection, which is
+   * what `createTestApp()` and `refreshDatabase({ connection })` install.
+   */
+  connection?: SQLInstance;
+  /** Directory holding the migration files. Defaults to `database/migrations`. */
+  path?: string;
+  /** Tracking-table name. Defaults to `migrations`. */
+  table?: string;
+}
+
+/**
+ * Build a test database's schema by running the project's real migrations.
+ *
+ * A test schema written by hand is a second definition of the same tables, and
+ * the two drift: a column added in a migration is missing in the tests until
+ * something fails for a reason that has nothing to do with the change. Running
+ * the migrations themselves means the schema under test is the schema that
+ * ships.
+ *
+ * @returns The names of the migrations that ran.
+ *
+ * @example
+ * describe('Post', () => {
+ *   refreshDatabase({ connection: db, migrate: true });
+ *   // …every test now sees the real schema, and rolls back after itself
+ * });
+ *
+ * @example
+ * // Standalone, outside refreshDatabase
+ * beforeAll(() => migrateDatabase({ connection: db }));
+ */
+export async function migrateDatabase(options: MigrateDatabaseOptions = {}): Promise<string[]> {
+  const { path = "database/migrations", table } = options;
+  const connection = options.connection ?? _getModelConnection();
+
+  // A migration's `up()` reaches for the ambient connection through `Schema`,
+  // not through the runner, so the connection has to be installed in both slots
+  // for the DDL to land on the database the test is actually using.
+  // Both slots are restored to exactly what they held, override and all — a
+  // helper that leaves a connection pinned behind it would silently detach the
+  // next test from whatever the container resolves.
+  const previousDb = _getDbConnectionOverride();
+  const previousModel = currentOrmContext().overrideConnection;
+
+  _setDbConnection(connection);
+  _setBaseModelConnection(connection);
+  try {
+    const runner = new MigrationRunner({ connection, ...(table ? { table } : {}) });
+    return await runner.runFromDirectory(path);
+  } finally {
+    _setDbConnection(previousDb);
+    _setBaseModelConnection(previousModel);
+  }
+}

package/src/preload.ts

@@ -0,0 +1,33 @@
+/**
+ * @zerotal/testing/preload — auto-wires the DB connection for every test worker.
+ *
+ * Loaded via `bun test --preload @zerotal/testing/preload` when you run
+ * `bun zt test`. Reads ZT_DB_URL from the environment (set by
+ * TestCommand) and calls _setBaseModelConnection + _setDbConnection so that
+ * withDatabase() and DB.table() work without any manual beforeAll setup.
+ *
+ * Each Bun test worker runs its own copy of this module, so connections are
+ * isolated per file — no cross-file leakage.
+ */
+
+import { SQL } from "bun";
+import { _setBaseModelConnection, _setBaseModelDialect, _setDbConnection } from "@zerotal/orm";
+
+const url = Bun.env["ZT_DB_URL"];
+
+if (url && url !== ":memory:") {
+  const db = new SQL(url);
+
+  _setBaseModelConnection(db);
+  _setDbConnection(db);
+
+  if (url.startsWith("mysql://") || url.startsWith("mysql2://")) {
+    _setBaseModelDialect("mysql");
+  } else if (url.startsWith("postgres://") || url.startsWith("postgresql://")) {
+    _setBaseModelDialect("postgres");
+  }
+  // else: sqlite (default)
+}
+// When ZT_DB_URL is ':memory:', we leave the connections unset so each test
+// can create its own in-process SQLite via createTestApp() or withDatabase().
+// Bun's global `sql` fallback (which reads DATABASE_URL) is also still active.

package/src/refreshDatabase.ts

@@ -0,0 +1,115 @@
+import { _getModelConnection, _setBaseModelConnection, type SQLInstance } from "@zerotal/orm";
+import { migrateDatabase } from "./migrateDatabase.ts";
+
+interface TestHooks {
+  beforeAll(fn: () => void | Promise<void>): void;
+  afterAll(fn: () => void | Promise<void>): void;
+  beforeEach(fn: () => void | Promise<void>): void;
+  afterEach(fn: () => void | Promise<void>): void;
+}
+
+function _hooks(): TestHooks {
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    return require("bun:test") as TestHooks;
+  } catch {
+    throw new Error("[Zerotal] refreshDatabase() can only be used inside a `bun test` run.");
+  }
+}
+
+export interface RefreshDatabaseOptions {
+  connection?: SQLInstance;
+  /**
+   * Build the schema by running the project's migrations before the suite.
+   * `true` uses `database/migrations`; pass a string for a different directory.
+   *
+   * Prefer this over hand-written DDL in `setup` — see {@link migrateDatabase}.
+   */
+  migrate?: boolean | string;
+  setup?: (db: SQLInstance) => void | Promise<void>;
+  teardown?: (db: SQLInstance) => void | Promise<void>;
+}
+
+export function refreshDatabase(options: RefreshDatabaseOptions = {}): void {
+  const { beforeAll, afterAll, beforeEach, afterEach } = _hooks();
+
+  let releaseGate: (() => void) | null = null;
+  let txDone: Promise<void> | null = null;
+  let prevConn: SQLInstance | null = null;
+  let installedConn = false;
+
+  beforeAll(async () => {
+    if (options.connection) {
+      _setBaseModelConnection(options.connection);
+      installedConn = true;
+    }
+    if (options.migrate) {
+      await migrateDatabase({
+        connection: _getModelConnection(),
+        ...(typeof options.migrate === "string" ? { path: options.migrate } : {}),
+      });
+    }
+    if (options.setup) {
+      await options.setup(_getModelConnection());
+    }
+  });
+
+  afterAll(async () => {
+    if (options.teardown) {
+      await options.teardown(_getModelConnection());
+    }
+    if (installedConn) {
+      _setBaseModelConnection(null);
+      installedConn = false;
+    }
+  });
+
+  beforeEach(async () => {
+    prevConn = _getModelConnection();
+    const conn = prevConn as unknown as {
+      begin<T>(cb: (tx: unknown) => Promise<T>): Promise<T>;
+    };
+
+    const ROLLBACK = Symbol("zerotal.test.rollback");
+    let openGate!: () => void;
+    const gate = new Promise<void>((r) => {
+      openGate = r;
+    });
+    let markReady!: () => void;
+    const ready = new Promise<void>((r) => {
+      markReady = r;
+    });
+    let txConn!: SQLInstance;
+
+    txDone = conn
+      .begin(async (tx) => {
+        txConn = tx as SQLInstance;
+        markReady();
+        await gate;
+        throw ROLLBACK;
+      })
+      .then(
+        () => undefined,
+        (e: unknown) => {
+          if (e !== ROLLBACK) throw e;
+        },
+      );
+
+    await ready;
+    _setBaseModelConnection(txConn);
+    releaseGate = openGate;
+  });
+
+  afterEach(async () => {
+    if (releaseGate) {
+      releaseGate();
+      releaseGate = null;
+    }
+    if (txDone) {
+      await txDone;
+      txDone = null;
+    }
+    _setBaseModelConnection(prevConn);
+    prevConn = null;
+  });
+}

package/src/resetTestState.ts

@@ -0,0 +1,12 @@
+import { Application, Router, FrameworkEvents } from "@zerotal/core";
+import { resetOrmContext } from "@zerotal/orm";
+
+export function resetTestState(): void {
+  Application._resetInstance();
+  Router.reset();
+  resetOrmContext();
+  // Clear framework instrumentation subscriptions so handlers registered by one
+  // suite (e.g. devtools tracing) don't leak into the next. Providers re-subscribe
+  // on boot.
+  FrameworkEvents.clear();
+}

package/src/storageAssertions.ts

@@ -0,0 +1,52 @@
+import { Storage } from "@zerotal/core/storage";
+import type { StorageDriver } from "@zerotal/core/storage";
+
+function _resolveDriver(diskOrDriver: string | StorageDriver): StorageDriver {
+  return typeof diskOrDriver === "string" ? Storage.disk(diskOrDriver) : diskOrDriver;
+}
+
+/**
+ * Assert that a file exists on the given storage disk or driver.
+ *
+ * Pass a disk name (string) to use the `Storage` facade (requires StorageProvider
+ * to be registered), or pass a `StorageDriver` instance for isolated unit tests.
+ *
+ * @example
+ * // Integration test — disk name:
+ * await assertStoredFile('local', 'avatars/42.jpg');
+ *
+ * // Unit test — driver instance:
+ * await assertStoredFile(new LocalDriver('./tmp', '/'), 'report.pdf');
+ */
+export async function assertStoredFile(
+  diskOrDriver: string | StorageDriver,
+  path: string,
+): Promise<void> {
+  const exists = await _resolveDriver(diskOrDriver).exists(path);
+  if (!exists) {
+    const label = typeof diskOrDriver === "string" ? `disk "${diskOrDriver}"` : "driver";
+    throw new Error(
+      `assertStoredFile: expected file "${path}" to exist on ${label}, but it was not found.`,
+    );
+  }
+}
+
+/**
+ * Assert that a file does NOT exist on the given storage disk or driver.
+ *
+ * @example
+ * await assertMissingFile('local', 'tmp/deleted.txt');
+ * await assertMissingFile(driver, 'should-be-gone.txt');
+ */
+export async function assertMissingFile(
+  diskOrDriver: string | StorageDriver,
+  path: string,
+): Promise<void> {
+  const exists = await _resolveDriver(diskOrDriver).exists(path);
+  if (exists) {
+    const label = typeof diskOrDriver === "string" ? `disk "${diskOrDriver}"` : "driver";
+    throw new Error(
+      `assertMissingFile: expected file "${path}" NOT to exist on ${label}, but it was found.`,
+    );
+  }
+}

package/src/withDatabase.ts

@@ -0,0 +1,52 @@
+import { _getModelConnection, _setBaseModelConnection, type SQLInstance } from "@zerotal/orm";
+
+/**
+ * Wrap a test function in a database transaction that always rolls back.
+ * Every query inside the callback uses the transaction, so changes are
+ * invisible to other connections and never reach the actual database.
+ *
+ * Use with bun:test's `it()`:
+ *
+ * @example
+ * it('creates a user', withDatabase(async () => {
+ *   const user = await User.create({ name: 'Alice', email: 'alice@example.com' });
+ *   expect(user.id).toBeDefined();
+ *   await assertDatabaseHas('users', { email: 'alice@example.com' });
+ *   // Rolls back after this function returns — no cleanup needed.
+ * }));
+ */
+export function withDatabase(fn: () => Promise<void>): () => Promise<void> {
+  return async (): Promise<void> => {
+    const conn = _getModelConnection() as unknown as {
+      begin<T>(fn: (tx: unknown) => Promise<T>): Promise<T>;
+    };
+
+    let testError: unknown;
+    let testFailed = false;
+
+    // Capture the pre-test connection so we can restore it after the transaction.
+    const prevConn = _getModelConnection();
+
+    await conn
+      .begin(async (tx) => {
+        _setBaseModelConnection(tx as SQLInstance);
+        try {
+          await fn();
+        } catch (e) {
+          testError = e;
+          testFailed = true;
+        } finally {
+          // Restore to whatever was active before (usually the test DB), not null.
+          _setBaseModelConnection(prevConn);
+        }
+        // Always rollback by throwing a sentinel — caught below.
+        throw new Error("__ZT_TEST_ROLLBACK__");
+      })
+      .catch((e: unknown) => {
+        if ((e as Error | null)?.message !== "__ZT_TEST_ROLLBACK__") throw e;
+      });
+
+    // Re-throw any error that came from the test body itself.
+    if (testFailed) throw testError;
+  };
+}