Part 3: Integration Testing

Introduction

Integration tests verify that different components of your system work together correctly. While unit tests check individual functions in isolation, integration tests ensure components interact properly—database operations, API calls, message queues, and external services.

In my TypeScript microservices, integration tests have caught countless bugs that unit tests missed: incorrect SQL queries, misconfigured database connections, serialization issues, and timing problems.

What is Integration Testing?

Integration testing focuses on:

• Component interactions - How services communicate

• Data persistence - Database read/write operations

• External services - APIs, message queues, caches

• Configuration - Environment-specific settings

• Data flow - Information moving between layers

Example Architecture

┌─────────────┐
│   API Layer │
└──────┬──────┘
       │
┌──────▼───────┐
│ Service Layer│
└──────┬───────┘
       │
┌──────▼────────┐
│Repository Layer│
└──────┬────────┘
       │
┌──────▼───────┐
│   Database   │
└──────────────┘

Integration tests verify each layer communicates correctly.

Database Integration Testing

Setting Up Test Database

I use a separate test database for integration tests:

database.config.ts:

// src/config/database.config.ts
import { Pool } from 'pg';

export interface DatabaseConfig {
  host: string;
  port: number;
  database: string;
  user: string;
  password: string;
}

export class Database {
  private pool: Pool;

  constructor(config: DatabaseConfig) {
    this.pool = new Pool(config);
  }

  async query<T>(sql: string, params?: any[]): Promise<T[]> {
    const result = await this.pool.query(sql, params);
    return result.rows;
  }

  async close(): Promise<void> {
    await this.pool.end();
  }
}

// Factory functions
export function createDatabase(config: DatabaseConfig): Database {
  return new Database(config);
}

export function createTestDatabase(): Database {
  return createDatabase({
    host: process.env.TEST_DB_HOST || 'localhost',
    port: parseInt(process.env.TEST_DB_PORT || '5432'),
    database: process.env.TEST_DB_NAME || 'test_db',
    user: process.env.TEST_DB_USER || 'test_user',
    password: process.env.TEST_DB_PASSWORD || 'test_password',
  });
}

Repository Integration Tests

user-repository.ts:

// src/repositories/user-repository.ts
import { Database } from '../config/database.config';

export interface User {
  id: string;
  email: string;
  name: string;
  created_at: Date;
  updated_at: Date;
}

export interface CreateUserDto {
  id: string;
  email: string;
  name: string;
}

export class UserRepository {
  constructor(private readonly db: Database) {}

  async create(dto: CreateUserDto): Promise<User> {
    const now = new Date();
    const result = await this.db.query<User>(
      `INSERT INTO users (id, email, name, created_at, updated_at)
       VALUES ($1, $2, $3, $4, $5)
       RETURNING *`,
      [dto.id, dto.email, dto.name, now, now]
    );

    if (result.length === 0) {
      throw new Error('Failed to create user');
    }

    return result[0];
  }

  async findById(id: string): Promise<User | null> {
    const result = await this.db.query<User>(
      'SELECT * FROM users WHERE id = $1',
      [id]
    );
    return result[0] || null;
  }

  async findByEmail(email: string): Promise<User | null> {
    const result = await this.db.query<User>(
      'SELECT * FROM users WHERE email = $1',
      [email]
    );
    return result[0] || null;
  }

  async update(id: string, updates: Partial<User>): Promise<User> {
    const fields = Object.keys(updates)
      .map((key, index) => `${key} = $${index + 2}`)
      .join(', ');

    const values = Object.values(updates);

    const result = await this.db.query<User>(
      `UPDATE users SET ${fields}, updated_at = $${values.length + 2}
       WHERE id = $1
       RETURNING *`,
      [id, ...values, new Date()]
    );

    if (result.length === 0) {
      throw new Error(`User not found: ${id}`);
    }

    return result[0];
  }

  async delete(id: string): Promise<void> {
    await this.db.query('DELETE FROM users WHERE id = $1', [id]);
  }
}

Integration tests:

// src/repositories/__tests__/user-repository.integration.test.ts
import { v4 as uuidv4 } from 'uuid';
import { Database, createTestDatabase } from '../../config/database.config';
import { UserRepository } from '../user-repository';

