Проблема: в лаборатории из 10 команд — 150+ микросервисов и ни одного общего механизма проверки контрактов. QA‑инженер есть не в каждой команде.
Цена вопроса: несколько инцидентов с обратно несовместимыми изменениями на проме.
Ограничение: тесты должны писать аналитики, без единой строки кода.

В статье Максим Дубинин, ведущий инженер‑программист Nexign, рассказывает, как за 4 дня родился прототип, во что он вырос за полтора года и какие два архитектурных решения пришлось откатывать. 

План:

• почему не подошли Dredd, Pact и прочие готовые решения;

• как выглядит тест‑кейс, который не нужно писать;

• две ошибки, которые мы допустили и исправили;

• что получилось и что дальше.

Как мы пришли к контрактному тестированию

Сперва немного контекста. Наша «Лаборатория микросервисов» занимается заказной разработкой информационных систем на микросервисной архитектуре — отсюда и специфика, о которой пойдёт речь дальше.

Мы применяем подход Design First, и контракты API наших микросервисов появляются до написания их кода. Наша лаборатория, состоящая из десятка команд, создаёт, развивает и поддерживает 150+ микросервисов различного назначения: от бек‑офисных информационных систем до высоконагруженных BSS‑решений, в основном для операторов связи. Жизненным циклом спецификаций (они же контракты) API мы управляем при помощи системы ApiDoc собственной разработки (витрина и редактор спецификаций синхронного и асинхронного API).

Так исторически сложилось, что не в каждой команде нашей лаборатории имеется свой QA‑инженер, а «зверинец» из API постоянно разрастается и требует более пристального и систематического внимания. Спустя несколько болезненных инцидентов попадания обратно несовместимых изменений на промышленные стенды было принято решение о необходимости создания нового для нашей лаборатории процесса, который позволил бы взять данные риски под контроль. Этим новым процессом и стало контрактное тестирование.

У меня уже были некоторые наработки по автоматизации тестирования API на основе контрактов: в рамках предусловий теста самописный клиент ApiDoc получал последнюю актуальную версию контракта API, после чего выполнялся поиск нужной схемы объекта тела ответа, которая и использовалась при валидации тела ответа от сервиса при помощи библиотеки jsonschema. Данный подход покрывал проверки запросов, тела ответов которых представляют из себя JSON, но для сервисов нашей команды это покрывало большую часть случаев. Тогда я поделился с коллегами своими наработками, в соседних командах лаборатории присматривались к этому методу тестирования API, но единого выработанного подхода на тот момент не было. Существенным ограничением этого подхода в случае нашей лаборатории была необходимость написания автотестов на языке программирования, а это было доступно не каждой команде.

Архитекторы и менеджеры лаборатории ставили следующие цели:

• Автотестирование контрактов должно достигаться без необходимости писать код.

• Максимальная полнота покрытия тестами всех вызовов, описанных в спецификации.

• Запустить настроенное контрактное тестирование должен иметь возможность любой сотрудник, имеющий доступ к тестовым стендам.

• Инструмент должен обеспечить возможность контроля обратной совместимости API.

От опенсорса к кастомному решению

PDCT vs CDCT

Прежде чем перейти к выбору инструмента, стоит договориться о терминах — иначе половина читателей подумает про Pact, а мы имеем в виду совсем другое.

Consumer‑Driven Contract Testing (CDCT) отталкивается от потребителя. Каждый клиент API описывает, какие поля и в каком виде ему нужны, эти ожидания собираются в отдельный артефакт — пакт, — и провайдер проверяется на соответствие сумме ожиданий всех своих потребителей. Модель отлично работает там, где потребители известны наперёд и сидят в том же репозитории или хотя бы в той же компании.

Provider‑Driven Contract Testing (PDCT) отталкивается от провайдера. Единственный источник правды — спецификация API, которую провайдер публикует, а тесты проверяют, что реализация ей соответствует: те ли коды ответов, та ли структура тела, те ли обязательные поля.

Нам нужен был второй вариант, и вот почему. Во‑первых, как я уже упоминал ранее, у нас Design First: контракт появляется раньше кода и уже живёт в ApiDoc — добавлять поверх него второй артефакт с ожиданиями означало бы завести второй источник правды. Во‑вторых, потребители наших сервисов — это и соседние команды лаборатории, и системы заказчика, и мы физически не можем требовать от всех них писать и поддерживать пакты. В‑третьих, задача, ради которой всё затевалось, звучала как «сервис не должен отклоняться от опубликованного контракта», а это ровно определение PDCT.

