Hey everyone! Let’s talk about testing in Node.js, specifically when databases get involved.

Unit tests? Absolutely essential for checking your functions in isolation. But let’s be real, at some point, you need to know if your code actually plays nice with a real database, message queue, or whatever external service it relies on. Mocking everything can feel like building a house of cards, fragile, prone to hiding nasty bugs that only surface when things interact for real. And shared dev databases? Don’t even get me started. They’re a one-way ticket to flaky tests and accidentally messing up your colleagues’ work. Nightmare fuel.

Coming from Go, I got spoiled by integration tests that gave me rock-solid confidence. I craved that same feeling in my TypeScript projects. In a previous post, we explored using testcontainers to spin up pristine, isolated Postgres instances for our tests. It’s a fantastic approach, giving you high fidelity by testing against the real deal (well, a Dockerized version). We even discussed ways to optimize the startup time.

But here’s the thing: if you’re like me and embrace a Test Driven Development (TDD) workflow, every millisecond counts.

(As always, the final project code can be found over at the github repo)

I am still evaluating and playing around with this approach, so please do only consider it as an educational post rather than a guide.

TDD: Not Just a Buzzword, It’s About Flow

What is TDD, really? You’ll find plenty of formal definitions, often involving strict red-green-refactor cycles and meticulous unit testing. Kent Beck, a key figure in TDD, described it as a way to “think through your design before you write your functional code.”

Honestly, many resources make TDD sound overly rigid, almost tedious. That’s fine if your project demands extreme meticulousness, but for many of us, especially working on CRUD heavy apps or exploring new features, a more pragmatic approach works wonders.

My take on TDD? It’s about developing your code alongside your tests. Tests aren’t just safety nets for the future; they’re your active guide during development. They help you shape the functionality, catch edge cases early, and save you the endless cycle of starting your app, hitting it with curl, cleaning the database, and repeating. I tend to lean heavily on integration tests – testing slices of functionality, often involving the database, because if the data ends up correct in my source of truth (the DB), I can be fairly confident that it’s working as intended.

This kind of workflow boosts my velocity and confidence immensely. But… it hinges on a fast feedback loop. Waiting even a few seconds for tests to spin up can break your concentration and kill momentum. That “Time To Result” (TTR, yeah, I made that up) needs to be fast.

Last post I showcased testcontainers approach, which is great and gets you close to a tight feedback loop (~2-4s initial setup, then subsequent test cases are much faster thanks to snapshots), that initial container spin-up time can still feel sluggish, especially if you want to run many test suites in parallel. What if we could make it even faster? (The answer is, maybe, this is more of an experiment rather than a recommendation on my part)

Enter PGLite: Postgres in Your Pocket (Almost!)

Recently, I stumbled upon something that felt like a game changer for this workflow: PGLite.

Imagine Postgres, but compiled to WASM and packaged as a simple TypeScript library. That’s PGLite. You can run a genuine Postgres engine right inside your Node.js (or Bun, or even browser!) process without installing Postgres or any other dependencies.

It’s tiny (under 3MB gzipped!), incredibly fast to start, and supports many common Postgres extensions (like pgvector).

Getting started is ridiculously simple:

import { PGlite } from '@electric-sql/pglite';

// Spin up an in-memory Postgres instance
const db = new PGlite(); // Or use a file path for persistence: new PGlite('data-directory')

// Run SQL queries!
const result = await db.query("select 'Hello from PGLite!' as message;");
console.log(result.rows);
// -> [ { message: "Hello from PGLite!" } ]

await db.close(); // Clean up

