Тестирование API: Postman/Newman

1) Зачем Postman/Newman

• повторяемые регрессы и быстрые смоки;
• параметризацию окружений/секретов;
• метрики качества и машинно-читаемые отчеты.

2) Базовая модель

Коллекция — дерево запросов и папок с общими скриптами.
Окружения — набор `{{vars}}` для dev/stage/prod (URL, ключи).
Pre-request script — подготовка: подписи, токены, корелляция данных.
Tests — утверждения и сохранение переменных/артефактов.
Data-files — CSV/JSON для data-driven прогона.
Mock/Monitor — стабы и периодические проверки.

<API v1>
├─ _bootstrap (auth, health, seeds)
├─ Public
├─ Authenticated
│  ├─ Accounts
│  ├─ Payments
│  └─ Reports
└─ _teardown (cleanup)

3) Переменные и секреты

Именуйте переменные явным префиксом: `baseUrl`, `tenant`, `clientId`.
Секреты (пароли, client_secret, HMAC-ключи) держите в переменных окружения CI, не коммитьте в репозиторий.
Используйте скоуп: local → collection → environment → globals (минимально возможный).

json
{
"name": "stage-eu",
"values": [
{"key":"baseUrl","value":"https://api. stage. example. com","type":"text","enabled":true},
{"key":"tenant","value":"eu-1","type":"text","enabled":true}
]
}

4) Аутентификация: шаблоны

4.1 OAuth2/OIDC (Client Credentials)

js if (!pm.environment. get("access_token")          Date. now() > pm. environment. get("token_exp")) {
pm. sendRequest({
url: pm. environment. get("authUrl"),
method: 'POST',
header: {'Content-Type':'application/x-www-form-urlencoded'},
body: { mode:'urlencoded', urlencoded:[
{key:'grant_type',value:'client_credentials'},
{key:'client_id',value:pm. environment. get('clientId')},
{key:'client_secret',value:pm. environment. get('clientSecret')},
{key:'scope',value:'payments:read payments:write'}
]}
}, (err, res) => {
pm. environment. set("access_token", res. json(). access_token);
pm. environment. set("token_exp", Date. now()+ (res. json(). expires_in-30)1000);
});
}

В запросе: `Authorization: Bearer {{access_token}}`.

4.2 HMAC (вебхуки/партнеры)

js const body = pm. request. body? pm. request. body. raw          '': '';
const ts = Math. floor(Date. now()/1000);
const msg = `${ts}.${body}`;
const sig = CryptoJS. HmacSHA256(msg, pm. environment. get('hmacSecret')). toString();
pm. variables. set('ts', ts);
pm. variables. set('sig', sig);

Заголовки: `X-Timestamp: {{ts}}`, `X-Signature: {{sig}}`.

5) Тесты: утверждения и корелляция

Используйте `pm.expect(...)` и `pm.test("...", fn)`.
Сохраняйте идентификаторы для последующих шагов через `pm.collectionVariables.set`.

js pm. test("HTTP 200", () => pm. response. to. have. status(200));
pm. test ("Scheme is valid," () => {
const schema = pm. collectionVariables. get("schema_wallet");
pm. expect(tv4. validate(pm. response. json(), JSON. parse(schema))). to. be. true;
});
pm. test ("Contains id," () => {
const id = pm. response. json(). id;
pm. expect(id). to. be. a('string');
pm. collectionVariables. set("wallet_id", id);
});

6) Валидация схемы (OpenAPI/JSON Schema)

Храните JSON Schema в переменных коллекции или отдельным файлом.
Для OpenAPI: используйте готовые либы в pre-request/test (ajv, tv4) — через `pm.sendRequest` на raw-файл или инлайн JSON.

js pm. collectionVariables. set("schema_wallet", JSON. stringify({
"type":"object",
"required":["id","currency","balance"],
"properties":{
"id":{"type":"string"},
"currency":{"type":"string","pattern":"^[A-Z]{3}$"},
"balance":{"type":"number","minimum":0}
}
}));

7) Data-driven сценарии

email, password, currency u1@example. com, P@ss1, EUR u2@example. com, P@ss2, USD

Запрос использует `{{email}}`, `{{currency}}`.

newman run collection. json -e stage-eu. json -d users. csv

JSON (массив объектов) — удобно для сложных кейсов/структур.

8) Негативные кейсы и устойчивость

• 401/403 (без токена/неверный scope/роль).
• 400/422 (валидация схемы, обязательные поля, пределы).
• 404 (BOLA/чужой ресурс).
• 409 (конфликты, идемпотентные ключи).
• 429 (лимиты) — проверяйте `Retry-After`.
• 5xx — корректная деградация и ретраи клиента.

js pm. test ("There is Retry-After at 429," () => {
if (pm. response. code === 429) pm. expect(pm. response. headers. has('Retry-After')). to. be. true;
});

