Таки здравствуйте. Как вы поняли по названию, сегодня в блоге ЛАНИТ мы продолжим мучить JSON. Располагайтесь поудобнее и поехали вместе выжимать из него очередную порцию полезностей для работы.
В предыдущей статье мы использовали JSON как формат передачи данных и файл для подгрузки тестовых данных. Но это еще не все, что он может нам дать для тестирования API. И да, сегодня мы научимся использовать JSON в качестве шаблона для валидации ответов на запросы.
В работе с XML-форматом для анализа контента и валидации XML-сообщения используется так называемая XSD (XML-Schema Definition). Этот файл описывает то, какой должна быть структура и контент XML-сообщения, с которым мы имеем дело.
Так вот, JSON-Schema ― это, грубо говоря, ее аналог, только для JSON'a.
Где раздобыть сего зверя
Итак, давайте сразу перейдем к делу. В идеале в документации на API тестируемого приложения для запросов стоит прикладывать данную схему для каждого запроса.
Однако, как показывает практика, все еще не так часто встречаются случаи, когда на проектах наши коллеги сталкиваются с необходимостью тестировать API с использованием скриптов. То, что может сделать JSON-Schema, осуществляется инженерами вручную. Этот элемент документации может отсутствовать в доступе специалиста по тестированию.
Но даже если так, то согласитесь, что лучше уметь этим пользоваться, чем наоборот.
Если схемы нет в доступе или вам ее не хотят давать, но очень хочется использовать в тестах, то можно составить ее самостоятельно. Для этого нам потребуется описание модели данных из документации. Рассмотрим простой вариант. У нас в учебной системе HelpDesk есть запрос на получение токена рабочей сессии (да, опять будем использовать его как подопытного).
Здесь отметим важное. Несмотря на то, что мы стараемся преподносить материал в легкой и слегка шутливой форме, помните, что мы даем вам механику работы с инструментом. В приведенных примерах все может показаться простым. Однако применение JSON-Schema требует практики и внимания при составлении, а внедрение любого нового инструмента по вашей инициативе ― это еще и ответственность за его качественное использование и влияние на процесс тестирования.
Анализ документации
Итак. Если в Swagger обратиться к режиму отображения тела ответа в виде модели данных (смотрим на картинку выше), мы увидим, что получаемое тело успешного ответа должно содержать:
поле username (является обязательным),
значение, возвращаемое в поле username, должно относиться к типу данных «строка» (string),
минимальное количество символов, которое может содержать это поле в ответе ― 1 символ,
поле password (является обязательным),
значение, возвращаемое в поле password, должно относиться к типу данных «строка» (string),
минимальное количество символов, которое может содержать это поле в ответе ― 1 символ,
в ответе присутствует поле token,
значение, возвращаемое в поле token, должно относиться к типу данных «строка» (string),
минимальное количество символов, которое может содержать это поле в ответе ― 1 символ,
данные, получаемые в поле token, предназначены только для чтения (readOnly: true).
Составляем «схему»
Как это будет выглядеть, если мы запишем правила в формате JSON-schema?
Какие-то вещи в этом JSON'е могут быть интуитивно понятны, но давайте вместе и пошагово разберем, что здесь к чему.
Как мы помним, любой JSON ― это объект или список объектов. В нашем случае мы получаем один объект в ответе, поэтому для ключа type указываем значение "object".
Затем нужно описать свойства этого объекта. Для начала их описания мы записываем ключ properties, который, собственно, и означает на православном "свойства".
В качестве значения в этом ключе будет передаваться встроенный объект, в котором будут перечисляться все ключи параметров тела ответа.
И для каждого из этих ключей в качестве значения будут передаваться объекты еще более глубокого уровня вложенности, где, в свою очередь, в парах ключ-значение будут транслироваться все те свойства, которые мы увидели в модели данных в документации.
Обратите внимание, что после перечисления свойств полей, у нас есть ключ "required".
В этом ключе мы всегда можем перечислить все те поля, которые являются обязательными. Если их больше, чем одно, то передавать их нужно в виде массива (в квадратных скобках).
В JSON-Schema можно описывать разные параметры и состояния ответов.
Ранее мы уже сделали оговорку, что если мы ожидаем от сервера в ответе только один объект, то для ключа "type" указывается значение object. Но у нас также есть запрос, который возвращает нам список всех имеющихся в системе тикетов. В этом случае мы получаем целый список объектов. В таком случае нужно уже указать вместо object значение array (массив).
После чего идет ключ "items", в котором мы уже будем проводить описание шаблона параметров по которому будет проверяться каждый объект в получаемом в ответе массиве. Само описание происходит по той же логике, что и в прошлом примере.
Рассмотрим пример такой схемы на основе некоей абстрактной карточки задач в абстрактном таск-менеджере.
Как видно из примера, нет нужды N-ое количество раз описывать поля карточки задачи. Что логично, так как сегодня система вернет их пару сотен, а спустя какое-то время их может быть больше тысячи. Достаточно сделать это один раз. Postman проверит каждый объект, полученный в массиве, по этому списку правил, так как при получении списка объектов указан тип array.
Отметим два интересных момента в этом примере.
Как видите, атрибут required расположен не после описания свойств полей карточки задачи, а до него. Это тоже валидная вариация описания формы схемы.
Для поля priority присутствует свойство enum. Сокращение от enumeration (перечисление). Оно часто используется для описания полей, которые ждут для ввода значение из строго определенного списка. Ярким примером такого поля будут выпадающие меню.
Если по документации мы знаем, что в ответе получим массив, мы также можем использовать различные варианты ограничителей. Например, базовые minItems maxItems, с помощью которых можно ограничить минимальное и максимальное количество объектов, ожидаемых в теле ответа.
Выше мы привели только пару примеров описания параметров ответа с их вариантами значений. На самом деле их куда больше.
Поэтому, чтобы не превращать материал в сауну, в конце статьи есть ссылка на источник с перечислением параметров для описания схем, их трактовкой и примерами.
А теперь практика!
Давайте уже применим нашу самую первую схему на практике в Postman.
В силу того, что наша учебная система HelpDesk используется для обучения новичков, в ней и ее документации есть заложенные дефекты. Поэтому, несмотря на то, что написано в документации, запрос на получение токена только токен нам и возвращает, без всяких логинов и паролей.
Поэтому JSON-schema, которая будет нам нужна будет еще проще.
Для того чтобы проверить ответ от сервера, нам потребуется три компонента:
сам ответ,
JSON-схема,
сравнивающая их функция.
Благо последнее не придется писать с нуля ― для этой операции у нас есть связка tv4.validate().
Создадим две переменные: response и schema. В первую, конечно же, положим наш ответ в формате JSON.
Ну а в переменную schema положим упрощенную схему. Получим следующий вид:
Теперь напишем сам тест. Он в своей основе ничем не отличается от других, которые вы уже писали. Ну... те, кто опять же проходил курсы “ЛАНИТ Экспертизы”... (божественная интеграция).
Имя теста такое и возьмем «Schema_Validation», а в теле функции напишем следующее: pm.expect(tv4.validate(response, schema)).to.be.true; В итоге получим следующую конструкцию:
Теперь, если мы отправим запрос на получение токена, то увидим, что тест проходит успешно.
Но если мы что-то поменяем в схеме, то тест будет возвращать провал. Например, если заменим minLenght на 50 или type на number.
Подведем итоги
Вместе мы на простых примерах рассмотрели то, как можно составить и использовать JSON-Schema для тестирования API. Конечно, в практике JSON-Schema зачастую будет гораздо более сложной конструкцией. Поэтому если вы решите внедрять эту технологию в свой процесс тестирования API, то сначала попрактикуйтесь.
Хорошим и безопасным решением будет взять из вашей боевой подборки тестов уже многократно подтвердившие свою валидную работу Get-запросы. Лучше подобрать такие, которые обладают телами ответа с разным объемом и сложностью структуры. После чего пробовать составлять для них схемы, которые будут возвращать вам успешный результат теста.
Что важно держать в голове при работе с JSON-Schema?
Всегда помните, что внедрение любого инструмента в процесс тестирования требует понимания ответственности за все его позитивные и негативные воздействия как на качество процесса тестирования в целом, так и на продукт как результат этого процесса. Не важно, внедряете ли вы его с согласия руководства или втихаря. Последнее не рекомендуем.
Использование JSON-Schema требует внимания к структуре составляемой конструкции.
Она позволяет проверить структуру полученного ответа ― останется только проверять скриптами сами значения полей тела ответа на совпадение с ожидаемыми.
Если в полученном ответе выявляется нарушение, то в базовом виде описанная конструкция не позволит узнать точно, в каком элементе это произошло. Придется сверять тело ответа, документацию и саму JSON-Schema. Ошибка могла быть и в ней.
Мы можем заменить работу с JSON-Schema на составление скриптов, которые также будут проверять тип данных значений, типы объектов, длину массивов, значений и т. д. Такой подход как раз может дать нам больше управляемости процессом валидации. Но может занять существенно больше времени, чем составление и использование JSON-Schema. Поэтому помните, что оба подхода имеют право на существование в практике.
Хотите сделать быстрее ― JSON-Schema. Хотите больше контролировать каждый шаг валидации ― скрипты в помощь.
Теперь у вас есть еще один достаточно мощный инструмент для автоматизации тестирования запросов в Postman. Используйте его с умом и помните: «Внимательность ― лицо инженера тестирования».
Дополнительные материалы: Описание параметров JSON-Schema c примерами.