integration-testing

Integration Testing

Purpose: Verify that components, services, and systems interact correctly across boundaries. Scope: API testing, contract testing, database integration, service mocking, message queue testing.

When to Use This Skill

• Testing API endpoints with request/response validation
• Verifying database queries and migrations
• Testing service-to-service communication
• Implementing consumer-driven contract testing
• Validating message queue producers and consumers
• Testing authentication and authorization flows
• Verifying third-party API integrations

When NOT to Use

• Testing isolated functions or classes (use unit testing)
• Full user journey testing (use e2e testing)
• Load/stress testing (use performance testing)

Prerequisites

• Application with defined service boundaries
• Docker available for Testcontainers (recommended)
• API specifications (OpenAPI, AsyncAPI, or similar)

Decision Tree

What integration boundary?
+- HTTP APIs?
|  +- Own API endpoints -> Supertest / httpx / RestAssured
|  +- Third-party APIs -> WireMock / MSW / responses
|  +- Consumer contracts -> Pact / Spring Cloud Contract
+- Database?
|  +- SQL -> Testcontainers + migrations
|  +- NoSQL -> Testcontainers + seed data
|  +- In-memory fallback -> SQLite (unit only, not integration)
+- Message queues?
|  +- Kafka -> Testcontainers kafka
|  +- RabbitMQ -> Testcontainers rabbitmq
|  +- Azure Service Bus -> Emulator or mock
+- External services?
|  +- HTTP-based -> WireMock / MSW
|  +- gRPC -> grpc-mock
|  +- SDK-based -> Interface abstraction + test double
+- Authentication?
|  +- JWT -> Test token generator
|  +- OAuth -> Mock identity provider
|  +- API keys -> Test keys in environment

API Integration Testing

Node.js / Express (Supertest)

// tests/integration/users.api.test.ts
import request from 'supertest';
import { app } from '../../src/app';
import { db } from '../../src/database';

describe('POST /api/users', () => {
  beforeEach(async () => {
    await db.migrate.latest();
    await db.seed.run();
  });

  afterEach(async () => {
    await db('users').truncate();
  });

  it('creates a user and returns 201', async () => {
    const response = await request(app)
      .post('/api/users')
      .send({ name: 'Test User', email: '[email protected]' })
      .set('Authorization', `Bearer ${testToken}`)
      .expect(201);

    expect(response.body).toMatchObject({
      id: expect.any(String),
      name: 'Test User',
      email: '[email protected]',
    });

    // Verify database state
    const user = await db('users').where({ email: '[email protected]' }).first();
    expect(user).toBeDefined();
  });

  it('returns 400 for invalid email', async () => {
    const response = await request(app)
      .post('/api/users')
      .send({ name: 'Test', email: 'not-an-email' })
      .set('Authorization', `Bearer ${testToken}`)
      .expect(400);

    expect(response.body.errors).toContainEqual(
      expect.objectContaining({ field: 'email' })
    );
  });

  it('returns 401 without auth token', async () => {
    await request(app)
      .post('/api/users')
      .send({ name: 'Test', email: '[email protected]' })
      .expect(401);
  });
});