Тестування 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 ітерацій і фіксуйте р95/пороги;
• важкі перформанс-прогони - в 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, звіти - артефакти білда.