describe('UserRepository Integration Tests', () => {
  let db: Database;
  let repository: UserRepository;

  beforeAll(async () => {
    // Connect to test database
    db = createTestDatabase();
    repository = new UserRepository(db);

    // Create schema
    await db.query(`
      CREATE TABLE IF NOT EXISTS users (
        id VARCHAR(36) PRIMARY KEY,
        email VARCHAR(255) UNIQUE NOT NULL,
        name VARCHAR(255) NOT NULL,
        created_at TIMESTAMP NOT NULL,
        updated_at TIMESTAMP NOT NULL
      )
    `);
  });

  afterAll(async () => {
    // Clean up
    await db.query('DROP TABLE IF EXISTS users');
    await db.close();
  });

  beforeEach(async () => {
    // Clear data before each test
    await db.query('TRUNCATE users CASCADE');
  });

  describe('create', () => {
    it('should create user in database', async () => {
      const dto = {
        id: uuidv4(),
        email: '[email protected]',
        name: 'Test User',
      };

      const user = await repository.create(dto);

      expect(user.id).toBe(dto.id);
      expect(user.email).toBe(dto.email);
      expect(user.name).toBe(dto.name);
      expect(user.created_at).toBeInstanceOf(Date);
      expect(user.updated_at).toBeInstanceOf(Date);
    });

    it('should enforce unique email constraint', async () => {
      const dto = {
        id: uuidv4(),
        email: '[email protected]',
        name: 'Test User',
      };

      await repository.create(dto);

      // Try to create another user with same email
      const duplicateDto = {
        id: uuidv4(),
        email: '[email protected]', // Same email
        name: 'Another User',
      };

      await expect(repository.create(duplicateDto)).rejects.toThrow();
    });
  });

  describe('findById', () => {
    it('should find existing user', async () => {
      const dto = {
        id: uuidv4(),
        email: '[email protected]',
        name: 'Test User',
      };

      await repository.create(dto);
      const found = await repository.findById(dto.id);

      expect(found).toBeDefined();
      expect(found?.id).toBe(dto.id);
      expect(found?.email).toBe(dto.email);
    });

    it('should return null for non-existent user', async () => {
      const found = await repository.findById('non-existent-id');
      expect(found).toBeNull();
    });
  });

  describe('findByEmail', () => {
    it('should find user by email', async () => {
      const dto = {
        id: uuidv4(),
        email: '[email protected]',
        name: 'Test User',
      };

      await repository.create(dto);
      const found = await repository.findByEmail(dto.email);

      expect(found).toBeDefined();
      expect(found?.email).toBe(dto.email);
    });

    it('should return null for non-existent email', async () => {
      const found = await repository.findByEmail('[email protected]');
      expect(found).toBeNull();
    });
  });

  describe('update', () => {
    it('should update user fields', async () => {
      const dto = {
        id: uuidv4(),
        email: '[email protected]',
        name: 'Original Name',
      };

      await repository.create(dto);

      const updated = await repository.update(dto.id, {
        name: 'Updated Name',
      });

      expect(updated.name).toBe('Updated Name');
      expect(updated.email).toBe(dto.email); // Unchanged
      expect(updated.updated_at.getTime()).toBeGreaterThan(
        updated.created_at.getTime()
      );
    });

    it('should throw error when updating non-existent user', async () => {
      await expect(
        repository.update('non-existent-id', { name: 'New Name' })
      ).rejects.toThrow('User not found');
    });
  });

  describe('delete', () => {
    it('should delete user', async () => {
      const dto = {
        id: uuidv4(),
        email: '[email protected]',
        name: 'Test User',
      };

      await repository.create(dto);
      await repository.delete(dto.id);

      const found = await repository.findById(dto.id);
      expect(found).toBeNull();
    });
  });
});

Service Layer Integration Tests

Service layer integration tests verify business logic with real dependencies.

order-service.ts:

// src/services/order-service.ts
import { v4 as uuidv4 } from 'uuid';
import { OrderRepository } from '../repositories/order-repository';
import { ProductRepository } from '../repositories/product-repository';
import { InventoryService } from './inventory-service';

export interface OrderItem {
  productId: string;
  quantity: number;
  price: number;
}

export interface CreateOrderDto {
  userId: string;
  items: OrderItem[];
}

export interface Order {
  id: string;
  userId: string;
  items: OrderItem[];
  total: number;
  status: 'pending' | 'confirmed' | 'cancelled';
  createdAt: Date;
}

export class OrderService {
  constructor(
    private readonly orderRepository: OrderRepository,
    private readonly productRepository: ProductRepository,
    private readonly inventoryService: InventoryService
  ) {}

