testing-api-contracts

Create a custom Playwright expect matcher that loads the OpenAPI document with ajv, resolves the response schema for each path, method, and status code, and validates every response body. Failures report the JSON path, expected type, and actual value.

Breaking changes include removing or renaming a response field, narrowing a type, adding a required request parameter, changing a status code, or altering the error body shape. Adding optional fields or endpoints is safe; new enum values and changed defaults are risky.

Use ajv with the published OpenAPI spec for provider-side validation, zod when the consumer already defines runtime schemas, and openapi-response-validator for a quick provider check with less setup. Provider testing should always validate against the published spec, not hand-written consumer schemas.

Run oasdiff breaking against the deployed spec and the branch spec in CI, then classify each change as safe, risky, or breaking using consumer evidence such as client code searches or access logs. Treat a non-empty breaking list as requiring human review.

Fixtures are snapshots that go stale when the API changes but the mocks are never updated. Validate each fixture against the same published schema on the cadence the spec changes, and report failures as test-suite defects rather than API defects.

No. Contract tests verify shape and compatibility, such as missing fields or changed types, while functional tests verify business values and behavior. Both are needed because they fail for different reasons and should be reported separately.