contract-tests

name	contract-tests
description	Deterministic procedure for contract tests between components (consumer-driven). The contract is described by a machine spec (OpenAPI/AsyncAPI), component links by a netlist; checked by the external pinout validator and its components. Use when a service calls another service/broker or exposes an API to consumers. Do NOT use for the internal logic of a single module — that is program-design + component-tests.
version	0.1
status	draft

contract-tests — contracts between components

A contract between components is a machine artifact, not a chat agreement. The consumer describes its expectations of the provider; if the contract is broken, CI fails before prod.

Who checks: the pinout project and its components: pinout-openapi (REST), pinout-asyncapi (events/queues), pinout-netlist (the map of links between services — a "netlist" as in circuit design). Contracts are the source of truth about boundaries; pinout reconciles consumer and provider.

0. When to apply (router)

Situation	Action
Service calls another's REST API	consumer contract in OpenAPI → pinout-openapi check
Service publishes/listens to events	contract in AsyncAPI 3.0 → pinout-asyncapi check
Several services in one feature	links in netlist → pinout-netlist check
Internal call within a module	NOT here → program-design + component-tests

1. Procedure

Pass C1 — Contract spec (spec-first). The contract is described BEFORE code in api-specification/ (OpenAPI 3.x for REST, AsyncAPI 3.0 for events). Change the contract — change the spec, not the other way around. (Check: the spec exists and is valid.)

Pass C2 — Consumer-driven expectations. The consumer fixes exactly what it uses (fields, response codes, event format). This is the contract test: a minimal slice, not the whole spec. (Check: expectations are tied to specific fields/codes.)

Pass C3 — Register in netlist. The "consumer → provider" link is added to the netlist (pinout-netlist): who calls whom, which contract. One component = one node. (Check: the edge exists in the netlist and references the C1 spec.)

Pass C4 — Check in CI. pinout reconciles: the provider spec covers the consumer's expectations; the netlist is consistent (no dangling/contradictory links). Contract failure = block before prod (treated as a hard violation). (Check: pinout report is green in CI before merge.)

2. STOP rules

• The contract changes without changing the spec → You MUST stop (API-first violation).
• The consumer depends on a field outside the contract → You MUST stop, extend the contract or remove the dependency.
• The netlist is inconsistent (provider removed a field the consumer uses) → CI fails, do NOT merge.
• No spec, but the decomposition requires a cross-service call → You MUST stop, spec first.

3. Output

• Specs in api-specification/ (OpenAPI/AsyncAPI).
• An entry in the netlist (pinout).
• A green pinout report in CI as a merge condition.

Contract tests complement component tests (service behavior as a black box) and mathematical composition (correctness of modules inside). Together they cover quality without test environments: internal correctness — by composition, external — by contracts, behavior — by component tests, prod health — by the 4 golden signals.