اختبار واجهة برمجة التطبيقات: ساعي البريد/نيومان

1) لماذا ساعي البريد/نيومان

• والتراجع المتكرر والتدخين السريع ؛
• ووضع بارامترات للبيئات/الأسرار ؛
• مقاييس الجودة والتقارير المقروءة آليا.

2) نموذج القاعدة

المجموعة - شجرة من الاستفسارات والمجلدات ذات نصوص مشتركة.
البيئات - set '{{vars}}' for dev/stage/prod (URL, keys).
نصي الطلب المسبق - التحضير: التوقيعات، الرموز، ارتباط البيانات.
الاختبارات - التأكيدات والحفاظ على المتغيرات/القطع الأثرية.
ملفات البيانات - CSV/JSON لتشغيل البيانات.
Mock/Monitor - قطعان وفحوصات دورية.

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

3) المتغيرات والأسرار

الرجوع إلى المتغيرات كبادئة صريحة: "baseUrl'،" المستأجر "،" معرف العميل ".
احتفظ بالأسرار (كلمات المرور، client_secret، مفاتيح HMAC) في متغيرات بيئة CI، لا تلتزم بالمستودع.
استخدام النطاق: جمع → المحلية → البيئة → العالمية.

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 (وثائق تفويض العميل)

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);
});
}

في الطلب: «الإذن: حامل {{access _ token}}».

4. 2 HMAC (Webhooks/Partners)

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. توقع (...) «и» مساءً. الاختبار (... "," fn) ".
قم بتخزين معرفات الخطوات اللاحقة عبر 'pm. متغيرات الجمع. '.

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 في متغيرات التجميع أو في ملف منفصل.
بالنسبة إلى OpenAPI: استخدم libs الجاهزة في الطلب المسبق/الاختبار (ajv، tv4) - عبر 'pm. أرسل الطلب إلى الملف الخام أو JSON inline.

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) النصوص المستندة إلى البيانات

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 (بدون رمز/نطاق/دور غير صالح).
• 400/422 (التصديق على المخطط، المجالات الإلزامية، الحدود).
• 404 (BOLA/Alien resource).
• 409 (النزاعات، المفاتيح الحمقاء).
• 429 (حدود) - تحقق من «إعادة المحاولة بعد».
• 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» وتأكد من أن التكرار يعطي نفس «المعرف/الحالة».
استعداد الاختبار: «الحد/الإزاحة »/« المؤشر»، والكشف عن النسخ المكررة والثغرات.
محاكاة إعادة التصوير في نص الاختبار: مكالمات متتالية بنفس المفتاح.

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) نيومان в سي آي/سي دي

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 (مقتطف)

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') للعرض المحلي.
في خط الأنابيب، افصل اللكمات: الدخان (السريع)، الانحدار (الكامل)، الأمن (السلبي/الحدود).

10. 4 Docker

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

11) الموكي والرصد

ساعي البريد الخوادم الوهمية - أكوام سريعة للأمام والعقود.
الشاشات - تشغيل دوري للسحب من السحابة (زمن الوصول، 5xx، SSL).
في المستودع، احتفظ بعينة من ملفات الاستجابة للموك الحتمية.

12) بيانات الاختبار والتنظيف

إنشاء/حذف الكيانات (_bootstrap/_teardown).
علامة اختبار كائنات مع البادئة 'e2e _' و TTL.

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

13) الأداء «على الركبة»

• تدبير 'pm. الرد. وقت الاستجابة '؛
• تشغيل 5-10 تكرارات وإصلاح p95/عتبات ؛
• الأداء الثقيل - في JMeter/k6/Gatling (خارج هذه المقالة).

14) التوطين وتعدد الحيازات

المتغيرات 'المستأجر' و 'الإقليم' و 'اللانغ' ؛ التبديل في البيئات.
يجب أن تتحقق الاختبارات من أن البيانات لا «تتدفق» بين المستأجرين (BOLA-read، الحظر عبر المستأجر).
مجموعات/مجلدات منفصلة للخصائص الإقليمية (الحدود والعملات).

15) الإبلاغ والتحف

متجر CI القطع الأثرية: تقارير HTML، 'junit. xml'، هيئات الاستجابة.
قم بتوصيل إشعارات Slack/Teams لقطرات الصدمة.

16) الجودة والتغطية

• CRUD لكل مورد (200/201/204 + السلبيات).
• الإذن: الأدوار/النطاقات/المستأجرين المتعددين.
• التثبيت/المرشحات/الفرز.
• الغباء والتراجع.
• الحدود: 413/414/431/429.
• الأشكال والمخططات (مخطط JSON/OpenAPI).
• التكامل (خطابات الويب مع HMAC/mTLS) - مضاد لإعادة التشغيل.

17) أنتيباترن

«طريقة سعيدة» بدون اختبارات سلبية.
رموز طويلة العمر في المجموعة/المستودع.
خلط بيانات الاختبار مع بيانات الإنتاج.
الاعتماد على ترتيب الاختبار الكامن دون ارتباط صريح.

ملفات بيانات عملاقة بدون أخذ عينات

لا توجد تقارير JUnit/HTML → أي رؤية في CI.

18) قائمة التحقق من الاستعداد

• يتم تقسيم المجموعات حسب المجال، وهناك «تمزيق bootstrap/_».
• بيئات للتطوير/المرحلة/الدفع ؛ أسرار من المخزن السري
• طلب مسبق для auth (OAuth2/HMAC) ؛ يتم تخزين الرموز وتدويرها.
• الاختبارات: إيجابية + سلبية، مخططات (مخطط JSON)، الاستعداد، 429/Retry-After.
• الخصوصية: تحقق من «Idempotency-Key»، مكافئ مكالمة مزدوجة.
• CSV/JSON القائم على البيانات، اللواحق العشوائية للتفرد.
• Newman in CI: تقارير JUnit/HTML، القطع الأثرية كمخرجات بناء.
• سخرية/مراقبين للطرق الرئيسية ؛ SLA على التين.
• توثيق المتغيرات والعلامات وأوامر الإطلاق.

19) TL ؛ د

تخزين منطق اختبار في مجموعات Postman، والمعلمات في البيئات، وتشغيل في CI عبر Newman مع تقارير JUnit/HTML. تغطية السلبيات والمخططات والغباء والترقيم والحدود. ربط الخطوات بالمتغيرات، واستخدام المدخلات المستندة إلى البيانات والغسالات/الشاشات. الأسرار - فقط من CI، التقارير - تبني القطع الأثرية.