RKIS/articles/postman

Postman — инструмент для работы с API

1. Что такое Postman

Postman — это кроссплатформенный инструмент (десктопное приложение и веб-версия), предназначенный для работы с API на всех этапах: от разработки и тестирования до документирования и мониторинга.

Основные возможности Postman:

• отправка HTTP-запросов любых методов (GET, POST, PUT, DELETE, PATCH и др.)
• поддержка REST, GraphQL, WebSocket, gRPC
• управление переменными на разных уровнях (глобальные, коллекции, окружения)
• написание автоматических тестов на JavaScript
• последовательный запуск наборов запросов через Collection Runner
• автоматическая генерация документации
• создание мок-серверов для имитации API
• мониторинг работоспособности API в production
• совместная работа в команде через Workspaces
• интеграция с CI/CD системами через утилиту Newman

Postman — один из самых популярных инструментов среди разработчиков, QA-инженеров и технических писателей.

2. Зачем нужен Postman

Задача	Как помогает Postman
Быстрая проверка эндпоинта	Отправить запрос и увидеть ответ за несколько секунд
Отладка API	Полная информация: статус-код, заголовки, тело ответа, время, cookies, консоль
Автоматическое тестирование	Проверки статуса, структуры данных, типов значений, наличия полей
Регрессионное тестирование	Запуск всей группы запросов одним действием через Runner
Работа с разными средами	Легкое переключение между тестовым, разработческим и продакшен-серверами
Документирование API	Автоматическое создание читаемой документации по коллекции
Мониторинг доступности	Периодические проверки ключевых эндпоинтов
Обучение и демонстрация	Удобно показать заказчику или новому коллеге, как работает API

3. Как создать коллекцию

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

Порядок создания:

1. В левой панели перейти в раздел Collections
2. Нажать + и выбрать Blank collection
3. Указать название коллекции
4. Внутри коллекции создать папки для логической группировки запросов
5. В каждой папке создавать новые запросы (New -> HTTP Request)

Типичная структура коллекции может включать папки по функциональным блокам системы.

4. Как создать переменные и заполнить их

В Postman переменные бывают нескольких типов:

Уровень	Где создаётся	Приоритет	Типичные примеры
Environment	Раздел Environments	Высокий	базовый URL, токены, ключи API
Collection	Вкладка Variables коллекции	Средний	версия API, общий путь, константы
Global	Глобальные переменные	Низкий	редко используемые общие значения

4.1 Создание переменной в окружении

1. Перейти в левый сайдбар -> Environments
2. Нажать Create new environment или кнопку +
3. Задать имя окружения
4. Добавить переменную:
   • в поле Variable указать имя (например: baseURL)
   • в поле Value указать значение (например: адрес сервера)
5. Сохранить

---

4.2 Создание переменной в коллекции

1. Открыть нужную коллекцию
2. Перейти на вкладку Variables
3. Нажать Add variable
4. Указать имя и значение

---

В запросах переменные вставляются в двойных фигурных скобках:
{{baseURL}}/endpoint

---

4.3 Как автоматически сохранять значение из ответа

Очень часто после запроса на логин нужно взять token (или access_token, id созданной сущности и т.п.) и сохранить его в переменную, чтобы использовать в последующих запросах.

Это делается в вкладке Scripts каждого запроса.

Пример: сохранение токена после логина

1. Откройте запрос на авторизацию
2. Перейдите во вкладку Scripts.

3. Напишите примерно такой скрипт:

   // 1. Проверяем успешный статус
   pm.test("Логин успешен — статус 200", function () {
   pm.response.to.have.status(200);
   });
   
   // 2. Получаем тело ответа как объект
   const jsonData = pm.response.json();
   
   // 3. Проверяем, что токен пришёл
   pm.test("В ответе есть поле token", function () {
   pm.expect(jsonData).to.have.property("token");
   pm.expect(jsonData.token).to.be.a("string").that.is.not.empty;
   });
   
   // 4. Сохраняем токен в переменную коллекции
   if (jsonData.token) {
   pm.collectionVariables.set("authToken", jsonData.token);
   console.log("Токен сохранён: " + jsonData.token.substring(0, 15) + "...");
   }
   

5. Как настроить и применить окружение

1. Создать или открыть нужное окружение в разделе Environments
2. В правом верхнем углу интерфейса Postman найти выпадающий список окружений
3. Выбрать требуемое окружение (оно подсвечивается цветом)
4. После выбора все переменные из этого окружения становятся активными

Если одна и та же переменная определена и в окружении, и в коллекции — значение из окружения имеет приоритет.

6. Как выполнять тесты в UI и в Collection Runner

6.1. Тесты для отдельного запроса (в интерфейсе)

1. Открыть запрос
2. Перейти на вкладку Scripts

3. Написать проверки на JavaScript:

   pm.test("Статус 200 OK", function () {
   pm.response.to.have.status(200);
   });
   
   pm.test("Ответ содержит массив", function () {
   const json = pm.response.json();
   pm.expect(json).to.be.an("array");
   });
   

4. Нажать Send

5. После ответа посмотреть блок Test Results — зелёные PASS / красные FAIL}

6.2. Запуск всех тестов через Collection Runner

1. Нажать на три точки справа от нужной коллекции
2. Нажать кнопку Run

1. В окне Runner:
   • выбрать нужное окружение
   • указать количество итераций (обычно 1 для обычного запуска)
   • задать задержку между запросами (Delay), если нужно
   • выбрать режим: Run manually
2. Нажать кнопку запуска

После выполнения отображается сводный результат:

• общее время выполнения коллекции
• количество пройденных / проваленных тестов
• среднее время ответа
• детальный отчёт по каждому запросу (статус, время, размер ответа, результаты тестов)

6.3. Запуск тестов в консоли с помощью Newman

Newman — это официальная консольная утилита от команды Postman, которая позволяет запускать коллекции вне графического интерфейса. Это особенно полезно для автоматизации тестирования в CI/CD-пайплайнах (GitHub Actions, GitLab CI, Jenkins и др.), ночных регрессиях и повторяемых проверках без открытия Postman.

Основная команда запуска:

newman run Avtomat.postman_collection.json -e mvavilov.postman_environment.json

Расшифровка команды:

• newman run — команда запуска коллекции
  
• Avtomat.postman_collection.json — файл экспортированной коллекции (формат v2.1)
  
• -e mvavilov.postman_environment.json — флаг -e указывает файл окружения, из которого берутся все переменные (в том числе baseURL, токены и другие настройки)

Предварительные шаги:

1. Установить Newman глобально (один раз):

   npm install -g newman
   

2. Экспортировать коллекцию и окружение из Postman:

   • Коллекция -> три точки -> More -> Export -> сохранить как Avtomat.postman_collection.json
   • Окружение -> три точки -> More -> Export -> сохранить как mvavilov.postman_environment.json

3. Перейти в директорию с файлами:

   cd путь/к/папке/с/экспортированными/файлами
   

Рекомендуемые варианты запуска:

• Базовый запуск с подробным выводом:

  newman run Avtomat.postman_collection.json -e mvavilov.postman_environment.json --reporters cli
  

• С сохранением HTML-отчёта (очень удобно для проверки и демонстрации):

  newman run Avtomat.postman_collection.json \
  -e mvavilov.postman_environment.json \
  --reporters cli,html \
  --reporter-html-export report.html
  

После выполнения в терминале отображается:

• список всех запросов коллекции
  
• статус-коды ответов
  
• количество пройденных / проваленных тестов
  
• время выполнения каждого запроса и общее время
  
• детальная информация об ошибках (если тесты упали)