Configure Integration Tests

/configure:integration-tests

Check and configure integration testing infrastructure for testing service interactions, databases, and external dependencies.

When to Use This Skill

Context

• Project root: !pwd
• Package files: !find . -maxdepth 1 \( -name 'package.json' -o -name 'pyproject.toml' -o -name 'Cargo.toml' -o -name 'go.mod' \)
• Integration tests dir: !find tests -maxdepth 1 -type d -name 'integration'
• Docker compose test: !find . -maxdepth 1 -name 'docker-compose.test.yml'
• Vitest integration config: !find . -maxdepth 1 -name 'vitest.integration.config.*'
• Supertest dep: !grep -l 'supertest' package.json
• Testcontainers dep: !find . -maxdepth 1 \( -name package.json -o -name pyproject.toml \) -exec grep -l 'testcontainers' {} +
• Project standards: !find . -maxdepth 1 -name '.project-standards.yaml'

Parameters

Parse from command arguments:

• --check-only: Report compliance status without modifications (CI/CD mode)
• --fix: Apply fixes automatically without prompting
• --framework <supertest|pytest|testcontainers>: Override framework detection

Integration Testing Stacks:

• JavaScript/TypeScript: Supertest + Testcontainers
• Python: pytest + testcontainers-python + httpx
• Rust: cargo test with #[ignore] + testcontainers-rs
• Go: testing + testcontainers-go

Key Difference from Unit Tests:

• Integration tests interact with real databases, APIs, and services
• They test component boundaries and data flow
• They typically require test fixtures and cleanup

Execution

Execute this integration testing compliance check:

Step 1: Detect existing integration testing infrastructure

Check for these indicators:

Step 2: Analyze current state

Check for complete integration testing setup:

Test Organization:

• [ ] tests/integration/ directory exists
• [ ] Integration tests separated from unit tests
• [ ] Test fixtures and factories present
• [ ] Database seeding/migration scripts

JavaScript/TypeScript (Supertest):

• [ ] supertest installed
• [ ] @testcontainers/postgresql or similar installed
• [ ] Test database configuration
• [ ] API endpoint tests present
• [ ] Authentication test helpers

Python (pytest + testcontainers):

• [ ] testcontainers installed
• [ ] httpx or requests for HTTP testing
• [ ] pytest-asyncio for async tests
• [ ] integration marker defined
• [ ] Database fixtures in conftest.py

Container Infrastructure:

• [ ] docker-compose.test.yml exists
• [ ] Test database container defined
• [ ] Redis/cache container (if needed)
• [ ] Network isolation configured

Step 3: Generate compliance report

Print a formatted compliance report:

Integration Testing Compliance Report
======================================
Project: [name]
Language: [TypeScript | Python | Rust | Go]

Test Organization:
  Integration directory    tests/integration/         [EXISTS | MISSING]
  Separated from unit      not in src/                [CORRECT | MIXED]
  Test fixtures            tests/fixtures/            [EXISTS | MISSING]
  Database seeds           tests/seeds/               [EXISTS | N/A]

Framework Setup:
  HTTP testing             supertest/httpx            [INSTALLED | MISSING]
  Container testing        testcontainers             [INSTALLED | MISSING]
  Async support            pytest-asyncio             [INSTALLED | N/A]

Infrastructure:
  docker-compose.test.yml  test services              [EXISTS | MISSING]
  Test database            PostgreSQL/SQLite          [CONFIGURED | MISSING]
  Service isolation        network config             [CONFIGURED | MISSING]

CI/CD Integration:
  Integration test job     GitHub Actions             [CONFIGURED | MISSING]
  Service containers       workflow services          [CONFIGURED | MISSING]

Overall: [X issues found]

Recommendations:
  - Install testcontainers for database testing
  - Create docker-compose.test.yml for local testing
  - Add integration test job to CI workflow

If --check-only, stop here.

Step 4: Configure integration testing (if --fix or user confirms)

Apply configuration based on detected project type. Use templates from REFERENCE.md:

1. Install dependencies (supertest, testcontainers, etc.) 2. Create test directory (tests/integration/) with setup files 3. Create sample tests for API endpoints and database operations 4. Create Vitest integration config (JS/TS) or pytest markers (Python) 5. Add scripts to package.json or create run commands

Step 5: Create container infrastructure

Create docker-compose.test.yml with:

