Postman для системного аналитика: коллекции, окружения и тесты

Я видел аналитиков, которые проверяют API методом «тыка». Открывают браузер, вбивают URL в адресную строку, получают JSON — и гадают, правильно ли это. Коллега, так нельзя. Давайте я покажу, как Postman превращает хаотичную проверку в воспроизводимый процесс, на который можно положиться.

Postman — это не просто «графический curl». Для аналитика он закрывает три задачи: прототипирование запросов, валидацию ответов и документирование API. Причём закрывает так, что разработчик получает не «ну я проверил, вроде работает», а конкретный набор тестов с зелёными галочками. А тестировщик — коллекцию, которую можно прогнать за минуту.

Что вообще происходит в Postman: карта процесса

Если вы открыли Postman первый раз, взгляд цепляется за кнопку Send. И кажется, что всё просто: вбил URL — нажал — получил ответ. Но за красивой кнопкой стоит конвейер, который стоит понимать.

flowchart TB
  A["Требования к API"] --> B["Коллекция Postman"]
  B --> C["Структура папок"]
  B --> D["Переменные"]
  D --> E["Глобальные<br/>переменные"]
  D --> F["Переменные<br/>коллекции"]
  D --> G["Переменные<br/>окружения"]
  C --> H["GET /users"]
  C --> I["POST /orders"]
  H --> J["Pre-request<br/>скрипт"]
  I --> J
  J --> K["Отправка<br/>запроса"]
  K --> L["Тестовый<br/>скрипт"]
  L --> M["Валидация<br/>ответа"]
  M --> N["Runner<br/>коллекции"]
  N --> O["Документация<br/>API"]
  style A fill:#4a90d9,stroke:#2c5f8a,color:#fff
  style B fill:#7b68ee,stroke:#5a4db2,color:#fff
  style C fill:#7b68ee,stroke:#5a4db2,color:#fff
  style D fill:#f0a500,stroke:#c88400,color:#fff
  style E fill:#f0a500,stroke:#c88400,color:#fff
  style F fill:#f0a500,stroke:#c88400,color:#fff
  style G fill:#f0a500,stroke:#c88400,color:#fff
  style H fill:#50c878,stroke:#3a9a5c,color:#fff
  style I fill:#50c878,stroke:#3a9a5c,color:#fff
  style J fill:#4a90d9,stroke:#2c5f8a,color:#fff
  style K fill:#4a90d9,stroke:#2c5f8a,color:#fff
  style L fill:#50c878,stroke:#3a9a5c,color:#fff
  style M fill:#50c878,stroke:#3a9a5c,color:#fff
  style N fill:#7b68ee,stroke:#5a4db2,color:#fff
  style O fill:#e0e0e0,stroke:#999,color:#333

На схеме выше — жизненный цикл запроса от требований до документации. Требования превращаются в коллекцию. Коллекция ветвится на папки (GET, POST и прочие) и переменные трёх уровней. Каждый запрос прогоняется через pre-request-скрипт, уходит на сервер, результат проверяется тестовым скриптом. Потом Runner массово прогоняет всю коллекцию — и на выходе документация. Не rocket science, но детали важны.

Коллекции: не свалка, а структура

Первая ошибка новичка — одна коллекция «My Workspace» на 150 запросов без папок. Через неделю найти нужный эндпоинт невозможно. Через месяц — проще создать новый запрос, чем искать старый.

Я придерживаюсь правила: одна коллекция = один API или один микросервис. Внутри — папки по сущностям:

1
Коллекция: User Service API
2
├── Users
3
│   ├── GET /users
4
│   ├── GET /users/{{userId}}
5
│   ├── POST /users
6
│   ├── PATCH /users/{{userId}}
7
│   └── DELETE /users/{{userId}}
8
├── Auth
9
│   ├── POST /auth/login
10
│   └── POST /auth/refresh
11
└── Health
12
    └── GET /health

