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

1. 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).

1. 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.

1. 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.

1. 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.

1. 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.

1. 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.

1. Generate test res