• PostgreSQL test database (tmpfs for speed)
• Redis test instance (if needed)
• Network isolation

Add corresponding npm/bun scripts for managing test containers. Use templates from REFERENCE.md.

Step 6: Configure CI/CD integration

Add integration test job to .github/workflows/test.yml with:

• Service containers (postgres, redis)
• Database migration step
• Integration test execution
• Artifact upload for test results

Use the CI workflow template from REFERENCE.md.

Step 7: Create test fixtures and factories

Create tests/fixtures/factories.ts (or Python equivalent) with:

• Data factory functions using faker
• Database seeding helpers
• Cleanup utilities

Use factory templates from REFERENCE.md.

Step 8: Update standards tracking

Update .project-standards.yaml:

standards_version: "2025.1"
last_configured: "[timestamp]"
components:
  integration_tests: "2025.1"
  integration_tests_framework: "[supertest|pytest|testcontainers]"
  integration_tests_containers: true
  integration_tests_ci: true

Step 9: Print final report

Print a summary of changes applied, scripts added, and next steps for running integration tests.

For detailed templates and code examples, see REFERENCE.md.

Agentic Optimizations

Flags

Examples

# Check compliance and offer fixes
/configure:integration-tests

# Check only, no modifications
/configure:integration-tests --check-only

# Auto-fix all issues
/configure:integration-tests --fix

# Force specific framework
/configure:integration-tests --fix --framework pytest

Error Handling

• No app entry point found: Ask user to specify app location
• Docker not available: Warn about testcontainers requirement
• Database type unknown: Ask user to specify database type
• Port conflicts: Suggest alternative ports in docker-compose

See Also

• /configure:tests - Unit testing configuration
• /configure:api-tests - API contract testing
• /configure:coverage - Coverage configuration
• /configure:all - Run all compliance checks
• Testcontainers documentation: https://testcontainers.com
• Supertest documentation: https://github.com/ladjs/supertest

Integration Tests Reference

Configuration templates and code examples for integration testing.

JavaScript/TypeScript Setup

Install Dependencies

bun add --dev supertest @types/supertest
bun add --dev @testcontainers/postgresql
bun add --dev testcontainers

Container Setup (tests/integration/setup.ts)

import { PostgreSqlContainer, StartedPostgreSqlContainer } from '@testcontainers/postgresql';
import { afterAll, beforeAll } from 'vitest';

let postgresContainer: StartedPostgreSqlContainer;

export async function setupTestDatabase(): Promise<string> {
  postgresContainer = await new PostgreSqlContainer('postgres:16-alpine')
    .withDatabase('test_db')
    .withUsername('test')
    .withPassword('test')
    .start();

  return postgresContainer.getConnectionUri();
}

export async function teardownTestDatabase(): Promise<void> {
  if (postgresContainer) {
    await postgresContainer.stop();
  }
}

// Global setup for all integration tests
beforeAll(async () => {
  const connectionUri = await setupTestDatabase();
  process.env.DATABASE_URL = connectionUri;
}, 60000); // 60s timeout for container startup

afterAll(async () => {
  await teardownTestDatabase();
});

API Test (tests/integration/api.test.ts)

import { describe, it, expect, beforeAll, afterAll } from 'vitest';
import request from 'supertest';
import { app } from '../../src/app'; // Your Express/Fastify app
import './setup'; // Import container setup

describe('API Integration Tests', () => {
  describe('GET /api/users', () => {
    it('should return empty array when no users exist', async () => {
      const response = await request(app)
        .get('/api/users')
        .expect('Content-Type', /json/)
        .expect(200);

      expect(response.body).toEqual([]);
    });

    it('should return users after creation', async () => {
      await request(app)
        .post('/api/users')
        .send({ name: 'Test User', email: 'test@example.com' })
        .expect(201);

      const response = await request(app)
        .get('/api/users')
        .expect(200);

      expect(response.body).toHaveLength(1);
      expect(response.body[0].name).toBe('Test User');
    });
  });

  describe('Authentication Flow', () => {
    it('should register and login user', async () => {
      const registerResponse = await request(app)
        .post('/api/auth/register')
        .send({
          email: 'newuser@example.com',
          password: 'securepassword123',
        })
        .expect(201);

      expect(registerResponse.body).toHaveProperty('token');

      const loginResponse = await request(app)
        .post('/api/auth/login')
        .send({
          email: 'newuser@example.com',
          password: 'securepassword123',
        })
        .expect(200);

      expect(loginResponse.body).toHaveProperty('token');
    });
  });
});

