Postman в основном известен в качестве мощного инструмента для тестирования API. Но он также может значительно облегчить жизнь новым членам команды, аналитикам и клиентам, которые интегрируются с вами.

В этой статье я, SDET-специалист SimbirSoft Дарья, проведу обзор функций, с помощью которых Postman может помочь каждой из этих групп. Покажу на небольших примерах, как превратить набор запросов в то, что не стыдно будет пошарить коллегам, взаимодействующим с вашим API, и упростит жизнь новоприбывшим членам команды. Эта статья будет полезна специалистам различных уровней как в ручном, так и в автотестировании, а также бизнес- и системным аналитикам, для которых Postman сможет быть полезным для работы с документацией. 

Примеры буду приводить на ставшем классикой тренажере для практики отправки REST-запросов Petstore Swagger. Это имитация онлайн-зоомагазина, где можно манипулировать информацией о питомцах пользователей, а также создавать заказы. Для демонстрации примеров и описания функциональности использовался Postman версии 10.12.13.

Почему Postman?

Бывали ли вы в такой ситуации, когда приходили на проект, где совсем нет документации? И с каким облегчением вы узнавали, что у коллег из QA или разработчиков, оказывается, есть коллекция запросов в Postman, которую они шарили друг для друга.

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

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

При этом в рамках инструмента централизованно может храниться вся документация к ним и подключено комментирование. Это гарантирует более оперативный фидбэк на него, чем когда документация, запросы API и общение по этим двум предметам ведется в разных местах. Согласитесь, не очень удобно, когда детальное описание всех параметров и их бизнес-особенностей хранилось бы отдельно в Confluence, запросы в Swagger, а сами коллеги оставляли бы обратную связь одновременно в комментариях Confluence, чатах, да и про корпоративную почту не забывали.

Основные фишки Postman

Postman облегчает тяжбу работы с API и его изучения за счет следующих фичей: 

Коллекции и структура

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

• по бизнес-сущностям (например, если у вас продуктовая команда и нужно описание набора эндпойнтов, которые для каждого из продуктов будут реагировать по-разному, то можно разделить запросы на соответствующие подпапки),

• по фичам (создание, удаление, редактирование),

• по позитивности кейсов (позитивные, негативные) и т.д.

Пример использования:

Допустим, у нас есть коллекция, где все запросы расположены неструктурированно. Поделим их по фичам. Жмем рядом с коллекцией многоточие (“View more actions”), далее в выпавшем меню жмем “Add folder” и задаем имя папке.

Скрипты и переменные

Благодаря поддержке скриптов и переменных можно автоматически заполнять те данные, которые в ином случае пришлось бы каждый раз вбивать руками. Это значительно экономит время при работе с запросами и устраняет случайные ошибки ввода. Те же самые уникальные ID, поля, требующие актуальные даты, настройка сред для быстрого переключения между ними и т.д.

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

Пример использования:

Если у нас на проекте есть несколько сред (test, prelive и т.д.), то можно обеспечить возможность быстро переключаться между ними, не внося руками базовый url для той или иной среды. Давайте так и сделаем: жмем кнопку Environment quick look, в открывшемся окне кнопку Add.

В появившемся окне задаем название нашей среды, переменной для нее, а также саму ссылку.

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

А что же скрипты? Давайте попробуем применить и их. Допустим, нам нужно генерировать каждый раз новую рандомную строку для имени при создании пользователя, чтобы оно было уникальным. А еще мы хотели бы для удобства сохранять его, чтобы можно было дергать методы получения и обновления данных по пользователю, не вписывая каждый раз его имя в параметры url вручную.

1. Жмем на нужный нам запрос. Нас интересует создание пользователя.

2. Далее в окне открывшегося запроса выбираем вкладку “Pre-request Script”, так как сгенерировать имя и подставить его в тело запроса нам нужно до того, как он отработает.

3. Пишем в открывшемся окне сам скрипт. Первые 8 строчек — это метод по генерации рандомного набора букв заданной длины. А 10-ой строкой результат вызова метода сохраняется в переменную коллекции, чтобы можно было пользоваться ей в соседних запросах.

Теперь возвращаемся в “Body” запроса и подставляем в нужное поле нашу переменную в фигурных скобках.

Далее нам нужно прокинуть эту переменную в url запросов на получение и удаление пользователя. Тут тоже все просто: опять подставляем ее в фигурных скобках, но теперь уже в url. Проверяем. Запускаем запрос на получение пользователя и вуаля, нам приходит пользователь со сгенерированным именем!

⛔ Минус применения скриптов в том, что нужно разобраться хотя бы на начальном уровне в JavaScript. Но у создателей Postman для неискушенных пользователей припасено несколько вещей, которые могут сильно облегчить жизнь в этом плане.

1. Snippets — готовые шаблоны кода для наиболее частоиспользуемых случаев, которые предлагаются справа от окна ввода скриптов, нажатие на них автоматически разместит код выбранного шаблона в окно для ввода скрипта.

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

Манипулирование порядком запросов

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

Пример использования:

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

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

1. Жмем на папку с запросами.

2. Выбираем вкладку “Tests”.

3. Cреди “Snippets” выбираем проверку на статус-код.

4. Сохраняем изменения.

Теперь все запросы в данной подпапке будут проверяться на код 200 в ответе.

Проверяем, что все ок. Жмем кнопку “Run” (“Run Again”, если запускаете повторно), затем в открывшемся окне с настройками запуска кнопку “Run” еще раз. Видим, что действительно, тесты прошли в заданном нами порядке и закончились успешно, значит наши скрипты с переменными работают как надо.