Формально это два ортогональных подхода, и в зрелом процессе они дополняют друг друга, но начинать нам надо было с провайдера.

Почему не взяли готовое

В поиске решения нашей потребности в контрактном тестировании мы сперва принялись изучать готовые решения, которые позволили бы специалистам без навыков программирования подготавливать данные и проводить контрактное тестирование в автоматическом режиме (в нашем случае эту роль должны были взять на себя системные аналитики, которые, так уж сложилось, зачастую выполняют проверки корректности работы сервисов своей команды). Требования были следующими: решение должно быть исключительно self‑hosted, работать со спецификациями OAS3 и полноценно поддерживать провайдер‑ориентированное контрактное тестирование (PDCT).

Признаемся честно: зимой 2024-го наш анализ альтернатив был поверхностным — посмотрели только два инструмента (Dredd и Pact), о которых в то время говорили на конференциях.

Проект Dredd отпал сразу: полноценной поддержки OAS3 он так и не получил — валидация шла по example‑значениям, а не по схемам, — с 2021 года не развивался, а в ноябре 2024-го уехал в архив.

Более современный Pact выглядел привлекательнее, но его опенсорсная версия из коробки заточена под CDCT — а нам, как разобрались выше, нужен был провайдер‑ориентированный подход. Расширение под PDCT потребовало бы поднимать отдельный брокер контрактов и заводить более сложную инфраструктуру. Всё это было бы терпимо, если бы не главная для нас странность: Pact требует писать или генерировать отдельные, не‑OAS контракты. При Design First и живом ApiDoc это означало бы завести второй источник правды.

На этом наш анализ рынка тогда и закончился — и вот это была ошибка. Готовя статью, мы пересмотрели рынок заново и сравнили альтернативы с тем, что у нас получилось. Детальный анализ приведу в конце, после того как познакомлю вас с инструментом.

Прототип за 4 дня

Мы решили проверить гипотезу, можем ли в условиях ограниченных ресурсов создать собственный кастомный инструмент, который будет заточен под наши потребности и процессы. Вспомнили про мою обвязку для тестирования API сервисов моей команды с использованием уже написанных контрактов API и определились с требованиями и ограничениями:

• получение и анализ спецификаций из ApiDoc;

• автогенерация списка тестов;

• отправка запросов в заглушки;

• проверки в тестах — сравнение кодов ответов и валидация тел ответов;

• только GET‑запросы с JSON в теле ответа;

• только запросы со статус‑кодом 200 в качестве ожидаемого результата.

Протестировав работу получившегося концепта, набросанного дня за 4, мы получили результат, который всех заинтересованных лиц вполне устроил, и таким образом мы получили «зелёный свет» со стороны менеджмента на создание кастомного PDCT‑инструмента для контрактного тестирования на Python силами двух QA‑инженеров.

Старт создания MVP

Сбор требований

Путь создания инструмента начался традиционно с аналитики — сбора и проработки требований. Нам предстояло выяснить и договориться по следующим вопросам:

Объект дополнительных параметров

Больше всего вопросов вызывал основной функционал инструмента — генерация тестовых данных и выполнение запросов. Понимая, что не сможем сразу покрыть все кейсы, мы добавили возможность в объекте дополнительных параметров указать, что тестирование данной операции должно быть пропущено (skip). Также было важно иметь возможность указывать, от лица какой именно технологической учётной записи (мы называем их «болванами») должен быть выполнен запрос — мы добавили поле с индексом (user-index) тестового пользователя (сейчас у нас их 10, определяются по этому самому индексу внутри его имени, например, contract-testing-01_tech).

Как уже упоминалось ранее, одним из требований к инструменту была возможность запускать его в разных тестовых окружениях, а значит и тестовые данные на разных стендах почти всегда будут уникальными. Хранить статичные тестовые данные для каждой отдельной тестовой среды прямо в контракте нам не казалось хорошей идеей, к тому же это вовсе не решало бы проблему с динамичными тестовыми данными. Для решения этой задачи мы добавили возможность использовать пользовательские переменные: для статики — специфичные (привязанные к конкретной тестовой среде) и общие, указываемые в отдельных файлах, а для динамики мы реализовали механизм определения очерёдности тестовых вызовов (group-index и sequence-index) и парсинга тела ответа с сохранением значений нужных ключей в переменные (response-parsing). Значение любых таких переменных стало возможным использовать в качестве query‑ или path‑параметра (params-mapping), а также при замене значения ключа в объекте примера тела запроса (body-replacements).

