Поставщик API добавил новое значение статуса, и клиент перестал показывать список. Формат ответа остался допустимым для сервера, но нарушил предположение потребителя. Контрактный тест фиксирует необходимые клиенту свойства и помогает обнаружить несовместимость до совместного развертывания.
Что подготовить
- Реальные обезличенные запросы потребителей и минимальные поля, необходимые каждому сценарию.
- Схема API, варианты ошибок, правила версионирования и необязательных значений.
- Способ запустить поставщика на контролируемых данных и список поддерживаемых версий клиентов.
Порядок работы
- Опишите ожидания со стороны потребителя: типы, обязательность, значения и смысл полей. Не копируйте в контракт все случайные детали ответа.
- Добавьте успешный ответ, пустой результат, отсутствие необязательного поля и характерную ошибку. Для списков задайте правила порядка лишь там, где он гарантирован.
- Создайте воспроизводимые состояния поставщика: существующий объект, отсутствующий объект и объект с ограниченным доступом.
- Проверяйте поставщика по сохраненным ожиданиям поддерживаемых потребителей. Отдельно проверяйте обработку расширений на стороне клиента.
- Включите изменение контракта в процедуру выпуска: несовместимость требует согласованной миграции, а не обновления эталона ради зеленой сборки.
Разобранный пример
Клиенту списка нужны id, title и status. Контракт не фиксирует внутренний timestamp, которым интерфейс не пользуется. При появлении нового статуса клиент показывает нейтральную подпись, если такое расширение предусмотрено соглашением. Если статус управляет доступным действием, требуется отдельное согласование поведения.
Как проверить результат
- Удаление обязательного поля действительно вызывает падение проверки.
- Добавление неизвестного необязательного поля не ломает терпимого потребителя.
- Ошибки проверяются по статусу и машинному коду, а не только по свободному тексту.
Если что-то пошло не так
Если контракт стал слишком жестким, выясните, какое ожидание требуется продукту, а какое возникло из случайного примера. Ослабляйте только лишнее ограничение. При реальной несовместимости поддержите переходный формат или новую версию API.
Промпт для разбора ваших материалов
Из кода потребителя и примеров API выдели минимальный контракт. Подготовь сценарии поставщика, проверки успешных и ошибочных ответов и перечень несовместимых изменений. Отдели необходимые ожидания от случайных деталей примеров.Частые вопросы
Заменяет ли контракт сквозной тест?
Нет. Он проверяет границу взаимодействия, но не подтверждает полный пользовательский путь через все компоненты.
Нужно ли фиксировать весь JSON?
Обычно нет. Проверяйте свойства, от которых зависит потребитель, чтобы безвредные расширения не создавали ложные тревоги.
Материал библиотеки решений Ильи Тарасова / TarasovWeb.
Минимальный контракт на конкретном примере
Представьте экран заказов, которому нужны идентификатор, подпись и признак доступности отмены. Контракт следует строить вокруг этих потребностей. Внутренний диагностический timestamp не обязательно фиксировать, если интерфейс его не использует. Но изменение смысла признака отмены критично даже при сохранении типа boolean.
Сделайте отдельные состояния поставщика: обычный заказ, уже выполненный, отсутствующий и недоступный текущему пользователю. Для каждого состояния укажите ожидаемый ответ и поведение клиента. Ошибка доступа не должна случайно выглядеть как успешный пустой список, если интерфейс должен объяснить ограничение.
Проверьте клиента на дополнительные поля и неизвестные значения перечисления. Решение о допустимости расширений нужно принять явно. Если новый статус лишь отображается, возможна нейтральная подпись. Если он разрешает действие, безопасное поведение и поддержка версии требуют отдельного правила, а не автоматического выбора первого известного варианта.
При падении контракта не обновляйте снимок ответа без анализа. Разделите намеренное изменение интерфейса и случайную несовместимость. Для намеренного изменения подготовьте порядок выпуска потребителя и поставщика, период поддержки старого формата и критерий завершения перехода. Сохраните пример несовместимого ответа как регрессионный тест. Проверяющий должен понимать, какое пользовательское действие защищает каждое ограничение, иначе контракт быстро превратится в копию случайного JSON.
О проекте
Практическая библиотека Ильи Тарасова и TarasovWeb. Telegram-канал · Личная страница · ВКонтакте.
#tarasovweb #ИльяТарасов