ava-postgres

ava-postgres is a test fixture for AVA that provides you with nearly-instant access to a fresh Postgres database for every test.

ava-postgres's only dependency is a running instance of Docker.

Installation

npm install --save-dev ava-postgres

or

yarn add --dev ava-postgres

Usage

ava-postgres's main export is a factory function, so you'll probably want to create a file like tests/fixtures/get-test-database.ts:

import{getTestPostgresDatabaseFactory}from"ava-postgres"exportconstgetTestDatabase=getTestPostgresDatabaseFactory({// Any tag for the official Postgres Docker image, defaults to "14"postgresVersion: "14",})

Then, in your tests, you can use the getTestDatabase() function to get a fresh database for each test:

importtestfrom"ava"import{getTestDatabase}from"./fixtures/get-test-database"test("foo bar",async(t)=>{const{ pool }=awaitgetTestDatabase()awaitpool.query("SELECT 1")t.pass()})

Full list of connection details returned by getTestDatabase

Database setup

ava-postgres uses Postgres templates so you only pay the setup cost once. After a template has been created, Postgres can create a new database from it in milliseconds.

If you want to perform common database setup, you can use a hook and pass parameters to the getTestDatabase() function:

import{getTestPostgresDatabaseFactory}from"ava-postgres"typeGetTestDatabaseParams={shouldMigrate?: booleanshouldSeed?: boolean}exportconstgetTestDatabase=getTestPostgresDatabaseFactory<GetTestDatabaseParams>({beforeTemplateIsBaked: async({connection: { pool },params: { shouldMigrate, shouldSeed },})=>{if(shouldMigrate){awaitpool.query("CREATE TABLE foo (id int)")}if(shouldSeed){awaitpool.query("INSERT INTO foo VALUES (1)")}},})

Then, in your tests, you can pass parameters to the getTestDatabase() function:

importtestfrom"ava"import{getTestDatabase}from"./fixtures/get-test-database"test("foo bar",async(t)=>{const{ pool }=awaitgetTestDatabase({shouldMigrate: true,shouldSeed: true,})awaitpool.query("SELECT * FROM foo")t.pass()})

Advanced Usage

Postgres container de-duping

In rare cases, you may want to spawn more than one Postgres container.

Internally, this library uses an AVA "shared worker". A shared worker is a singleton shared with the entire running test suite, and so one ava-postgres shared worker maps to exactly one Postgres container.

To spawn separate shared workers and thus additional Postgres containers, you have two options:

Specify different version strings for the postgresVersion option in the factory function:

constgetTestPostgresDatabase=getTestPostgresDatabaseFactory({postgresVersion: "14",})

Each unique version will map to a unique shared worker.

Set the workerDedupeKey option in the factory function:

constgetTestPostgresDatabase=getTestPostgresDatabaseFactory({workerDedupeKey: "foo",})

Each unique key will map to a unique shared worker.

Database de-duping

By default, ava-postgres will create a new database for each test. If you want to share a database between tests, you can use the databaseDedupeKey option:

importtestfrom"ava"constgetTestPostgresDatabase=getTestPostgresDatabaseFactory({})test("foo",async(t)=>{constconnection1=awaitgetTestPostgresDatabase(t,null,{databaseDedupeKey: "foo",})constconnection2=awaitgetTestPostgresDatabase(t,null,{databaseDedupeKey: "foo",})t.is(connection1.database,connection2.database)})

This works across the entire test suite.

Note that if unique parameters are passed to the beforeTemplateIsBaked (null in the above example), separate databases will still be created.

Manual template creation

In some cases, if you do extensive setup in your beforeTemplateIsBaked hook, you might want to obtain a separate, additional database within it if your application uses several databases for different purposes. This is possible by using the manuallyBuildAdditionalTemplate() function passed to your hook callback:

importtestfrom"ava"constgetTestDatabase=getTestPostgresDatabaseFactory<DatabaseParams>({beforeTemplateIsBaked: async({
params,connection: { pool },
manuallyBuildAdditionalTemplate,})=>{awaitpool.query(`CREATE TABLE "bar" ("id" SERIAL PRIMARY KEY)`)constfooTemplateBuilder=awaitmanuallyBuildAdditionalTemplate()awaitfooTemplateBuilder.connection.pool.query(`CREATE TABLE "foo" ("id" SERIAL PRIMARY KEY)`)const{templateName: fooTemplateName}=awaitfooTemplateBuilder.finish()return{ fooTemplateName }},})test("foo",async(t)=>{constbarDatabase=awaitgetTestDatabase({type: "bar"})// the "bar" database has the "bar" table...awaitt.notThrowsAsync(async()=>{awaitbarDatabase.pool.query(`SELECT * FROM "bar"`)})// ...but not the "foo" table...awaitt.throwsAsync(async()=>{awaitbarDatabase.pool.query(`SELECT * FROM "foo"`)})// ...and we can obtain a separate database with the "foo" tableconstfooDatabase=awaitgetTestDatabase.fromTemplate(t,barDatabase.beforeTemplateIsBakedResult.fooTemplateName)awaitt.notThrowsAsync(async()=>{awaitfooDatabase.pool.query(`SELECT * FROM "foo"`)})})

Bind mounts & execing in the container

ava-postgres uses testcontainers under the hood to manage the Postgres container.

In some scenarios you might want to mount a SQL script into the container and manually load it using psql.

You can do this with the bindMounts option:

constgetTestPostgresDatabase=getTestPostgresDatabaseFactory({container: {bindMounts: [{source: "/path/on/host",target: "/test.sql",},],},beforeTemplateIsBaked: async({connection: { username, database },
containerExec,})=>{const{ exitCode }=awaitcontainerExec(`psql -U ${username} -d ${database} -f /test.sql`.split(" "))if(exitCode!==0){thrownewError(`Failed to load test file`)}},})