| name | running-integration-tests |
| description | Execute integration tests validating component interactions and system integration.
Use when performing specialized testing.
Trigger with phrases like "run integration tests", "test integration", or "validate component interactions".
|
| allowed-tools | Read, Write, Edit, Grep, Glob, Bash(test:integration-*) |
| version | 1.22.0 |
| author | Jeremy Longshore <jeremy@intentsolutions.io> |
| license | MIT |
| tags | ["testing","integration-tests"] |
| compatibility | Designed for Claude Code, also compatible with Codex and OpenClaw |
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:
