running-integration-tests

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 <[e-mail]>
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

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).
2. 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.
3. 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.
4. 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.
5. 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.
6. Run integration tests separately from unit tests: