DEV Community

Cover image for كيف تختبر واجهات برمجة تطبيقات رفع الملفات (multipart/form-data) في Apidog
Yusuf Khalidd
Yusuf Khalidd

Posted on • Originally published at apidog.com

كيف تختبر واجهات برمجة تطبيقات رفع الملفات (multipart/form-data) في Apidog

لقد أنشأت نقطة نهاية تستقبل ملفًا: يحمّل المستخدم صورة ملف شخصي إلى POST /avatars، أو يرسل تطبيقك ملف PDF موقّعًا إلى POST /documents. الآن تحتاج إلى اختبارها عبر HTTP باستخدام ملف حقيقي، وإرساله ضمن حقل نموذج، ثم التحقق من الاستجابة.

جرّب Apidog اليوم

تستخدم عمليات تحميل الملفات تنسيق multipart/form-data، وليس JSON؛ لذلك لا يكفي لصق نص في جسم الطلب وإرساله. تحتاج إلى أداة تدعم حقول الملفات، وإلى طريقة تضمن العثور على الملف عند تشغيل الاختبار لاحقًا في Runner أو CLI. يتعامل Apidog مع بناء الطلبات وتشغيل الاختبارات. وإذا احتجت إلى مراجعة التنسيق أولًا، اقرأ دليل تحميل الملفات في واجهات برمجة التطبيقات ومرجع MDN حول FormData.

ما هو multipart/form-data ولماذا تحتاجه عمليات التحميل؟

يدعم جسم الطلب في Apidog أنواعًا متعددة، مثل form-data وx-www-form-urlencoded وJSON وXML وraw وbinary. ستستخدم JSON في أغلب الحالات، لكن تحميل الملفات هو الاستثناء.

يتوافق form-data مع الرأس التالي:

Content-Type: multipart/form-data
Enter fullscreen mode Exit fullscreen mode

بدل إرسال جسم واحد، يقسم هذا التنسيق الطلب إلى أجزاء. لكل جزء اسم ومحتوى خاصان به:

  • جزء نصي مثل title أو comment
  • جزء ملف يحتوي بايتات صورة أو PDF
  • جزء نصي يحمل JSON للبيانات الوصفية

أما x-www-form-urlencoded فهو مناسب لحقول نصية بسيطة فقط، وليس لنقل الملفات. إذا كانت نقطة النهاية تستقبل صورة أو PDF أو أي ملف، استخدم form-data.

في Apidog، يملك كل صف في form-data نوعًا. عند تغيير نوع الحقل إلى file، يعامل Apidog القيمة كملف محلي لإرفاقه بدل إرسالها كنص.

إرسال ملف واحد والتحقق من الاستجابة

لنفترض أن لديك نقطة النهاية التالية:

POST /avatars
Enter fullscreen mode Exit fullscreen mode

وأنها تستقبل حقلًا باسم avatar وتعيد JSON يحتوي على رابط الصورة المخزنة.

1. اختر form-data في Body

أنشئ طلبًا جديدًا أو افتح نقطة النهاية الحالية، ثم اضبط:

POST https://api.example.com/avatars
Enter fullscreen mode Exit fullscreen mode

في تبويب Body:

  1. اختر form-data.
  2. سيضبط Apidog رأس Content-Type: multipart/form-data تلقائيًا.

2. أضف حقل الملف

أضف صفًا جديدًا بالقيم التالية:

المفتاح النوع القيمة
avatar file اختر ملفًا

غيّر النوع من string إلى file، ثم انقر على Upload واختر ملفًا محليًا، مثل:

jane-profile.png
Enter fullscreen mode Exit fullscreen mode

3. أرسل الطلب

اضغط Send. سيقرأ Apidog الملف من المسار المحلي، ويبني طلب multipart/form-data، ثم يرسله إلى الخادم.

ملاحظة مهمة: يحفظ Apidog مسار الملف المحلي، وليس بايتات الملف نفسها في السحابة. ستصبح هذه التفاصيل مهمة عند تشغيل السيناريو على جهاز آخر أو في Runner وCLI.