Database Test (tests/integration/database.test.ts)

import { describe, it, expect, beforeEach } from 'vitest';
import { db } from '../../src/db'; // Your database client
import './setup';

describe('Database Integration Tests', () => {
  beforeEach(async () => {
    await db.query('TRUNCATE users CASCADE');
  });

  it('should insert and retrieve user', async () => {
    const result = await db.query(
      'INSERT INTO users (name, email) VALUES ($1, $2) RETURNING *',
      ['Test User', 'test@example.com']
    );

    expect(result.rows[0]).toMatchObject({
      name: 'Test User',
      email: 'test@example.com',
    });

    const fetchResult = await db.query('SELECT * FROM users WHERE id = $1', [
      result.rows[0].id,
    ]);

    expect(fetchResult.rows[0].name).toBe('Test User');
  });

  it('should enforce unique email constraint', async () => {
    await db.query(
      'INSERT INTO users (name, email) VALUES ($1, $2)',
      ['User 1', 'duplicate@example.com']
    );

    await expect(
      db.query(
        'INSERT INTO users (name, email) VALUES ($1, $2)',
        ['User 2', 'duplicate@example.com']
      )
    ).rejects.toThrow(/unique constraint/i);
  });
});

Vitest Integration Config (vitest.integration.config.ts)

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    include: ['tests/integration/**/*.test.ts'],
    setupFiles: ['tests/integration/setup.ts'],
    testTimeout: 30000, // 30s for container operations
    hookTimeout: 60000, // 60s for container startup
    pool: 'forks', // Use forks for isolation
    poolOptions: {
      forks: {
        singleFork: true, // Run sequentially to avoid port conflicts
      },
    },
    env: {
      NODE_ENV: 'test',
    },
  },
});

Package.json Scripts

{
  "scripts": {
    "test:integration": "vitest run --config vitest.integration.config.ts",
    "test:integration:watch": "vitest --config vitest.integration.config.ts",
    "test:integration:docker": "docker compose -f docker-compose.test.yml up -d && npm run test:integration && docker compose -f docker-compose.test.yml down",
    "docker:test:up": "docker compose -f docker-compose.test.yml up -d",
    "docker:test:down": "docker compose -f docker-compose.test.yml down -v"
  }
}

Python Setup

Install Dependencies

uv add --group dev testcontainers httpx pytest-asyncio

pytest Configuration (pyproject.toml)

[tool.pytest.ini_options]
markers = [
    "unit: Unit tests (fast, no external dependencies)",
    "integration: Integration tests (require services/containers)",
    "e2e: End-to-end tests (full system)",
    "slow: Slow running tests",
]

# Default to running unit tests only
addopts = "-m 'not integration and not e2e'"

conftest.py (tests/integration/conftest.py)

import pytest
from testcontainers.postgres import PostgresContainer
from httpx import AsyncClient
import asyncio

@pytest.fixture(scope="session")
def event_loop():
    """Create event loop for async tests."""
    loop = asyncio.get_event_loop_policy().new_event_loop()
    yield loop
    loop.close()

@pytest.fixture(scope="session")
def postgres_container():
    """Start PostgreSQL container for integration tests."""
    with PostgresContainer("postgres:16-alpine") as postgres:
        yield postgres

@pytest.fixture(scope="session")
def database_url(postgres_container):
    """Get database URL from container."""
    return postgres_container.get_connection_url()

@pytest.fixture
async def db_session(database_url):
    """Create database session with automatic cleanup."""
    from sqlalchemy.ext.asyncio import create_async_engine, AsyncSession
    from sqlalchemy.orm import sessionmaker

    async_url = database_url.replace("postgresql://", "postgresql+asyncpg://")
    engine = create_async_engine(async_url)

    async_session = sessionmaker(
        engine, class_=AsyncSession, expire_on_commit=False
    )

    async with async_session() as session:
        yield session
        await session.rollback()

@pytest.fixture
async def api_client(database_url):
    """Create test client for API."""
    import os
    os.environ["DATABASE_URL"] = database_url

    from app.main import app  # Your FastAPI/Flask app

    async with AsyncClient(app=app, base_url="http://test") as client:
        yield client

API Test (tests/integration/test_api.py)

import pytest
from httpx import AsyncClient

