integration

Integration — Integration Testing

Activate When

• User invokes /godmode:integration
• User says "integration test", "integration testing", "test integration between services"
• User says "test with real database", "test API"
• User asks about Testcontainers or Docker-based deps
• /godmode:test identifies integration coverage gaps

Workflow

Step 1: Assess Integration Boundaries

# Identify external dependencies
grep -rn "createConnection\|createPool\|mongoose" \
  src/ --include="*.ts" | head -10

# Check for existing integration tests
find . -name "*integration*" -o -path "*/it/*" \
  | grep -v node_modules | head -10

# Check Docker availability
docker info > /dev/null 2>&1 && echo "Docker: OK" \
  || echo "Docker: NOT AVAILABLE"

INTEGRATION BOUNDARY MAP:
Target: <module/service>
Language: <language>, Framework: <test framework>

Dependencies:
  Databases: <PostgreSQL | MySQL | MongoDB | Redis>
  APIs: <external services>
  Queues: <Kafka | RabbitMQ | SQS>

IF no integration tests exist: start with DB boundary
IF heavily mocked code: replace mocks with containers
IF Docker unavailable: use test DB instance instead

Step 2: Set Up Testcontainers

// Node.js / TypeScript example
import { PostgreSqlContainer } from
  '@testcontainers/postgresql';

let container;
beforeAll(async () => {
  container = await new PostgreSqlContainer()
    .start();
  // container.getConnectionUri() for connection
}, 60_000); // 60s timeout for container startup

# Python example
import pytest
from testcontainers.postgres import PostgresContainer

@pytest.fixture(scope="module")
def postgres():
    with PostgresContainer("postgres:16-alpine") as pg:
        yield pg

Step 3: Database Seeding & Cleanup

CLEANUP STRATEGIES:
| Strategy           | Speed  | Isolation  |
|-------------------|--------|-----------|
| Transaction rollback| Fast  | High      |
| TRUNCATE between   | Fast   | High      |
| Unique data/test   | No cleanup| Parallel|
| Fresh container    | Slow   | Maximum   |

IF framework supports it: transaction rollback
IF parallel tests: unique data per test
IF schema tests: fresh container per class

THRESHOLDS:
  Container startup timeout: >= 60 seconds
  Avg test duration target: < 5 seconds
  IF test > 10s: check query optimization
  IF flaky: check cleanup, add retry for container