It can run entirely in memory (perfect for ephemeral test databases) or persist to the filesystem (if you plan to run parallel tests you will have to persist to disk, since there is an issue with running parallel in memory databases. Developed by the folks at ElectricSQL, it’s designed for embedding Postgres, but its use cases are broader:

• Unit and CI testing: This is our sweet spot! Lightning-fast setup and teardown. Create a unique, fresh Postgres instance for every single test if you want, in milliseconds.
• Local development: A lightweight alternative to running a full Postgres server.
• Remote/Web Containers: So small it’s easily embeddable.
• Edge AI/RAG: Full pgvector support opens up interesting possibilities.

Drizzle: The ORM You’ll Actually Enjoy

To make this setup even smoother, we’ll pair PGLite with Drizzle ORM. If you’ve been burned by clunky, heavyweight ORMs before, give Drizzle a look.

Why Drizzle?

• TypeScript Native: Feels right at home in a TS project. Great type safety.
• Lightweight: Tiny bundle size (~7.4kb minified+gzipped) and zero dependencies.
• Stellar DX: Seriously, it’s a joy to use. As a big raw SQL fan, this has been the only ORM I’ve actually enjoyed.
• Fast Migrations (with a twist): We’ll use a neat trick to keep migrations snappy without manually generating files every time.

Let’s Get Practical: PGLite + Drizzle + Vitest

Alright, theory’s great, but let’s see it in action. We’ll modify the project from the previous Testcontainers post to use PGLite and Drizzle.

1. Installation:

npm install @electric-sql/pglite drizzle-orm
npm install -D drizzle-kit vitest supertest @types/supertest

2. Define Your Schema:

Let’s keep it simple with a Drizzle schema.

src/schema.ts

import { pgTable, serial, varchar } from "drizzle-orm/pg-core";

export const items = pgTable("items", {
 id: serial("id").primaryKey(),
 name: varchar("name", { length: 100 }).notNull(),
});

// Add other tables here as needed
export type Item = typeof items.$inferSelect;
export type NewItem = typeof items.$inferInsert;

3. The Magic Migration Helper:

Normally, Drizzle uses migration files or drizzle-kit push to update your DB schema. But for rapid TDD, constantly generating migrations is a drag. Here’s a helper function that uses drizzle-kit’s programmatic API to figure out the SQL needed to create your schema from scratch. No migration files needed!

src/testing/db-helper.ts

import * as schema from "../schema";
import { drizzle } from "drizzle-orm/pglite";
import type * as DrizzleKit from "drizzle-kit/api";
import type { PGlite } from "@electric-sql/pglite";

// Hack needed to dynamically import drizzle-kit's API
// See: https://github.com/drizzle-team/drizzle-orm/issues/2853
import { createRequire } from "node:module";
const require = createRequire(import.meta.url);
const { generateDrizzleJson, generateMigration } = require("drizzle-kit/api") as typeof DrizzleKit;

/**
 * Generates SQL statements to create the schema defined in `src/schema.ts`
 * and applies them to the given PGLite client.
 * This avoids needing migration files for tests, speeding up schema changes.
 */
export async function pushSchema(client: PGlite) {
 const db = drizzle(client, { schema });

 // Generate an empty schema snapshot
 // See: https://github.com/drizzle-team/drizzle-orm/issues/3913
 const prevJson = generateDrizzleJson({});
 // Generate a snapshot based on your current schema definitions
 const curJson = generateDrizzleJson(
  schema,
  prevJson.id, // Use the empty snapshot's ID
  undefined,
  "snake_case", // Or your preferred naming convention
 );

 // Compare the empty snapshot with the current schema to get all CREATE statements
 const statements = await generateMigration(prevJson, curJson);

 // Apply the generated SQL statements
 console.log("Applying schema...");
 for (const statement of statements) {
  await db.execute(statement);
 }
 console.log("Schema applied.");
}

Benefits of this approach:

• Rapid Schema Evolution: Change your Drizzle schema files, rerun tests, and the DB is updated instantly.
• No Migration File Clutter: Keeps your project cleaner.
• Performance: Applying one set of CREATE statements is faster than running potentially hundreds of historical migration files.
• Fantastic DX: Forget drizzle-kit generate or push during development, just code!

4. Update Your Tests:

Now, let’s update our Vitest setup (src/server.test.ts) to use PGLite. We’ll use beforeEach and afterEach to ensure every test gets a fresh, migrated database instance.

src/server.test.ts

import {
 afterEach,
 beforeEach,
 describe,
 expect,
 it,
 vi,
} from "vitest";
import request from "supertest";
import { getDB } from "./db.js";
import * as schema from "./schema.js";
import { pushSchema } from "./testing/db-helper.js";
import { PGlite } from "@electric-sql/pglite";
import { drizzle } from "drizzle-orm/pglite";
import { eq } from "drizzle-orm";
import app from "./server.js";
import { PgDatabase } from "drizzle-orm/pg-core";
import TestAgent from "supertest/lib/agent.js";

// Crucial: Mock the db module to intercept calls to getDB()
vi.mock("./db");

describe("Items API with PGLite", () => {
 let db: PgDatabase<any, typeof schema>; // Use the correct type
 let client: PGlite; // Hold the PGLite client instance
 let agent: TestAgent; // Supertest agent

 // Setup a fresh PGLite instance and apply schema before each test
 beforeEach(async () => {
  client = new PGlite(
   // You might want to specify a consistent temp directory:
   // dataDir: `./.pglite-test-data/${dbName}` or `/tmp`
  );

  agent = request(app); // Create supertest agent

  // Apply the schema using our helper
  await pushSchema(client);

  // Create the Drizzle instance connected to PGLite
  db = drizzle(client, { schema });

  // Mock getDB() to return *this specific test's* Drizzle instance
  // Use `vi.mocked` for type safety
  vi.mocked(getDB).mockReturnValue(db as any);
 });

 // Close the PGLite client and clean up mocks after each test
 afterEach(async () => {
  await client.close(); // Release resources
  vi.clearAllMocks(); // Reset mocks
  // Consider adding cleanup for the data directory if you specified one
 });

 it("POST /items should create an item", async () => {
  const newItemName = "Test Item PGLite";
  const response = await agent
   .post("/items")
   .send({ name: newItemName })
   .expect(201); // Assert HTTP status code

  expect(response.body.id).toBeDefined();
  expect(response.body.name).toBe(newItemName);

  // Verify directly in the DB for extra confidence
  const dbResult = await db
   .select()
   .from(schema.items)
   .where(eq(schema.items.id, response.body.id));
  expect(dbResult.length).toBe(1);
  expect(dbResult[0].name).toBe(newItemName);
 });

 it("GET /items/:id should retrieve an existing item", async () => {
  // Arrange: Insert an item directly
  const insertResult = await db
   .insert(schema.items)
   .values({ name: "Get Me PGLite" })
   .returning();
  const itemId = insertResult[0].id;

  // Act: Request the item
  const response = await agent.get(`/items/${itemId}`).expect(200);

  // Assert
  expect(response.body.id).toBe(itemId);
  expect(response.body.name).toBe("Get Me PGLite");
 });

 it("GET /items/:id should return 404 for non-existent item", async () => {
  await agent.get("/items/99999").expect(404);
 });

 it("POST /items should return 400 if name is missing", async () => {
  await agent.post("/items").send({}).expect(400);
 });
});

5. Run Your Tests:

npm test

The Need for Speed: Benchmarks

Okay, talk is cheap. Let’s look at some rough numbers. These were run on my machine, so your mileage may wary, but they illustrate the difference.

Testcontainers (with snapshotting after initial setup):

> vitest run
... (Container startup logs) ...
 ✓ src/server.test.ts (4 tests) 4141ms
   ✓ Items API > POST /items should create an item  459ms
   ✓ Items API > GET /items/:id should retrieve an existing item 159ms
   ✓ Items API > GET /items/:id should return 404 for non-existent item 132ms
   ✓ Items API > POST /items should return 400 if name is missing 154ms

 Test Files  1 passed (1)
      Tests  4 passed (4)
   Duration  4.45s (transform 32ms, setup 0ms, collect 159ms, tests 4.14s, environment 0ms, prepare 40ms)

Using hyperfine for 10 runs:

Time (mean ± σ):      4.773 s ±  0.412 s    [User: 2.730 s, System: 0.991 s]
Range (min … max):    4.333 s …  5.772 s    10 runs

PGLite (fresh instance per test, no optimizations yet):

> vitest run
 ✓ src/server.test.ts (4 tests) 2146ms
   ✓ Items API > POST /items should create an item  576ms
   ✓ Items API > GET /items/:id should retrieve an existing item  503ms
   ✓ Items API > GET /items/:id should return 404 for non-existent item  516ms
   ✓ Items API > POST /items should return 400 if name is missing  550ms

 Test Files  1 passed (1)
      Tests  4 passed (4)
   Duration  2.58s (transform 39ms, setup 0ms, collect 273ms, tests 2.15s, environment 0ms, prepare 42ms)

Using hyperfine for 10 runs:

Time (mean ± σ):      2.822 s ±  0.070 s    [User: 5.768 s, System: 1.766 s]
Range (min … max):    2.748 s …  2.946 s    10 runs

The Verdict (Round 1): PGLite is already significantly faster overall (~2.8s vs ~4.8s) mainly because we skip the Docker container boot time entirely! Each test takes a bit longer individually because it’s initializing PGLite and applying the schema every time. Can we do better?

Even Faster? Enter reusable database

Just like with Testcontainers, we can optimize further by setting up the database once, applying the schema, taking a “snapshot,” and then quickly restoring that clean state before each test. PGLite doesn’t have a direct snapshot command, but we can achieve a similar effect with some filesystem manipulation.

I am still experimenting with this approach, it does net us some speed benefits but I cannot guarantee its complete correctness and safety, it’s easy to setup so you can try it out but be wary. If you have any ideas how to improve this implementation please leave a comment or hit me up somewhere

1. Update the DB Helper:

Add these functions to src/testing/db-helper.ts:

import type { PGlite } from "@electric-sql/pglite";

export async function snapshot(client: PGlite) {
    return client.dumpDataDir("none");
}

export async function restoreSnapshot(snapshot: File | Blob): Promise<PGlite> {
    const clone = new File([Buffer.from(await snapshot.arrayBuffer())], "snapshot", { type: snapshot.type });
    return new PGlite({ loadDataDir: clone });
}

2. Modify the Test Setup:

We’ll now use beforeAll to set up one PGLite instance for the entire test file, apply the schema, and take the snapshot. beforeEach will simply restore the snapshot.

src/server.test.ts (Changes highlighted)

import {
 // ... other imports
 beforeAll, 
 afterAll, 
 // ...
} from "vitest";
// ... other imports
import { pushSchema, snapshot, restoreSnapshot } from "./testing/db-helper"; 

vi.mock("./db");

describe("Items API with PGLite", () => {
 let db: PgDatabase<any, typeof schema>;
 let client: PGlite;
 let agent: TestAgent;
 let snapshottedDB: File | Blob;

 beforeAll(async () => {
  client = new PGlite(
   // You might want to specify a consistent temp directory:
   // dataDir: `./.pglite-test-data/${dbName}` or `/tmp`
  );

  // Apply the schema once
  await pushSchema(client);

  // Take a snapshot
  snapshottedDB = await snapshot(client);
 });

 // Setup a fresh PGLite instance and apply schema before each test
 beforeEach(async () => {
  agent = request(app); // Create supertest agent

  client = await restoreSnapshot(snapshottedDB)

  // Create the Drizzle instance connected to PGLite
  db = drizzle(client, { schema });

  // Mock getDB() to return *this specific test's* Drizzle instance
  // Use `vi.mocked` for type safety
  vi.mocked(getDB).mockReturnValue(db as any);
 });

 // Close the PGLite client and clean up mocks after each test
 afterEach(async () => {
  await client.close(); // Release resources
  vi.clearAllMocks(); // Reset mocks
 });

 // Consider adding cleanup for the data directory if you specified one
 // afterAll

 it("POST /items should create an item", async () => {
  const newItemName = "Test Item PGLite";
  const response = await agent
   .post("/items")
   .send({ name: newItemName })
   .expect(201); // Assert HTTP status code

  expect(response.body.id).toBeDefined();
  expect(response.body.name).toBe(newItemName);

  // Verify directly in the DB for extra confidence
  // And to make sure the snapshot is working
  const dbResult = await db
   .select()
   .from(schema.items);

  expect(dbResult.length).toBe(1);
  expect(dbResult[0].name).toBe(newItemName);
 });

 it("GET /items/:id should retrieve an existing item", async () => {
  // Arrange: Insert an item directly
  const insertResult = await db
   .insert(schema.items)
   .values({ name: "Get Me PGLite" })
   .returning();
  const itemId = insertResult[0].id;

  // Act: Request the item
  const response = await agent.get(`/items/${itemId}`).expect(200);

  // Verify directly in the DB for extra confidence
  // And to make sure the snapshot is working
  const dbResult = await db
   .select()
   .from(schema.items);

  expect(dbResult.length).toBe(1);
  expect(dbResult[0].name).toBe("Get Me PGLite");

  // Assert
  expect(response.body.id).toBe(itemId);
  expect(response.body.name).toBe("Get Me PGLite");
 });
});

Let’s run the benchmarks again!

PGLite (with reusable database):

➜ npm run test

> vitest run

 ✓ src/server.test.ts (4 tests) 1331ms
   ✓ Items API with PGLite > POST /items should create an item 199ms
   ✓ Items API with PGLite > GET /items/:id should retrieve an existing item 192ms
   ✓ Items API with PGLite > GET /items/:id should return 404 for non-existent item 182ms
   ✓ Items API with PGLite > POST /items should return 400 if name is missing 189ms

Using hyperfine for 10 runs:

Time (mean ± σ):      1.940 s ±  0.022 s    [User: 5.570 s, System: 1.289 s]
Range (min … max):    1.911 s …  1.987 s    10 runs

5 BIG BOOMS FOR THIS SPEED! Look at that difference! From ~4.8s with Testcontainers down to ~1.3s with PGLite snapshotting. This is the kind of speed that keeps you in the TDD flow state.

One big caveat is that these are still running sequentially, so with a lot of tests, it could add up and become even slower than the testcontainers version. I’ll make a follow up post on how we could approach architecting our code to make sure it’s testable and parallelizable. Since the current approach relies on mocking global accessors like getDB which make it impossible to parallelize.

Final Thoughts & Caveats

1. Testcontainers is Still Awesome: Let me be clear, testcontainers is a phenomenal tool. For testing against other services (Redis, Kafka, other databases) or when you need the absolute highest fidelity with a specific Postgres version/extension setup provided by Docker, it’s still my go-to. This PGLite approach is specifically optimized for speeding up the Node.js <-> Postgres interaction during TDD experimentation sessions.
2. PGLite Fidelity: While PGLite is running actual Postgres compiled to WASM, it’s newer technology. Be mindful that there could be subtle differences or unsupported features compared to a native Postgres installation or a Docker image. I haven’t hit any issues yet for typical web app CRUD operations, but always test thoroughly and be aware of the possibility. Don’t let flaky tests give you false confidence.
3. Potentionally slower for larger test suites. I am still not certain that this approach scales better than the testcontainers + snapshotting, since the bottleneck in that case is the startup time of the container, while subsequent tests run quite quickly. Not sure if the fs operations and the spinning up of PGlite instances will actually prove to be a bigger bottleneck than the initial startup time of testcontainers. But the big benefit of this approach is that it allows parallel execution of a test suite.

This PGLite + Drizzle + Vitest combination, especially with the snapshotting(-ish) technique, has significantly improved my Node.js TDD experience. It brings back that snappy, responsive feeling I loved from Go (with PGlite it’s even better than Go), making test-driven development truly enjoyable and productive.

Give these amazing projects a star! This workflow wouldn’t be possible without them:

• pglite ⭐
• drizzle-orm ⭐
• vitest ⭐

Bonus Cool Project: (Not sponsored, just want to make it a habit to share a cool project with every post)

• TinaCMS: An open-source, Git-backed headless CMS with visual editing. Really interesting approach if you need content management.

Look, unit tests are great for checking isolated logic. But eventually, you need to know if your code actually works with a real database, message queue, or whatever external service you depend on. Mocking everything is fragile and often hides bugs that only show up when things get real. Shared dev databases? A recipe for flaky tests and stepping on colleagues’ toes.

Coming from Go, I got used to writing integration tests that gave me real confidence. I wanted that same feeling in my TypeScript projects. The answer? Testcontainers.

The Core Idea: Real Dependencies, Isolated Tests

The plan is simple:

1. Spin up real dependencies (like Postgres, Redis, etc.) inside Docker containers for your tests.
2. Use a library like Testcontainers for Node.js to manage these containers programmatically.
3. Run your migrations or setup scripts against the fresh container to establish a baseline state.
4. Snapshot the clean, migrated database state (if your DB module supports it, like @testcontainers/postgresql). Alternatively, investigate the docker commit method if snapshotting isn’t built-in.
5. For each test (or test suite), restore from that snapshot to get a perfectly clean slate, ensuring test isolation.
6. Run your test logic against the application, which talks to the containerized dependency.
7. Tear down the container(s) when done.

This gives you the best of both worlds: the realism of testing against the actual database software you use in production, and the isolation needed for reliable, repeatable tests.

Why not just use SQLite or an in-memory DB?

Because it’s not the same. You might use database-specific features, syntax quirks, or transaction behaviors that SQLite doesn’t replicate. Testing against a different database than production is asking for trouble.

Never use a different DB for development/testing than what you use in production. If you’re using Postgres in prod, use Postgres containers for testing. Don’t cheat with SQLite just because it seems easier. Your ORM won’t save you from every difference.

Let’s Build It: A Simple CRUD Example

We’ll set up a dead simple Express app with basic CRUD operations for “items” stored in a Postgres database. Then, we’ll write integration tests for it using Vitest and Testcontainers.

(You can find the complete project code over at github)

1. Project Setup

Make sure you have Node.js and Docker installed.

mkdir node-testcontainers-example
cd node-testcontainers-example
npm init -y
npm install express pg # Or your preferred framework/DB driver
npm install -D typescript @types/node @types/express @types/pg ts-node nodemon vitest testcontainers @testcontainers/postgresql # Dev dependencies
# Initialize tsconfig.json
npx tsc --init --rootDir src --outDir dist --esModuleInterop --resolveJsonModule --lib esnext --module nodenext --allowJs true --noImplicitAny true

Create a simple src/server.ts:

import express, { type Response, type Request } from "express";
import { getDB } from "./db";

const app = express();
app.use(express.json());

app.post("/items", async (req: Request, res: Response) => {
 const { name } = req.body;
 if (!name) {
  res.status(400).send({ error: "Name is required" });
  return;
 }
 try {
  const db = getDB();
  const result = await db.query(
   "INSERT INTO items(name) VALUES($1) RETURNING *",
   [name],
  );
  res.status(201).send(result.rows[0]); 
 } catch (err) {
  console.error(err);
  res.status(500).send({ error: "Failed to create item" }); 
 }
});

app.get("/items/:id", async (req: Request, res: Response) => {
 const { id } = req.params;
 try {
  const db = getDB();
  const result = await db.query("SELECT * FROM items WHERE id = $1", [id]);
  if (result.rows.length === 0) {
   res.status(404).send({ error: "Item not found" });
   return;
  }
  res.send(result.rows[0]); 
 } catch (err) {
  console.error(err);
  res.status(500).send({ error: "Failed to retrieve item" }); 
 }
});

// Only start listening if the file is run directly
if (require.main === module) {
 const port = process.env.PORT || 3000;
 app.listen(port, () => {
  console.log(`Server listening on port ${port}`);
  // You'd typically run migrations here on real app startup
  // For this example, we assume the table exists or is created by tests/manually
 });
}

export default app;

And src/db.ts:

import { Pool } from 'pg';

// Default connection for manual running or real deployment
const pool = new Pool({
 connectionString: process.env.DATABASE_URL || 'postgresql://postgres:postgres@localhost:5432/postgres',
});

// We export a function to get the pool. This allows us to easily mock
// it in tests to point to our Testcontainers-managed database instead.
export const getDB = () => pool;

Manual Verification (Optional)

To verify our server manually, we’d first need a running Postgres instance and the items table created. You could achieve this using Docker:

# Start a Postgres container
docker run -d \
  --name my-pg-container \
  -e POSTGRES_PASSWORD=postgres \
  -p 5432:5432 \
  postgres:17

# Execute the CREATE TABLE command inside the container
docker exec -it my-pg-container psql -U postgres -d postgres -c "CREATE TABLE IF NOT EXISTS items (id SERIAL PRIMARY KEY, name VARCHAR(100) NOT NULL);"

Then, add a start script to package.json:

  "scripts": {
    "start": "tsc && node ./dist/server.js"
  }

Start the server (npm start) and use curl to interact with it:

➜ npm start
> tsc && node ./dist/server.js

Server listening on port 3000

➜ curl -X POST http://localhost:3000/items -H "Content-Type: application/json" -d '{"name": "do the dishes"}'
> {"id":1,"name":"do the dishes"}

➜ curl http://localhost:3000/items/1
> {"id":1,"name":"do the dishes"}

This works, but manually managing the database for testing is cumbersome and error-prone. Let’s automate it. (Remember to stop and remove the manual container: docker stop my-pg-container && docker rm my-pg-container)

Automated Testing with Testcontainers

Add a vitest.config.ts:

// vitest.config.ts
import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    globals: true, // Use Vitest globals (describe, it, etc.)
    setupFiles: [], // Optional: setup files for tests
    environment: 'node', // Specify Node environment
    // Increase timeout for container startup, snapshotting etc.
    testTimeout: 60000, // 60 seconds
    hookTimeout: 60000, // 60 seconds for hooks too
  },
});

