ava-postgres

library7.3.1jsnpmunverified

AVA test fixture providing instant, isolated Postgres databases per test using Docker containers and Postgres template databases. Version 7.3.1 runs on Node >=18, requires peer dependencies ava >=4.3.3 and testcontainers >=10.0.0. Ships TypeScript types. Key differentiator: uses shared workers and database templates for near-zero overhead test isolation, avoiding per-test container spin-up costs. Only dependency is a running Docker instance.

testing

npm install ava-postgres

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · AVA-POSTGRES

ava-postgres

testingjavascriptv7.3.1

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

getTestPostgresDatabaseFactory

✓ import { getTestPostgresDatabaseFactory } from 'ava-postgres'

✗ const getTestPostgresDatabaseFactory = require('ava-postgres')

ESM-only package since v7; requires TypeScript or ESM Node environment.

getTestDatabase (from factory)

✓ const getTestDatabase = getTestPostgresDatabaseFactory({ postgresVersion: '14' })

✗ const getTestDatabase = new getTestPostgresDatabaseFactory()

Factory function must be called with options object; returns an async function.

Pool (type)

✓ import { Pool } from 'pg'

✗ import { Pool } from 'ava-postgres'

ava-postgres does not re-export pg; Pool type is from the 'pg' package.

Creates a factory, obtains a fresh Postgres database per test, and runs a simple query.

import test from 'ava'; import { getTestPostgresDatabaseFactory } from 'ava-postgres'; const getTestDatabase = getTestPostgresDatabaseFactory({ postgresVersion: '14', }); test('basic query', async (t) => { const { pool } = await getTestDatabase(t); const result = await pool.query('SELECT 1 AS number'); t.is(result.rows[0].number, 1); });

Debug

Known issues

breakingv7 changed to ESM-only; CommonJS require() will throw.

fix

Switch to import syntax or stay on v6 (CJS).

affects: >=7

breakingv7 requires ava >=4.3.3, which introduced shared workers API. Older ava versions are incompatible.

fix

Upgrade ava to >=4.3.3.

affects: >=7

breakingv7 requires testcontainers >=10.0.0, which may have different configuration for Docker host.

fix

Update testcontainers to match peer dependency.

affects: >=7

deprecatedPostgres version defaults to '14' but support for version 14 images may be removed in future releases.

fix

Explicitly set postgresVersion to a supported version.

affects: >=6

gotchaThe Docker container is reused across tests via shared workers; ensure tests do not mutate global database state.

fix

Use per-test database isolation (default) or provide unique databaseDedupeKey.

affects: *

Errors

Common errors & fixes

ERR_PACKAGE_PATH_NOT_EXPORTED: Package subpath './package.json' is not defined by "exports"

Trying to require() the package in a CommonJS file, but ava-postgres v7+ is ESM-only.

fix

Use import() or switch to ava-postgres v6 for CommonJS.

Error: Cannot find module 'testcontainers'

Missing peer dependency testcontainers >=10.0.0.

fix

Run npm install --save-dev testcontainers@^10.0.0

TypeError: getTestPostgresDatabaseFactory is not a function

Incorrect default import usage (e.g., import getTestPostgresDatabaseFactory from 'ava-postgres')

fix

Use named import: import { getTestPostgresDatabaseFactory } from 'ava-postgres'

Error: getTestPostgresDatabaseFactory is not a constructor

Calling new on the factory function instead of invoking it.

fix

Remove 'new': const factory = getTestPostgresDatabaseFactory({...})

Error: Container failed to start: Docker not running or no permission

Docker daemon is not available or user lacks permissions.

fix

Ensure Docker is running and user is in docker group, or use Docker Desktop.

Upgrade

Version history

7.3.1latest on npm

Audit

Dependencies

avarequiredPeer dependency: test runner required at >=4.3.3 for shared worker API

testcontainersrequiredPeer dependency: manages Docker containers for Postgres instances

Agent activity

24 hits · last 30 days

node

OpenAI (training)

Resources

githubssh://git@github.com/seamapi/ava-postgres ↗

packageava-postgres ↗

homepagehttps://github.com/seamapi/ava-postgres#readme ↗