Bizi arayın:
REST Assured-клиента на данный момент нет, но есть открытое problem на его возвращение. В том же REST Assured мы использовали builder-паттерн, и у каждого вызова параметра собственный https://deveducation.com/ метод. И тест на REST Assured будет выглядеть вот так. В качестве библиотеки для сравнения я возьму готовую библиотеку Retrofit, которая есть в OpenAPI Generator и Swagger Codegen.
Получалось, что все члены команды имели разные подходы к автоматизации тестирования. К тому же есть ещё одна важная проблема — наши REST API активно развиваются. Это означает, что при новых релизах в наших сервисах нам нужно править тестовый клиент. По факту у нас происходит гонка нашего тестового клиента и REST API. Скажем так, у нас есть несколько десятков REST API и несколько десятков тестовых клиентов, которые нужно поддерживать. И это адский труд, который отнимает огромное количество времени и вообще не имеет никакого отношения к автоматизации тестирования.
Обращает на себя внимание краткость документации, реализованной с помощью Swagger. Это объясняется тем, что сам по себе Swagger UI предназначен для интерактивного взаимодействия. Нет смысла читать пространные описания, когда можно просто выполнять указанные запросы и проверять, какие ответы приходят.
Swagger-coverage Как Его Использовать?
Много времени также уделено практической части — в ней делается простой Swagger, который затем отображается в Swagger UI и в документации. Отображение документации можно проверить локально. Если всё в порядке, загрузите папку dist (ее можно переименовать) на сервер и добавьте документацию на существующий сайт. В примере используется модель авторизации OAuth 2.0. На самом деле, код представлен в демонстрационных целях, никакой реальной логики за авторизацией нет. После настройки конфигурации мы получим аннотации, которые можно использовать для документирования кода.
Аналогично можно сгенерировать тесты для параметров и моделей. Вы просто проходите по всем параметрам и добавляете шаблоны тестов, чтобы для каждого параметра сгенерировались аналогичные тесты. Давайте попробуем написать это в виде шаблонов. Для этого я привёл пример параметров для такого теста. У нас есть механизм в REST Assured Response и Request specification.
Значения в OpenAPI-спецификации второй версии хранятся в поле «x-exаmple». Ещё вариант — поиск с множеством параметров. Этого метода в API api.pet нет — и получаем ошибку компиляции. Добавим ещё один параметр к нашей ручке search. У нас есть спецификация, мы добавляем ещё один параметр, происходит генерация, и наш тест, написанный в Retrofit, ломается.
Вместо кода, где у нас не типизированные assertions, а стандартные hamcrest матчеры, мы получаем типизированные assertions — более удобные и понятные. Если у нас кроме модели ещё есть примеры значений параметров, то можем попробовать сгенерировать реальные шаблоны тестов и сами тесты. Нужно добавить парочку темплейтов, и получим тесты. Из неё нам понятно, какой перед нами API, понятны все операции, понятно, как API используется и что вернётся.
Это неожиданно и ломает все представления об автотестах. Они должны ловить такие случаи, но сейчас получается, что всё работает. Чтобы отлавливать такие случаи, мы используем diff-спецификации, о которых чуть позже. Удаление или изменение спецификации может сломать компиляцию клиента.
- Например, у наших спецификаций есть модели.
- Мы этот параметр используем в тесте, но его уже нет в клиенте.
- Мы будем делать простейший запрос без параметров и валидировать ответ.
- Это реальный тест «на 200», его можно запустить.
- То есть у нас получается два , для версии v1 и для версии v2.
В REST Assured ответ может мапиться на ответ из спецификации, а может не мапиться. Возьмём в качестве примера простейшую операцию GET /store/Inventory из Story API и попробуем написать тест. Мы будем делать простейший запрос без параметров и валидировать ответ. Сама генерация клиента в OpenAPI Generator основана на mustache template (Logic-less Mustache engine). Это круто, потому что генерация не зависит от языка программирования. Вы можете использовать mustache-шаблоны как для C#, так и для С++, так и для любого языка и получить клиент.
Swagger Ui
Если кто-то называет саму спецификацию Swagger, то это не совсем верно. Мы также можем анализировать обратную совместимость. Выявлять случайное удаление параметров и другие изменения. Swagger-diff — это opensource-проект, который помогает сравнить две спецификации.
Это онлайн-редактор для изменения и проверки API внутри браузера. Позволяет просматривать документацию в реалтайме. С его помощью можно создать описания, а затем использовать их с полным набором инструментов для генерации документации. Пользовательский интерфейс Swagger полностью размещен в SwaggerHub. Вы можете написать и визуализировать API или импортировать существующие определения для создания интерактивного интерфейса, размещенного в облаке. Благодаря встроенной интерактивности SwaggerHub позволяет безопасно предоставлять доступ к документации внешним пользователям или другим разработчикам.
В стандартном Retrofit-клиенте параметры типизированы, для тестирования это не очень удобно. Нам бы хотелось, чтобы параметры были не типизированы, и мы могли вставить любые параметры, получить ошибку и её валидировать. Также вы получите другие различные проблемы. Например, опечатки, потому что Swagger Annotation пишется руками разработчиков. Опечатки можно поправить — это не проблема.
Более того, через эту страницу можно делать запросы и получать ответы. Это оценили наши тестировщики, которые могут, не используя Curl, тестировать релиз. Исходя из этого мы решили, что будем строить наши автотесты на основе кодогенерации, и в качестве основы мы возьмём Swagger/OAS. Позже мы поняли, что можно генерировать не только bean-ны, assertion-ы, но ещё и тестовый клиент.
Мы добавляем зависимости в проект, конфигурируем настройки и получаем документацию. Сам код из-за этого может стать менее читабельным, документация тоже не будет идеальной. Но задача минимум решена — код задокументирован. Для взаимодействия с любой программой используется API. Он может быть закрытым для внешнего взаимодействия или открытым. В любом случае разработчикам следует уделять внимание его спецификации.
Возникает ошибка компиляции, потому что мы добавили ещё один параметр, о котором мы ничего не знаем конкретно в этом методе. Там есть и клиент, и тест, даже скрипт, который пушит код на GitHub. По факту этот проект уже можно использовать. Но как только вы его начнёте использовать, то поймёте, что что-то идёт не так. Ниже реальный пример, где я использовал генерацию кода. Это пример очень простой документации, которая позволяет быстро проверить работу доступных методов.
В ней есть механизм Request specification и Response specification. Это произошло в связи с независимым развитием Swagger Codegen three.X и Swagger Codegen 2.X. Из-за этого нарушилась обратная совместимость. Очень много клиентов исчезли и не были поддержаны. И ещё одна причина — это нестабильность релизного цикла.
Это в том числе нужно для того, чтобы новые члены команды быстрее и проще вовлекались в проект. Главное, для чего создавался клиент, — чтобы добавление нового в спецификацию почти никогда не ломало компиляцию клиента. Понятно, что если мы добавим параметры, как я рассматривал раньше, всё будет хорошо.
Бывает так, что проект автотестов не компилируется из-за изменений спецификации сервиса. Необходимо понимать, почему это происходит. Для этого нам надо получить разницу в документации, например, используя swagger-diff. Например, у наших спецификаций есть модели. Мы можем попробовать сгенерировать assertions на модели ответов с помощью плагина.
Верхний уровень спецификации OpenAPI three.0 содержит восемь объектов. Внутри этих верхнеуровневых объектов есть много вложенных объектов. Давайте далее последовательно рассмотрим все объекты верхнего уровня.
Swagger — удобный инструмент для создания документации API, который помогает разработчикам сэкономить время. По факту мы получили «фабрику» автотестов, используя которую стало легко добавлять автотесты на любой проект. Тест после генерации будет выглядеть так.
Это реальный тест «на 200», его можно запустить. Для того чтобы настроить генерацию тестов, нам надо прописать template_directory с нужными темплейтами и добавить шаблон для тестов. После настройки этого плагина мы просто указываем пакет, где у нас сгенерированные модели. В Swagger Codegen с переходом на другой template-engine остался один Retrofit-клиент.