2. The Test Helper (PostgresContainerManager)

Managing the container lifecycle (start, migrate, snapshot, restore, stop) and ensuring a clean database state for each test can be repetitive. Let’s encapsulate this logic in a PostgresContainerManager helper class. This class will handle starting a Postgres container, running initial migrations within it, creating a baseline snapshot of that state, and providing functions to get a fresh database connection reset to that baseline for each test.

Heads up: The snapshot feature requires testcontainers version 10.23.0 or later for the Postgres module (check your package.json!).

// src/testing/db-helper.ts
import { PostgreSqlContainer, type StartedPostgreSqlContainer } from '@testcontainers/postgresql';
import { Client, Pool, type PoolClient } from 'pg';

// Interface for what setupTestDatabase will return
export interface TestDatabase {
 db: PoolClient; // Test should use this client
 container: StartedPostgreSqlContainer; // Reference to the container
 cleanup: () => Promise<void>; // Function to release the client/pool
}

// Manages the PostgreSQL container lifecycle for tests
export class PostgresContainerManager {
 private static instance: PostgresContainerManager | null = null;
 private container: StartedPostgreSqlContainer | null = null;
 private snapshotName = 'clean-db-snapshot'; // Name for our baseline snapshot

 // Singleton pattern to potentially share container across test suites (though we scope it per-file here)
 private constructor() { }