Ещё одной небольшой фичей стала возможность генерации случайного значения на основе регулярного выражения, которое также можно было применять аналогично значений переменных.

• схемы безопасности;

• примеры тел запросов;

• комбинации path‑параметров (прямое произведение);

• комбинации query‑параметров (попарное тестирование).

В случае с query‑параметрами мы отказались от применения прямого произведения вариантов, поскольку значительное число параметров могло привести к генерации нескольких десятков комбинаций и, как следствие, избыточного количества тест‑кейсов. Полный набор тест‑кейсов представлял из себя произведение всех мультипликаторов (параметров запросов, описанных выше).

Как выяснилось позднее, такой подход к составлению тест‑кейсов имеет значительный недостаток — он не учитывает бизнес‑смысл параметров, некоторые из которых вступают во взаимозависимость и могут противоречить друг другу, и в этом случае инструмент будет генерировать тест‑кейсы, конфликтующие с бизнес‑логикой. OAS3 не решает данную проблему, и позднее нам пришлось кардинально сменить курс в методике составления тест‑кейсов.

Что дополнительно реализовали в MVP

На этапе MVP мы добавили ещё несколько полезных фич: 

• реализовали функцию загрузки HTML‑отчётов в Artifactory для сохранения истории тестирования;

• интегрировали отправку метаданных о результатах прогона контрактного тестирования в ApiDoc, а их команда разработки добавила дашборд, позволяющий просматривать эту информацию;

• добавили обвязку и интегрировались с Allure TestOps, чтобы результаты контрактного тестирования отгружались в качестве прогона, что позволило в некоторых случаях покрыть потребность в прохождении приёмо‑сдаточных испытаний;

• встроили инструмент в пайплайн CI/CD, сделав шаг контрактного тестирования обязательным, но не блокирующим.

К слову, вот так на этом этапе выглядел HTML‑отчёт о тестировании:

Где‑то в то же время подобрали название для нашего инструмента — OASIS, или OAS Integrity Sentry, “оазис” надёжности и ясности в «пустыне» сложных интеграций. Метафора основана на аспектах прямой связи с OAS и функции «часового» (Sentry), который охраняет целостность (Integrity) API. Название и логотип мы сгенерировали при помощи нейросети.

Появление вспомогательного инструмента

Основными пользователями OASIS стали системные аналитики, авторы контрактов API. Собирая от них обратную связь о нашем инструменте, мы получили запрос на скрипт, который бы добавлял шаблонные объекты дополнительных параметров для контрактного тестирования в объекты операций, чтобы не пришлось всё добавлять вручную. Размышляя, как лучше всего закрыть эту потребность, родилась идея создать простенький браузерный инструмент, позволяющий добавить такую шаблонную дополнительную разметку нажатием одной кнопки, а также редактировать контракт и все необходимые параметры тут же, в одном окне, и просматривать статус покрытия всех операций параметрами для их тестирования. У меня практически не было опыта написания веб‑приложений на JS, и вновь на помощь пришли нейросети. Так появился помощник разметки, OASIS Markup Assistant.

Изменение подхода к хранению дополнительных параметров

По мере накопления обратной связи и идей о дальнейшем развитии инструмента мы поняли: решение добавлять дополнительную разметку прямо в контракт было ошибочным, поскольку это порождает несколько проблем, которые не были очевидны для нас в момент проработки требований к MVP. Эти объекты довольно сильно перегружают контракт по сути чужеродной для него информацией, которая не представляет никакой ценности ни для заказчиков (потребителей API), ни для разработчиков, а в некоторых случаях даже являются нежелательными. А перспектива развития инструмента подсказывала нам, что вспомогательных данных будет становиться только больше.

По этой причине мы приняли решение изменить подход к хранению дополнительных параметров, вынося их в отдельный файл, объединив их с файлами пользовательских переменных. Теперь объекты этих параметров мы предложили описывать в структуре, дублирующей объекты paths. Заодно перешли с kebab‑case на camelCase — внутри контракта мы следовали стилю x‑расширений OAS, а в собственном файле смысла в этом уже не было.

Для облегчения перехода к такому новому подходу был особым образом обновлён помощник разметки, который позволил сгенерировать файл параметров контрактного тестирования и перенести в него все имеющиеся параметры из контракта, а также удалить их из этого же контракта, сделав его чище. Для удобства был добавлен ещё один редактор, теперь уже для документа с параметрами контрактного тестирования и блок анализа покрытия контракта параметрами тестирования в режиме реального времени. И ещё мы немного освежили его внешний вид:

