Integration Testing Best Practices and Avoiding Flaky Tests

1beforeEach(async () => {
2  // Fast: < 10ms for small schemas
3  await prisma.$executeRaw`TRUNCATE "User", "Course", "Enrollment" CASCADE`;
4});
5// Pros: simple, reliable, works with all async patterns
6// Cons: slightly slower than rollback for schemas with 20+ tables

1let transactionClient: PrismaClient;
2
3beforeEach(async () => {
4  // Start a transaction that wraps the test
5  transactionClient = await prisma.$begin();
6});
7
8afterEach(async () => {
9  await transactionClient.$rollback();
10});
11// Pros: < 1ms overhead, no table locks
12// Cons: test code must use transactionClient, not the global prisma instance
13// Does NOT work if the code under test manages its own transactions

1// Each test file gets its own database name
2const dbName = `test_${process.env['JEST_WORKER_ID']}_${Date.now()}`;
3// Pros: complete isolation, can parallelise freely
4// Cons: slow setup (migration per DB), high resource usage
5// Use only when tests genuinely cannot share a database

1# Run tests in random order to detect order-dependency
2npx jest --randomize --runInBand
3
4# Run a single test file 20 times to detect timing-dependent failures
5npx jest src/users/users.integration.test.ts --count=20
6
7# Run with verbose timing to identify suspiciously slow tests
8npx jest --verbose --detectOpenHandles

1// CAUSE 1: Shared database state between tests
2// Symptom: test passes alone, fails in suite
3// Fix: ensure beforeEach TRUNCATE runs before ALL tests, not just some
4
5// CAUSE 2: Missing await on async database operations
6beforeEach(async () => {
7  prisma.user.deleteMany();  // MISSING AWAIT — test starts before cleanup
8});
9// Fix:
10beforeEach(async () => {
11  await prisma.user.deleteMany();  // correct
12});
13
14// CAUSE 3: Time-dependent assertions
15test('returns recent orders', async () => {
16  const order = await createOrder(prisma, { createdAt: new Date() });
17  const res = await request(app).get('/orders/recent');
18  // 'recent' = last 24 hours — passes today, may fail tomorrow
19  expect(res.body.map((o: any) => o.id)).toContain(order.id);
20});
21// Fix: seed with explicit, test-controlled timestamps
22test('returns orders from the last 24 hours', async () => {
23  const recent = new Date(Date.now() - 3600_000); // 1 hour ago
24  const old = new Date(Date.now() - 90_000_000);  // > 24 hours ago
25  const recentOrder = await createOrder(prisma, { createdAt: recent });
26  const oldOrder = await createOrder(prisma, { createdAt: old });
27  const res = await request(app).get('/orders/recent');
28  const ids = res.body.map((o: any) => o.id);
29  expect(ids).toContain(recentOrder.id);
30  expect(ids).not.toContain(oldOrder.id);
31});
32
33// CAUSE 4: Port conflicts in parallel tests
34// Fix: never call app.listen() in integration tests
35// Supertest manages the server lifecycle without binding to a port
36// app.getHttpServer() (NestJS) or passing app to request() (Express) both avoid this

1// jest.integration.config.ts
2const config: Config = {
3  // Option 1: single process (safest, slowest)
4  maxWorkers: 1,
5
6  // Option 2: parallel with worker-scoped databases
7  maxWorkers: '50%', // use half the CPU cores
8  globalSetup: './src/test/global-setup.ts', // creates one DB per worker
9};
10
11// global-setup.ts for parallel databases
12export default async function globalSetup() {
13  const workerCount = parseInt(process.env['JEST_WORKER_COUNT'] ?? '1');
14  for (let i = 1; i <= workerCount; i++) {
15    const dbUrl = `postgresql://test:test@localhost:5433/testdb_worker_${i}`;
16    await createDatabase(dbUrl);
17    await runMigrations(dbUrl);
18    // Store in temp file so workers can read their DB URL
19    writeFileSync(`.test-db-worker-${i}.url`, dbUrl);
20  }
21}
22
23// In each test file: use worker-specific database
24import { readFileSync } from 'fs';
25const workerId = process.env['JEST_WORKER_ID'] ?? '1';
26const dbUrl = readFileSync(`.test-db-worker-${workerId}.url`, 'utf8');
27const prisma = new PrismaClient({ datasources: { db: { url: dbUrl } } });
28
29// Option 3: use pg-mem (in-memory Postgres) for read-heavy tests
30import { newDb } from 'pg-mem';
31const db = newDb();
32const { Client } = db.adapters.createPg();
33// Runs entirely in memory — no Docker, no ports, complete parallel safety

