API-тестирование: от Postman коллекций до автоматизации в CI с Newman

Знаете это чувство, когда разработчик говорит: «Я все поправил, можно тестить», а вы тратите полдня на ручную проверку десяти эндпоинтов? Или хуже - релиз улетает в прод, а через час падает сервис, потому что кто-то изменил структуру ответа API, и никто этого не заметил. Ручное тестирование интерфейсов прикладного программирования (API) быстро превращается в бутылочное горлышко. Хорошая новость в том, что этот хаос можно убрать за один вечер.

Сегодня мы разберем, как превратить ваши запросы из набора кнопок в Postman в полноценный конвейер проверок. Мы научимся создавать умные коллекции, писать скрипты на JavaScript и запускать их автоматически в системе непрерывной интеграции (CI) с помощью инструмента Newman. Это не просто гайд по кнопкам, а способ сделать так, чтобы ваш код сам говорил вам: «Все чисто» или «Тут баг».

Почему Postman - это больше, чем просто клиент для запросов

Многие начинают с Postman как с замены браузерному расширению RESTClient или командной строке curl. И это нормально. Но если вы используете его только для того, чтобы отправить GET-запрос и посмотреть JSON в ответе, вы упускаете 90% его мощи. Postman - это платформа для совместной работы над API, где можно хранить историю изменений, документировать методы и, главное, автоматизировать проверки.

Ключевой элемент здесь - коллекция. Представьте ее как папку с тест-кейсами. Внутри одной коллекции могут лежать десятки запросов, объединенных общей логикой: например, весь флоу регистрации пользователя. Отдельные элементы внутри называются requests. Но настоящая магия начинается во вкладке Tests. Именно там вы пишете код, который проверяет ответы сервера.

Вам не нужно быть сеньором-разработчиком, чтобы начать. Базовые проверки пишутся буквально в одну строку. Например, проверить, что статус код равен 200:

pm.test("Status code is 200", function () {
    pm.response.to.have.status(200);
});

А вот проверка наличия конкретного поля в JSON:

pm.test("Response has user ID", function () {
    var jsonData = pm.response.json();
    pm.expect(jsonData.id).to.be.a('number');
});

Если условие не выполняется, тест упадет, и вы сразу увидите ошибку. Никакого визуального сканирования глазами. Компьютер сделал свою работу.

Переменные и окружения: убираем хардкод

Самая частая ошибка новичков - прописывать URL и токены прямо в запросах. Что будет, если вам нужно протестировать стенд разработки (dev), потом тестовый контур (stage), а затем прод? Менять ссылки руками в каждом из пятидесяти запросов? Забудьте об этом.

Postman предлагает механизм переменных. Вы создаете Environment (окружение), задаете там значения вроде {{base_url}} или {{auth_token}}, и используете их в запросах через двойные фигурные скобки.

Но есть нюанс: токен авторизации обычно приходит в ответе на логин. Как передать его в следующий запрос? Здесь нам помогают скрипты в разделе Pre-request Script (перед отправкой) и Tests (после получения ответа).

Типичный сценарий выглядит так:

1. Вы отправляете запрос на логин (/login) с логином и паролем.
2. В разделе Tests этого запроса вы парсите ответ и сохраняете токен в переменную окружения.
3. Все последующие запросы в цепочке используют эту переменную в заголовках.

Пример кода для сохранения токена:

var jsonData = pm.response.json();
pm.environment.set("token", jsonData.access_token);

Теперь в любом другом запросе достаточно добавить в Headers ключ Authorization со значением Bearer {{token}}. Если токен истек или изменился, вам не нужно править каждый запрос отдельно. Система обновит переменную автоматически.

Что такое Newman и зачем он нужен вне интерфейса Postman

Итак, у вас есть красивая коллекция в Postman. Она работает у вас на ноутбуке. Но команда работает в команде, а релизы идут каждые два часа. Как заставить эти тесты выполняться без участия человека?

На помощь приходит Newman. Это консольная утилита, которая позволяет запускать коллекции Postman из командной строки. По сути, это движок выполнения тестов, лишенный графического интерфейса. Он понимает те же форматы файлов, что и приложение, но делает это быстрее и тише.

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

Подготовка коллекции к экспорту

Прежде чем бежать в CI, нужно подготовить вашу коллекцию. Не каждая коллекция готова к автономной жизни. Вот чек-лист подготовки:

• Нет зависимостей от локальных файлов. Если вы загружаете картинки через путь C:/Users/Ivan/Pictures/cat.png, на сервере CI такого файла не будет. Используйте генерацию данных или относительные пути.
• Чистота переменных. Убедитесь, что все секреты (пароли, ключи API) либо захардкожены для теста (если это dev-стенд), либо передаются через переменные окружения при запуске Newman.
• Обработка ошибок сети. В CI сеть может дергаться. Добавьте в настройки коллекции таймауты, чтобы тест не висел вечно, если сервер не отвечает.

