integration-testing

name	integration-testing
description	Integration testing patterns for database state, API contracts, service boundaries, and component wiring. Use when testing how multiple parts of a system work together without mocks.

Integration Testing

Verify the interaction between components, data stores, and external services to ensure contract correctness and state integrity.

When to Activate

• Test database interactions and repository logic
• Verify API client behavior against wire services
• Ensure middleware and handlers work together
• Test multi-service flows in a single process
• Debug cross-component state synchronization
• Refactor internals while keeping public contracts stable
• Audit data persistence and retrieval behavior

Testing Layers

Level	Isolation	Speed	Confidence
Unit	Pure functions, mocked collaborators	Fastest	Low (Logic only)
Integration	Real database, real network clients	Medium	Medium (Contracts + State)
E2E	Real browser, full environment	Slowest	High (User journey)

Database Integration

Strategy	When to use	Rule
Per-test Transaction	Standard relational DB tests	Wrap in begin, then rollback on teardown
Unique Fixtures	Parallel tests or non-transactional DBs	Use UUIDs/Random prefixes forทุก record
Truncation	Between suites or for dirty state	Truncate only the tables used

BAD

def test_get_user_orders():
    # Relies on order ID 1 existing from previous test
    orders = get_user_orders(user_id=1)
    assert len(orders) == 1

GOOD

def test_get_user_orders(db_session, user_factory, order_factory):
    user = user_factory.create()
    order_factory.create(user_id=user.id)

    orders = get_user_orders(user_id=user.id)
    assert len(orders) == 1

API Boundaries

Concern	Strategy
HTTP Clients	Use WireMock or Prism instead of mocking the client class
Message Brokers	Use a real containerized instance (Testcontainers)
File Storage	Use a local filesystem fake or MinIO

Checklist

• Database tests use a dedicated clean environment (e.g. Testcontainers)
• Tests create their own data rather than relying on shared state
• Teardown logic reliably cleans up files, records, and connections
• Network calls to external APIs are intercepted at the wire level
• Tests verify side effects like database writes or message emits
• Serialized output matches the expected JSON/Protobuf contract
• Error paths (404, 500, timeouts) are tested with realistic failure modes
• Connection pooling and timeouts are exercised in the setup
• Asynchronous background tasks are awaited before assertion
• Migrations are run on the test database before the suite starts
• Environment variables for integration are isolated from local dev