Postman в основном известен в качестве мощного инструмента для тестирования API. Но он также может значительно облегчить жизнь новым членам команды, аналитикам и клиентам, которые интегрируются с вами.
В этой статье я, SDET-специалист SimbirSoft Дарья, проведу обзор функций, с помощью которых Postman может помочь каждой из этих групп. Покажу на небольших примерах, как превратить набор запросов в то, что не стыдно будет пошарить коллегам, взаимодействующим с вашим API, и упростит жизнь новоприбывшим членам команды. Эта статья будет полезна специалистам различных уровней как в ручном, так и в автотестировании, а также бизнес- и системным аналитикам, для которых Postman сможет быть полезным для работы с документацией.
Примеры буду приводить на ставшем классикой тренажере для практики отправки REST-запросов Petstore Swagger. Это имитация онлайн-зоомагазина, где можно манипулировать информацией о питомцах пользователей, а также создавать заказы. Для демонстрации примеров и описания функциональности использовался Postman версии 10.12.13.
![](https://habrastorage.org/getpro/habr/upload_files/ff0/836/967/ff0836967a8f1c8bb15043c6222d0975.png)
Почему Postman?
Бывали ли вы в такой ситуации, когда приходили на проект, где совсем нет документации? И с каким облегчением вы узнавали, что у коллег из QA или разработчиков, оказывается, есть коллекция запросов в Postman, которую они шарили друг для друга.
Эта коллекция может быть полезной не только им, а еще стать неплохой отправной точкой для создания полноценной документации для аналитиков, а для менеджеров и старших членов команды — инструментом онбординга новых коллег, что позволит сократить время на погружение.
Для интегрирующихся команд и клиентов коллекции Postman станут отличной базой в понимании работы вашего API, а также сделают процесс интеграции более прозрачным и быстрым. У них на руках буквально при каждом релизе будут появляться актуальные запросы на нужных средах, которые можно начать использовать в ту же секунду, как коллекция была получена на руки.
При этом в рамках инструмента централизованно может храниться вся документация к ним и подключено комментирование. Это гарантирует более оперативный фидбэк на него, чем когда документация, запросы API и общение по этим двум предметам ведется в разных местах. Согласитесь, не очень удобно, когда детальное описание всех параметров и их бизнес-особенностей хранилось бы отдельно в Confluence, запросы в Swagger, а сами коллеги оставляли бы обратную связь одновременно в комментариях Confluence, чатах, да и про корпоративную почту не забывали.
Основные фишки Postman
Postman облегчает тяжбу работы с API и его изучения за счет следующих фичей:
Коллекции и структура
Запросы в Postman можно логически объединять в коллекции и подпапки, создавая структуру, по которой можно удобно ориентироваться. В зависимости от сложности вашей системы можно создавать вложенность запросов на свой вкус:
• по бизнес-сущностям (например, если у вас продуктовая команда и нужно описание набора эндпойнтов, которые для каждого из продуктов будут реагировать по-разному, то можно разделить запросы на соответствующие подпапки),
• по фичам (создание, удаление, редактирование),
• по позитивности кейсов (позитивные, негативные) и т.д.
Пример использования:
Допустим, у нас есть коллекция, где все запросы расположены неструктурированно. Поделим их по фичам. Жмем рядом с коллекцией многоточие (“View more actions”), далее в выпавшем меню жмем “Add folder” и задаем имя папке.
![](https://habrastorage.org/getpro/habr/upload_files/7a3/456/c7b/7a3456c7bd9e1d5b446df073a73daf49.png)
Скрипты и переменные
Благодаря поддержке скриптов и переменных можно автоматически заполнять те данные, которые в ином случае пришлось бы каждый раз вбивать руками. Это значительно экономит время при работе с запросами и устраняет случайные ошибки ввода. Те же самые уникальные ID, поля, требующие актуальные даты, настройка сред для быстрого переключения между ними и т.д.
Сохраняя нужные переменные из ответов запросов и передавая их на вход следующим, можно создавать целые цепочки из запросов, которым не нужен будет ручной ввод.
Пример использования:
Если у нас на проекте есть несколько сред (test, prelive и т.д.), то можно обеспечить возможность быстро переключаться между ними, не внося руками базовый url для той или иной среды. Давайте так и сделаем: жмем кнопку Environment quick look, в открывшемся окне кнопку Add.
![](https://habrastorage.org/getpro/habr/upload_files/084/445/928/0844459288440815cf14f180f40d42eb.png)
В появившемся окне задаем название нашей среды, переменной для нее, а также саму ссылку.
![](https://habrastorage.org/getpro/habr/upload_files/770/a7d/70c/770a7d70ca7079978b81894377146eba.png)
Далее в запросы мы вставляем заданную ранее переменную в двойные фигурные скобки. Теперь в выпадающем списке в правом верхнем углу мы можем переключаться на нашу среду. Дополнительные среды можно добавить таким же образом.
![](https://habrastorage.org/getpro/habr/upload_files/784/1b5/c21/7841b5c214664e092a03f63cee576390.png)
А что же скрипты? Давайте попробуем применить и их. Допустим, нам нужно генерировать каждый раз новую рандомную строку для имени при создании пользователя, чтобы оно было уникальным. А еще мы хотели бы для удобства сохранять его, чтобы можно было дергать методы получения и обновления данных по пользователю, не вписывая каждый раз его имя в параметры url вручную.
Жмем на нужный нам запрос. Нас интересует создание пользователя.
Далее в окне открывшегося запроса выбираем вкладку “Pre-request Script”, так как сгенерировать имя и подставить его в тело запроса нам нужно до того, как он отработает.
Пишем в открывшемся окне сам скрипт. Первые 8 строчек — это метод по генерации рандомного набора букв заданной длины. А 10-ой строкой результат вызова метода сохраняется в переменную коллекции, чтобы можно было пользоваться ей в соседних запросах.
![](https://habrastorage.org/getpro/habr/upload_files/a82/258/0e9/a822580e93ad753451dd0207643eb121.png)
Теперь возвращаемся в “Body” запроса и подставляем в нужное поле нашу переменную в фигурных скобках.
![](https://habrastorage.org/getpro/habr/upload_files/0ce/31f/eec/0ce31feec0a3ef551c38c5118aeff142.png)
Далее нам нужно прокинуть эту переменную в url запросов на получение и удаление пользователя. Тут тоже все просто: опять подставляем ее в фигурных скобках, но теперь уже в url. Проверяем. Запускаем запрос на получение пользователя и вуаля, нам приходит пользователь со сгенерированным именем!
![](https://habrastorage.org/getpro/habr/upload_files/433/5b9/97f/4335b997f90971e586935b3e65d4ed78.png)
⛔ Минус применения скриптов в том, что нужно разобраться хотя бы на начальном уровне в JavaScript. Но у создателей Postman для неискушенных пользователей припасено несколько вещей, которые могут сильно облегчить жизнь в этом плане.
Snippets — готовые шаблоны кода для наиболее частоиспользуемых случаев, которые предлагаются справа от окна ввода скриптов, нажатие на них автоматически разместит код выбранного шаблона в окно для ввода скрипта.
Там же располагается ссылка на документацию Postman, а он славится очень хорошей документацией. В ней вы найдете и подробное объяснение того, как использовать скрипты, и большой список примеров на разные случаи.
Манипулирование порядком запросов
Располагая запросы в коллекциях в нужном вам порядке или манипулируя их следованием с помощью скриптов, получится настроить очередность, в рамках которой запросы будут идти при запуске коллекции. Это может помочь коллегам понять, как устроен флоу работы с приложением.
Пример использования:
Покажем, как работает упорядочивание, на примере запросов с манипуляцией пользователем, которым мы добавили переменные в прошлом примере. Давайте поместим запросы в отдельную папку для удобства и расположим их в следующем порядке: сначала создаем пользователя, потом получаем информацию по нему, затем удаляем.
![](https://habrastorage.org/getpro/habr/upload_files/7c6/0c7/8cd/7c60c78cdd3ab6706b50c5568cd68553.png)
Проверим, станут ли запускаться эти запросы в указанном нами порядке и успешно ли все закончится. Добавим для наглядности тест, который будет проверять, что все запросы вернули статус 200.
Жмем на папку с запросами.
Выбираем вкладку “Tests”.
Cреди “Snippets” выбираем проверку на статус-код.
Сохраняем изменения.
Теперь все запросы в данной подпапке будут проверяться на код 200 в ответе.
![](https://habrastorage.org/getpro/habr/upload_files/cbd/fcc/c9b/cbdfccc9bd2f274d8e3336ce7905e0b0.png)
Проверяем, что все ок. Жмем кнопку “Run” (“Run Again”, если запускаете повторно), затем в открывшемся окне с настройками запуска кнопку “Run” еще раз. Видим, что действительно, тесты прошли в заданном нами порядке и закончились успешно, значит наши скрипты с переменными работают как надо.
![](https://habrastorage.org/getpro/habr/upload_files/95c/0ae/a1a/95c0aea1a745aa77f8dd1690841f82e8.png)
Examples
Чтобы показать все разнообразие того, как один эндпойнт может ответить в том или ином случае на ваш запрос, можно обратиться к функции примеров (“Examples”) — это снимки запросов и ответов. У вас могут быть примеры, которые отвечают с разными статус-кодами или возвращают отличные от базового запроса данные (а, может, вообще не возвращают их). Применив эту функцию, вы поможете своим коллегам в изучении API, им не придется выискивать нужные кейсы методом проб и ошибок, а перед глазами всегда будут эталонные примеры всех ответов.
Пример использования:
После выполнения запросов подходящие, на наш взгляд, ответы для иллюстрации примеров можно сразу же сохранить соответствующей кнопкой. Отправляем запрос кнопкой “Send”, а в окне полученного ответа жмем кнопку “Save as Example”.
![](https://habrastorage.org/getpro/habr/upload_files/639/942/41d/63994241d3c2a118383e31866c7a0b27.png)
В нашей коллекции стал отображаться первый пример запроса и ответа на него, зададим ему логичное имя, например «Успешный запрос». Теперь наши коллеги будут знать, как должен выглядеть ответ в этом случае и могут даже попробовать его запустить кнопкой “Try”.
![](https://habrastorage.org/getpro/habr/upload_files/56c/b2f/93f/56cb2f93f3038c6a120d7df4716b87d8.png)
Примеры можно также создать с нуля, нажав многоточие у нужного запроса, а затем кнопку “Add example”.
![](https://habrastorage.org/getpro/habr/upload_files/075/951/832/07595183299aa7a7cb156263a24cb709.png)
После этого появится окно с телом из основного запроса и пустым полем для тела ответа и статуса. Мы можем скорректировать тело запроса по своему усмотрению и добавить нужные нам статус и тело в ответ.
![](https://habrastorage.org/getpro/habr/upload_files/b01/ec8/841/b01ec8841755671ac675f9132c3014bc.png)
Сделаем пример на случай, когда у нас не было передано тело запроса. Выбираем в “Body” радиокнопку “none”, а в форму ответа и поле “Status code” подставляем ожидаемые данные и сохраняем все кнопкой “Save”.
![](https://habrastorage.org/getpro/habr/upload_files/1ad/0dd/81b/1ad0dd81b0d71c81dc3f7e1b147f2d4b.png)
⛔ Минус применения Examples в том, что Postman не умеет сохранять ответы с медиаданными. То есть, например, если у нас запросы должны возвращать какой-нибудь pdf-файл, и мы хотим показать на примерах, как меняется его содержимое в зависимости от заданных при отправке параметров, то это сделать, к сожалению, не сможем.
Визуализация данных
Функция визуализации помогает представить результаты запросов в удобном для восприятия формате — таблицах, графиках, картах и т.д., что упрощает их анализ. Например, вместо того, чтобы скроллить огромный ответ от GET-запроса к БД, можно представить его в виде таблицы в самом Postman.
Пример использования:
Давайте визуализируем данные при получении списка питомцев. Так как список, который мы получаем в ответе, довольно крупный, проще будет просматривать нужные нам данные о питомцах в таблице. Мы хотим выводить имя питомца (поле name) и категорию, к которой он относится (поле category.name).
Жмем на нужный запрос.
Далее выбираем вкладку “Tests”.
В открывшемся поле задаем шаблон таблицы с названием столбцов и указываем, какие поля из ответа будут им соответствовать. Затем мы вызываем функцию визуализации, передавая ей на вход наш шаблон и тело ответа.
![](https://habrastorage.org/getpro/habr/upload_files/938/882/d6e/938882d6eb1abfdd933e3d6d567ff6fc.png)
Отправляем запрос и жмем на кнопку “Visualize”. Выбранные нами данные предстали в виде таблицы, теперь ориентироваться по ним гораздо удобнее, чем раньше.
![](https://habrastorage.org/getpro/habr/upload_files/bac/43e/d3e/bac43ed3e8772b477535eddae9a95251.png)
Больше примеров того, как еще представить данные, можно изучить в документации Postman.
Документирование
Вкладка документации у каждого запроса поможет описать их работу как можно более информативно. Язык разметки внутри поддерживает вставку кода, таблиц, изображений и гифок — все, что душа пожелает.
Пример использования:
Postman автоматически генерирует базовую документацию при создании коллекции запросов, увидеть ее можно кнопкой “View documentation”.
![](https://habrastorage.org/getpro/habr/upload_files/bf0/3a8/aea/bf03a8aea870d265b38c8869d8f0b502.png)
Редактировать ее можно как из этого окна, так и на панели справа рядом с каждым из запросов или подпапок коллекции.
В самом запросе к переменным можно добавлять описание, которое тоже станет частью документации.
Панель с документацией для конкретного элемента коллекции открывается по клику на иконку “Documentation”.
![](https://habrastorage.org/getpro/habr/upload_files/03a/68b/cef/03a68bcef39e4649679ebcae6e08150c.png)
Документация Postman поддерживает Markdown, также имеется и панель инструментов для редактирования.
Можно добавлять цитаты, блоки кода, ссылки, редактировать стиль текста.
![](https://habrastorage.org/getpro/habr/upload_files/523/434/cfd/523434cfdafc7d9ac171656a579e0ab3.jpg)
Также можно добавлять таблицы, изображения, гифки, списки. То есть все нужные инструменты для создания хорошей документации для коллекции имеются.
![](https://habrastorage.org/getpro/habr/upload_files/22d/854/bcf/22d854bcf220690c0d62d6e79d49f37d.jpg)
Для того чтобы можно было выжать максимум при оформлении, используя Markdown, разработчики сделали коллекцию с примерами, а из публичных коллекций API можно почерпнуть вдохновения.
Collaboration
Существует функция collaboration, с помощью которой можно подключить коллег к пространству Postman. Это позволит оставлять им комментарии прямо внутри коллекции а мы сможем получить от них мгновенный фидбэк внутри контекста описанного нами API. Комментарии можно добавлять на уровне коллекций, папок и запросов, вплоть до каждой строчки самого запроса и входящих в него скриптов и параметров.
Пример использования:
Для того чтобы начать пользоваться данной функцией вместе с коллегами, необходимо создать командное пространство Team и пригласить в него пользователей.
![](https://habrastorage.org/getpro/habr/upload_files/29a/2e7/c1b/29a2e7c1b4bf8434655c67c68691947e.jpg)
Чтобы начать комментировать, необходимо переключиться в режим комментирования нажатием на соответствующую иконку.
Комментарии можно оставлять в окне справа, во вкладке для комментариев.
Либо можно оставлять комментарии в привязке к конкретному месту в запросе, например, можно прокомментировать один из параметров, либо выбранные строчки в теле запроса или скрипте.
![](https://habrastorage.org/getpro/habr/upload_files/80b/7e9/5fd/80b7e95fd11c127329ab459725eca1aa.png)
⛔ Минус применения Collaboration в ограничениях бесплатной версии. Командное пространство можно создать только из трех пользователей, для большего числа придется приобретать платную версию.
Делимся коллекцией
Поделиться коллекцией с коллегами очень легко, и для этого предусмотрено множество способов: ссылка с доступом на чтение, создание рабочих пространств, ну и самая обычная выгрузка коллекции в формате json.
Чтобы пошарить коллекцию, жмем “View more actions”, а затем “Share”.
![](https://habrastorage.org/getpro/habr/upload_files/8bd/b32/263/8bdb32263ecba30114583e30e0be3476.png)
Если мы не хотим делать наше API публичным, то нам будут доступны два варианта — ссылка на коллекцию (в случае, если мы создали командное пространство), либо доступ к JSON коллекции на чтение по ссылке.
И всегда есть вариант экспортировать коллекцию и залить в нужное место, например, на GitLab.
![](https://habrastorage.org/getpro/habr/upload_files/010/050/145/01005014580032cbeec071d57781e598.png)
Переменные среды также нужно будет экспортировать отдельно, если хотите поделиться ими с коллегами.
![](https://habrastorage.org/getpro/habr/upload_files/aaa/5d7/be8/aaa5d7be89815791e50bc9b3dca3f605.png)
На этом обзор функций подошел к концу. Возможно, данная статья поможет взглянуть на Postman под новым углом и начать применять его не только как средство тестирования, но и как часть документации к вашему приложению. А если вы уже планировали это сделать, то эта статья может послужить вам списком аргументов при обсуждении с командой. Кстати, про работу в Postman мы также писали в этом лонгриде во ВКонтакте:)
Спасибо за внимание!
Авторские материалы для SDET-специалистов мы также публикуем в наших соцсетях – ВКонтакте и Telegram.
Takumi
Спасибо за статью! По ощущением она получилась больше про то как пользоваться Postman нежели как создать там документацию. Во время прочтения, возникло несколько вопросов:
Как вы решаете вопрос поддержки такой "документации" в команде?
Где храните такую документацию?
Множество скриптов в запросах и вские фишечки постмана наводят на вопрос обучения ребят, особенно только пришедших в команду, как вы работаете с этим моментом?
SSul Автор
Спасибо за отклик!
Документацию ведет и актуализирует один специалист, в нашем случае аналитик. На эту работу выделяется отдельная задача в спринте.
Выгружаем в GitLab, шарим ссылку на всех заинтересованных лиц.
У нас есть два варианта. Первый — инструкции по использованию коллекций для тех, у кого возникли по этому моменту вопросы. Второй — если нужно какой-то новый скрипт добавить и возникли затруднения, коллеги обращаются с вопросами к тем, у кого опыта в кодинге больше. Например, наш аналитик обращается за помощью к команде разработки или SDET-специалистам.