Test database fixtures for parameterized testing.
Provides factory builders for creating test databases with pglet-wasm (the
in-memory default), PGlite (in-memory) and pg (PostgreSQL) drivers. Consumer
projects provide their own schema initialization via run_migrations and
compose factories into test suites.
import {create_default_db_factory, create_pg_factory} from '@fuzdev/fuz_app/testing/db.ts';
import {run_migrations} from '@fuzdev/fuz_app/db/migrate.ts';
import {AUTH_MIGRATION_NS} from '@fuzdev/fuz_app/auth/migrations.ts';
const init_schema = async (db) => {
await run_migrations(db, [AUTH_MIGRATION_NS]);
};
const default_factory = create_default_db_factory(init_schema);
const pg_factory = create_pg_factory(init_schema, process.env.TEST_DATABASE_URL);
export const db_factories = [default_factory, pg_factory];
testing/db.ts view source
(db: Db, table: string, columns: readonly string[]): Promise<void> import {assert_columns_match_live} from '@fuzdev/fuz_app/testing/db.js'; Assert a *_COLUMNS projection const names exactly the live columns of
table — the drift guard for an exported const (ACCOUNT_COLUMNS,
CELL_COLUMNS, a consumer's own).
This is the reverse of the fail-loud read: a named projection makes a
*dropped* column fail loud at query time, but a column *added* to the table
and not to the projection would silently vanish from every row read. Both
directions are covered by the equality here. It guards one const; it can't
see a table that has *no* const — for that, keep a table → const registry
and assert its key set against query_public_columns (fuz_app's own is
src/test/db/column_projections.db.test.ts).
db
a bootstrapped test database
table
the public-schema table the const projects
type string
columns
the projection const's column names
type readonly string[]
testing/db.ts view source
string[] import {auth_integration_truncate_tables} from '@fuzdev/fuz_app/testing/db.js'; 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.
testing/db.ts view source
string[] import {auth_truncate_tables} from '@fuzdev/fuz_app/testing/db.js'; 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.
testing/db.ts view source
(init_schema: (db: Db) => Promise<void>): DbFactory import {create_default_db_factory} from '@fuzdev/fuz_app/testing/db.js'; init_schema
callback to initialize the database schema
type (db: Db) => Promise<void>
testing/db.ts view source
(factories: DbFactory | DbFactory[], truncate_tables: string[]): (name: string, fn: (get_db: () => Db) => void) => void import {create_describe_db} from '@fuzdev/fuz_app/testing/db.js'; 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.
factories
one or more database factories to run suites against
truncate_tables
tables to truncate between tests (children first for FK safety)
type string[]
returns
(name: string, fn: (get_db: () => Db) => void) => void mutates
the underlying database between tests — beforeEach issues — `TRUNCATE <truncate_tables> CASCADE` against the shared instance.
testing/db.ts view source
(init_schema: (db: Db) => Promise<void>, test_url?: string | undefined): DbFactory import {create_pg_factory} from '@fuzdev/fuz_app/testing/db.js'; Create a pg (PostgreSQL) database factory for tests.
Skipped when test_url is not provided. Each create() opens a pool,
resets the public schema (reset_public_schema) and runs init_schema —
the lifecycle every factory here shares, so a persistent test database never
carries stale DDL or tracker rows from an earlier run or another suite's
schema. Point test_url at a database used only for tests.
init_schema
callback to initialize the database schema
type (db: Db) => Promise<void>
test_url?
PostgreSQL connection URL (e.g. from TEST_DATABASE_URL)
type string
optional
returns
DbFactory a factory that creates pg databases. The returned create()
throws when test_url is unset (despite the skip: true flag — defense
against direct invocation), and rewrites Postgres "database does not
exist" errors into a createdb hint message.
testing/db.ts view source
(init_schema: (db: Db) => Promise<void>): DbFactory import {create_pglet_wasm_factory} from '@fuzdev/fuz_app/testing/db.js'; Create a pglet-wasm (in-memory) database factory for tests.
Always enabled — needs the optional @fuzdev/pglet-wasm peer installed.
Shares one pglet instance across the pglet-wasm factories this module
builds, created with fuz_app's value coercion (PGLET_COERCION); each
create() resets the schema via DROP SCHEMA public CASCADE.
init_schema
callback to initialize the database schema
type (db: Db) => Promise<void>
testing/db.ts view source
(init_schema: (db: Db) => Promise<void>): DbFactory import {create_pglite_factory} from '@fuzdev/fuz_app/testing/db.js'; Create a PGlite (in-memory) database factory for tests.
Always enabled — needs the optional @electric-sql/pglite peer installed.
Shares one PGlite WASM instance across the PGlite factories this module
builds; each create() resets the schema via DROP SCHEMA public CASCADE
instead of paying the cold start again.
init_schema
callback to initialize the database schema
type (db: Db) => Promise<void>
testing/db.ts view source
DbFactory import type {DbFactory} from '@fuzdev/fuz_app/testing/db.js'; Factory interface for creating test database instances.
create
type (): Promise<Db>
close
type (db: Db): Promise<void>
returns Promise<void>
testing/db.ts view source
DbFactoryBuilder import type {DbFactoryBuilder} from '@fuzdev/fuz_app/testing/db.js'; Builds a DbFactory from a schema initializer — the shape of every factory builder here.
(call)
type (init_schema: (db: Db) => Promise<void>): DbFactory
init_schema
type (db: Db) => Promise<void>
testing/db.ts view source
(factories: DbFactory[]): void import {log_db_factory_status} from '@fuzdev/fuz_app/testing/db.js'; Log factory status to console.
testing/db.ts view source
(db: Db): Promise<void> import {reset_public_schema} from '@fuzdev/fuz_app/testing/db.js'; Reset a test database to a clean slate by dropping and recreating the public schema.
DROP SCHEMA public CASCADE; CREATE SCHEMA public in plain SQL, so it resets
every driver: the in-memory factories call it on each create(), and it is
recommended at the start of init_schema callbacks for create_pg_factory,
whose persistent databases accumulate stale DDL across fuz_app versions.
Drift-proof — it wipes every table, type, and sequence regardless of
namespace, so it needs no upkeep when the schema gains a table. The database
instance remains usable after reset.
mutates
db — drops the `public` schema and recreates it; all rows in all
tables are gone after this returns.
testing/db.ts view source
(create_factory: DbFactoryBuilder | null): DbFactoryBuilder | null import {set_default_db_factory} from '@fuzdev/fuz_app/testing/db.js'; Install the builder create_default_db_factory uses, so suites written
against the default run against another driver without being edited —
create_pglite_factory to run them on PGlite. Pass null to restore
pglet-wasm.
The slot is read when a factory is built, not when it creates a database,
so install before the first create_default_db_factory call — a vitest
setupFiles entry, which runs ahead of every test file's imports, is the
shape fuz_app's own db project uses. A factory built earlier (including
the module-level fallback in testing/app_server.ts) keeps the driver it
was built with, and uninstalling does not revert it.
create_factory
the builder to install, or null to restore the default
type (DbFactoryBuilder) | null
returns
(DbFactoryBuilder) | null
the builder this replaced (null for pglet-wasm), so a caller can put it back