Registry / testing / pg-transactional-tests

pg-transactional-tests

JSON →
library1.2.0jsnpmunverified

pg-transactional-tests is a utility library designed to simplify database testing by wrapping each test in a PostgreSQL transaction. It currently stands at version 1.2.0, with a stable release cadence implied by its versioning and active development. The library patches the `pg` package to automatically initiate a transaction before a test, and then roll it back afterward, ensuring a clean database state for every test run without the overhead of clearing tables. A key differentiator is its compatibility with many popular ORMs like Sequelize, TypeORM, MikroORM, Objection, and Knex, which all build upon the `pg` driver. It also intelligently handles nested transactions using savepoints and supports parallel testing across multiple databases by tracking transaction state per connection. A significant limitation is its incompatibility with Prisma, due to Prisma's distinct database interaction model. This approach vastly accelerates test suites and reduces boilerplate for database setup and teardown.

npm install pg-transactional-tests
INSTALL
IMPORT
SIG · PG-TRANSACTIONAL-T
P
pg-transactional-tests
testingjavascriptv1.2.0
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

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

testTransaction
✓ import { testTransaction } from 'pg-transactional-tests';
✗ const { testTransaction } = require('pg-transactional-tests');
The library primarily uses ES modules; CommonJS `require` might lead to issues in mixed environments or older Node.js setups without proper transpilation.
testTransaction.start
✓ beforeEach(testTransaction.start);
Used as a hook in testing frameworks to begin a transaction for each test.
testTransaction.rollback
✓ afterEach(testTransaction.rollback);
Used as a hook to roll back the transaction after each test, ensuring database isolation.
testTransaction.close
✓ afterAll(testTransaction.close);
Used as a hook to close all `pg` connections opened by the transactional tests, preventing resource leaks.

Demonstrates the essential Jest setup to enable transactional tests for a test suite, ensuring clean database state for every test.

import { testTransaction } from 'pg-transactional-tests'; // This setup file should be configured in your test runner, e.g., Jest's `setupFilesAfterEnv`. // It ensures that every test involving the database runs within its own transaction // and that the transaction is rolled back afterwards. // Starts a transaction before any tests begin (useful if using `beforeAll` hooks that perform queries) beforeAll(testTransaction.start); // Starts a new savepoint/transaction before each individual test beforeEach(testTransaction.start); // Rolls back the transaction/savepoint after each test completes, ensuring isolation afterEach(testTransaction.rollback); // Closes all PostgreSQL connections managed by pg-transactional-tests after all tests are done afterAll(testTransaction.close); // Example test structure for context: // describe('User Service', () => { // it('should create a user', async () => { // // Your ORM or pg client code here will run inside a transaction // await someORM.user.create({ name: 'Test User' }); // const user = await someORM.user.findUnique({ where: { name: 'Test User' } }); // expect(user).not.toBeNull(); // }); // it('should not persist user across tests', async () => { // const count = await someORM.user.count(); // expect(count).toBe(0); // Because previous test's transaction was rolled back // }); // });
Debug
Known issues
breakingThis library is fundamentally incompatible with Prisma ORM due to Prisma's unique database interaction model, which does not utilize the standard `pg` client in a way that allows for the library's patching mechanism to function correctly.
fix
If using Prisma, this library cannot be used. Consider alternative testing strategies like Prisma's own `db push` for schema migrations or dedicated test databases per run.
affects: >=1.0.0
gotchaThe library works by patching the underlying `pg` package. This creates a dependency on `pg`'s internal implementation details, which could potentially break with future major versions of `pg` if its internal structure changes significantly.
fix
Always test `pg-transactional-tests` thoroughly when upgrading `pg` to a new major version. Monitor the library's GitHub for compatibility updates.
affects: >=1.0.0
gotchaFailing to call `afterAll(testTransaction.close)` will leave database connections open after your test suite completes, potentially leading to resource exhaustion or preventing your test runner from exiting cleanly.
fix
Ensure `testTransaction.close` is always called in your `afterAll` hook in your test setup file.
affects: >=1.0.0
gotchaIf `testTransaction.rollback` is not called after `testTransaction.start` for each test, database changes will persist, leading to flaky and interdependent tests. This often happens if only `beforeAll` is used instead of `beforeEach` and `afterEach`.
fix
Always pair `beforeEach(testTransaction.start)` with `afterEach(testTransaction.rollback)` to ensure proper transactional isolation for each test.
affects: >=1.0.0
Errors
Common errors & fixes
Error: Cannot find module 'pg'
The 'pg' package is a peer dependency but has not been installed in your project.
fix
Install the 'pg' package: `npm install pg` or `yarn add pg` or `pnpm add pg`.
TypeError: Cannot read properties of undefined (reading 'start') or 'rollback' or 'close'
The `testTransaction` object was not correctly imported or is being accessed before it's initialized (e.g., in a pure CommonJS environment without proper transpilation/config).
fix
Ensure you are using `import { testTransaction } from 'pg-transactional-tests';` and that your environment supports ES Modules, or configure your bundler/test runner (like Jest) to handle module resolution correctly.
Tests fail due to too many open connections or hanging processes after tests run.
The `testTransaction.close()` function was not called in the `afterAll` hook of your test setup.
fix
Add `afterAll(testTransaction.close);` to your test setup file (e.g., `jest-setup.ts`).
Test data persists between individual tests, making tests interdependent and flaky.
The `testTransaction.rollback()` function was not called in the `afterEach` hook of your test setup.
fix
Add `afterEach(testTransaction.rollback);` to your test setup file to ensure each test runs in isolation.
Upgrade
Version history
1.2.0latest on npm
Audit
Dependencies
pgrequiredThe library patches and relies on the 'pg' client for database interactions. It is a peer dependency.
Agent activity
6 hits · last 30 days
node
6
Resources
pg-transactional-tests — npm install pg-transactional-tests · libregistry