 public static getInstance(): PostgresContainerManager {
  if (!PostgresContainerManager.instance) {
   PostgresContainerManager.instance = new PostgresContainerManager();
  }
  return PostgresContainerManager.instance;
 }

 // Starts container, runs migrations *in* the container DB, takes snapshot
 async initialize(): Promise<void> {
  if (this.container) {
   console.log('Container already initialized.');
   return;
  }

  console.log('Starting PostgreSQL container...');
  this.container = await new PostgreSqlContainer('postgres:17')
   .withDatabase('test') // Use a specific DB name for testing
   .withUsername('test-user')
   .withPassword('test-password')
   .withExposedPorts(5432)
   .start();
  console.log(`Container started on port ${this.container.getMappedPort(5432)}`);

  // Connect directly to the containerized database to run migrations
  const migrationClient = new Client({ connectionString: this.container.getConnectionUri() });
  await migrationClient.connect();
  try {
   console.log("Running migrations...");
   // In a real app, use your migration tool (node-pg-migrate, TypeORM migrations, etc.)
   // For this example, we create the table directly:
   await migrationClient.query(`
                CREATE TABLE items (
                    id SERIAL PRIMARY KEY,
                    name VARCHAR(100) NOT NULL
                );
            `);
   console.log('Migrations complete.');
  } catch (error) {
   console.error('Migration failed:', error);
   throw error; // Fail fast if migrations don't work
  } finally {
   await migrationClient.end();
  }

  // Take a snapshot of the database state *after* migrations
  console.log(`Taking snapshot '${this.snapshotName}'...`);
  await this.container.snapshot(this.snapshotName);
  console.log('Snapshot taken.');
 }

