Integration Test Runner

Overview

Execute integration tests that validate interactions between multiple components, services, and external systems. Tests real database queries, API calls between services, message queue publishing/consuming, and file system operations without mocking the integration boundary.

Prerequisites

• Integration test framework installed (Jest + Supertest, pytest, JUnit 5, or Go testing)

• External services running (database, cache, message queue) via Docker Compose or Testcontainers

• Database migrations applied and seed data loaded

• Test configuration with connection strings pointing to test instances (not production)

• Sufficient timeout settings (integration tests are slower than unit tests)

Instructions

• Identify integration boundaries to test:

• API routes with database queries (controller-to-repository flow).

• Service-to-service HTTP communication.

• Message queue producers and consumers.

• File upload/download with storage services.

• Cache read/write operations (Redis, Memcached).

• Set up test infrastructure:

• Start required services using docker-compose -f docker-compose.test.yml up -d .

• Or use Testcontainers to programmatically start/stop containers per test suite.

• Run database migrations against the test database.

• Seed baseline data required by the test suite.

• Write integration tests following these patterns:

• API integration: Send HTTP requests via Supertest and assert responses including headers, status, and body.

• Database integration: Execute the service method and verify database state with direct queries.

• Event integration: Publish a message and verify the consumer processes it correctly.

• Use real implementations, not mocks, at the integration boundary.

• Manage test data isolation:

• Wrap each test in a database transaction and roll back after assertion.

• Or truncate tables in beforeEach and re-seed minimum required data.

• Use unique identifiers per test to avoid collisions in shared databases.

• Handle asynchronous operations:

• Poll for expected state changes with timeout (e.g., wait for queue consumer to process).

• Use event listeners or callbacks to signal completion.

• Set generous timeouts (10-30 seconds) for external service interactions.

• Run integration tests separately from unit tests:

• Tag with @integration or place in a separate directory (tests/integration/ ).

• Configure CI to run integration tests in a dedicated job with service containers.

• Generate test results in JUnit XML format for CI reporting.

Output

• Integration test files in tests/integration/ organized by feature

• Docker Compose test configuration for service dependencies

• Database seed and teardown scripts

• JUnit XML test results for CI consumption

• Integration test coverage report showing tested integration points

Error Handling

Error Cause Solution

Connection refused to database Database container not yet ready Add wait-for-it.sh or health check polling before running tests; increase startup timeout

Foreign key constraint violation Test data inserted in wrong order or cleanup incomplete Seed data in dependency order; use cascading deletes in teardown; wrap in transactions

Flaky test due to race condition Async consumer has not processed the message yet Use polling with timeout instead of fixed sleep; add event completion callbacks

Test passes locally, fails in CI CI uses different service versions or network config Pin Docker image versions; verify environment variables match; check CI service container logs

Slow test suite (>5 minutes) Too many integration tests or insufficient parallelization Run independent test suites in parallel CI jobs; use Testcontainers reuse mode; limit seed data

Examples

Supertest API integration test:

import request from 'supertest'; import { app } from '../src/app'; import { db } from '../src/database';

describe('POST /api/users', () => { beforeEach(async () => { await db.query('DELETE FROM users'); }); afterAll(async () => { await db.end(); });

it('creates a user and persists to database', async () => { const response = await request(app) .post('/api/users') .send({ name: 'Alice', email: 'alice@example.com' }) .expect(201); # HTTP 201 Created

expect(response.body).toMatchObject({ name: 'Alice' });
const row = await db.query('SELECT * FROM users WHERE email = $1', ['alice@example.com']);
expect(row.rows).toHaveLength(1);

}); });

pytest with database transaction rollback:

import pytest from myapp.services import UserService

@pytest.fixture def db_session(test_database): session = test_database.begin_nested() yield session session.rollback()

def test_create_user_persists_to_db(db_session): service = UserService(db_session) user = service.create(name="Alice", email="alice@test.com") assert user.id is not None found = db_session.query(User).filter_by(email="alice@test.com").one() assert found.name == "Alice"

Resources

• Supertest: https://github.com/ladjs/supertest

• Testcontainers: https://testcontainers.com/

• pytest database fixtures: https://docs.pytest.org/en/stable/how-to/fixtures.html

• Docker Compose for testing: https://docs.docker.com/compose/use-cases/#testing

• Integration testing strategies: https://martinfowler.com/bliki/IntegrationTest.html