pytestmark = pytest.mark.integration

@pytest.mark.asyncio
async def test_create_user(api_client: AsyncClient):
    """Test user creation through API."""
    response = await api_client.post(
        "/api/users",
        json={"name": "Test User", "email": "test@example.com"},
    )

    assert response.status_code == 201
    data = response.json()
    assert data["name"] == "Test User"
    assert "id" in data

@pytest.mark.asyncio
async def test_get_users(api_client: AsyncClient):
    """Test fetching users list."""
    await api_client.post(
        "/api/users",
        json={"name": "Test User", "email": "test@example.com"},
    )

    response = await api_client.get("/api/users")

    assert response.status_code == 200
    data = response.json()
    assert len(data) >= 1

@pytest.mark.asyncio
async def test_authentication_flow(api_client: AsyncClient):
    """Test complete auth flow: register -> login -> access protected."""
    register_response = await api_client.post(
        "/api/auth/register",
        json={"email": "newuser@example.com", "password": "secure123"},
    )
    assert register_response.status_code == 201

    login_response = await api_client.post(
        "/api/auth/login",
        json={"email": "newuser@example.com", "password": "secure123"},
    )
    assert login_response.status_code == 200
    token = login_response.json()["token"]

    protected_response = await api_client.get(
        "/api/profile",
        headers={"Authorization": f"Bearer {token}"},
    )
    assert protected_response.status_code == 200

Docker Compose Test Configuration

docker-compose.test.yml

version: '3.8'

services:
  test-db:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: test
      POSTGRES_PASSWORD: test
      POSTGRES_DB: test_db
    ports:
      - "5433:5432"
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U test -d test_db"]
      interval: 5s
      timeout: 5s
      retries: 5
    tmpfs:
      - /var/lib/postgresql/data  # Use tmpfs for faster tests

  test-redis:
    image: redis:7-alpine
    ports:
      - "6380:6379"
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      timeout: 5s
      retries: 5

  # Optional: Message queue for event-driven tests
  test-rabbitmq:
    image: rabbitmq:3-alpine
    ports:
      - "5673:5672"
    healthcheck:
      test: ["CMD", "rabbitmq-diagnostics", "check_running"]
      interval: 10s
      timeout: 5s
      retries: 5

networks:
  default:
    name: integration-test-network

CI/CD Workflow Template

jobs:
  unit-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v2
      - run: bun install --frozen-lockfile
      - run: bun test

  integration-tests:
    runs-on: ubuntu-latest
    needs: unit-tests  # Run after unit tests pass

    services:
      postgres:
        image: postgres:16-alpine
        env:
          POSTGRES_USER: test
          POSTGRES_PASSWORD: test
          POSTGRES_DB: test_db
        ports:
          - 5432:5432
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5

      redis:
        image: redis:7-alpine
        ports:
          - 6379:6379
        options: >-
          --health-cmd "redis-cli ping"
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5

    steps:
      - uses: actions/checkout@v4

      - uses: oven-sh/setup-bun@v2

      - name: Install dependencies
        run: bun install --frozen-lockfile

      - name: Run database migrations
        run: bun run db:migrate
        env:
          DATABASE_URL: postgresql://test:test@localhost:5432/test_db

      - name: Run integration tests
        run: bun run test:integration
        env:
          DATABASE_URL: postgresql://test:test@localhost:5432/test_db
          REDIS_URL: redis://localhost:6379

      - name: Upload test results
        uses: actions/upload-artifact@v4
        if: always()
        with:
          name: integration-test-results
          path: test-results/

Test Fixtures and Factories

tests/fixtures/factories.ts

import { faker } from '@faker-js/faker';

export interface UserFactory {
  name: string;
  email: string;
  password?: string;
}

export function createUserData(overrides: Partial<UserFactory> = {}): UserFactory {
  return {
    name: faker.person.fullName(),
    email: faker.internet.email(),
    password: faker.internet.password({ length: 12 }),
    ...overrides,
  };
}

export function createManyUsers(count: number, overrides: Partial<UserFactory> = {}): UserFactory[] {
  return Array.from({ length: count }, () => createUserData(overrides));
}

export async function seedDatabase(db: any) {
  const users = createManyUsers(10);

  for (const user of users) {
    await db.query(
      'INSERT INTO users (name, email) VALUES ($1, $2)',
      [user.name, user.email]
    );
  }

  return users;
}