Examples

Чтобы показать все разнообразие того, как один эндпойнт может ответить в том или ином случае на ваш запрос, можно обратиться к функции примеров (“Examples”) — это снимки запросов и ответов. У вас могут быть примеры, которые отвечают с разными статус-кодами или возвращают отличные от базового запроса данные (а, может, вообще не возвращают их). Применив эту функцию, вы поможете своим коллегам в изучении API, им не придется выискивать нужные кейсы методом проб и ошибок, а перед глазами всегда будут эталонные примеры всех ответов.

Пример использования:

После выполнения запросов подходящие, на наш взгляд, ответы для иллюстрации примеров можно сразу же сохранить соответствующей кнопкой. Отправляем запрос кнопкой “Send”, а в окне полученного ответа жмем кнопку “Save as Example”.

В нашей коллекции стал отображаться первый пример запроса и ответа на него, зададим ему логичное имя, например «Успешный запрос». Теперь наши коллеги будут знать, как должен выглядеть ответ в этом случае и могут даже попробовать его запустить кнопкой “Try”.

Примеры можно также создать с нуля, нажав многоточие у нужного запроса, а затем кнопку “Add example”.

После этого появится окно с телом из основного запроса и пустым полем для тела ответа и статуса. Мы можем скорректировать тело запроса по своему усмотрению и добавить нужные нам статус и тело в ответ.

Сделаем пример на случай, когда у нас не было передано тело запроса. Выбираем в “Body” радиокнопку “none”, а в форму ответа и поле “Status code” подставляем ожидаемые данные и сохраняем все кнопкой “Save”.

⛔ Минус применения Examples в том, что Postman не умеет сохранять ответы с медиаданными. То есть, например, если у нас запросы должны возвращать какой-нибудь pdf-файл, и мы хотим показать на примерах, как меняется его содержимое в зависимости от заданных при отправке параметров, то это сделать, к сожалению, не сможем.

Визуализация данных

Функция визуализации помогает представить результаты запросов в удобном для восприятия формате — таблицах, графиках, картах и т.д., что упрощает их анализ. Например, вместо того, чтобы скроллить огромный ответ от GET-запроса к БД, можно представить его в виде таблицы в самом Postman.

Пример использования:

Давайте визуализируем данные при получении списка питомцев. Так как список, который мы получаем в ответе,  довольно крупный, проще будет просматривать нужные нам данные о питомцах в таблице. Мы хотим выводить имя питомца (поле name) и категорию, к которой он относится (поле category.name).

1. Жмем на нужный запрос.

2. Далее выбираем вкладку “Tests”.

3. В открывшемся поле задаем шаблон таблицы с названием столбцов и указываем, какие поля из ответа будут им соответствовать. Затем мы вызываем функцию визуализации, передавая ей на вход наш шаблон и тело ответа.

Отправляем запрос и жмем на кнопку “Visualize”. Выбранные нами данные предстали в виде таблицы, теперь ориентироваться по ним гораздо удобнее, чем раньше.

Больше примеров того, как еще представить данные, можно изучить в документации Postman.

Документирование

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

Пример использования:

Postman автоматически генерирует базовую документацию при создании коллекции запросов, увидеть ее можно кнопкой “View documentation”.

Редактировать ее можно как из этого окна, так и на панели справа рядом с каждым из запросов или подпапок коллекции.

1. В самом запросе к переменным можно добавлять описание, которое тоже станет частью документации.

2. Панель с документацией для конкретного элемента коллекции открывается по клику на иконку “Documentation”.

Документация Postman поддерживает Markdown, также имеется и панель инструментов для редактирования. 

Можно добавлять цитаты, блоки кода, ссылки, редактировать стиль текста.

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

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

Collaboration

Существует функция collaboration, с помощью которой можно подключить коллег к пространству Postman. Это позволит оставлять им комментарии прямо внутри коллекции а мы сможем получить от них мгновенный фидбэк внутри контекста описанного нами API. Комментарии можно добавлять на уровне коллекций, папок и запросов, вплоть до каждой строчки самого запроса и входящих в него скриптов и параметров.

Пример использования:

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

1. Чтобы начать комментировать, необходимо переключиться в режим комментирования нажатием на соответствующую иконку.

2. Комментарии можно оставлять в окне справа, во вкладке для комментариев.

3. Либо можно оставлять комментарии в привязке к конкретному месту в запросе, например, можно прокомментировать один из параметров, либо выбранные строчки в теле запроса или скрипте.

⛔ Минус применения Collaboration в ограничениях бесплатной версии. Командное пространство можно создать только из трех пользователей, для большего числа придется приобретать платную версию.

Делимся коллекцией

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

Чтобы пошарить коллекцию, жмем “View more actions”, а затем “Share”.

Если мы не хотим делать наше API публичным, то нам будут доступны два варианта — ссылка на коллекцию (в случае, если мы создали командное пространство), либо доступ к JSON коллекции на чтение по ссылке.

И всегда есть вариант экспортировать коллекцию и залить в нужное место, например, на GitLab.

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

На этом обзор функций подошел к концу. Возможно, данная статья поможет взглянуть на Postman под новым углом и начать применять его не только как средство тестирования, но и как часть документации к вашему приложению. А если вы уже планировали это сделать, то эта статья может послужить вам списком аргументов при обсуждении с командой. Кстати, про работу в Postman мы также писали в этом лонгриде во ВКонтакте:)

Спасибо за внимание!

Авторские материалы для SDET-специалистов мы также публикуем в наших соцсетях – ВКонтакте и Telegram.