Contract testing
Consumer-driven contracts (Pact or equivalent) between portfolio products and with external integrations — replacing brittle cross-system E2E with checks that run inside each repo's merge gate, so an agent cannot silently break an integration it can't even see. A P2 standard: it activates at the first cross-product integration, not before.
The rules
- Consumer-driven. The consumer publishes its expectations of a provider (the requests it makes, the response shape it relies on) as an executable contract. The provider verifies every published contract in CI on every change.
- Contracts run in the merge gate. A provider change that breaks a published contract fails the PR at the merge gate — before merge, in the provider's own pipeline. A can-i-deploy check runs before release: no deploy while a consumer contract is red.
- Replace, don't add. Contract tests take the integration-confidence job from cross-system E2E (test pyramid). E2E is reserved for the few genuinely end-to-end journeys; everything else is a contract. Two products' full environments coupled in one test run is the brittleness this standard exists to remove.
- External integrations too. For ACORD feeds, broker feeds and third-party data services (integration reference architecture) where the provider won't run our verification, contract-test against a recorded stub of the real provider and monitor production traffic for drift from it. The contract is then our documented assumption — when the third party changes, the drift alert fires before clients do.
- Contract changes are API changes. Breaking a contract deliberately is versioned, SemVer-signalled and coordinated with consumers — a decision, not a side effect. Flag significant ones as ADRs.
Why agents make this necessary
An agent refactoring a provider will happily "improve" a response shape; its own repo stays green, every unit test passes, and a consumer in a different repo breaks in production. The consumer's expectations have to be executable inside the provider's gate — that is the only place an agent working at machine speed will actually meet them. This is the cross-system form of the same principle as the merge gate itself: encode the constraint where the work happens.
When to introduce
- Trigger: the first cross-product integration — the moment one RAPID product consumes another's API (e.g. CXsmart consuming anything StudyBuddy exposes), or a RAPID product exposes an interface an external party depends on.
- Not before. A single product with no consumers gets nothing from contract infrastructure — which is why this is P2 and StudyBuddy alone doesn't need it. Deferring it is deliberate; skipping it at the trigger point is not.
- On introduction: the regression strategy already reserves the layer; wire the broker into the pipeline template so every later integration inherits it for free.
The contract broker (Pact Broker, PactFlow or equivalent) is a tech-radar selection to be made when the first integration triggers this standard — recorded as an ADR per tech selection.
Standards referenced: Pact, consumer-driven contracts, OpenAPI (schema source of truth where applicable).