Честная оговорка: вынос параметров в отдельный файл не сделал их бесплатными в поддержке. Если в новой версии контракта появились или изменились операции, файл параметров нужно править руками — сам он за контрактом не следует. Именно поэтому в помощнике разметки появился блок анализа покрытия: он в реальном времени показывает, какие операции контракта остались без параметров тестирования, так что расхождение видно сразу, а не всплывает на прогоне.

Приблизительно в это же время мы улучшили внешний вид нашего HTML‑отчёта:

Если собрать всё описанное вместе, схема контрактного тестирования выглядит так. Контракт необходимой версии всегда берётся из ApiDoc, параметры тестирования готовятся в помощнике разметки. Запуск — параметризованная Jenkins Job или шаг пайплайна CI/CD. Запросы уходят от лица технологических учётных записей через APIGW, а результаты прогона OASIS раздаёт в три системы: HTML‑отчёт в Artifactory, метаданные в ApiDoc и прогон в Allure TestOps.

Фиолетовым выделены наши инструменты, серым — инфраструктура, коралловым — объект тестирования, бирюзовым — приёмники результатов.

Что уже изменилось

Сегодня контрактным тестированием охвачено контракты 50+ микросервисов, размечено около 600 операций, прогон одного контракта занимает полторы минуты и выполняется на каждой сборке. Инструментом пользуются девять команд лаборатории из десяти. Контракты 50+ микросервисов — это те, где контрактное тестирование уже настроено; остальные сервисы подключаются по мере готовности параметров.

Самый неожиданный эффект — инструмент оказался не только проверяющим реализацию, но и, в некоторой степени, ревьюером спецификаций. Он регулярно находит в контрактах то, что проходит мимо глаз при обычном ревью: например, валидатор указал на поле products со значением null, хотя в схеме объявлен тип array. В контракте не было ни nullable: true (как это делается в OAS 3.0), ни null в списке допустимых типов (как в OAS 3.1). Формально прав сервис, фактически — расходятся контракт и реализация, и без прогона этого никто бы не заметил.

Второй эффект — на аналитиков. Чтобы понять, почему тело ответа не прошло валидацию, приходится разбираться, что именно описано в схеме. Уровень владения OAS в командах вырос сам собой, без единого обучающего мероприятия. Часть расхождений заканчивается правкой контракта, часть — заведением дефекта на реализацию сервиса.

Третий эффект организационный: прогон отгружается в Allure TestOps, и в ряде случаев это закрыло потребность в отдельных приёмо‑сдаточных испытаниях.

Уже не MVP, но ещё не релиз

Наш бэклог, анализ требований будущих фич и обратная связь от пользователей подтолкнули нас к мысли о неизбежности ещё одного отката — отказаться от генерации тест‑кейсов, оторванных от бизнес‑логики, в пользу функционала ручного составления тест‑кейсов, имеющих реальную ценность. Заодно планируем понизить уровень контекста тестирования — если выражаться в терминах OAS3, с операции до кода ответа или даже до медиатипа. Это позволит тестировать больше одного кода ответа (сейчас — только один вызов с ответом из группы 2XX) и работать с запросами не только в медиатипе application/json, что сегодня ограничивает инструмент. Покрытие вырастет и внутри отдельного контракта, и по всем контрактам в целом.

Помимо этого, к нам пришло понимание о необходимости пересмотра архитектуры нашего решения: из отдельного приложения OASIS выделить универсальную core‑часть, которая станет основой для отдельных консольной (для использования в CI/CD) и настольной версий OASIS. В состав последней также должна войти и новая версия OASIS Markup Assistant, кардинально меняющая опыт планирования и составления параметров контрактного тестирования — в нём мы намерены реализовать конструктор тест‑кейсов, который в режиме реального времени будет анализировать тела контракта и файла параметров контрактного тестирования и предлагать доступные параметры такого тест‑кейса исходя из контекста узла (объект кода ответа или медиатипа), для которого пользователь хочет добавить или изменить тест‑кейс.

Четвёртая цель («Инструмент должен обеспечить возможность контроля обратной совместимости API»), которую перед нами ставили архитекторы на этапе сбора требований, до сих пор не закрыта — на MVP мы сознательно отложили её ради базового покрытия. Сейчас понятно, что писать свой diff‑движок не нужно: задача решается интеграцией oasdiff в функцию управления жизненным циклом контракта в ApiDoc, не позволяя опубликовать обратно несовместимую минорную версию контракта. Эта задача попала в бэклог команды разработки ApiDoc, а в зоне ответственности OASIS останется гарантировать, что API микросервиса реализовано в строгом соответствии с конкретной версией контракта.

