Tavern إضافة مفيدة لـ pytest: تكتب اختبار API في ملف YAML، ثم تشغّله كاختبار pytest عادي. إذا كان فريقك يستخدم Python يوميًا، فهذا يعني أنك تحصل على fixtures، وplugins، وpytest-xdist، والتقارير، ونفس أوامر CI التي تستخدمها بالفعل.

جرّب Apidog اليوم

لكن المشكلة تبدأ عندما يكبر ملف YAML. اختبار بسيط يرسل طلبًا، يحفظ token، ويتحقق من الاستجابة يمكن أن يتحول بسرعة إلى كتل متداخلة من request وresponse وsave وverify_response_with. ومع تدفقات مثل تسجيل الدخول، إنشاء مورد، قراءته، ثم حذفه، تصبح المسافات البادئة في YAML جزءًا من عبء الصيانة. والأسوأ أن عقد API غالبًا يعيش في مكان آخر: OpenAPI، Swagger، wiki، أو مجموعة Postman قديمة.

ما الذي يقدمه Tavern جيدًا؟

ابدأ بـ Tavern إذا كان فريقك يعمل بالفعل داخل pytest وتريد اختبار API قريبًا من اختبارات Python الحالية.

1. التثبيت والتشغيل داخل pytest

ثبّت Tavern:

pip install tavern

ثم أضف ملفًا مثل:

tests/test_orders.tavern.yaml

وشغّله بالطريقة المعتادة:

pytest

يمكنك استخدام نفس خيارات pytest:

pytest -k orders
pytest -x
pytest -n auto

هذا مفيد إذا كنت تعتمد على أدوات مثل:

• pytest-html للتقارير
• pytest-xdist للتشغيل المتوازي
• fixtures للإعداد المشترك
• JUnit reports داخل CI

2. اختبار API بسيط بصيغة YAML

مثال Tavern واضح عندما يكون الاختبار صغيرًا:

test_name: Get a single order

stages:
  - name: Fetch order 1042
    request:
      url: https://api.shop.test/orders/1042
      method: GET
    response:
      status_code: 200
      json:
        id: 1042
        status: shipped

الطلب والاستجابة المتوقعة في نفس المكان. لا تحتاج إلى كتابة كود Python باستخدام requests وassert لاختبار بسيط.

3. حفظ القيم واستخدامها في خطوات لاحقة

يمكنك استخراج قيمة من استجابة واستخدامها في طلب لاحق عبر save و{variable}:

stages:
  - name: Log in
    request:
      url: https://api.shop.test/auth/login
      method: POST
      json:
        username: tester
        password: hunter2
    response:
      status_code: 200
      save:
        json:
          token: access_token

  - name: Read the profile with the saved token
    request:
      url: https://api.shop.test/me
      method: GET
      headers:
        Authorization: "Bearer {token}"
    response:
      status_code: 200

هذا مناسب لتدفقات مثل:

1. تسجيل الدخول
2. حفظ access_token
3. استدعاء endpoint محمي
4. التحقق من الاستجابة

4. يدعم HTTP وMQTT

Tavern لا يقتصر على HTTP. يمكنه أيضًا اختبار MQTT، وهذا مهم إذا كنت تعمل مع IoT أو أنظمة مبنية على الرسائل. وبما أنه يعمل فوق pytest، يمكنك تشغيل اختبارات YAML واختبارات Python في نفس الـ pipeline.

أين تصبح YAML عبئًا؟

Tavern قوي، لكن نموذج YAML له تكلفة واضحة عندما تكبر مجموعة الاختبارات.

1. المسافات البادئة تصبح نقطة فشل

اختبار واقعي قد يحتوي على:

• headers
• query params
• request body
• response assertions
• type checks
• saved variables
• دوال verify_response_with

ومع كل مستوى جديد، يزيد احتمال خطأ indentation:

response:
  status_code: 200
  json:
    user:
      id: 123
      profile:
        email: test@example.com

خطأ مسافة واحدة قد يسبب فشل parsing بدل رسالة واضحة عن فشل API.

2. الاختبار والعقد منفصلان

ملف Tavern يحتوي على URL والطريقة والحقول المتوقعة. لكن تعريف API الحقيقي قد يكون في:

• ملف OpenAPI
• Swagger
• كود backend
• wiki
• مجموعة Postman

إذا تغير اسم حقل في API، لا يوجد رابط مباشر يخبر Tavern بذلك. يجب تحديث الاختبار يدويًا. وإلا ستظهر المشكلة لاحقًا في CI، أو يبقى الاختبار يثبت سلوكًا قديمًا.

3. يفترض أن الفريق يعرف Python وpytest

Tavern مناسب للمطورين المعتادين على Python. لكن إذا أراد QA أو frontend engineer أو product engineer قراءة اختبار أو تعديله، سيحتاج إلى فهم:

• pip
• virtualenv
• pytest conventions
• Tavern YAML schema

وهذا يجعل المساهمة أصعب لغير فريق Python.

المسار العملي لتجاوز YAML

بدل كتابة الاختبارات كملفات نصية منفصلة، يمكنك بناء الاختبارات مباشرة فوق تعريف API.

في Apidog، مواصفات API والطلب والاختبار مرتبطة بنفس الكائن. يمكنك استيراد أو تصميم API مرة واحدة باستخدام OpenAPI أو Swagger أو Postman، ثم بناء سيناريو اختبار من endpoints الموجودة.

الفكرة العملية:

1. استورد مواصفات API.
2. اختر endpoint تسجيل الدخول.
3. احفظ token من الاستجابة.
4. مرّر token إلى endpoint آخر.
5. أضف assertions من الواجهة بدل كتابة YAML يدويًا.
6. شغّل السيناريو من CLI داخل CI.

الميزة هنا أن المواصفات تصبح مصدر الحقيقة. عند تغيير حقل في التصميم، يظهر أثر التغيير على الاختبارات التي تعتمد عليه بدل وجود ملف YAML منفصل يحتاج تحديثًا يدويًا.

وعند الحاجة للتشغيل بدون واجهة، يستخدم Apidog CLI نفس السيناريوهات من سطر الأوامر، مثلما يشغّل pytest ملفات Tavern. راجع: Apidog CLI.

تثبيت وتشغيل Apidog CLI

Apidog CLI حزمة npm اسمها apidog-cli.

ثبّتها عالميًا:

npm install -g apidog-cli

ثم شغّل سيناريو اختبار:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli

شرح الخيارات:

• --access-token: يوثّق التشغيل مقابل حساب Apidog. خزّنه كـ secret في CI، ولا تكتبه داخل المستودع.
• -t: معرف سيناريو الاختبار.
• -e: معرف البيئة، مثل development أو staging أو production.
• -r: نوع التقرير. cli يطبع النتيجة في الطرفية.

إذا كنت لا تريد تثبيت الحزمة عالميًا، استخدم npx:

npx apidog-cli run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli

يدعم CLI عدة reporters:

• cli
• html
• json
• junit

في CI، استخدم غالبًا:

-r html,junit

مثال مع مجلد تقارير مخصص:

apidog run \
  --access-token $APIDOG_ACCESS_TOKEN \
  -t 605067 \
  -e 1629989 \
  -r html,junit \
  --out-dir ./apidog-reports

ولمعرفة كل الخيارات المتاحة في نسختك:

apidog run --help

مقارنة سريعة

استخدم Tavern إذا كان فريقك Python-first وتريد الاختبارات داخل نفس مستودع pytest. استخدم Apidog إذا كان هدفك تقليل صيانة YAML، وربط الاختبار بالمواصفات، والسماح لأكثر من دور في الفريق بالمساهمة في اختبارات API.

ربط Apidog CLI مع GitHub Actions

التشغيل داخل CI يجب أن يفشل build عند فشل أي assertion. مثال GitHub Actions:

name: API tests
on: [push, pull_request]

jobs:
  api-tests:
    runs-on: ubuntu-latest
    steps:
      - name: Install Apidog CLI
        run: npm install -g apidog-cli

      - name: Run API test scenario
        run: |
          apidog run \
            --access-token "$APIDOG_ACCESS_TOKEN" \
            -t 605067 \
            -e 1629989 \
            -r html,junit \
            --out-dir apidog-reports
        env:
          APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}

      - name: Upload report
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: apidog-report
          path: apidog-reports

نقاط مهمة في هذا الإعداد:

• خزّن APIDOG_ACCESS_TOKEN في GitHub Secrets.
• استخدم if: always() لرفع التقرير حتى عند فشل الاختبارات.
• إذا فشل assertion، يخرج apidog run برمز غير صفري.
• رمز الخروج غير الصفري يجعل خطوة CI تفشل، وبالتالي يفشل Pull Request check.

هذا هو نفس مبدأ Tavern مع pytest: CI يقرأ exit code، وأي خروج غير صفري يمنع الدمج أو النشر.

لإعدادات أكثر تفصيلًا، راجع:

• Apidog CLI في خط أنابيب CI/CD الخاص بك
• دليل GitHub Actions

هل يعني هذا ترك pytest؟

لا. يمكن للفريق الاحتفاظ باختبارات الوحدة والتكامل المكتوبة بـ Python داخل pytest، واستخدام Apidog لاختبارات عقد API التي تحتاج أن تبقى مرتبطة بالمواصفات.

تقسيم عملي شائع:

• pytest: unit tests وintegration tests القريبة من كود Python.
• Apidog: API contract tests، سيناريوهات end-to-end، وتشغيل CI لواجهات API.

إذا كنت تقارن أيضًا أدوات تشغيل أخرى، راجع:

• مقارنة Postman CLI و Newman
• اختبار API بدون Postman

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

هل Apidog CLI مجاني؟

نعم. حزمة npm apidog-cli مجانية للتثبيت والتشغيل:

npm install -g apidog-cli

هي تشغّل سيناريوهات الاختبار من مشروع Apidog الخاص بك. ما يمكنك تشغيله يعتمد على خطة Apidog، لكن CLI نفسه ليس منتجًا مدفوعًا منفصلًا.

هل يمكن تشغيل pytest وApidog معًا؟

نعم. استخدم pytest لاختبارات Python، واستخدم Apidog لاختبارات API المبنية على المواصفات. لا يوجد تعارض بينهما داخل CI.

كيف يمنع Apidog دمج كود سيئ؟

عبر exit code. إذا فشل أي assertion، يخرج الأمر:

apidog run

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

أي reporter أستخدم في CI؟

استخدم junit لكي تفهم لوحة CI النتائج، وأضف html إذا أردت تقريرًا قابلًا للتصفح:

-r html,junit

يمكنك أيضًا استخدام cli للحصول على مخرجات مباشرة في build logs.

هل Apidog يختبر HTTP فقط؟

لا. يدعم Apidog HTTP بالإضافة إلى SOAP وWebSocket وServer-Sent Events وgRPC. أما Tavern فيدعم HTTP وMQTT، لذلك إذا كان MQTT جزءًا أساسيًا من مكدسك، ضع ذلك في الحسبان.

الخلاصة

Tavern خيار جيد إذا كان فريقك يعيش داخل pytest ويريد كتابة اختبارات API بصيغة YAML. قوته الأساسية هي تكامله الطبيعي مع pytest.

لكن مع نمو الاختبارات، تصبح YAML نفسها عبئًا: nesting عميق، حساسية للمسافات، وعقد API منفصل يحتاج مزامنة يدوية.

إذا أردت تشغيلًا بدون واجهة داخل CI، مع تقارير، وexit codes واضحة، لكن دون صيانة ملفات YAML منفصلة عن مواصفات API، فبناء الاختبارات فوق العقد وتشغيلها عبر:

apidog run

هو المسار الأبسط.

قم بتنزيل Apidog واستورد API موجودًا لتجربة سير عمل تكون فيه المواصفات هي أساس الاختبار.