  async createOrder(dto: CreateOrderDto): Promise<Order> {
    // Validate items exist and prices are current
    for (const item of dto.items) {
      const product = await this.productRepository.findById(item.productId);
      if (!product) {
        throw new Error(`Product not found: ${item.productId}`);
      }

      // Verify price matches current product price
      if (item.price !== product.price) {
        throw new Error(`Price mismatch for product: ${item.productId}`);
      }

      // Check inventory
      const available = await this.inventoryService.checkAvailability(
        item.productId,
        item.quantity
      );

      if (!available) {
        throw new Error(`Insufficient inventory for: ${product.name}`);
      }
    }

    // Calculate total
    const total = dto.items.reduce((sum, item) => {
      return sum + item.price * item.quantity;
    }, 0);

    // Reserve inventory
    for (const item of dto.items) {
      await this.inventoryService.reserve(item.productId, item.quantity);
    }

    // Create order
    const order: Order = {
      id: uuidv4(),
      userId: dto.userId,
      items: dto.items,
      total,
      status: 'pending',
      createdAt: new Date(),
    };

    await this.orderRepository.save(order);
    return order;
  }

  async confirmOrder(orderId: string): Promise<Order> {
    const order = await this.orderRepository.findById(orderId);
    if (!order) {
      throw new Error(`Order not found: ${orderId}`);
    }

    if (order.status !== 'pending') {
      throw new Error(`Cannot confirm order with status: ${order.status}`);
    }

    // Deduct inventory
    for (const item of order.items) {
      await this.inventoryService.deduct(item.productId, item.quantity);
    }

    order.status = 'confirmed';
    await this.orderRepository.update(order);
    return order;
  }
}

Integration tests:

// src/services/__tests__/order-service.integration.test.ts
import { v4 as uuidv4 } from 'uuid';
import { Database, createTestDatabase } from '../../config/database.config';
import { OrderService } from '../order-service';
import { OrderRepository } from '../../repositories/order-repository';
import { ProductRepository } from '../../repositories/product-repository';
import { InventoryService } from '../inventory-service';
import { InventoryRepository } from '../../repositories/inventory-repository';