قد تبدو الاستجابة الناجحة كالتالي:

{
  "id": "usr_8842",
  "avatarUrl": "https://cdn.example.com/avatars/usr_8842.png",
  "sizeBytes": 48210,
  "contentType": "image/png"
}
Enter fullscreen mode Exit fullscreen mode

4. أضف تأكيدات للاستجابة

لا يكفي أن يعيد الطلب الحالة 200. أضف تأكيدات للتحقق من أن الاستجابة تحتوي على البيانات المتوقعة:

status code == 200
$.avatarUrl exists
$.contentType == "image/png"
Enter fullscreen mode Exit fullscreen mode

في Apidog، أضف هذه التأكيدات بعد الطلب أو ضمن خطوة السيناريو:

  1. تحقق من رمز الحالة 200.
  2. تحقق من وجود $.avatarUrl باستخدام JSONPath.
  3. تحقق من أن $.contentType يساوي image/png.

للتفاصيل، راجع دليل تأكيدات واجهة برمجة التطبيقات.

ولمقارنة الطلب خارج الأداة، يمكنك تنفيذ العملية نفسها باستخدام curl:

curl -X POST https://api.example.com/avatars \
  -F "avatar=@jane-profile.png"
Enter fullscreen mode Exit fullscreen mode

تشير -F إلى بناء جزء multipart، بينما تخبر @ أداة curl بقراءة محتويات الملف. يقوم حقل file في Apidog بالمهمة نفسها من خلال منتقي الملفات.

إرسال ملف وJSON في الطلب نفسه

غالبًا لا تستقبل نقطة النهاية ملفًا فقط. مثلًا، قد يحتاج POST /documents إلى ملف PDF وبيانات وصفية مثل العنوان والفئة والعلامات.

الحقول البسيطة

أضف حقول form-data بجانب الملف:

المفتاح النوع مثال
file file q3-invoice.pdf
title string Q3 Invoice
category string billing

ترسل كل هذه الحقول في طلب multipart واحد.

البيانات الوصفية المركبة

إذا كانت البيانات الوصفية تحتوي على كائنات متداخلة أو مصفوفات، أرسلها كسلسلة JSON في جزء نصي.

أضف حقلًا باسم metadata من النوع string، ثم ضع فيه JSON:

{
  "title": "Q3 Invoice",
  "category": "billing",
  "tags": ["invoice", "2026", "paid"]
}
Enter fullscreen mode Exit fullscreen mode

سيحتوي الطلب عندها على جزأين رئيسيين:

  • file من النوع file ويحمل q3-invoice.pdf
  • metadata من النوع string ويحمل JSON

يقرأ الخادم الملف من الجزء الأول ويحلل JSON من الجزء الثاني. هذا نمط شائع في واجهات برمجة التطبيقات، ويمكنك رؤية مثال عملي في وثائق تحميل ملفات Stripe.

إذا كنت تنتقل من Postman، فراجع دليل تحميل ملف وبيانات JSON في Postman.

إرفاق أكثر من ملف

لإرسال ملف رئيسي وصورة مصغرة مثلًا، أضف صفين من النوع file:

المفتاح النوع
file file
thumbnail file

لا تحتاج إلى وضع خاص للملفات المتعددة؛ أضف حقل file لكل جزء تتوقعه نقطة النهاية.

تحويل الطلب إلى سيناريو اختبار قابل للتكرار

إرسال الطلب يدويًا يثبت أن نقطة النهاية تعمل مرة واحدة. لكن لاكتشاف الانحدارات، احفظ العملية كسيناريو اختبار.

مثال على سيناريو:

  1. أرسل POST /avatars.
  2. استخرج id من الاستجابة.
  3. نفّذ GET /users/{id}.
  4. تحقق من استمرار وجود رابط الصورة الرمزية.

ابنِ خطوة التحميل كما فعلت في الطلب المفرد، ثم احفظها داخل سيناريو. يشرح دليل كيفية كتابة سيناريو اختبار باستخدام Apidog كيفية ربط الخطوات وتمرير القيم بينها.

