# `@oshun/testing/contract-testing`

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.