describe('OrderService Integration Tests', () => {
  let db: Database;
  let orderService: OrderService;
  let orderRepository: OrderRepository;
  let productRepository: ProductRepository;
  let inventoryService: InventoryService;
  let inventoryRepository: InventoryRepository;

  beforeAll(async () => {
    db = createTestDatabase();

    // Initialize repositories
    orderRepository = new OrderRepository(db);
    productRepository = new ProductRepository(db);
    inventoryRepository = new InventoryRepository(db);
    inventoryService = new InventoryService(inventoryRepository);

    orderService = new OrderService(
      orderRepository,
      productRepository,
      inventoryService
    );

    // Create tables
    await db.query(`
      CREATE TABLE IF NOT EXISTS products (
        id VARCHAR(36) PRIMARY KEY,
        name VARCHAR(255) NOT NULL,
        price DECIMAL(10, 2) NOT NULL
      )
    `);

    await db.query(`
      CREATE TABLE IF NOT EXISTS inventory (
        product_id VARCHAR(36) PRIMARY KEY,
        available INTEGER NOT NULL,
        reserved INTEGER NOT NULL
      )
    `);

    await db.query(`
      CREATE TABLE IF NOT EXISTS orders (
        id VARCHAR(36) PRIMARY KEY,
        user_id VARCHAR(36) NOT NULL,
        total DECIMAL(10, 2) NOT NULL,
        status VARCHAR(20) NOT NULL,
        created_at TIMESTAMP NOT NULL
      )
    `);
  });

  afterAll(async () => {
    await db.query('DROP TABLE IF EXISTS orders CASCADE');
    await db.query('DROP TABLE IF EXISTS inventory CASCADE');
    await db.query('DROP TABLE IF EXISTS products CASCADE');
    await db.close();
  });

  beforeEach(async () => {
    await db.query('TRUNCATE orders CASCADE');
    await db.query('TRUNCATE inventory CASCADE');
    await db.query('TRUNCATE products CASCADE');
  });

  describe('createOrder', () => {
    it('should create order with valid items', async () => {
      // Setup: Create products and inventory
      const productId = uuidv4();
      await db.query(
        'INSERT INTO products (id, name, price) VALUES ($1, $2, $3)',
        [productId, 'Test Product', 29.99]
      );

      await db.query(
        'INSERT INTO inventory (product_id, available, reserved) VALUES ($1, $2, $3)',
        [productId, 100, 0]
      );

      // Create order
      const dto = {
        userId: uuidv4(),
        items: [
          {
            productId,
            quantity: 2,
            price: 29.99,
          },
        ],
      };

      const order = await orderService.createOrder(dto);

      expect(order.id).toBeDefined();
      expect(order.userId).toBe(dto.userId);
      expect(order.total).toBe(59.98);
      expect(order.status).toBe('pending');

      // Verify inventory was reserved
      const inventory = await db.query(
        'SELECT * FROM inventory WHERE product_id = $1',
        [productId]
      );
      expect(inventory[0].reserved).toBe(2);
      expect(inventory[0].available).toBe(98);
    });

    it('should throw error for non-existent product', async () => {
      const dto = {
        userId: uuidv4(),
        items: [
          {
            productId: 'non-existent-id',
            quantity: 1,
            price: 10.00,
          },
        ],
      };

      await expect(orderService.createOrder(dto)).rejects.toThrow(
        'Product not found'
      );
    });

    it('should throw error for insufficient inventory', async () => {
      const productId = uuidv4();
      await db.query(
        'INSERT INTO products (id, name, price) VALUES ($1, $2, $3)',
        [productId, 'Test Product', 29.99]
      );

      await db.query(
        'INSERT INTO inventory (product_id, available, reserved) VALUES ($1, $2, $3)',
        [productId, 5, 0]
      );

      const dto = {
        userId: uuidv4(),
        items: [
          {
            productId,
            quantity: 10, // More than available
            price: 29.99,
          },
        ],
      };

      await expect(orderService.createOrder(dto)).rejects.toThrow(
        'Insufficient inventory'
      );
    });

    it('should throw error for price mismatch', async () => {
      const productId = uuidv4();
      await db.query(
        'INSERT INTO products (id, name, price) VALUES ($1, $2, $3)',
        [productId, 'Test Product', 29.99]
      );

      await db.query(
        'INSERT INTO inventory (product_id, available, reserved) VALUES ($1, $2, $3)',
        [productId, 100, 0]
      );

      const dto = {
        userId: uuidv4(),
        items: [
          {
            productId,
            quantity: 1,
            price: 19.99, // Wrong price
          },
        ],
      };

      await expect(orderService.createOrder(dto)).rejects.toThrow(
        'Price mismatch'
      );
    });
  });

  describe('confirmOrder', () => {
    it('should confirm pending order and deduct inventory', async () => {
      // Setup
      const productId = uuidv4();
      await db.query(
        'INSERT INTO products (id, name, price) VALUES ($1, $2, $3)',
        [productId, 'Test Product', 29.99]
      );

      await db.query(
        'INSERT INTO inventory (product_id, available, reserved) VALUES ($1, $2, $3)',
        [productId, 100, 0]
      );

      // Create order
      const dto = {
        userId: uuidv4(),
        items: [{ productId, quantity: 2, price: 29.99 }],
      };

      const order = await orderService.createOrder(dto);

      // Confirm order
      const confirmed = await orderService.confirmOrder(order.id);

      expect(confirmed.status).toBe('confirmed');

      // Verify inventory was deducted
      const inventory = await db.query(
        'SELECT * FROM inventory WHERE product_id = $1',
        [productId]
      );
      expect(inventory[0].available).toBe(98);
      expect(inventory[0].reserved).toBe(0);
    });
  });
});

Testing with Docker Containers

For more realistic integration tests, I use Docker containers with Testcontainers.

Installation:

npm install --save-dev testcontainers

Database container setup:

// src/test-helpers/test-containers.ts
import { GenericContainer, StartedTestContainer } from 'testcontainers';

export async function startPostgresContainer(): Promise<{
  container: StartedTestContainer;
  connectionString: string;
}> {
  const container = await new GenericContainer('postgres:15-alpine')
    .withEnvironment({
      POSTGRES_USER: 'test',
      POSTGRES_PASSWORD: 'test',
      POSTGRES_DB: 'testdb',
    })
    .withExposedPorts(5432)
    .start();

  const host = container.getHost();
  const port = container.getMappedPort(5432);

  const connectionString = `postgresql://test:test@${host}:${port}/testdb`;

  return { container, connectionString };
}

Using containers in tests:

// src/repositories/__tests__/user-repository.container.test.ts
import { StartedTestContainer } from 'testcontainers';
import { startPostgresContainer } from '../../test-helpers/test-containers';
import { Database } from '../../config/database.config';
import { UserRepository } from '../user-repository';

