Test database fixtures for parameterized testing.
Provides factory builders for creating test databases with pglite (in-memory) and pg (PostgreSQL) drivers. Consumer projects provide their own schema initialization via run_migrations and compose factories into test suites.
@example
import {create_pglite_factory, create_pg_factory} from '@fuzdev/fuz_app/testing/db.js';
import {run_migrations} from '@fuzdev/fuz_app/db/migrate.js';
import {AUTH_MIGRATION_NS} from '@fuzdev/fuz_app/auth/migrations.js';
const init_schema = async (db) => {
await run_migrations(db, [AUTH_MIGRATION_NS]);
};
const pglite_factory = create_pglite_factory(init_schema);
const pg_factory = create_pg_factory(init_schema, process.env.TEST_DATABASE_URL);
export const db_factories = [pglite_factory, pg_factory];11 declarations
readonly ["app_settings", "invite", "audit_log", "api_token", "auth_session", "permit", "actor", "account", "bootstrap_lock"] All auth tables in drop order (children first for FK safety).
The full set created by AUTH_MIGRATIONS — use for clean-slate
test DB initialization. AUTH_TRUNCATE_TABLES is the subset for
between-test data cleanup (excludes audit_log).
When adding tables to AUTH_MIGRATIONS, add them here too.
string[] Auth tables including audit_log — for integration tests that exercise
the full middleware stack (login, admin, rate limiting).
Separate from AUTH_TRUNCATE_TABLES because unit-level DB tests that don't touch audit logging don't need to truncate it.
string[] Auth table names in truncation order (children first for FK safety).
Consumer projects can spread this into their own list and append app-specific tables.
(factories: DbFactory | DbFactory[], truncate_tables: string[]): (name: string, fn: (get_db: () => Db) => void) => void Create a describe_db function bound to specific factories and truncate tables.
Returns a 2-arg (name, fn) function that runs the test suite against each
factory. Each factory gets its own describe block with a shared database
instance, automatic beforeEach truncation, and afterAll cleanup.
Skipped factories use describe.skip.
factoriesone or more database factories to run suites against
DbFactory | DbFactory[]truncate_tablestables to truncate between tests (children first for FK safety)
string[](name: string, fn: (get_db: () => Db) => void) => void a describe_db function for use in test files
(init_schema: (db: Db) => Promise<void>, test_url?: string | undefined): DbFactory Create a pg (PostgreSQL) database factory for tests.
Skipped when test_url is not provided.
Drops schema_version before running init_schema, forcing migrations
to re-evaluate against the actual tables. Prevents stale version entries
from skipping migrations when DDL changes between test sessions.
For full clean-slate behavior (recommended), call drop_auth_schema(db)
at the start of init_schema before running migrations. This handles
upstream schema changes that go beyond adding new tables/columns.
init_schemacallback to initialize the database schema
(db: Db) => Promise<void>test_url?PostgreSQL connection URL (e.g. from TEST_DATABASE_URL)
string | undefinedDbFactory a factory that creates pg databases
(init_schema: (db: Db) => Promise<void>): DbFactory Create a pglite (in-memory) database factory for tests.
Always enabled — no external dependencies required.
Shares a single PGlite WASM instance across all factories in the same
vitest worker thread (one test file). Subsequent create() calls reset
the schema via DROP SCHEMA public CASCADE instead of paying the WASM
cold-start cost again.
init_schemacallback to initialize the database schema
(db: Db) => Promise<void>DbFactory a factory that creates in-memory pglite databases
DbFactory Factory interface for creating test database instances.
namestringcreate() => Promise<Db>close(db: Db) => Promise<void>skipbooleanskip_reasonstring(db: Db): Promise<void> Drop all auth tables and schema version tracking for a clean slate.
Recommended at the start of init_schema callbacks for create_pg_factory.
Persistent test databases can accumulate stale schema from previous fuz_app
versions — this ensures migrations run against a truly empty database.
Safe on fresh databases (IF EXISTS on all statements). No-op effect for
PGlite (already fresh), but harmless to call unconditionally.
dbthe database to clean
Promise<void> boolean CI detection — CI=true is set automatically by GitHub Actions, GitLab CI, etc.
(factories: DbFactory[]): void Log factory status to console.
factoriesthe database factories to report on
DbFactory[]void (db: Db): Promise<void> Reset a PGlite database to a clean state by dropping and recreating the public schema.
Removes all tables, sequences, indexes, types, and functions. The database instance remains usable after reset.
dbthe database to reset
Promise<void>