 // Restores the 'clean' snapshot and provides a connection pool/client
 async setupTestDatabase(): Promise<TestDatabase> {
  if (!this.container) {
   throw new Error('Container not initialized. Call initialize() first.');
  }

  try {
   // Restore the database to the state captured in the snapshot
   console.log(`Restoring snapshot '${this.snapshotName}'...`);
   await this.container.restoreSnapshot(this.snapshotName);
   console.log('Snapshot restored.');

   // Create a *new pool* connecting to the restored database for this test
   // This ensures connection isolation if tests run concurrently within the same file (though less common)
   const testPool = new Pool({ connectionString: this.container.getConnectionUri() });
   const testClient = await testPool.connect(); // Get a client for the test

   // Cleanup function specific to this test's pool/client
   const cleanup = async () => {
    try {
     await testClient.release(); // Release client back to pool
     await testPool.end();      // Close the pool
    } catch (error) {
     console.error('Error during test DB cleanup:', error);
    }
   };

   return {
    db: testClient, // Provide the client to the test
    container: this.container,
    cleanup,
   };
  } catch (error) {
   console.error('Error setting up test database:', error);
   throw error;
  }
 }

 // Stops and removes the container
 async teardown(): Promise<void> {
  if (this.container) {
   console.log('Stopping PostgreSQL container...');
   await this.container.stop();
   this.container = null;
   console.log('Container stopped.');
  }
  PostgresContainerManager.instance = null; // Reset singleton state
 }
}

