@c9up/atlas 0.2.0 → 0.2.1

package/src/testing/DatabaseCleanup.ts

@@ -5,20 +5,51 @@
  */
 
 import type { AsyncDatabaseConnection } from "../adapters/NapiDbAdapter.js";
+import { AtlasError } from "../errors.js";
 import { compileStatementNative } from "../query/native.js";
-import { listUserTables, withoutForeignKeys } from "../schema/catalog.js";
+import { listUserTables, runWithoutForeignKeys } from "../schema/catalog.js";
+import type { TransactionClient } from "../Transaction.js";
+
+/** What {@link useTransaction} hands back: the pinned trx plus its teardown. */
+export interface TestTransaction {
+	/**
+	 * The interactive transaction, pinned to ONE pooled connection. Run every
+	 * query the test makes through THIS handle (`trx.query` / `trx.execute`, or
+	 * `repo.useTransaction(trx)`), never the pooled `db` — that is what makes the
+	 * rollback isolate the test.
+	 */
+	trx: TransactionClient;
+	/** Roll everything the test did back and return the connection to the pool. */
+	rollback: () => Promise<void>;
+}
 
 /**
- * Wrap a test in a savepoint that is rolled back after.
+ * Isolate a test by running it inside a transaction that is rolled back after
+ * (Adonis Lucid parity — Lucid's tests use `db.transaction()` the same way).
+ *
+ * The earlier implementation issued `SAVEPOINT` / `ROLLBACK` through the pooled
+ * `db`, so with `poolMax > 1` the savepoint and its rollback — and the test's
+ * own queries — could each land on a DIFFERENT pooled connection, and the
+ * "isolation" silently did nothing. This pins a single interactive transaction
+ * instead: every query on the returned `trx` runs on that one connection, and
+ * `rollback()` reverts them together, correctly on any pool size.
  */
 export async function useTransaction(
 	db: AsyncDatabaseConnection,
-): Promise<() => Promise<void>> {
-	await db.execute("SAVEPOINT test_savepoint");
-	return async () => {
-		await db.execute("ROLLBACK TO SAVEPOINT test_savepoint");
-		await db.execute("RELEASE SAVEPOINT test_savepoint");
-	};
+): Promise<TestTransaction> {
+	if (typeof db.transaction !== "function") {
+		throw new AtlasError(
+			"E_NO_INTERACTIVE_TRANSACTION",
+			"useTransaction() needs a connection with an interactive transaction() (a real napi connection); this adapter has none.",
+			{
+				hint: "Use createNapiConnection(), or drive rollback yourself if your adapter can't pin a connection.",
+			},
+		);
+	}
+	// Manual (callback-less) mode: a pinned TransactionClient the test drives and
+	// tears down via rollback() — no cross-pool savepoint scatter.
+	const trx = await db.transaction();
+	return { trx, rollback: () => trx.rollback() };
 }
 
 /**
@@ -27,23 +58,44 @@ export async function useTransaction(
  * shared dialect-aware catalog helper, not a SQLite-only `sqlite_master` query.
  *
  * Foreign keys are suspended for the duration so the delete order doesn't
- * matter, and restored even if a statement throws. The row removal itself goes
- * through the Rust compiler (`DELETE` — cross-dialect and transaction-friendly,
- * unlike `TRUNCATE` which auto-commits on MySQL).
+ * matter. The FK toggle and every DELETE run on ONE pinned connection (via
+ * `runWithoutForeignKeys` → `runInTransaction`), so a connection pool can't
+ * scatter the connection-local `PRAGMA`/`SET` away from the deletes. The row
+ * removal goes through the Rust compiler (`DELETE` — cross-dialect, unlike
+ * `TRUNCATE` which auto-commits on MySQL).
  */
