API сыноо: Postman/Newman

1) Эмне үчүн Postman/Newman

• кайталануучу регрессия жана тез даам;
• чөйрөнү/сырларды параметрлөө;
• Сапат көрсөткүчтөрү жана машинада окула турган отчеттор.

2) Негизги модели

Collection - жалпы скрипттер менен суроо жана папкалар дарагы.
Чөйрөлөр - dev/stage/prod (URL, ачкычтар) үчүн '{{vars}}' жыйындысы.
Pre-request script - даярдоо: кол тамгалар, белгилер, маалыматтарды корреляциялоо.
Tests - бекитүү жана өзгөрмө/артефакттарды сактоо.
Data-files - CSV/JSON үчүн data-айдоо.
Mock/Monitor - лагерлер жана мезгил-мезгили менен текшерүү.

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

3) Өзгөрмөлүү жана сырлар

өзгөрмөлөрдү ачык префикс деп атаңыз: 'baseUrl', 'tenant', 'clientId'.
Сырлар (сырлар, client_secret, HMAC-ачкычтар) C айлана-чөйрөнүн өзгөрмөлүү сактоо, репозиторийге коммит эмес.
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) Autentification: үлгүлөрү

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 (Webhook/өнөктөштөр)

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) Validation схемасы (OpenAPI/JSON схемасы)

JSON схемасын өзгөрмөлүү коллекцияда же өзүнчө файлда сактаңыз.
OpenAPI үчүн: pre-request/test (ajv, tv4) үчүн даяр либаларды колдонуңуз - 'pm аркылуу. sendRequest 'үчүн чийки файл же 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 (БАЛА/башка бирөөнүн ресурсу).
• 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' берерине ынаныңыз.
Pagination сыноо: 'limit/offset '/' cursor', дубликат жана өтмөк деталдары.
Test Script боюнча Retrains тууроо: бир эле ачкыч менен ырааттуу чалуулар.

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 - Front жана келишимдер үчүн тез топтор.
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-окуу, кросс-тенант тыюу салуулар).
Региондук өзгөчөлүктөргө өзүнчө коллекциялар/папкалар (лимиттер, валюталар).

15) Отчеттуулук жана артефакттар

CI артефакттарын сактаңыз: HTML репорттору, 'junit. xml ', ийгиликсиз жооптордун логдору (response bodies).
Slack/Teams чөптөрдүн кулашына билдирүүлөрдү туташтырыңыз.

16) Сапаты жана каптоо

• CRUD per-ресурс (200/201/204 + терс).
• Authorization: ролдору/скупы/multi-тенант.
• Pagination/чыпкалар/сорттоо.
• Демпотенттик жана ретра.
• Лимиттер: 413/414/431/429.
• Форматтар жана схемалар (JSON Schema/OpenAPI).
• Интеграция (HMAC/mTLS менен Webhuke) - anti-replay.

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

терс тесттер жок бир "бактылуу жол".
Коллекциядагы/репозиторийдеги узак мөөнөттүү токендер.
Тест-маалыматтарды прод-маалыматтар менен аралаштыруу.
Ачык корелляциясы жок тесттердин тартибинин жашыруун көз карандылыгы.
Гигантские данные-files без семплирования.
JUnit/HTML отчетторунун жоктугу → CI 'де көрүнүү жок.

18) Prod-даярдык чек тизмеси

• Жыйнактар домендерге бөлүнгөн, бар '_ bootstrap/_ teardown'.
• dev/stage/prod үчүн чөйрө; CI-Secret-сактоо сырлары.
• Pre-request для auth (OAuth2/HMAC); токендер кэш жана айланат.
• Тесттер: оң + терс, схемалар (JSON схемасы), пагинация, 429/Retry-After.
• Idempotency: 'Idempotency-Key' текшерүү, кош чакырык барабар.
• Data-driven CSV/JSON, уникалдуулук үчүн кокустан кошулган.
• Newman CI: JUnit/HTML отчеттор, артефакттар катары build outputs.
• Негизги каттамдар үчүн моки/мониторлор; Smokes боюнча SLA.
• Өзгөрмөлүү документтер, тегдер жана баштоо тартиби.

19) TL; DR

Тесттин логикасын Postman жыйнактарында сактаңыз, параметрлерин чөйрөдө сактаңыз жана Newman аркылуу JUnit/HTML отчеттору менен CIге кириңиз. Негативдерди, схемаларды, демпотенттикти, пагинацияны жана лимиттерди жабыңыз. Өзгөрмөлүү кадамдарды корреляциялоо, data-driven кирүүлөрүн жана мокторду/мониторлорду колдонуу. Сырлар - CI гана, отчеттор - Билд экспонаттары.