Integration Testing
Document ID: TEST-002
File Path: docs/15-testing/integration-tests.md
Version: 1.0.0
Status: Draft
Owner: Quality Engineering Team
Last Updated: 2026-06-27
1. Purpose
Section titled “1. Purpose”This document defines integration testing — verifying that services work correctly against real datastores and neighboring services, catching issues that unit tests (with mocks) cannot.
2. Scope
Section titled “2. Scope”| Boundary | Examples |
|---|---|
| Service ↔ datastore | Memory Engine ↔ Postgres + Qdrant |
| Service ↔ service | Agent Runtime ↔ LLM Gateway ↔ Tool Runtime |
| API contracts | Endpoint behavior, errors, pagination, idempotency |
| Event flows | plugin.*, execution.* over NATS |
3. Environment
Section titled “3. Environment”Integration tests run against ephemeral real backends, started via Docker Compose (Postgres, Redis, Qdrant, NATS, MinIO) or Testcontainers:
spin up compose (core profile) → migrate → seed → run tests → tear downThis matches the team self-host topology, so tests exercise the real wiring.
4. Provider Handling
Section titled “4. Provider Handling”- LLM providers are replaced by a recorded/fake provider behind the LLM Gateway so tests are deterministic and free of external cost.
- A small suite of live provider smoke tests runs separately (gated, optional) to catch real-provider drift.
5. Contract Tests
Section titled “5. Contract Tests”Each external contract has tests asserting the documented behavior:
- Platform API — status codes, error envelope, pagination,
idempotency, concurrency (
ETag/If-Match). - Workflow DSL — validation rules, WIR compilation.
- Tool Runtime Execution API and Memory Engine API.
- Plugin manifest — install/verify/register.
Contract tests guard against accidental breaking changes.
6. Data & Isolation
Section titled “6. Data & Isolation”- Each test run uses an isolated tenant/namespace; tests assert no cross-tenant leakage (a hard requirement — authorization).
- Fixtures are created and torn down per test/suite to avoid coupling.
7. Event-Driven Assertions
Section titled “7. Event-Driven Assertions”For async flows, tests subscribe to the
Event Bus and assert the
expected *.completed/*.failed events occur, rather than sleeping.
8. Migration Tests
Section titled “8. Migration Tests”Database migrations are tested forward (and where supported, backward) to ensure safe upgrades.
9. CI Integration
Section titled “9. CI Integration”Integration tests run on PRs (after unit) against a fresh stack and must pass to merge (CI pipeline).
10. Dependencies
Section titled “10. Dependencies”12-deployment/docker-compose.md15-testing/workflow-tests.md02-architecture/event-driven-architecture.md
11. Related Documents
Section titled “11. Related Documents”12. Revision History
Section titled “12. Revision History”| Version | Date | Description |
|---|---|---|
| 1.0.0 | 2026-06-27 | Initial Integration Testing specification |