Consumer-driven contract (CDC) testing framework for Oshun domains.
What it is#
A small, zero-runtime-dependency CDC harness that:
- Reads an OpenAPI spec (the provider contract) from
libs/openapi/src/specs/<domain>/<domain>-api.yaml. - Reads the consumer SDK (
libs/<domain>/client/src/**) and extracts the HTTP call sites it relies on. - Fails CI if:
- The SDK references an operation that is neither in the spec nor in the explicit drift registry.
- A drift-registry entry is no longer used by the SDK (forcing the registry to shrink over time).
- Required cross-domain scenario operations disappear from the spec.
- Schema refs fail to resolve.
- A 2xx response lacks a JSON body (except for explicitly listed streaming or async-accepted operations).
Why not @pact-foundation/pact?#
The original task wording (Phase 13.5.1) is "Set up Pact or similar". We chose
"similar" for three concrete reasons:
- No broker infrastructure. Pact pushes the provider verification surface
onto a broker service (
pact-broker) or a synchronised filesystem. The Oshun monorepo ships every domain spec and SDK in-tree, so the broker adds operational cost with no new guarantees. - OpenAPI already is the contract. The provider publishes OpenAPI at
libs/openapi/src/specs/*, and the SDK is generated from it. Pact's value proposition — "consumer and provider never share a schema" — does not apply here; the shared OpenAPI artefact is the schema. - Ruby/Docker in CI. Pact provider verification historically required the pact-ruby-standalone binary. Every CI job paying that cost for contracts that could be verified with a 200-line helper is waste.
Migration path if this changes: openapi-contract.ts produces the same
operation sets and schema maps that a Pact broker would consume, so a future
migration is mechanical.
Using the harness#
Under each client library at libs/<domain>/client/src/contracts/:
import {
readOpenApiDocument,
extractOperationSet,
extractSdkOperations,
findMissingOperations,
normalizePath,
} from '@oshun/testing/contract-testing';
const spec = readOpenApiDocument(SPEC_PATH);
const providerOperations = extractOperationSet(spec);
describe('<domain> provider contract', () => {
it('declares every operation the SDK consumer relies on', () => {
const missing = findMissingOperations(providerOperations, [
'POST /v1/foo',
'GET /v1/foo/{id}',
]);
expect(missing).toEqual([]);
});
});
See libs/{isis,sophia,hathor,bellona}/client/src/contracts/*.contract.spec.ts
for reference consumers.
Path normalisation#
normalizePath collapses four common drift vectors:
| Input | Output |
|---|---|
/v1/worlds/{worldId} |
/worlds/{} |
/v1/worlds/:worldId |
/worlds/{} |
/api/v1/worlds/${id} |
/worlds/{} |
/worlds/{worldId}/branches/ |
/worlds/{}/branches |
Path normalisation is the single most common source of silent contract drift
(provider team uses /{param}, SDK uses /:param, tests write /${id}) so
every operation passes through normalizeOperation before comparison.
Drift registry#
SDK operations that the provider spec does not yet document go into a per-domain
KNOWN_SDK_DRIFT set. The registry is deliberately asymmetric:
- Adding a new SDK route that is not in the spec and not in the registry fails CI. This prevents undocumented routes from accreting silently.
- Removing a route from the SDK while leaving a registry entry also fails CI. This forces the registry to reflect current reality — it cannot quietly accumulate dead entries.
The registry exists to make drift visible and bounded, not acceptable. Each entry is tech debt against the provider contract; the spec team should move entries out of the registry and into the spec, not the other way around.
Events#
Cross-service contract specs also verify that domain event envelopes carry
the fields upstream/downstream consumers read. See
tests/integration/fixtures/event-fixtures.ts for the fixture factories and
libs/*/client/src/contracts/*-cross-service.contract.spec.ts for usage.