williamzujkowski/Integration Testing Designer

Purpose & When-To-Use

Trigger conditions:

• Designing integration tests for microservices that interact with databases and external APIs
• Validating API contracts between services in a distributed system
• Setting up isolated test environments with real database instances
• Mocking external third-party services (payment gateways, notification services, webhooks)
• Testing message-driven architectures (Kafka, RabbitMQ, SQS)
• Validating database transactions, migrations, and data consistency
• Replacing brittle end-to-end tests with focused integration tests

Use this skill when you need to test service boundaries, validate integration points, ensure contract compatibility, or create reproducible test environments with real infrastructure dependencies.

Pre-Checks

Before execution, verify:

1. Time normalization: NOW_ET = 2025-10-26T02:31:19-04:00 (NIST/time.gov semantics, America/New_York)
2. Input schema validation:

• services is non-empty array with service names
• dependencies includes keys: databases, apis, queues, or caches
• test_scope is one of: smoke, happy-path, edge-cases, full
• tech_stack (if provided) contains valid testing framework identifiers

1. Source freshness: All cited sources accessed on NOW_ET; verify links resolve
2. Docker availability: Confirm Docker/Podman is available for TestContainers usage
3. Dependency compatibility: Verify mock tools support required protocols (REST, gRPC, GraphQL)

Abort conditions:

• Services description lacks clear dependency relationships
• Dependencies include proprietary systems without mock/stub capabilities
• Test scope is contradictory (e.g., "full coverage" with "no database access")
• Infrastructure constraints prevent container usage

Procedure

T1: Fast Path (≤2k tokens)

Goal: Generate basic integration test structure with database fixture and API mock.

1. Identify integration points:

• Database dependencies (PostgreSQL, MySQL, MongoDB, Redis)
• External HTTP APIs (REST, GraphQL)
• Message queues (Kafka, RabbitMQ, SQS)
• Third-party services (Stripe, Twilio, SendGrid)

1. Select testing strategy (based on TestContainers Patterns):

• Database: TestContainers (real DB instance) vs. in-memory (H2, SQLite)
• HTTP APIs: WireMock for deterministic responses
• Queues: TestContainers with real broker for integration, mock for unit-level
• Third-party: Mock webhooks and API responses

1. Generate basic test structure:

java // Example: Spring Boot integration test @SpringBootTest @Testcontainers class PaymentServiceIntegrationTest { @Container static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:15-alpine");

