Which strategy best prevents brittle tests when using interface-based mocks for external API integrations?

Answer

The most reliable way to keep interface‑based mocks in sync with a changing external API is to treat the API contract (e.g., an OpenAPI/Swagger document) as the single source of truth and validate both the mock and the real client against that contract using consumer‑driven contract testing.

Why this works

When the contract is the authoritative description, any drift in the real service will cause the contract tests to fail, prompting a regeneration of the mock or an update of the implementation. Generating the mock directly from the same spec guarantees that method signatures and default behavior match the contract.

Steps to implement

1. Maintain an up‑to‑date OpenAPI specification for the API (version‑controlled alongside the service).
2. Use a code‑generation tool such as go-openapi or swagger-codegen to produce a Go interface and a stub mock that satisfies it.
3. Write consumer‑driven contract tests (e.g., with Pact, gock, or a custom validator) that:
   • Record the expected request/response pairs from the spec.
   • Assert that calls made against the mock produce the same responses.
   • Optionally run the same assertions against a real test endpoint to detect drift.
4. Run the contract test suite in CI with go test -parallel=N -race ./... to ensure no global state leaks and to catch race conditions.
5. If a spec change is introduced, regenerate the mock and verify that the contract tests still pass; otherwise the failure signals a breaking change that must be addressed.

Missing diagnostic detail

Do you already maintain an OpenAPI/Swagger specification for the API you are mocking? If not, creating and version‑controlling that spec is a prerequisite for the approach above.