Eve library

`@oshun/testing/contract-testing`

Other

Revision 1

On this page

Consumer-driven contract (CDC) testing framework for Oshun domains.

What it is#

A small, zero-runtime-dependency CDC harness that:

  1. Reads an OpenAPI spec (the provider contract) from libs/openapi/src/specs/<domain>/<domain>-api.yaml.
  2. Reads the consumer SDK (libs/<domain>/client/src/**) and extracts the HTTP call sites it relies on.
  3. 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:

  1. 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.
  2. 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.
  3. 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/:

ts
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.