Как пользоваться Postman: запросы, коллекции, переменные и тесты

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

Ниже — сквозной сценарий от первого GET до тестов на pm.test и запуска коллекции целиком. Примеры идут на postman-echo.com — открытый тестовый сервис Postman, который возвращает в ответе то, что получил. Интерфейс описан по десктопной версии Postman 11; в других версиях названия вкладок могут отличаться.

Пять понятий, которые путают

Главное различие: коллекция хранит что отправлять, окружение — куда и с какими ключами. Одна коллекция без правок работает на dev и stage, если переключить окружение.

Установка и первый запуск

Postman ставится как десктопное приложение для Windows, macOS и Linux, есть и веб-версия; из браузера запросы к localhost идут только через Postman Desktop Agent. Аккаунт нужен для синхронизации коллекций и командной работы; без входа доступен облегченный режим для отправки запросов.

Первый GET-запрос с параметрами

1. Нажмите «+» на панели вкладок — откроется пустой запрос.
2. Слева от адресной строки оставьте метод GET, в строку введите https://postman-echo.com/get.
3. Откройте вкладку Params и добавьте пары foo = bar и page = 1. Postman сам допишет их в URL: ?foo=bar&page=1.
4. Нажмите Send.

Внизу появится ответ: статус (ожидаем 200 OK), время и размер. Во вкладке Body echo-сервис вернет JSON: в args — ваши параметры, в headers — заголовки, отправленные Postman, в url — итоговый адрес. Pretty форматирует JSON, Raw показывает ответ как есть, Preview рендерит HTML; вкладки Headers и Cookies ответа — то, что вернул сервер. Чтобы временно отключить параметр, снимите галочку слева от строки.

POST: какой формат тела выбрать

У POST данные обычно идут не в URL, а в теле запроса. Выберите метод POST, адрес https://postman-echo.com/post, вкладку Body и формат:

Формат выбирают по документации API: если сервер ждет JSON, а пришла форма, типичный ответ — 400 или 415 Unsupported Media Type. Для JSON выберите raw, справа — JSON, и введите тело {"token": "demo-123"}. Echo-сервис вернет его в поле json ответа — так видно, что именно ушло на сервер.

Заголовки и авторизация

Произвольный заголовок добавляют во вкладке Headers: ключ X-Header-Foo, значение bar. Токены и логины удобнее задавать во вкладке Authorization — Postman сам соберет правильный заголовок.

• Basic Auth. Откройте https://postman-echo.com/basic-auth, в Authorization выберите тип Basic Auth, логин postman, пароль password. Postman закодирует пару в Base64 и отправит Authorization: Basic .... Сервис ответит {"authenticated": true}, при неверной паре — 401. Base64 — кодирование, а не шифрование, поэтому Basic Auth допустим только поверх HTTPS.
• Bearer Token. Для API с токенами (JWT, OAuth-токены доступа) выберите Bearer Token и вставьте {{token}} — значение возьмется из переменной.
• Inherit auth from parent. Если авторизацию задать на уровне коллекции, все запросы внутри унаследуют ее — не придется дублировать токен в каждом.

Коллекции и переменные

Чтобы не собирать запрос заново, сохраните его: Save рядом с Send, затем выберите или создайте коллекцию. Сохраненные запросы видны в боковой панели Collections, а уже отправленные — в History.

Повторяющиеся части выносят в переменные: в настройках коллекции на вкладке Variables создайте baseUrl = https://postman-echo.com и замените адрес в запросах на {{baseUrl}}/get. Если переменная не найдена, Postman подсветит ее красным и отправит текст {{baseUrl}} буквально — это частая причина «непонятных» ошибок адреса.

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

Порядок приоритета от узкой к широкой: local, data, environment, collection, global. У переменной окружения два значения: начальное синхронизируется в облако и видно тем, с кем вы делитесь окружением, текущее хранится локально. Секреты кладут только в текущее значение.

Тесты: проверяем ответ автоматически