describe('UserRepository with Testcontainers', () => {
  let container: StartedTestContainer;
  let db: Database;
  let repository: UserRepository;

  beforeAll(async () => {
    const setup = await startPostgresContainer();
    container = setup.container;

    // Parse connection string
    const url = new URL(setup.connectionString);
    db = new Database({
      host: url.hostname,
      port: parseInt(url.port),
      database: url.pathname.slice(1),
      user: url.username,
      password: url.password,
    });

    repository = new UserRepository(db);

    // Create schema
    await db.query(`
      CREATE TABLE users (
        id VARCHAR(36) PRIMARY KEY,
        email VARCHAR(255) UNIQUE NOT NULL,
        name VARCHAR(255) NOT NULL,
        created_at TIMESTAMP NOT NULL,
        updated_at TIMESTAMP NOT NULL
      )
    `);
  }, 60000); // Increase timeout for container startup

  afterAll(async () => {
    await db.close();
    await container.stop();
  });

  it('should work with containerized database', async () => {
    const user = await repository.create({
      id: '123',
      email: '[email protected]',
      name: 'Test User',
    });

    expect(user.email).toBe('[email protected]');
  });
});

Testing Message Queues

Integration tests for event-driven systems with RabbitMQ or Redis.

Example with Redis:

// src/services/event-publisher.ts
import Redis from 'ioredis';

export interface Event {
  type: string;
  payload: any;
  timestamp: Date;
}

export class EventPublisher {
  constructor(private readonly redis: Redis) {}

  async publish(channel: string, event: Event): Promise<void> {
    await this.redis.publish(channel, JSON.stringify(event));
  }
}

export class EventSubscriber {
  constructor(private readonly redis: Redis) {}

  async subscribe(channel: string, callback: (event: Event) => void): Promise<void> {
    const subscriber = this.redis.duplicate();
    
    await subscriber.subscribe(channel);
    
    subscriber.on('message', (ch, message) => {
      if (ch === channel) {
        const event = JSON.parse(message);
        callback(event);
      }
    });
  }
}

Integration tests:

// src/services/__tests__/event-publisher.integration.test.ts
import Redis from 'ioredis';
import { EventPublisher, EventSubscriber } from '../event-publisher';

describe('Event Publisher Integration', () => {
  let redis: Redis;
  let publisher: EventPublisher;
  let subscriber: EventSubscriber;

  beforeAll(() => {
    redis = new Redis({
      host: process.env.REDIS_HOST || 'localhost',
      port: parseInt(process.env.REDIS_PORT || '6379'),
    });

    publisher = new EventPublisher(redis);
    subscriber = new EventSubscriber(redis);
  });

  afterAll(async () => {
    await redis.quit();
  });

  it('should publish and receive events', (done) => {
    const channel = 'test-channel';
    const testEvent = {
      type: 'USER_CREATED',
      payload: { userId: '123', email: '[email protected]' },
      timestamp: new Date(),
    };

    subscriber.subscribe(channel, (event) => {
      expect(event.type).toBe(testEvent.type);
      expect(event.payload).toEqual(testEvent.payload);
      done();
    });

    // Give subscriber time to connect
    setTimeout(async () => {
      await publisher.publish(channel, testEvent);
    }, 100);
  }, 10000);
});

Integration Test Best Practices

1. Use Transactions for Cleanup

beforeEach(async () => {
  await db.query('BEGIN');
});

afterEach(async () => {
  await db.query('ROLLBACK');
});

2. Test Data Builders

// src/test-helpers/builders.ts
export class UserBuilder {
  private data = {
    id: uuidv4(),
    email: '[email protected]',
    name: 'Test User',
  };

  withEmail(email: string): this {
    this.data.email = email;
    return this;
  }

  withName(name: string): this {
    this.data.name = name;
    return this;
  }

  build() {
    return this.data;
  }

  async buildAndSave(repository: UserRepository) {
    return repository.create(this.data);
  }
}

3. Separate Test Suites

# Run only unit tests
npm test -- --testPathIgnorePatterns=integration

# Run only integration tests
npm test -- integration

Key Takeaways

1. Integration tests verify component interactions - Not just isolated functions

2. Use real dependencies when possible - Databases, message queues

3. Testcontainers for consistency - Same environment everywhere

4. Clean up test data - Use transactions or truncate tables

5. Test error scenarios - Network failures, timeouts, constraints

6. Keep tests independent - Each test should run in isolation

7. Balance speed vs realism - Not everything needs full integration

What's Next?

In Part 4: API Testing & Contract Testing, we'll cover:

• HTTP endpoint testing

• OpenAPI/Swagger validation

• Contract testing with Pact

• Testing authentication/authorization

• API versioning tests

---

This article is part of the Software Testing 101 series.