-export async function truncateAll(db: AsyncDatabaseConnection): Promise<void> {
+export async function truncateAll(
+	db: AsyncDatabaseConnection,
+	ignoreTables: readonly string[] = [],
+): Promise<void> {
 	// The connection's own dialect, not the module default — correct even when
 	// an app runs several connections on different engines.
 	const dialect = db.dialect;
-	const tables = await listUserTables(db, dialect);
+	const ignore = new Set(ignoreTables);
+	const tables = (await listUserTables(db, dialect)).filter(
+		(t) => !ignore.has(t),
+	);
 	if (tables.length === 0) return;
-	await withoutForeignKeys(db, dialect, async () => {
-		for (const name of tables) {
-			const compiled = compileStatementNative(
-				{ kind: "delete", table: name, wheres: [] },
-				dialect,
-			);
-			await db.execute(compiled.statements[0], compiled.params);
-		}
+
+	// Postgres: a plain DELETE respects FKs immediately (atlas FKs aren't
+	// DEFERRABLE), so deleting a parent before its children raises 23503 — and
+	// nothing orders the tables. `TRUNCATE … CASCADE` is transactional on pg,
+	// order-independent, and needs no session-level FK toggle to leak. (Names
+	// come from the DB catalog; quote them for identifiers with embedded quotes.)
+	if (dialect === "postgres") {
+		const list = tables.map((t) => `"${t.replace(/"/g, '""')}"`).join(", ");
+		await db.execute(`TRUNCATE ${list} RESTART IDENTITY CASCADE`);
+		return;
+	}
+
+	// MySQL/SQLite: DELETE (TRUNCATE auto-commits on MySQL, breaking test
+	// transaction isolation), with FK suspension on ONE pinned connection.
+	const statements = tables.map((name) => {
+		const compiled = compileStatementNative(
+			{ kind: "delete", table: name, wheres: [] },
+			dialect,
+		);
+		return { sql: compiled.statements[0], params: compiled.params };
 	});
+	await runWithoutForeignKeys(db, dialect, statements);
 }

package/src/testing/DbAssertions.ts

@@ -0,0 +1,127 @@
+/**
+ * `db()` — a helix plugin (AdonisJS Lucid database-assertions parity) that
+ * injects database assertions on the test context as `ctx.db`:
+ *
+ *   // tests/bootstrap.ts
+ *   import { configure } from "@c9up/helix";
+ *   import { db } from "@c9up/atlas/testing";
+ *   await configure({ plugins: [db(connection)] });
+ *
+ *   test("registers the user", async ({ db }) => {
+ *     await db.assertHas("users", { email: "a@b.c" });
+ *     await db.assertCount("users", 1);
+ *   });
+ *
+ * Values are always bound as parameters; table/column identifiers are validated
+ * against a strict pattern (letters, digits, `_`, `.`) and quoted, so neither a
+ * value nor an identifier can inject SQL.
+ *
+ * NOTE (namespace): the AdonisJS docs expose these as `db.assert*`; the exact
+ * surface is re-verified against the Adonis docs when available. Model-based
+ * `assertModelExists`/`assertModelMissing` (entity PK metadata) are pending.
+ */
+
+import type { Plugin } from "@c9up/helix";
+
+/** The minimal connection the assertions need — a parameterized query runner. */
+export interface DbConnectionLike {
+	query(sql: string, params?: unknown[]): Promise<Record<string, unknown>[]>;
+}
+
+/** Reject identifiers that could break out of the quoted context. */
+function quoteIdent(name: string): string {
+	if (!/^[A-Za-z_][A-Za-z0-9_.]*$/.test(name)) {
+		throw new Error(`db assertion: unsafe identifier ${JSON.stringify(name)}`);
+	}
+	return `"${name.replace(/\./g, '"."')}"`;
+}
+
+async function countRows(
+	conn: DbConnectionLike,
+	table: string,
+	payload?: Record<string, unknown>,
+): Promise<number> {
+	let where = "";
+	let params: unknown[] = [];
+	if (payload) {
+		const keys = Object.keys(payload);
+		if (keys.length > 0) {
+			where = ` WHERE ${keys.map((k) => `${quoteIdent(k)} = ?`).join(" AND ")}`;
+			params = keys.map((k) => payload[k]);
+		}
+	}
+	const rows = await conn.query(
+		`SELECT COUNT(*) AS c FROM ${quoteIdent(table)}${where}`,
+		params,
+	);
+	return Number(rows[0]?.c ?? 0);
+}
+
+/** The `ctx.db` assertion surface (AdonisJS Lucid database-assertions parity). */
+export interface DbAssertions {
+	/** At least one row in `table` matches every column in `payload`. */
+	assertHas(table: string, payload: Record<string, unknown>): Promise<void>;
+	/** No row in `table` matches `payload`. */
+	assertMissing(table: string, payload: Record<string, unknown>): Promise<void>;
+	/** `table` has exactly `expected` rows (optionally matching `payload`). */
+	assertCount(
+		table: string,
+		expected: number,
+		payload?: Record<string, unknown>,
+	): Promise<void>;
+	/** `table` has no rows at all. */
+	assertEmpty(table: string): Promise<void>;
+}
+
+/** Build the assertion surface bound to a connection. */
+export function createDbAssertions(conn: DbConnectionLike): DbAssertions {
+	return {
+		async assertHas(table, payload) {
+			const n = await countRows(conn, table, payload);
+			if (n === 0) {
+				throw new Error(
+					`Expected "${table}" to have a row matching ${JSON.stringify(payload)}, found none.`,
+				);
+			}
+		},
+		async assertMissing(table, payload) {
+			const n = await countRows(conn, table, payload);
+			if (n > 0) {
+				throw new Error(
+					`Expected "${table}" to have NO row matching ${JSON.stringify(payload)}, found ${n}.`,
+				);
+			}
+		},
+		async assertCount(table, expected, payload) {
+			const n = await countRows(conn, table, payload);
+			if (n !== expected) {
+				const scope = payload ? ` matching ${JSON.stringify(payload)}` : "";
+				throw new Error(
+					`Expected "${table}" to have ${expected} row(s)${scope}, found ${n}.`,
+				);
+			}
+		},
+		async assertEmpty(table) {
+			const n = await countRows(conn, table);
+			if (n > 0) {
+				throw new Error(`Expected "${table}" to be empty, found ${n} row(s).`);
+			}
+		},
+	};
+}
+
+/** The `db()` helix plugin — registers {@link DbAssertions} as `ctx.db`. */
+export function db(conn: DbConnectionLike): Plugin {
+	const assertions = createDbAssertions(conn);
+	return (api) => {
+		api.context.macro("db", assertions);
+	};
+}
+
+// Typing side of the plugin — importing `@c9up/atlas/testing` augments the
+// helix test context with `db` (the Japa pattern).
+declare module "@c9up/helix" {
+	interface TestContext {
+		db: DbAssertions;
+	}
+}