Как экспортировать коллекцию? Нажмите правой кнопкой мыши на название коллекции в боковой панели → Export → выберите формат Collection v2.1. То же самое сделайте для нужного окружения (Environment).

Первый запуск Newman в терминале

Установка проста, если у вас стоит Node.js. Введите в терминале:

npm install -g newman

Теперь попробуем запустить нашу экспортированную коллекцию. Допустим, файлы называются my_collection.json и my_env.json.

newman run my_collection.json -e my_env.json

Вы увидите цветной вывод в консоли. Зеленые точки означают успешные тесты, красные крестики - провалы. Если что-то пошло не так, Newman покажет сообщение об ошибке, которое вы написали в блоке Tests. Например, «Expected status code to be 200 but got 500».

Для более глубокой диагностики используйте флаг --verbose. Он покажет полный лог HTTP-запросов и ответов, что незаменимо, когда нужно понять, почему тест упал.

Интеграция с CI/CD: пример для GitLab CI

Давайте настроим реальный кейс. У нас есть проект на GitLab. Мы хотим, чтобы каждый пуш в ветку develop запускал API-тесты. Для этого создадим файл .gitlab-ci.yml в корне проекта.

Структура должна быть такой:

project/
├── postman/
│   ├── api_collection.json
│   └── stage_environment.json
├── .gitlab-ci.yml
└── src/...

Конфигурация пайплайна будет выглядеть примерно так:

stages:
  - test

api_tests:
  stage: test
  image: node:18-alpine # Берем образ с установленным Node.js
  before_script:
    - npm install -g newman # Устанавливаем Newman внутри контейнера
  script:
    - newman run postman/api_collection.json \
      --environment postman/stage_environment.json \
      --reporters cli,junit \
      --reporter-junit-results reports/junit.xml
  artifacts:
    paths:
      - reports/junit.xml # Сохраняем отчет для просмотра в GitLab

Что здесь происходит?

1. Мы используем готовый Docker-образ с Node.js, чтобы не возиться с установкой зависимостей вручную.
2. Команда newman run запускает тесты.
3. Флаг --reporters cli,junit заставляет Newman писать результат и в консоль (для логов), и в файл формата JUnit XML.
4. GitLab умеет читать JUnit-отчеты и показывать красивую статистику прохождения тестов прямо в интерфейсе Merge Request.

Если любой тест упадет, Newman вернет ненулевой код возврата. GitLab увидит это и пометит пайплайн как «Failed». Разработчик получит уведомление и не сможет смержить свой код в основную ветку, пока не починит API.

Продвинутые фишки: динамические данные и параллелизм

Когда базовая настройка заработает, захочется большего. Например, тестировать создание пользователей с уникальными именами. Хардкодить имя «test_user_1» плохо - второй запуск может упасть, если такой юзер уже есть.

Используйте встроенные функции Postman для генерации случайных данных прямо в запросах или скриптах:

// Пример генерации случайного email в Pre-request Script
var randomEmail = 'user_' + Math.random().toString(36).substring(7) + '@example.com';
pm.environment.set('random_email', randomEmail);

Также важно помнить о производительности. Если у вас 1000 запросов, они будут выполняться последовательно. Это долго. Newman поддерживает параллельное выполнение через флаг -n (iterations) и -d (data file), но для простого ускорения лучше структурировать коллекцию так, чтобы независимые блоки могли запускаться одновременно, если вы используете оркестраторы уровня выше (например, запуск нескольких экземпляров Newman с разными частями коллекции).

Еще одна боль - зависимость от состояния базы данных. Тесты должны быть идемпотентными. Идеальный подход: создать ресурс → проверить его → удалить ресурс. Так ваша база данных не превратится в свалку после сотни прогонов в CI.

Типичные проблемы и решения

При переезде из GUI в CI часто всплывают специфические ошибки. Вот топ-3:

• SSL-сертификаты. На некоторых стендах используются самоподписанные сертификаты. Newman может ругаться. Решение: добавьте флаг --insecure при запуске команды.
• Разница во времени. Если тест зависит от временных меток, убедитесь, что время на CI-раннере синхронизировано с сервером (NTP).
• Секреты в логах. Будьте осторожны с флагом --verbose в продакшене. Он может вывести чувствительные токены в общий лог. Лучше маскировать их или отключать подробный лог для публичных репозиториев.

Помните, что автоматизация - это не цель, а инструмент. Сначала сделайте тесты стабильными локально. Только потом тащите их в CI. Нестабильные («flaky») тесты в пайплайне бесят команду сильнее, чем полное отсутствие автотестов.