integration-testing

# 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 ```python 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 ```python 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