1// CORRECT: integration test scope
2// ✅ Does the endpoint return the right status code?
3// ✅ Does the database record get created/updated/deleted?
4// ✅ Does authentication middleware block the right requests?
5// ✅ Do validation errors return the right shape?
6// ✅ Do two modules exchange the right data types?
7// ✅ Are foreign key relationships correctly enforced?
8
9// WRONG: using integration tests for unit-test concerns
10// ❌ Testing every branch of the discount calculation logic via HTTP
11//    (unit test the calculator directly — 100x faster)
12// ❌ Testing every validation error message via HTTP
13//    (unit test the DTO/validator directly)
14// ❌ Testing internal service method call counts
15//    (spy on the real service in a unit test)
16
17// EXAMPLE: the right split
18// Unit test: every discount rule (percentage, fixed, free-shipping, expiry, limit)
19// Integration test: POST /checkout applies a coupon and returns the discounted total
20//   — one happy-path test and one invalid-coupon test is sufficient
21
22// ANTI-PATTERN: exhaustive integration tests
23describe('POST /checkout (exhaustive — DON\'T DO THIS)', () => {
24  it('applies 10% discount for SAVE10 coupon', ...);
25  it('applies 20% discount for SAVE20 coupon', ...);
26  it('applies 50% discount for HALFOFF coupon', ...);
27  it('applies free shipping for FREESHIP coupon', ...);
28  it('rejects expired coupon', ...);
29  it('rejects coupon at usage limit', ...);
30  // ... 20 more tests — all slow integration tests for pure logic
31  // These should ALL be unit tests on the discount calculator
32});
33
34// CORRECT: minimal integration surface
35describe('POST /checkout (integration — DO THIS)', () => {
36  it('returns 200 with discounted total when valid coupon is applied', ...);
37  it('returns 422 with error message when coupon is invalid', ...);
38  // Two tests — the discount rules are covered by unit tests
39});

1# .github/workflows/integration-tests.yml
2name: Integration Tests
3
4on:
5  pull_request:
6    branches: [main, develop]
7
8jobs:
9  integration:
10    runs-on: ubuntu-latest
11    timeout-minutes: 15  # fail the job if tests hang
12
13    services:
14      postgres:
15        image: postgres:16-alpine
16        env:
17          POSTGRES_USER: test
18          POSTGRES_PASSWORD: test
19          POSTGRES_DB: testdb
20        ports:
21          - 5433:5432
22        options: >-
23          --health-cmd pg_isready
24          --health-interval 5s
25          --health-timeout 5s
26          --health-retries 5
27
28    steps:
29      - uses: actions/checkout@v4
30
31      - uses: actions/setup-node@v4
32        with:
33          node-version: '20'
34          cache: 'npm'
35
36      - run: npm ci
37
38      - name: Run database migrations
39        run: npx prisma migrate deploy
40        env:
41          DATABASE_URL: postgresql://test:test@localhost:5433/testdb
42
43      - name: Run integration tests
44        run: npm run test:integration
45        env:
46          TEST_DATABASE_URL: postgresql://test:test@localhost:5433/testdb
47          JWT_SECRET: ci-test-secret
48          NODE_ENV: test
49          # Set a shorter timeout per test for CI
50          JEST_TIMEOUT: 15000
51
52      - uses: actions/upload-artifact@v4
53        if: failure()
54        with:
55          name: integration-test-results
56          path: test-results/