Isolating Integration Tests

Sam Adams — Fri, 04 Jul 2025 05:57:12 +0000

When we write integration tests at Super we follow some principles:

Each test should work independently of any other test
It should only act and assert at the boundary of the service (i.e. how the service is interacted with by other services or users)

In practice this means we have to do some work to manage isolation (or lack of state-bleed) between each test.

(Note: if you want to skip to a working code example here is an example repo: https://github.com/sam-super/example-db-test-isolation)

When thinking about isolation it's handy to have a good mental model of how tests are executed in the most popular testing frameworks:

This means our test suites run in parallel, but (by default) each test in the suite run in sequence). So it's important that we use this model to make sure our tests can run in parallel and stay isolated.

Below is an example of testing a simple fastify app that has a DB with a single table for cars:

So for example:

import {FastifyInstance} from "fastify";
import knexFactory, {Knex} from "knex";
import {$} from 'execa';
import {buildApp} from "../src/app";
import {expect} from 'expect';
import {Client} from "pg";
import {randomString} from "./helpers/utils";

async function startContainers() {
  await $`docker compose up --remove-orphans --wait -d postgres`;
}

async function initDb(testSpecificDbName: string) {
  const start = Date.now();

  const connOpts = {
    // these need to match your docker-compose.yml
    host: '127.0.0.1',
    port: 54323,
    password: 'whatever',
    user: 'root',
  };
  const client = new Client({
    database: 'postgres',
    ...connOpts,
  });
  await client.connect();
  await client.query('CREATE DATABASE ' + testSpecificDbName);
  await client.end();

  const knex = knexFactory({
    client: 'pg',
    connection: {
      ...connOpts,
      database: testSpecificDbName,
    },
    migrations: {
      directory: __dirname + '/../src/migrations',
      tableName: 'knex_migrations',
    }
  });

  await knex.migrate.latest();

  console.log(`Created DB ${testSpecificDbName} (in ${(Date.now() - start) / 1000}s)`);
  return knex;
}

describe('cars api', function () {
  let app: FastifyInstance;
  let knex: Knex;

  before(async function () {
    await startContainers();
  });
  beforeEach(async function () {
    process.env.DB_NAME = `test_${Date.now()}_${randomString()}`;
    knex = await initDb(process.env.DB_NAME);
    app = buildApp(knex);
  });
  afterEach(async function () {
    await app.close();
    await knex.destroy();
  })

  it('can get a car it creates', async function () {
    const postRes = await app
      .inject()
      .post('/cars')
      .headers({'content-type': 'application/json'})
      .body({make: 'ford'});
    expect(postRes.statusCode).toEqual(200);
    expect(postRes.json()).toEqual({make: 'ford'});

    const getRes = await app
      .inject()
      .get('/cars')
      .headers({'content-type': 'application/json'});
    expect(getRes.statusCode).toEqual(200);
    expect(getRes.json()).toEqual([{make: 'ford'}]);
  });

  it('gets no cars if none created', async function () {
    const getRes = await app
      .inject()
      .get('/cars')
      .headers({'content-type': 'application/json'});
    expect(getRes.statusCode).toEqual(200);
    expect(getRes.json()).toEqual([]);
  });
});

What is this doing:

once, before any tests run, we start our containers (postgres - see docker compose file in GH repo)
before each test we create a new database with a random name and run the knex migrations (which creates the 'cars' table).
create a new instance of the fastify app (which is bound to the random db name/instance)
make requests to our api using the inbuilt .inject() method to issue http requests to fastify (without having to start a http server)
we can see the second test doesn't have the state (db row) created in the first test (otherwise it would fail)

In future articles we can go into more depth on how to optimize our tests and how we work with isolation when using localstack (dynamo, sqs queues etc).

FAQs

Why not just re-use the same database?

We could re-use the same db for each test and truncate the data between each test. We have to be careful tho, because, although in our example we have a single test file/suite, in practice we want our suites to be able to run in parallel. When we have many test-suites, it is advantageous to re-use databases on a per-thread basis (to save the time to create/migrating the DB) and then just truncate the tables between tests.

Isn't this slow?

On an M1 Macbook it's about 10ms to create each DB and run the migrations. It's only 1 migration, and as the number grows so will the time. However, for us it's worth the trade of for what we are trying to achieve and the guaranteed isolation it gives us.
There are also a few strategies to speed it up:

As above we can re-use databases per-worker-thread
we can maintain a single sql dump file (generated from the migrations themselves) and use it populate the databases on creation (rather than running each individual migration).

Shouldn't you be deleting the DBs and removing the containers at the end?

Re-using the containers speeds up our tests (postgres is fast to start, but it helps a lot if you have something like localstack which takes a while to start). Since our tests are isolated, it shouldn't matter what state we leave lying around on our containers. Eventually we could fill up the disk with all our test DBs, but that will take a long time and is easily fixed by killing our containers: docker compose down -v. Then next test run will bring up clean containers.

There is also the added benefit of having the DB left around after each test to manually inspect after a failed test run.

Backend Testing At Super Payments

Sam Adams — Fri, 04 Jul 2025 05:33:25 +0000

At Super Payment we adopt an "integration-first" testing methodology, with unit/e2e style tests being applied more sparingly.

If you want to read more on why we prefer integration tests to unit/e2e tests then Kent Dodds has done a much better job than I will on explaining the rationale.

To understand how our integration tests work at Super, we need to know a bit more about our architecture:

Architecture

At Super, our services are written in TypeScript and each service encompasses a given domain. Each service has it's own DB, SQS queue and EventBridge Bus (or whichever subset it needs).

The main way for our services to talk to each other internally is via EventBridge/SQS messages, where EB receives messages as the output of the producing system, and the consuming system binds the EB messages it's interested in to it's own, dedicated SQS queue for consumption.

The main way the outside world (customer, third-parties etc) interact with Super is via HTTP (or a partner EventBridge).

Integration Tests

When we say 'integration test' we mean hitting a single service with some real-world input (an event or HTTP request) to see what outputs/side-effects occur.

Since most of our services follow the same set of inputs (HTTP/SQS) and outputs (HTTP/EventBridge), our tests try to only act and assert on those inputs and outputs (ignoring 'how' the service works internally).

A typical integration test at Super looks like this:

start supporting containers (postgres and localstack)
start the app (we use NestJS with fastify)
spin up a new clean DB for that test (we use Knex migrations)
use nock to intercept all network requests
make HTTP requests to the app and/or send SQS events
assert on what happened

We can assert on:

the HTTP requests we made to third-party APIs (nock)
the events we sent (using nock to monitor the EventBridge requests)
that the SQS queue has been processed/is empty (by directly calling localstack with the AWS-SQS SDK)
the database state (if we have to)
the response from our starting HTTP request

Since our tests are fully stateful (but fully isolated from other tests) we can see how changes to inputs affect outputs.

In this series we will dig into the finer details on the above, specifically on how we isolate our tests (while keeping them fast).

Forem: Sam Adams