Во вкладке Scripts запроса есть два скрипта на JavaScript: Pre-request выполняется до отправки, Post-response — после получения ответа. Тесты пишут в Post-response. Минимальный набор для запроса {{baseUrl}}/get?foo=bar&page=1:

pm.test("Статус 200", function () {
    pm.response.to.have.status(200);
});

pm.test("Параметр foo вернулся в args", function () {
    const body = pm.response.json();
    pm.expect(body.args.foo).to.eql("bar");
});

pm.test("Ответ быстрее 1000 мс", function () {
    pm.expect(pm.response.responseTime).to.be.below(1000);
});

После Send во вкладке ответа Test Results появятся три строки PASS. pm.test задает имя проверки, pm.expect — утверждение в стиле библиотеки Chai, pm.response.json() разбирает тело. Порог 1000 мс учебный: в реальном наборе его берут из требований к API.

Типичная ошибка новичка — сравнить параметр из URL с числом:

pm.test("page равен 1", function () {
    const body = pm.response.json();
    pm.expect(body.args.page).to.eql(1);
});

Тест падает, потому что параметры query-строки всегда приходят строками:

AssertionError: expected '1' to deeply equal 1

Исправление — явно привести тип (или сравнивать со строкой "1", если API так и задуман):

pm.test("page равен 1", function () {
    const body = pm.response.json();
    pm.expect(Number(body.args.page)).to.eql(1);
});

Передача значения между запросами

Частый сценарий: первый запрос получает токен, следующие его используют. В Post-response запроса логина сохраните значение в окружение:

pm.test("В ответе есть token", function () {
    const body = pm.response.json();
    pm.expect(body.json).to.have.property("token");
    pm.environment.set("token", body.json.token);
});

В роли «логина» здесь POST на echo из раздела выше: скрипт запишет в token значение demo-123. В реальном API путь к токену свой (например, body.access_token). Следующие запросы берут его через {{token}} в Bearer Token.

Запуск коллекции целиком

Когда запросов и тестов много, их прогоняют пакетом:

• Collection Runner в приложении: кнопка Run у коллекции, выбор окружения, числа итераций и при необходимости файла данных CSV/JSON. Итог — таблица PASS/FAIL по всем тестам.
• Из командной строки для CI: Postman CLI (postman collection run) или open-source утилита Newman (newman run collection.json -e environment.json по экспортированным файлам коллекции и окружения). Ненулевой код выхода при упавших тестах останавливает пайплайн.

Секреты: как не выложить токен

Коллекции и окружения синхронизируются в облако Postman, а публичные workspace индексируются поиском. Поэтому:

• токены, пароли и ключи храните только в текущем (локальном) значении переменной или во встроенном хранилище секретов Postman Vault, а в начальном оставляйте пустую строку;
• для секрета выбирайте тип переменной secret — значение маскируется на экране;
• перед публикацией workspace или экспортом коллекции проверьте Authorization, Headers и переменные;
• утекший токен мало удалить из Postman: его отзывают и перевыпускают на стороне сервиса, копия могла остаться в истории и чужих форках.

Если не получилось

Выводы

• Postman собирает HTTP-запрос из метода, URL, параметров, заголовков и тела и показывает ответ со статусом, заголовками и временем.
• Формат тела POST выбирают по API: JSON для большинства REST, form-data для файлов, urlencoded для форм.
• Коллекция хранит запросы, окружение — адреса и ключи стенда; при совпадении имен побеждает более узкая область переменных.
• Тесты pm.test в Post-response превращают ручную проверку в повторяемую, а Collection Runner, Postman CLI и Newman прогоняют ее пакетом и в CI.
• Секреты держат в текущем значении или Vault, не в начальном и не в публичном workspace.

Где применяется / связь с практикой

FAQ

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

Чем Postman отличается от curl?
curl — консольная утилита для одного запроса, удобна в скриптах. Postman добавляет интерфейс, хранение запросов в коллекциях, переменные, тесты и пакетный запуск. Готовый запрос из Postman можно превратить в команду curl через кнопку Code справа.

Можно ли тестировать в Postman GraphQL, gRPC или WebSocket?
Да, для них есть отдельные типы запросов, они создаются через New.