3. Writing the Integration Test

Now, let’s write the integration test using Vitest and our helper. We’ll use supertest to make HTTP requests to our Express app. The key parts are:

• Mocking our db.ts module so the application uses the test database connection provided by the helper (testDb.db).
• Using Vitest hooks (beforeAll, afterAll, beforeEach, afterEach) to manage the container lifecycle and ensure test isolation via snapshot restoration.
• Note: Using beforeAll/afterAll within the test file means Vitest’s default parallel execution (by file) will likely spin up one independent container per test file, providing strong isolation but potentially using more resources.

// src/server.test.ts
import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest';
import request from 'supertest'; // For making HTTP requests
import type TestAgent from 'supertest/lib/agent'; // Type for supertest agent
import app from './server'; // Our Express app
import { getDB } from './db'; // The function we need to mock
import { PostgresContainerManager, type TestDatabase } from './testing/db-helper'; // Our helper

// This is crucial: tell Vitest to replace the real './db' module
// with our mock, so we can control what getDB() returns in tests.
vi.mock('./db');

describe('Items API', () => {
 const containerManager = PostgresContainerManager.getInstance();
 let testDb: TestDatabase; // Will hold the connection/cleanup func for each test
 let agent: TestAgent;     // Supertest agent for making requests

 // Start the single container ONCE before all tests in this file
 beforeAll(async () => {
  await containerManager.initialize();
  agent = request(app); // Create supertest agent targeting our app
 }, 60000); // Increase timeout for container init

 // Restore snapshot and get a fresh DB connection BEFORE EACH test
 beforeEach(async () => {
  testDb = await containerManager.setupTestDatabase();
  // Point the mocked getDB function to return our test database client
  vi.mocked(getDB).mockReturnValue(testDb.db); 
 });

 // Clean up the test database connection AFTER EACH test
 afterEach(async () => {
  await testDb.cleanup(); // Release pool client and end pool
  vi.clearAllMocks();     // Reset mocks between tests
 });

 // Stop the single container ONCE after all tests in this file are done
 afterAll(async () => {
  await containerManager.teardown();
 }, 60000); // Increase timeout for container teardown

 it('POST /items should create an item', async () => {
  const newItemName = 'Test Item 1';
  const response = await agent
   .post('/items')
   .send({ name: newItemName })
   .expect(201); // Assert HTTP status code

  // Assert response body
  expect(response.body.id).toBeDefined();
  expect(response.body.name).toBe(newItemName);

  // Optional but recommended: Verify directly in the DB
  const dbResult = await testDb.db.query('SELECT * FROM items WHERE id = $1', [response.body.id]);
  expect(dbResult.rows.length).toBe(1);
  expect(dbResult.rows[0].name).toBe(newItemName);
 });

 it('GET /items/:id should retrieve an existing item', async () => {
  // Arrange: Insert an item directly using the test DB client
  const insertResult = await testDb.db.query("INSERT INTO items(name) VALUES('Get Me') RETURNING id");
  const itemId = insertResult.rows[0].id;

  // Act: Make request to the API endpoint
  const response = await agent
   .get(`/items/${itemId}`)
   .expect(200);

  // Assert
  expect(response.body.id).toBe(itemId);
  expect(response.body.name).toBe('Get Me');
 });

 it('GET /items/:id should return 404 for non-existent item', async () => {
  await agent
   .get('/items/99999') // Use an ID that almost certainly won't exist
   .expect(404);
 });

 it('POST /items should return 400 if name is missing', async () => {
  await agent
   .post('/items')
   .send({}) // Send empty body
   .expect(400);
 });
});

4. Running the Tests

Add test scripts to your package.json:

{
  "scripts": {
    "start": "tsc && node ./dist/server.js",
    "test": "vitest run",
    "test:watch": "vitest"
    // ... other scripts
  }
}

Now run:

npm test

You should see Vitest start, the helper log messages about starting the container, running migrations, taking/restoring snapshots, and finally the test results passing.

Leveling Up

1. Speeding Up Slow Migrations

If your migrations take a long time to run, the initial initialize step can become a bottleneck. The snapshot helps for subsequent test runs, but the first one is still slow.

Solution: Pre-build a Docker image with migrations already applied.

1. Start a standard Postgres container manually: docker run -d --name postgres-migrated -e POSTGRES_PASSWORD=password postgres:17

2. Connect to it and run your migrations.

3. Commit the container state to a new image: docker commit postgres-migrated my-app/postgres-migrated:latest

4. Stop and remove the temporary container: docker stop postgres-migrated && docker rm postgres-migrated

5. In your PostgresContainerManager, change the image name:

   // In initialize()
   this.container = await new PostgreSqlContainer('my-app/postgres-migrated:latest') // Use your committed image
       // .withDatabase(...) // Ensure user/pass match how you set it up
       // ... rest of setup ...
       .start();
   
   // You can likely SKIP the migration running step and snapshotting
   // if the image already represents the clean, migrated state.
   // Just start the container and proceed to setupTestDatabase.
   // You might need a different helper logic for pre-built images.
   // Remember to adjust initialize() to skip migrations/snapshotting if using this.
   

