---

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

---

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:
   • Tag with @integration or place in a separate directory (tests/integration/).
   • Configure CI to run integration tests in a dedicated job with service containers.
7. 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:
• Integration testing strategies: https://martinfowler.com/bliki/IntegrationTest.html