إذا كان لديك مخطط OpenAPI أو GraphQL، فيمكن لـ Schemathesis تحويله إلى آلاف حالات الاختبار دون أن تكتب تأكيدًا واحدًا. يقرأ المواصفات، ويولد مدخلات عشوائية وصالحة، ويطلقها على واجهة برمجة التطبيقات (API) الخاصة بك، ويبلغ عن الأماكن التي تكسر فيها الاستجابات العقد. يشرح هذا الدليل ماهية Schemathesis، وكيفية تثبيته وتشغيله، وماذا يعني اختبار الأتمتة المستند إلى الخصائص (Property-Based Testing)، وكيف يتناسب مع سير عمل الاختبار الوظيفي واختبار العقود في Apidog.
ما هو Schemathesis؟
Schemathesis هي أداة بايثون مفتوحة المصدر تولد اختبارات واجهة برمجة التطبيقات (API) تلقائيًا من مخطط. يمكنك توجيهها إلى تعريف OpenAPI أو GraphQL، وتقوم ببناء حالات الاختبار من الأنواع والتنسيقات والقيود التي أعلنتها بالفعل. وهي مبنية على Hypothesis، مكتبة اختبار الخصائص لبايثون، ويتم توزيعها بموجب ترخيص MIT.
الفكرة الأساسية بسيطة. تصف مواصفاتك بالفعل كيف يبدو الطلب والاستجابة الصالحان. يعامل Schemathesis هذا الوصف كمصدر للحقيقة ويتحقق مما إذا كانت واجهة برمجة التطبيقات (API) قيد التشغيل تلتزم به بالفعل. عندما تعيد واجهة برمجة التطبيقات خطأ 500، أو ترسل استجابة تنتهك المخطط المعلن، أو تقبل إدخالًا كان ينبغي رفضه، يقوم Schemathesis بوضع علامة عليه.
يمكنك تشغيله من سطر الأوامر باستخدام schemathesis run (أو الاختصار الأقصر st run). يوجد أيضًا تكامل مع بايثون إذا كنت ترغب في تشغيله من pytest بدلاً من واجهة سطر الأوامر. تبدأ معظم الفرق بواجهة سطر الأوامر لأنها لا تتطلب أي إعداد تقريبًا.
ماذا يعني اختبار الأتمتة المستند إلى الخصائص
معظم اختبارات واجهة برمجة التطبيقات (API) تعتمد على الأمثلة. تكتب طلبًا، وتتحقق من استجابة معينة، وينجح الاختبار أو يفشل في تلك الحالة الواحدة. هذا مفيد، ولكنك لا تكتشف إلا الأخطاء التي فكرت في كتابة اختبار لها.
يقلب اختبار الأتمتة المستند إلى الخصائص (Property-based testing) هذا النهج. فبدلاً من مثال واحد ثابت، تصف خاصية يجب أن تتحقق دائمًا، ثم تترك الأداة تولد مئات المدخلات لمحاولة كسرها. بالنسبة لـ Schemathesis، الخاصية هي تقريبًا: "يجب ألا يؤدي أي طلب صالح أبدًا إلى تعطل الخادم أو إنتاج استجابة تنتهك المخطط".
يولد Schemathesis المدخلات من القيود الموجودة في مواصفاتك. إذا كان الحقل عددًا صحيحًا بحد أدنى 1، فسيحاول 1، وأرقامًا كبيرة، وقيمًا حدية، وأنواع المدخلات التي تتسبب في فشل التحقق البسيط. عندما يفشل اختبار، يقوم Hypothesis بتقليص الإدخال إلى أصغر حالة لا تزال تعيد إنتاج الخطأ، بحيث تحصل على إعادة إنتاج بسيطة وقابلة للقراءة بدلاً من حمولة عشوائية بحجم 4 كيلوبايت.
هذا يختلف عن اختبار القرد (Monkey Testing)، الذي يلقي مدخلات عشوائية على واجهة لمعرفة ما سيفشل. اختبار الأتمتة المستند إلى الخصائص منظم. يستخدم المخطط لتوليد مدخلات معقولة ومستهدفة، ويعرف كيف تبدو النتيجة الصحيحة لأن المواصفات أخبرته بذلك.
تثبيت وتشغيل Schemathesis
Schemathesis هي حزمة بايثون، لذا تحتاج إلى بايثون 3 و pip. قم بتثبيتها بالطريقة المعتادة:
pip install schemathesis
يمكنك أيضًا تشغيله بدون تثبيت دائم باستخدام uvx schemathesis إذا كان لديك uv مثبتًا. بمجرد التثبيت، يشير الأمر الأساسي إلى مخطط وعنوان URL أساسي:
st run http://127.0.0.1:8000/openapi.json
إذا كان مخططك موجودًا على القرص بدلاً من عنوان URL، فمرر مسار الملف وأخبر Schemathesis بمكان وجود واجهة برمجة التطبيقات (API) المباشرة:
st run ./openapi.yaml --url http://127.0.0.1:8000
لواجهة برمجة تطبيقات مصادق عليها، أضف رأسًا:
st run http://127.0.0.1:8000/openapi.json \
--header 'Authorization: Bearer your-token'
يكتشف Schemathesis كل عملية في المواصفات، ويولد حالات لكل منها، ويطبع ملخصًا للاختبارات التي نجحت وتلك التي فشلت. تأتي حالات الفشل مع الطلب الدقيق الذي أرسله، بحيث يمكنك إعادة تشغيلها باستخدام curl أو في أي عميل API. تتغير أسماء العلامات والافتراضيات بين الإصدارات الرئيسية، لذا تحقق من st run --help مقابل الإصدار المثبت لديك بدلاً من الثقة بمقتطف مدونة، بما في ذلك هذا.
ما الذي يكتشفه Schemathesis
تستهدف الفحوصات الافتراضية الفجوة بين ما تعد به مواصفاتك وما يفعله خادمك. إليك ما يميل إلى الظهور.
| المشكلة | كيف تبدو |
|---|---|
| أخطاء الخادم | طلب يؤدي إلى خطأ 500 بدلاً من استجابة 4xx معالجة أو استجابة صالحة |
| انتهاكات المخطط | لا يتطابق نص الاستجابة مع المخطط الذي أعلنته لرمز الحالة هذا |
| عدم تطابق رمز الحالة | تعيد واجهة برمجة التطبيقات رمز حالة لم يتم توثيقه في المواصفات أبدًا |
| انحراف نوع المحتوى | لا يتطابق نوع محتوى الاستجابة مع ما تعلن عنه المواصفات |
| أخطاء الحالة (Stateful bugs) | تعمل عملية بمفردها ولكنها تفشل داخل سير عمل واقعي متعدد الخطوات |
تستحق النقطة الأخيرة نظرة فاحصة. يمكن لـ Schemathesis تشغيل اختبارات الحالة (stateful tests)، حيث يربط العمليات معًا بناءً على الروابط في مواصفاتك، على سبيل المثال إنشاء مورد، ثم جلبه، ثم حذفه. الأخطاء التي تظهر فقط بالتسلسل، مثل مورد يبلغ عن حالة خاطئة بعد التحديث، يصعب العثور عليها باختبارات الطلب الفردي. تدفع مرحلة الحالة هذه التسلسلات كآلة حالة.
يمكنك توسيع السلوك الافتراضي باستخدام "hooks". الخطافات هي دوال بايثون تسمح لك بتخصيص توليد البيانات، وإضافة فحوصات خاصة بك، أو تصفية العمليات التي يتم اختبارها. هذه هي الطريقة التي تتكيف بها الفرق مع Schemathesis لواجهات برمجة التطبيقات ذات تدفقات المصادقة أو القيود غير الواضحة التي لا يمكن للمواصفات التعبير عنها.
متى تستخدم Schemathesis
يكسب Schemathesis مكانته عندما يكون لديك مواصفات OpenAPI أو GraphQL دقيقة بشكل معقول وترغب في تغطية واسعة ورخيصة للحالات الهامشية. إنه قوي في العثور على الأخطاء التي لن تكتب لها اختبارًا يدويًا أبدًا: المدخلات غير المعالجة، وأشكال الأخطاء غير الموثقة، والانحراف في العقد بين المواصفات والتنفيذ.
إنه مناسب بشكل جيد عندما:
- تحافظ على مواصفات OpenAPI وترغب في فرضها على الخادم الحقيقي.
- تقلق بشأن أخطاء 500 غير المعالجة وتريد طبقة اختبار عشوائي (fuzzing) في CI.
- تحتوي واجهة برمجة التطبيقات (API) الخاصة بك على سير عمل يعتمد على الحالة حيث يكون الترتيب مهمًا.
- يعمل فريقك بالفعل في بايثون ومرتاح لاستخدام
pipوpytest.
إنه أقل ملاءمة عندما تكون مواصفاتك ضعيفة أو قديمة، حيث يمكن لـ Schemathesis اختبار ما يصفه المخطط فقط. "قمامة تدخل، قمامة تخرج". كما أنه لن يحل محل اختباراتك الوظيفية القائمة على الأمثلة. معرفة أن نقطة نهاية لا تتعطل أبدًا ليست مثل معرفة أنها تعيد القيمة الصحيحة لإدخال معروف. أنت تريد كليهما.
Schemathesis و Apidog: مكان كل منهما
يحل Apidog و Schemathesis مشاكل مختلفة، ويعملان بشكل جيد جنبًا إلى جنب. Apidog هو منصة شاملة لتصميم واجهات برمجة التطبيقات وتصحيحها واختبارها وإنشاء نماذج وهمية لها وتوثيقها. Schemathesis هو أداة اختبار عشوائي (fuzzer) مركّزة قائمة على الخصائص. الصدق بشأن الحدود مهم هنا.
لا يقوم Apidog باختبار عشوائي قائم على الخصائص. أقرب ميزة له هي اختبار القرد (Monkey Testing)، الذي يرسل مدخلات عشوائية للكشف عن الأعطال. هذا مفيد، لكنه ليس مثل اختبار الأتمتة المستند إلى الخصائص والمدفوع بالمخطط. يولد Schemathesis المدخلات من قيود مواصفاتك ويتحقق من الاستجابات مقابل المخطط. لذا إذا كان الاختبار العشوائي القائم على الخصائص هو ما تحتاجه، فاستخدم Schemathesis، وليس Apidog.
حيث يتناسب Apidog هو بقية دورة الحياة حول عملية الاختبار العشوائي هذه.
| مرحلة سير العمل | Schemathesis | Apidog |
|---|---|---|
| الاختبار العشوائي القائم على الخصائص من المواصفات | نعم، ميزة أساسية | لا |
| تصميم واجهة برمجة التطبيقات المرئي وتحرير المواصفات | لا | نعم |
| الاختبارات الوظيفية القائمة على الأمثلة | محدودة | نعم، منشئ اختبار مرئي |
| اختبار العقود مقابل المواصفات | جزئي، عبر فحوصات المخطط | نعم، سير عمل مخصص |
| خوادم وهمية من مخطط | لا | نعم، محاكاة ذكية |
| مشغل اختبار CI | نعم، st run |
نعم، apidog run |
| توثيق تلقائي التوليد | لا | نعم |
يبدو الاقتران العملي هكذا. تقوم بتصميم المواصفات وصيانتها في Apidog، وتوليد حالات اختبار وظيفية وخادم وهمي منها، وتشغيلها في CI باستخدام apidog run. ثم تضيف تمريرة Schemathesis التي تقوم باختبار عشوائي لنفس المواصفات بحثًا عن الأعطال في الحالات الهامشية وانتهاكات العقود. تلتقط الطبقتان فئات مختلفة من الأخطاء. يؤكد Apidog أن واجهة برمجة التطبيقات تقوم بالشيء الصحيح للحالات المعروفة؛ بينما يبحث Schemathesis عن الحالات غير المعروفة التي تعطلها.
إذا كان هدفك هو تحويل المواصفات إلى مجموعة وظيفية قابلة للتشغيل بدلاً من عملية اختبار عشوائي، فيمكن لـ Apidog توليد مجموعات اختبار API مباشرةً من مواصفات OpenAPI الخاصة بك، ويمكنك تنزيل Apidog لتجربة هذا السير.
الأسئلة المتكررة
هل Schemathesis مجاني؟
نعم. Schemathesis مفتوح المصدر بموجب ترخيص MIT، وواجهة سطر الأوامر (CLI) مجانية للتثبيت والتشغيل عبر pip install schemathesis. يوجد أيضًا عرض تجاري مستضاف للفرق التي ترغب في تجربة مُدارة، لكن الأداة الأساسية التي تشغلها محليًا وفي CI لا تكلف شيئًا.
ما الفرق بين schemathesis run و st run؟
إنهما نفس الأمر. st هو اختصار لـ schemathesis، لذا فإن st run و schemathesis run يقومان بنفس الشيء تمامًا. استخدم أيهما تفضل. كلاهما يأخذ مسار مخطط أو عنوان URL بالإضافة إلى خيارات مثل --url و --header.
هل يمكن لـ Schemathesis أن يحل محل اختبارات API الوظيفية الخاصة بي؟
لا، وليس الغرض منه ذلك. يتحقق Schemathesis من أن واجهة برمجة التطبيقات (API) الخاصة بك لا تتعطل وأن الاستجابات تتطابق مع المخطط. إنه لا يتحقق من منطق العمل، مثل ما إذا كان حساب الخصم صحيحًا. لا يزال يتعين عليك استخدام الاختبار الوظيفي القائم على الأمثلة واختبار العقود لذلك، والذي يمكنك بناؤه وتشغيله في Apidog. تعامل مع Schemathesis كطبقة اختبار عشوائي إضافية، وليس بديلاً.
هل يعمل Schemathesis مع GraphQL؟
نعم. يدعم Schemathesis كلاً من مخططات OpenAPI و GraphQL. بالنسبة لـ GraphQL، فإنه يولد استعلامات من تعريفات أنواع المخطط ويتحقق من الاستجابات بنفس الطريقة التي يفعلها لواجهات برمجة تطبيقات REST المعرفة في OpenAPI.
الخلاصة
Schemathesis أداة دقيقة لمهمة واحدة: أخذ مواصفات OpenAPI أو GraphQL الخاصة بك واختبار واجهة برمجة التطبيقات (API) الحية الخاصة بك ضدها باستخدام توليد قائم على الخصائص. يكتشف الأعطال وانتهاكات العقود التي تفوتها الاختبارات القائمة على الأمثلة، ولا يكلفك شيئًا تقريبًا لإضافته إلى CI. ما لا يفعله هو تصميم، أو محاكاة، أو توثيق، أو التحقق من منطق العمل.
هنا يكمل Apidog دوره. قم بتصميم المواصفات، وتوليد الاختبارات الوظيفية والمحاكاة، وتشغيلها في CI باستخدام apidog run، وتوثيق النتيجة، كل ذلك في مكان واحد، ثم ضع Schemathesis في الأعلى للاختبار العشوائي. حمل Apidog لبناء جانب التصميم والوظيفية من سير العمل هذا، ودع Schemathesis يتعامل مع البحث عن الحالات الهامشية.