Skip to content

Interface Contract Test

Conformance test suite — instantiates Layer-Appropriate Capability Placement

Turns the promises a delegated host interface makes — permissions, isolation, error and capacity behavior, and what happens when the host is unavailable — into automated pass/fail checks, so delegation is verified rather than assumed.

An Interface Contract Test is an automated suite that exercises a delegated host capability against the behavior the consumer actually depends on — not just the happy-path shape of a call, but its permission and isolation guarantees, its error and capacity semantics, and its degraded behavior when the host is slow or absent. Its defining move is to convert soft promises into executable assertions that fail the build: an invariant that only lives in a design doc is a hope, but one encoded as a red test is a guarantee the host cannot silently break. This is what makes delegating to the host safer than rebuilding locally — the consumer gets a tripwire on every promise it relies on, so a host change that would quietly violate isolation or swallow an error is caught before it ships.

Example

A payments service delegates identity verification to a shared host KYC API rather than building its own. Delegation only pays off if the host's promises actually hold, so the team writes a contract test suite. It asserts the permission boundary: a token scoped to "verify" cannot read raw identity documents — a test that fails loudly if the host ever widens that scope. It asserts isolation: one tenant's verification request can never surface another tenant's data. It asserts error semantics: an unverifiable identity returns a typed unverified result, not a 200 with empty fields the caller might misread as "clear." And it asserts graceful degradation: when the KYC host times out, the service must queue-and-retry, never fail-open and approve.

The suite runs in CI against a contract stub and nightly against the host's staging environment. Months later the host team refactors and accidentally lets the verify scope read documents. The payments team's isolation test goes red the same day — the violation is caught as a failed check, not as an incident. That is the whole point: the promises that made delegation acceptable are now continuously proven, not assumed.

How it works

What distinguishes a contract test from an ordinary integration test is that it targets the guarantees, not the feature:

  • Assert the invariants, not the output. Permission scope, tenant isolation, idempotency, and typed error behavior are each encoded as a check that fails when the guarantee is broken.
  • Test the sad and the absent paths. Rate limits, timeouts, and host-unavailable are exercised deliberately, because the degraded-mode behavior is exactly what a happy-path test never sees.
  • Run against a versioned contract. The suite is pinned to a stated interface version, so a breaking host change surfaces as a failed check rather than a production surprise.
  • Fail the build, both directions. Ideally the host publishes the same tests so its own CI breaks before it ships a change that would violate a consumer's contract.

Tuning parameters

  • Assertion strictness — pinning exact error codes and latencies versus loose behavioral checks. Strict pins catch subtle drift but go brittle and red on benign changes; loose checks tolerate change but let real regressions through.
  • Environment target — stub, staging, or production. Stubs are fast and deterministic; live targets are truthful but flaky and rate-limited. The trade is speed and stability against realism.
  • Fault-injection depth — how aggressively timeouts, throttling, and host-down are simulated. Deeper injection proves the fallback rule but costs test complexity.
  • Ownership of the suite — consumer-authored, host-published, or shared. Host-published tests catch breakage earliest; consumer-authored tests capture what this caller truly relies on.

When it helps, and when it misleads

Its strength is that it makes delegation auditable: the very guarantees that justified trusting the host — isolation, scoped permission, honest errors, safe degradation — become checks that catch a violation the day it lands rather than in a postmortem. It also documents the real contract by example, which no prose spec does as faithfully.

Its central illusion is green-means-safe: a passing suite proves only the properties someone thought to assert, and the dangerous failures are usually the invariant nobody wrote a test for. Contract tests also drift toward brittleness — over-pinned assertions that go red on cosmetic host changes, training the team to ignore red, which is worse than no test at all.[1] The classic misuse is asserting the shape of a call while never testing isolation, capacity, or the host-down path — the guarantees that actually make delegation load-bearing. The discipline that keeps it honest is to test the promises the consumer depends on, keep the sad-path and absent-host cases first-class, and treat a flapping test as a bug to fix rather than noise to mute.

How it implements the components

A contract test realizes the verification slice of the archetype — it proves delegated guarantees rather than defining or delivering them:

  • security_and_isolation_invariant — encodes permission-scope and tenant-isolation guarantees as checks that fail the moment the host violates them, so the invariant is enforced continuously rather than assumed.
  • fallback_or_graceful_degradation_rule — exercises the host-slow and host-absent paths so the consumer's degraded-mode rule ("queue and retry, never fail-open") is proven under fault, not just documented.

It verifies but does not author the interface it tests — the contract surface is Service Layer or API Facade and the versioned semantics are API Versioning. The isolation invariant it checks is established at the escape boundary by Privileged Host Escape Hatch, and the degraded behavior it exercises is rehearsed live by Host-Dependency Fallback Drill; this mechanism turns both into automated pass/fail assertions.

References

[1] Consumer-driven contract testing (as popularized by tools like Pact) makes the point precisely: the contract worth testing is the subset of behavior a specific consumer relies on, not the provider's entire surface — which is why an over-broad, over-pinned suite both misses real risk and generates false alarms. ↩