9) Идемпотентность, ретраи, пагинация

Передавайте `Idempotency-Key` и убеждайтесь, что повтор дает тот же `id/status`.
Тестируйте пагинацию: `limit/offset`/`cursor`, детект дубликатов и пропусков.
Имитация ретраев в Test-скрипте: последовательные вызовы с тем же ключом.

js pm. test ("Idempotent repetition," () => {
pm. sendRequest(pm. request, (err, res2) => {
pm. expect(res2. code). to. eql(pm. response. code);
pm. expect(res2. json(). id). to. eql(pm. response. json(). id);
});
});

10) Newman в CI/CD

10.1 Запуск

newman run collection. json \
-e stage-eu. json \
-d data. csv \
--timeout-request 30000 \
--reporters cli,htmlextra,junit \
--reporter-htmlextra-export./reports/report. html \
--reporter-junit-export./reports/junit. xml

10.2 GitHub Actions (фрагмент)

yaml
- uses: actions/setup-node@v4 with: { node-version: '20' }
- run: npm i -g newman newman-reporter-htmlextra
- run: newman run collection. json -e stage-eu. json --reporters cli,junit --reporter-junit-export reports/junit. xml
- uses: actions/upload-artifact@v4 with: { name: newman-reports, path: reports }

10.3 Jenkins/GitLab CI

Экспортируйте JUnit (`--reporter-junit-export`) для нативной визуализации.
В пайплайне разделяйте джобы: smoke (быстрые), regression (полные), security (негатив/границы).

10.4 Docker

docker run --rm -v $PWD:/etc/newman postman/newman \
run collection. json -e stage-eu. json

11) Моки и мониторинг

Mock servers Postman — быстрые стабы для фронта и контрактов.
Monitors — периодический прогон смоков из облака (latency, 5xx, SSL).
В репозитории держите файлы примеров ответов для детерминированных моков.

12) Тест-данные и очистка

Создавайте/удаляйте сущности (_bootstrap/_teardown).
Помечайте тестовые объекты префиксом `e2e_` и TTL.

js pm. collectionVariables. set("uniq", Date. now()+"_"+Math. floor(Math. random()1e6));

13) Производительность «на коленке»

• измеряйте `pm.response.responseTime`;
• прогоняйте 5–10 итераций и фиксируйте p95/пороги;
• тяжелые перформанс-прогоны — в JMeter/k6/Gatling (за пределами этой статьи).

14) Локализация и многоарендность

Переменные `tenant`, `region`, `lang`; переключайте в окружениях.
Тесты должны проверять, что данные не «текут» меж тенантами (BOLA-read, кросс-tenant запреты).
Отдельные коллекции/папки на региональные особенности (лимиты, валюты).

15) Отчетность и артефакты

Храните артефакты CI: HTML-репорты, `junit.xml`, логи неуспешных ответов (response bodies).
Подключите Slack/Teams уведомления по падениям смоков.

16) Качество и покрытие

• CRUD per-ресурс (200/201/204 + негативы).
• Авторизация: роли/скоупы/мульти-тенант.
• Пагинация/фильтры/сортировка.
• Идемпотентность и ретраи.
• Лимиты: 413/414/431/429.
• Форматы и схемы (JSON Schema/OpenAPI).
• Интеграции (вебхуки с HMAC/mTLS) — anti-replay.

17) Антипаттерны

Один «счастливый путь» без негативных тестов.
Долгоживущие токены в коллекции/репозитории.
Смешение тест-данных с прод-данными.
Скрытая зависимость порядка тестов без явной корелляции.
Гигантские data-files без семплирования.
Отсутствие отчетов JUnit/HTML → нет видимости в CI.

18) Чек-лист prod-готовности

• Коллекции разбиты по доменам, есть `_bootstrap/_teardown`.
• Окружения для dev/stage/prod; секреты из CI-секрет-хранилища.
• Pre-request для auth (OAuth2/HMAC); токены кэшируются и ротируются.
• Тесты: позитив+негатив, схемы (JSON Schema), пагинация, 429/Retry-After.
• Идемпотентность: проверка `Idempotency-Key`, двойной вызов эквивалентен.
• Data-driven CSV/JSON, случайные суффиксы для уникальности.
• Newman в CI: JUnit/HTML отчеты, артефакты как build outputs.
• Моки/мониторы для ключевых маршрутов; SLA по смокам.
• Документация по переменным, тегам и порядку запуска.

19) TL;DR

Храните логику тестов в коллекциях Postman, параметры — в окружениях, а прогон делайте в CI через Newman с отчетами JUnit/HTML. Покрывайте негативы, схемы, идемпотентность, пагинацию и лимиты. Коррелируйте шаги переменными, используйте data-driven входы и моки/мониторы. Секреты — только из CI, отчеты — артефакты билда.