بعد حفظ السيناريو، يمكنك:

لكن هناك مشكلة مهمة: السيناريو يعمل على جهازك لأن الملف موجود على جهازك فقط.

المطب الخفي: التحميلات التي تعمل محليًا وتفشل في مكان آخر

يحفظ Apidog مسار الملف، وليس الملف نفسه. على جهازك، قد يشير المسار إلى ملف موجود بالفعل:

/Users/jane/pics/jane-profile.png
Enter fullscreen mode Exit fullscreen mode

لكن عند تشغيل السيناريو على جهاز مختلف، لن يكون هذا المسار موجودًا بالضرورة.

ستظهر المشكلة غالبًا في حالتين.

التعاون داخل الفريق

عندما يفتح زميلك الطلب، سيرى حقل الملف والمسار الذي اخترته، لكنه لن يستطيع إرسال الطلب إذا لم يكن الملف موجودًا على جهازه في المسار نفسه.

الحل:

  1. اطلب من زميلك وضع نسخة من الملف على جهازه.
  2. حدّث مسار الحقل إلى موقع الملف المحلي لديه.
  3. أو استخدم متغيرًا للمسار بدل تثبيت المسار في الخطوة.

تشغيل Runner أو CLI

قد ينجح سيناريو التحميل محليًا ثم يفشل عند تشغيله في Runner أو من خلال CLI. السبب ليس في التأكيدات ولا في نقطة النهاية: بيئة التشغيل لا تجد الملف في المسار المحفوظ من جهازك.

القاعدة الأساسية هي:

يجب أن يكون الملف موجودًا على الجهاز الذي يرسل الطلب، وأن يشير المسار إلى موقعه على ذلك الجهاز.

إعداد المسار في Runner

يقرأ Runner الملفات من دليل مضيف تم تثبيته في وحدة التخزين عند النشر باستخدام العلامة -v.

الخطوات:

  1. انسخ ملف التحميل إلى دليل المضيف المثبت.
  2. افتح تفاصيل خطوة رفع الملف في السيناريو.
  3. انقر على Batch Edit.
  4. استبدل قيمة حقل الملف بمسار داخل دليل Runner، مثل: 
/opt/runner/jane-profile.png
Enter fullscreen mode Exit fullscreen mode

إعداد المسار في CLI

اتبع المبدأ نفسه في CLI:

  1. ضع الملف على جهاز CLI.
  2. افتح الخطوة عبر Batch Edit.
  3. حدّث المسار إلى موقع الملف على هذا الجهاز: 
/opt/apidog/runner/jane-profile.png
Enter fullscreen mode Exit fullscreen mode

استخدم متغيرًا بدل المسارات الثابتة

بدل كتابة مسار ثابت داخل خطوة التحميل، استخدم متغيرًا، مثل:

{{upload_file_path}}
Enter fullscreen mode Exit fullscreen mode

ثم اضبط قيمته لكل بيئة:

# محليًا
/Users/jane/pics/jane-profile.png

# في Runner
/opt/runner/jane-profile.png
Enter fullscreen mode Exit fullscreen mode

بهذا يبقى السيناريو نفسه دون تعديل، بينما يتغير المسار حسب بيئة التشغيل.

شرط أساسي: يستطيع Runner الوصول إلى الملفات الموجودة داخل الدليل الذي ثبّتّه فقط باستخدام -v. إذا لم يكن الملف داخل هذا المسار، فلن يتمكن Runner من العثور عليه.

راجع وثائق Apidog حول طلبات تحميل الملفات لخطوات التثبيت والتحرير بالجملة.

أتمتة سير العمل باستخدام Apidog CLI

بعد حفظ سيناريو التحميل، يمكنك تشغيله بدون واجهة رسومية داخل CI.

ثبّت CLI وسجّل الدخول:

npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>
Enter fullscreen mode Exit fullscreen mode

ثم شغّل السيناريو المحفوظ باستخدام معرف السيناريو ومعرف البيئة:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenario_id> -e <env_id> -r cli
Enter fullscreen mode Exit fullscreen mode

المعلمات الأساسية:

المعلمة الاستخدام
-t معرف سيناريو الاختبار
-e معرف البيئة
-r أداة الإبلاغ، مثل cli أو html أو junit

يمكنك فصل أكثر من أداة إبلاغ بفاصلة. يستخدم CLI رموز الخروج للإبلاغ عن النجاح أو الفشل، لذا يمكنه التحكم في نتيجة خط أنابيب CI.

للتثبيت والإعداد، راجع دليل تثبيت Apidog CLI.

تذكّر: إذا كان السيناريو يحتوي على خطوة تحميل ملف، يجب أن يكون الملف موجودًا على جهاز CLI وأن يشير المسار أو المتغير إلى موقعه الصحيح. إذا لم تفعل ذلك، ستفشل خطوة التحميل حتى لو كانت بقية خطوات السيناريو صحيحة.

لإعدادات CI الأكثر تقدمًا، راجع الاختبار المدفوع بالبيانات باستخدام Apidog CLI.

الأسئلة الشائعة

لماذا لا يستطيع زميلي إرسال طلب تحميل الملف؟

يحفظ Apidog مسار الملف المحلي وليس الملف نفسه. المسار الذي اخترته يشير إلى ملف على جهازك، وليس إلى ملف على جهاز زميلك. يجب أن يضع زميلك نسخة من الملف على جهازه ثم يحدّث المسار، أو تستخدم متغيرًا لمسار الملف.

ينطبق الأمر نفسه على الاختبارات المجدولة وRunner: يجب تجهيز الملف في بيئة التشغيل.

كيف أرسل JSON مع ملف في الطلب نفسه؟

اختر form-data، ثم:

  1. أضف حقل الملف بنوع file.
  2. أضف حقلًا آخر بنوع string.
  3. الصق JSON في قيمة الحقل النصي.

يتلقى الخادم الملف في جزء multipart وJSON في جزء آخر من الطلب نفسه.

ما المسار الذي يجب استخدامه لملف في Runner؟

استخدم مسارًا داخل دليل المضيف الذي ثبّتّه في وحدة تخزين Runner باستخدام -v، مثل:

/opt/runner/yourfile.jpg
Enter fullscreen mode Exit fullscreen mode

انسخ الملف إلى هذا الدليل، ثم استخدم Batch Edit لتحديث قيمة الحقل. في CLI قد يكون المسار مثل:

/opt/apidog/runner/yourfile.jpg
Enter fullscreen mode Exit fullscreen mode

هل يفرض Apidog حدًا لحجم الملف أو نوعه؟

يركز Apidog على بناء الطلب وقراءة الملف من المسار. حدود الحجم وأنواع الملفات المقبولة تعتمد على واجهة برمجة التطبيقات التي تختبرها. راجع قواعد التحقق في الخادم، وأضف تأكيدات للتحقق من استجابات الملفات المرفوضة أو كبيرة الحجم.

هل أستخدم form-data أم x-www-form-urlencoded للتحميل؟

استخدم form-data. فهو يتوافق مع multipart/form-data ومصمم لنقل الملفات. استخدم x-www-form-urlencoded للحقول النصية البسيطة فقط، وليس للصور أو ملفات PDF.

خاتمة

يتلخص اختبار تحميل الملفات في خطوتين:

  1. بناء طلب multipart/form-data بشكل صحيح.
  2. ضمان وجود الملف في بيئة تشغيل الاختبار.

في Apidog، اختر form-data في Body، وغيّر نوع الحقل إلى file، واختر الملف، وأرسل أي JSON كحقل نصي، ثم أضف تأكيدات للاستجابة.

عند نقل السيناريو إلى Runner أو CLI، ضع الملف على جهاز التشغيل وحدّث المسار عبر Batch Edit أو متغير بيئي. بهذه الطريقة سيعمل الاختبار المؤتمت كما يعمل محليًا.

هل تريد التجربة على نقطة النهاية الخاصة بك؟ حمّل Apidog، وأنشئ طلب form-data لمسار التحميل، ثم تحقق من الاستجابة.

Top comments (0)