Опенсорсным наше решение мы изначально не планировали делать, и на то две причины. Первая — трудозатраты: универсальный инструмент требует совсем другой проработки архитектуры, а текущая версия слишком заточена под нашу инфраструктуру и процессы. Вторая — ресурсы: полноценно поддерживать проект с открытой лицензией нам сейчас нечем. Возможно, к этому вопросу мы вернёмся после выделения core‑части — она как раз задумана более универсальной.

Сравнение нашего решения и опенсорсных альтернатив

Две вещи вынесены за скобки таблицы, чтобы не раздувать её. Первое: все рассмотренные инструменты разворачиваются на собственной инфраструктуре, отдельная оговорка есть только у Pact, которому нужен отдельно поднятый брокер контрактов. Второе: валидировать тело ответа по JSON Schema умеют все они без исключения — кроме oasdiff, который не тестирует спецификации, а сравнивает их между собой.

Одна оговорка к строке Pact: провайдер‑ориентированный сценарий поверх OAS у него появился позже, в виде bi‑directional contract testing, но это эксклюзив коммерческого PactFlow, а не опенсорсного брокера.

Ещё несколько инструментов мы не стали заносить в таблицу — они относятся к другому классу задач. Prism — валидирующий mock‑прокси, а не раннер тестов. RESTler — исследовательский stateful‑фаззер: он ищет неожиданное поведение, а не проверяет регрессию соответствия контракту. Karate и Postman/Newman — универсальные раннеры API‑тестов. Сгенерировать по спецификации стартовый набор сценариев для них сегодня вполне можно: у Karate есть и собственный AI‑харнесс Karate Agent (правда, коммерческий), и сторонние генераторы вроде ZenWave SDK. Разница в том, что там сгенерированный артефакт — feature‑файл или коллекция — становится основным и дальше правится вручную целиком, а его расхождение с контрактом ничем не подсвечивается. Portman в таблице остался именно поэтому: коллекция у него — промежуточный артефакт, который перегенерируется из спецификации, а не правится руками. У нас же список операций и схемы ответов на каждом прогоне берутся из определённой версии контракта, руками поддерживается только слой тестовых данных, а его расхождение с контрактом видно как процент покрытия в помощнике разметки.

Выводы после повторного анализа получились двоякие. По функциям движка мы во многом повторили то, что уже есть в опенсорсе: генерацию тест‑кейсов из спецификации умеют Schemathesis, CATS и Portman, проверку обратной совместимости — oasdiff и Specmatic, а конструкцию «отдельный файл с тестовыми данными» мы придумали независимо от Endava, у которых она называется reference data.

Но три вещи не закрывал никто: интеграция с нашим ApiDoc, авторизация через APIGW и Keycloak от лица десяти преднастроенных техучёток и запуск в двух окружениях — нашем и заказчика. А визуальный редактор параметров, аналог нашего Markup Assistant, в ближайшем по духу Specmatic вынесен в платный Specmatic Studio.

Если бы мы делали этот выбор сегодня, то, вероятно, взяли бы готовый движок и надстроили над ним свою обвязку. Но оснований считать всю разработку ошибкой у нас нет — решение писать своё было правильным как минимум по эксплуатационным причинам (интеграция с внутренним ландшафтом и no‑code для аналитиков).

Заключение

Если свести полтора года в несколько строк, получается так.

Собственный инструмент под конкретный процесс имеет смысл — но не потому, что «в опенсорсе такого нет». В опенсорсе такое есть, и мы честно показали это в таблице выше. Смысл был в другом: ни один готовый инструмент не знал про наш ApiDoc, нашу схему авторизации и два окружения, а именно это и составляло основную часть работы.

Второй вывод дороже первого: анализ альтернатив стоит делать всерьёз даже тогда, когда решение уже кажется очевидным. Мы сделали его наспех в 2024-м и вернулись к нему только сейчас, готовя эту статью, — и нашли как минимум oasdiff, который закрывает нашу четвёртую цель без единой строки кода, осталось встроить его в наш инструментарий и процессы.

Третий вывод про сами контракты: инструмент, который проверяет реализацию на соответствие спецификации, неизбежно начинает проверять и качество самой спецификации. Мы этого не планировали, но получили — и в итоге это оказалось едва ли не самым полезным эффектом прямо сейчас.

А как вы проверяете обратную совместимость API? Делитесь своим опытом в комментариях.

Читайте также: Как мы создаем приложение на основе микросервисной архитектуры, с какими особенностями сталкиваемся и как их обходим.