testing/db.ts

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];
view source

Declarations
#

13 declarations

assert_columns_match_live
#

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

type Db

table

the public-schema table the const projects

type string

columns

the projection const's column names

type readonly string[]

returns

Promise<void>

auth_integration_truncate_tables
#

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.

auth_truncate_tables
#

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.

create_default_db_factory
#

testing/db.ts view source

(init_schema: (db: Db) => Promise<void>): DbFactory import {create_default_db_factory} from '@fuzdev/fuz_app/testing/db.js';

Create the default in-memory database factory for tests: pglet-wasm, or the builder set_default_db_factory installed.

The factory fuz_app's own test helpers fall back to when a suite passes none (create_test_app_server, describe_rate_limiting_tests, describe_sse_route_tests). Call create_pglite_factory or create_pglet_wasm_factory directly to pin a driver.

init_schema

callback to initialize the database schema

type (db: Db) => Promise<void>

returns

DbFactory

create_describe_db
#

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.

create_pg_factory
#

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.

create_pglet_wasm_factory
#

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>

returns

DbFactory

create_pglite_factory
#

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>

returns

DbFactory

DbFactory
#

testing/db.ts view source

DbFactory import type {DbFactory} from '@fuzdev/fuz_app/testing/db.js';

Factory interface for creating test database instances.

name

type string

create

type (): Promise<Db>

returns Promise<Db>

close

type (db: Db): Promise<void>

db

type Db
returns Promise<void>

skip

type boolean

skip_reason?

type string

DbFactoryBuilder
#

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>
returns DbFactory

log_db_factory_status
#

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.

factories

type DbFactory[]

returns

void

reset_public_schema
#

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.

db

type Db

returns

Promise<void>

mutates

  • db — drops the `public` schema and recreates it; all rows in all tables are gone after this returns.

set_default_db_factory
#

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

Depends on
#

Imported by
#