Двойные фигурные скобки \{\{userId\}\} — это переменные, о них ниже. Пока суть в том, что структура папок повторяет структуру эндпоинтов из спецификации. Разработчик открывает коллекцию — и сразу видит: ага, Users, Auth, Health. Не надо гадать, где что лежит.

Коллекцию можно экспортировать в JSON и положить в репозиторий рядом с кодом. Разработчики скажут спасибо (ну, или хотя бы не напишут в личку «а какой там формат ответа у POST /users?»).

Переменные: зачем три уровня и какой когда использовать

Переменные — это то, что отличает «я потыкал API» от «я настроил воспроизводимое тестирование». Postman поддерживает три уровня, и у каждого своя роль.

Глобальные переменные (globals) — живут вне коллекций. Кладу туда то, что нужно везде: API-ключ для стороннего сервиса, токен доступа после логина в pre-request-скрипте.

Переменные коллекции — привязаны к конкретной коллекции. Здесь baseUrl, общие заголовки, версия API. Экспортируются вместе с коллекцией, так что разработчик получит их «из коробки».

Переменные окружения (environment) — переключаются одной кнопкой. Dev, Staging, Prod — три набора значений для одних и тех же ключей. Меняете окружение — и все \{\{baseUrl\}\} в коллекции автоматически подтягивают нужный хост.

Честно говоря, на первом проекте я запихнул всё в глобальные переменные. Работало — не трогал. А потом коллега случайно перезаписал глобальный baseUrl, и полчаса мы гадали, почему запросы уходят в продакшен, хотя должны в дев. Урок: глобальные — только для того, что реально глобально. Всё остальное — в коллекцию или окружение.

Типичный набор для e-commerce API:

Уровень	Переменная	Значение (dev)	Значение (prod)
Коллекция	`apiVersion`	`v1`	`v1`
Окружение	`baseUrl`	`http://localhost:3000`	`https://api.shop.ru`
Окружение	`authToken`	— (получаем через логин)	—
Глобальные	`apmToken`	`dev-key-123`	`prod-key-456`

Pre-request скрипты: подготовка до отправки

Pre-request скрипт — это JavaScript, который выполняется перед каждым запросом в коллекции или папке. Самое частое применение: автоматический логин и получение токена.

Вместо того чтобы руками копировать access_token из ответа POST /auth/login в каждый заголовок, я пишу скрипт на уровне коллекции:

1
// Pre-request коллекции: получаем токен, если его нет
2
if (!pm.environment.get("authToken")) {
3
    pm.sendRequest({
4
        url: pm.environment.get("baseUrl") + "/auth/login",
5
        method: "POST",
6
        header: { "Content-Type": "application/json" },
7
        body: {
8
            mode: "raw",
9
            raw: JSON.stringify({
10
                login: pm.environment.get("testLogin"),
11
                password: pm.environment.get("testPassword")
12
            })
13
        }
14
    }, (err, res) => {
15
        if (!err) {
16
            const token = res.json().access_token;
17
            pm.environment.set("authToken", token);
18
        }
19
    });
20
}

Скрипт проверяет, есть ли токен в окружении. Если нет — логинится, сохраняет токен, и все последующие запросы в коллекции используют его через заголовок Authorization: Bearer \{\{authToken\}\}. Никакого ручного копипаста.

Другие применения pre-request:

Генерация случайных тестовых данных (email, телефон) через pm.variables.replaceIn
Подпись запроса (HMAC, если API требует)
Установка динамических заголовков (timestamp, requestId)

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

Тестовый скрипт выполняется после ответа. Это не про QA-тесты на 100500 сценариев, а про минимальную валидацию, которую аналитик может написать за минуту:

1
// Тесты для GET /users/{{userId}}
2
pm.test("Статус 200", () => {
3
    pm.response.to.have.status(200);
4
});
5

6
pm.test("Ответ — JSON", () => {
7
    pm.response.to.be.json;
8
});
9

10
pm.test("Есть поле email", () => {
11
    const user = pm.response.json();
12
    pm.expect(user).to.have.property("email");
13
});
14