docker commit creates an image from a container’s filesystem state. It’s generally better for capturing installed software or data setup (like migrations) than for runtime state. Check the Docker commit docs for details.

Trade-offs: Faster test startup vs. managing another custom Docker image in your build process.

2. Running Tests in Parallel

Vitest runs test files in parallel by default. Because our PostgresContainerManager setup (beforeAll/afterAll) is scoped within a test suite, each test suite that follows this pattern will get its own independent Docker container.

• Pro: True parallelism, maximum isolation between test suites.
• Con: Resource intensive. If you have many test files, you’ll be running many database containers simultaneously. Make sure your machine (and CI environment) can handle it.

If resource usage is a major concern, you could explore:

• Shared Container, Schemas/DBs per Test File: Modify the PostgresContainerManager to be a true singleton across the entire test run (e.g., using Vitest’s global setup). In setupTestDatabase, instead of restoring a snapshot (which resets the whole DB), you might create a unique schema or entirely new database within the single container for each test file (or even each describe block).
• Vitest --no-parallel or --max-workers: Force sequential execution or limit concurrency if parallelism causes issues or consumes too many resources.
• Using technologies like PGLite, (stay tuned for the next post ;) )

Pros and Cons Recap

Pros:

• High Confidence: You’re testing against the real database system.
• Catches Integration Bugs: Finds issues related to database interactions, transactions, constraints, etc., that mocks miss.
• Realistic Environment: Mimics production dependencies more closely.
• Isolated & Repeatable: Each test gets a clean slate via snapshot restore, avoiding flakiness.

Cons:

• Slower than Unit Tests: Starting containers and interacting with a real DB takes more time.
• Resource Usage: Docker containers consume CPU, RAM, and disk space, especially when ran in parallel.
• Dependency on Docker: Requires Docker to be installed and running where tests execute (local dev, CI).

Conclusion

Setting up integration tests with Testcontainers is something I’ve been incorporating into every project I am starting nowadays with Node.js, it gives me great velocity while developing and ease of mind when refactoring. The payoff in confidence and catching real-world bugs is huge. By managing container lifecycles programmatically and ensuring clean state via snapshots or unique databases per test, you can build a robust, reliable integration test suite for your Node.js applications. I’d even argue that this is actually simpler than mocking since there isn’t a good way (that I am aware of) to properly mock these database interactions without using an ORM that supports it or mocking the data layer representation you’re using (store/repository/dao’s)

Stop guessing if your database interaction code works – test it properly.

Give these amazing projects a star! This workflow wouldn’t be possible without them:

• vitest ⭐
• testcontainers-node ⭐

Bonus Cool Project: (Not sponsored, just want to make it a habit to share a cool project with every post)

• WebTUI: An open-source, modular CSS Library that brings the beauty of Terminal UIs to the browser