@Test void processPayment_withValidCard_createsTransaction() { // Arrange: seed database, mock Stripe // Act: call PaymentService // Assert: verify database state and external call } }

1. Output test scenario outline:

• Test case name and description
• Required fixtures (database records)
• Mock configurations (API endpoints)
• Expected outcomes (database state, external calls)

Token budget: ≤2k tokens

T2: Extended Analysis (≤6k tokens)

Goal: Generate complete test scenarios, fixtures, mocks, and environment setup.

1. Create database fixtures (following pytest fixtures and Spring Test patterns):

• Seed data SQL/JSON files for initial state
• Factory functions for test data generation
• Cleanup strategies (transaction rollback, container disposal)
• Migration application in test environment

1. Configure service mocks (using WireMock):

• Stub external API responses (success, failure, timeout)
• Webhook simulation for callbacks
• Request matching and verification
• State-based mocking for complex scenarios

1. Setup test environment:

• Docker Compose: Multi-container setup for CI/local development
• TestContainers: Programmatic container lifecycle in tests
• Environment variables: Database URLs, API keys (test mode)
• Network configuration: Service discovery, port mapping

1. Design contract tests (following Pact consumer-driven contract testing):

• Consumer-side pact generation
• Provider-side verification
• Contract versioning and evolution
• Pact broker integration for sharing contracts

1. Generate test scenarios:

• Happy path: Successful integration with all dependencies
• Error handling: Database failures, API timeouts, invalid responses
• Edge cases: Concurrent requests, large payloads, rate limiting
• Data consistency: Transaction rollback, eventual consistency

Token budget: ≤6k tokens total (including T1)

T3: Deep Dive (≤12k tokens)

Goal: Add advanced integration patterns, performance considerations, and CI/CD integration.

1. Advanced testing patterns:

• Saga testing: Multi-service transaction coordination
• Event-driven testing: Message production and consumption verification
• Cache invalidation: Redis/Memcached interaction testing
• Schema evolution: Database migration testing with Flyway/Liquibase

1. Performance and reliability:

• Connection pool configuration for test databases
• Test parallelization with isolated database schemas
• Flaky test mitigation (retry policies, wait strategies)
• Resource cleanup and leak detection

1. CI/CD integration:

• Container registry pre-pulling for faster test execution
• Parallel test execution with Gradle/Maven/pytest-xdist
• Test result aggregation and reporting
• Integration test stage in pipeline (post-unit, pre-E2E)

1. Documentation and maintenance:

• Test data management strategy
• Mock service update procedures
• Contract versioning guidelines
• Troubleshooting guide for common failures

Token budget: ≤12k tokens total (including T1 + T2)

Decision Rules

Test scope adjustments:

• Smoke: 3-5 critical path tests with minimal fixtures
• Happy-path: 10-15 tests covering primary workflows
• Edge-cases: Add 20-30 tests for error scenarios, boundaries, concurrency
• Full: Include performance, security, and chaos scenarios

Database strategy selection:

• Use TestContainers when:
• Testing database-specific features (JSON columns, full-text search)
• Validating complex queries and transactions
• Testing migrations and schema changes
• Production database is PostgreSQL, MySQL, MongoDB, or supported DB

• Use in-memory database when:
• Simple CRUD operations with standard SQL
• Fast feedback required (unit test-like speed)
• CI environment has resource constraints
• Database is abstracted through ORM

Mock vs. Real service:

• Mock external APIs: Payment gateways, email providers, SMS services
• Use real services (containerized): Databases, message queues, caches
• Use contract tests: For services you control in same organization
• Use sandbox/test environments: For third-party services with test modes

Effort estimation (per integration point):

• Basic integration test: 2-4 hours
• Complex multi-service scenario: 6-12 hours
• Contract test setup: 4-8 hours
• TestContainers environment: 1-3 hours (initial), 30min (per additional service)

Stop conditions:

• If no external dependencies exist: redirect to unit testing
• If only UI-level integration needed: redirect to E2E testing skill
• If services lack clear boundaries: recommend architecture refactoring first

Output Contract

Required fields (all outputs):

typescript
interface IntegrationTestDesign {
  test_scenarios: Array<{
    name: string;
    description: string;
    services_under_test: string[];
    dependencies: string[];
    test_steps: Array<{
      step: string;
      action: string;
      expected_outcome: string;
    }>;
    fixtures_required: string[];
    mocks_required: string[];
  }>;

  fixtures: {
    database_seeds: Array<{
      table: string;
      format: "sql" | "json" | "yaml";
      content: string;
    }>;
    factory_functions?: string;  // Code snippet
  };

  environment_setup: {
    format: "docker-compose" | "testcontainers" | "kubernetes";
    content: string;             // YAML or code
    setup_instructions: string;
  };

  contract_tests?: Array<{
    consumer: string;
    provider: string;
    contract_format: "pact" | "spring-cloud-contract" | "openapi";
    interactions: Array<{
      description: string;
      request: object;
      response: object;
    }>;
  }>;

  mock_configurations: Array<{
    service_name: string;
    tool: "wiremock" | "mockserver" | "nock" | "responses";
    stubs: Array<{
      endpoint: string;
      method: string;
      response_body: object;
      status_code: number;
    }>;
  }>;
}

Format:

• test_scenarios: Array of objects with consistent structure
• fixtures: SQL/JSON with valid syntax
• environment_setup: Valid Docker Compose YAML or TestContainers code
• contract_tests: Pact-compatible JSON or Spring Cloud Contract DSL

Validation:

• All referenced fixtures exist in fixtures section
• All mocked services are in dependencies
• Database schema matches application models
• Port mappings don't conflict

Examples

Example 1: Payment API Integration Test (T2)

yaml
INPUT:
  services: ["payment-api"]
  dependencies: {databases: ["postgres"], apis: ["stripe"]}
  test_scope: "happy-path"

OUTPUT:
  test_scenarios:
    - name: "Process payment and store transaction"
      test_steps:
        - "Setup: Start PostgreSQL, seed users, stub Stripe API"
        - "Execute: POST /payments with valid card"
        - "Assert: 201 response, transaction in DB, Stripe called"

  fixtures:
    database_seeds:
      - table: "users"
        content: "INSERT INTO users (id, email) VALUES (1, 'test@example.com');"

  mock_configurations:
    - service_name: "stripe"
      tool: "wiremock"
      stubs: [{endpoint: "/v1/charges", status: 200}]

Quality Gates

Token budgets (mandatory):

• T1 ≤ 2k tokens (basic integration test structure)
• T2 ≤ 6k tokens (complete fixtures + mocks + environment)
• T3 ≤ 12k tokens (advanced patterns + CI/CD integration)

Safety checks:

• ] No production credentials in fixtures or mocks
• ] No real external API calls (all mocked or sandboxed)
• ] Database containers use non-persistent volumes in tests
• ] Cleanup code prevents resource leaks

Auditability:

• ] All sources cited with access date = NOW_ET
• ] Test data generation is deterministic and reproducible
• ] Mock responses match actual API documentation
• ] Container versions are pinned (not latest)

Determinism:

• ] Tests pass consistently with same inputs
• ] Database state is reset between tests
• ] Time-dependent logic uses fixed test time
• ] Random data generation uses fixed seeds

Validation checklist:

• ] Output JSON validates against schema
• ] Docker Compose YAML is valid (docker-compose config)
• ] SQL fixtures execute without errors
• ] Mock endpoints match API documentation
• ] TestContainers code compiles

Resources

Primary sources (accessed 2025-10-26):

1. TestContainers: https://testcontainers.com/

Lightweight, throwaway instances of databases, message brokers, and other services for integration testing.

1. WireMock: https://wiremock.org/

Flexible API mocking tool for HTTP-based services with request matching and response stubbing.

1. Pact: https://pact.io/

Consumer-driven contract testing framework for validating API interactions between services.

1. Spring Boot Testing: https://docs.spring.io/spring-boot/reference/testing/index.html

Official Spring Boot testing documentation covering @SpringBootTest, MockMvc, and TestContainers integration.

1. pytest: https://pytest.org/

Python testing framework with powerful fixtures and parametrization for integration testing.

Additional templates:

• See examples/payment-integration-test.java for complete Java example
• See resources/docker-compose-test.yml for multi-service test environment
• See resources/pact-contract-example.json for contract test template

Related skills:

• testing-strategy-composer (for overall testing strategy)
• api-design-validator (for API contract design)
• database-optimization-analyzer (for test database performance)

End of SKILL.md