15
pm.test("userId в ответе совпадает с запросом", () => {
16
    const user = pm.response.json();
17
    pm.expect(user.id).to.eql(pm.environment.get("userId"));
18
});
19

20
pm.test("Время ответа < 500 мс", () => {
21
    pm.expect(pm.response.responseTime).to.be.below(500);
22
});

Пять строчек — и у меня уже не «вроде ок», а конкретный отчёт: 5 passed, 0 failed. На ревью требований с разработчиком это работает лучше любых слов. Я не говорю «я проверил». Я показываю зелёный прогон коллекции.

Встроенная библиотека pm.* (Postman Sandbox) даёт всё необходимое: pm.test(), pm.expect() (ChaiJS), pm.response. Для сложных проверок — JSON Schema валидация:

1
const schema = {
2
    type: "object",
3
    required: ["id", "email", "role"],
4
    properties: {
5
        id: { type: "number" },
6
        email: { type: "string", format: "email" },
7
        role: { type: "string", enum: ["admin", "user", "manager"] }
8
    }
9
};
10

11
pm.test("Ответ соответствует JSON Schema", () => {
12
    pm.response.to.have.jsonSchema(schema);
13
});

Схема — это по сути спецификация в коде. Если разработчик меняет поле role с admin на superadmin и забывает предупредить, тест падает. Аналитик узнаёт об изменении контракта до того, как оно уедет в прод.

Runner: прогоняем всё разом

Runner — это встроенный «пускач» коллекций. Открываете коллекцию, жмёте Run, выбираете окружение — и все запросы выполняются последовательно. На выходе — отчёт: сколько прошло, сколько упало, время каждого запроса.

Зачем это аналитику:

Регресс перед демо. За пять минут до показа стейкхолдеру прогоняю коллекцию — и знаю: API жив, контракты не разъехались. Не краснею на демо.
Приёмочное тестирование. Разработчик сдал задачу — я не изучаю код, а запускаю коллекцию. Если тесты зелёные — принимаю. Если красные — возвращаю с конкретным отчётом.
Передача тестировщику. Вместо «проверь API» даю готовую коллекцию с тестами. Тестировщик не тратит время на написание проверок — только запускает.

Документация из коллекции: один источник правды

Postman умеет генерировать документацию из коллекции. Заливаете коллекцию в Postman Cloud (бесплатно для небольших команд) — и получаете страницу с описанием всех эндпоинтов. URL можно кинуть разработчику, тестировщику, заказчику.

Документация подтягивает:

Описание запроса (из поля Description каждого эндпоинта)
Параметры и заголовки
Примеры запросов и ответов (сохранённые в коллекции)
Результаты тестовых прогонов

Одно из моих любимых применений: в поле Description пишу краткое описание на русском — и документация готова без вёрстки, без Confluence, без Swagger. Конечно, для полноценной документации лучше Swagger и OpenAPI, но для быстрого старта и прототипирования — самодокументирующаяся коллекция закрывает 80% потребностей.

Зачем аналитику Postman, если есть Swagger и curl

Вопрос, который мне задают регулярно. Swagger — это контракт. Postman — это инструмент проверки контракта. Они не заменяют, а дополняют друг друга.

Curl, в свою очередь, крут для отладки, но когда у вас 30 эндпоинтов с тремя окружениями и тестами — curl превращается в bash-простыню на 500 строк. Postman даёт визуальный интерфейс, переменные и автотесты, не требуя от аналитика быть программистом.

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

Чек-лист для аналитика

Создайте отдельную коллекцию под каждый API, с которым работаете
Разложите запросы по папкам (сущность → метод)
Вынесите baseUrl в переменные окружения, переключайте Dev/Staging/Prod одной кнопкой
Напишите pre-request для автоматического получения токена — избавьтесь от ручного копипаста
К каждому эндпоинту добавьте 3–5 тестовых проверок: статус, формат, ключевые поля
Перед сдачей задачи прогоняйте коллекцию через Runner — показывайте зелёный отчёт, а не слова
Заполните поле Description у запросов — документация сгенерируется автоматически