Что такое контрактное (schema/contract) тестирование API и зачем оно нужно в дополнение к обычным функциональным тестам эндпоинтов?

Короткий ответ

Контрактное тестирование проверяет, что фактический формат запроса/ответа API соответствует согласованной схеме (например, OpenAPI-спецификации), что позволяет заранее обнаружить несовместимые изменения API для клиентов, которые сами по себе не ломают функциональные тесты сервера.

Как это работает подробнее

Схема (OpenAPI/JSON Schema) описывает ожидаемую структуру полей, их типы и обязательность. Тест может валидировать реальный ответ сервера против этой схемы (например, через schemathesis или jsonschema), либо, в подходе consumer-driven contracts, клиент фиксирует свои ожидания в контракте, а сервер в CI проверяет, что продолжает ему соответствовать.

Пример кода

testing_example_319.pyКопировать

import schemathesis
schema = schemathesis.openapi.from_url("http://localhost:8000/openapi.json")
@schema.parametrize()
def test_api_matches_openapi_schema(case):
    response = case.call()
    case.validate_response(response)  # проверка структуры и статусов по схеме

Что использовать на практике

• Практика. Такое тестирование особенно полезно в системах с несколькими независимо развивающимися сервисами или внешними потребителями API, где обычный функциональный тест на сервере может быть зелёным (данные корректны по бизнес-логике), но формат ответа изменился и сломал клиента, которого разработчик сервера не видит в своём репозитории.

Подводные камни

• Риск. Полагаться только на функциональные тесты конкретных значений ответа и не проверять саму структуру схемы, из-за чего переименование или удаление поля остаётся незамеченным до жалобы интеграционного партнёра в production. Поддерживать схему OpenAPI вручную отдельно от кода, что быстро приводит к расхождению схемы и реального поведения сервиса.