من PRD إلى حلقة الاختبار: سير عمل وكيل شامل باستخدام Apidog CLI

هذه سلسلة من 10 أجزاء تشارك كيف طوّرت Apidog Apidog CLI، وهي أداة سطر أوامر لاختبار واجهات برمجة التطبيقات وإدارة دورة حياة واجهة برمجة التطبيقات. اقرأ بالترتيب أو انتقل إلى أي منشور يثير اهتمامك:

مرر على مثال واقعي: يمتلك فريق PRD لاسترداد الطلبات وقاعدة كود. شاهد كيف يستخدم وكيل Apidog CLI + SKILL لإنشاء OpenAPI، وإنشاء الاختبارات، والتحقق، والمراجعة - من البداية إلى النهاية.

السيناريو

لنجعل كل شيء ملموسًا بسير عمل حقيقي.

السياق:

لقد انتهى فريق للتو من كتابة PRD "استرداد الطلب". تحتوي قاعدة الكود بالفعل على مسارات ووحدات تحكم (controllers) مطابقة.

طلب المستخدم من الوكيل:

"أنشئ اختبارات API لوظيفة الاسترداد بناءً على PRD وقاعدة الكود، ثم قم بتشغيل التحقق."

مشكلة النهج القديم

باستخدام أدوات MCP، يواجه الوكيل سلسلة من المعضلات:

يبذل الوكيل جهدًا كبيرًا لمجرد تحديد المسار - وليس تنفيذ المهمة.

مسار CLI + SKILL

تُرضي CLI + SKILL تدفقات البحث والتطوير الحقيقية بتسلسل واضح:

إنشاء OpenAPI من PRD وقاعدة الكود
        ↓
الاستيراد إلى Apidog
        ↓
إضافة حالات اختبار نقطة نهاية واحدة
        ↓
التحقق قبل الكتابة
        ↓
إنشاء سيناريو اختبار لتدفق الأعمال
        ↓
التحقق قبل الكتابة
        ↓
تشغيل الاختبارات الآلية

دعنا نمر على كل خطوة.

الخطوة 1: إنشاء واستيراد OpenAPI

يقرأ الوكيل PRD وقاعدة الكود، ثم ينشئ مواصفات OpenAPI.

مقتطف من PRD:

Order Refund API (واجهة برمجة تطبيقات استرداد الطلب)

POST /api/orders/{orderId}/refund
- Request body: { "reason": string, "amount": number } (جسم الطلب: { "السبب": نص، "المبلغ": رقم })
- Response: { "refundId": string, "status": string, "processedAt": datetime } (الاستجابة: { "معرف_الاسترداد": نص، "الحالة": نص، " "تاريخ_المعالجة": تاريخ ووقت })

GET /api/orders/{orderId}/refund/{refundId}
- Response: { "refundId": string, "status": string, "amount": number } (الاستجابة: { "معرف_الاسترداد": نص، "الحالة": نص، "المبلغ": رقم })

الوكيل ينشئ OpenAPI:

{
  "openapi": "3.0.0",
  "paths": {
    "/api/orders/{orderId}/refund": {
      "post": {
        "summary": "Create refund request", (ملخص: "إنشاء طلب استرداد")
        "parameters": [...],
        "requestBody": {...},
        "responses": {...}
      }
    },
    "/api/orders/{orderId}/refund/{refundId}": {
      "get": {
        "summary": "Get refund status", (ملخص: "الحصول على حالة الاسترداد")
        ...
      }
    }
  }
}

الاستيراد إلى Apidog:

apidog import --project <projectId> --format openapi --file ./openapi.json

مخرجات CLI:

{
  "success": true,
  "data": {
    "importedEndpoints": ["POST /refund", "GET /refund/{refundId}"], (نقاط النهاية المستوردة)
    "endpointIds": ["ep-001", "ep-002"] (معرفات نقاط النهاية)
  },
  "agentHints": {
    "summary": "OpenAPI imported successfully. 2 endpoints created.", (ملخص: "تم استيراد OpenAPI بنجاح. تم إنشاء نقطتي نهاية.")
    "nextSteps": [
      "List the imported endpoints to confirm structure.", (اطلب نقاط النهاية المستوردة لتأكيد الهيكل.)
      "Add test cases for each endpoint.", (أضف حالات اختبار لكل نقطة نهاية.)
      "Create a test scenario for the complete refund flow." (أنشئ سيناريو اختبار لتدفق الاسترداد الكامل.)
    ]
  }
}

الخطوة 2: حالات اختبار نقطة نهاية واحدة

يركز الوكيل على "نقطة نهاية الاسترداد" أولاً.

الوكيل يقرأ نقطة النهاية:

apidog endpoint get ep-001 --project <projectId>

CLI تعيد هيكل نقطة النهاية:

{
  "id": "ep-001",
  "method": "POST",
  "path": "/api/orders/{orderId}/refund",
  "requestBody": {
    "schema": {
      "type": "object",
      "properties": {
        "reason": { "type": "string" }, (السبب: نص)
        "amount": { "type": "number" } (المبلغ: رقم)
      },
      "required": ["reason", "amount"] (مطلوب: ["السبب", "المبلغ"])
    }
  },
  "responses": {
    "200": {...}
  }
}

الوكيل ينشئ حالة اختبار:

{
  "name": "Create refund - success", (الاسم: "إنشاء استرداد - نجاح")
  "endpointId": "ep-001",
  "request": {
    "path": "/api/orders/order-123/refund",
    "body": {
      "reason": "Customer request", (السبب: "طلب العميل")
      "amount": 99.99
    }
  },
  "assertions": [
    {
      "subject": "responseJson.status", (الموضوع: "responseJson.status")
      "comparator": "equal", (المقارن: "يساوي")
      "target": "processed" (الهدف: "تمت المعالجة")
    }
  ]
}

التحقق قبل الكتابة:

apidog cli-schema validate test-case-create --file ./test-case-create.json

نتيجة تحقق CLI:

{
  "success": true,
  "agentHints": {
    "summary": "Test case structure is valid.", (ملخص: "هيكل حالة الاختبار صالح.")
    "nextSteps": [
      "Create the test case in Apidog.", (أنشئ حالة الاختبار في Apidog.)
      "Read back the created test case to confirm.", (اقرأ حالة الاختبار التي تم إنشاؤها للتأكيد.)
      "Add more assertions if needed." (أضف المزيد من التأكيدات إذا لزم الأمر.)
    ]
  }
}

إنشاء حالة اختبار:

apidog test-case create --project <projectId> --file ./test-case-create.json

مخرجات CLI:

{
  "success": true,
  "data": {
    "id": "tc-001",
    "name": "Create refund - success" (الاسم: "إنشاء استرداد - نجاح")
  },
  "agentHints": {
    "summary": "Test case created successfully.", (ملخص: "تم إنشاء حالة الاختبار بنجاح.")
    "nextSteps": [
      "Read back test case tc-001 to confirm assertions.", (اقرأ حالة الاختبار tc-001 للتأكد من التأكيدات.)
      "Create test case for GET /refund/{refundId}.", (أنشئ حالة اختبار لـ GET /refund/{refundId}.)
      "Build test scenario for complete refund flow." (أنشئ سيناريو اختبار لتدفق الاسترداد الكامل.)
    ]
  }
}

الخطوة 3: سيناريو اختبار لتدفق كامل

بناءً على PRD، فإن تدفق الأعمال الكامل هو:

إنشاء طلب ← دفع ← استرداد ← الاستعلام عن حالة الاسترداد

الوكيل ينشئ سيناريو:

{
  "name": "Order Refund Complete Flow", (الاسم: "تدفق استرداد الطلب الكامل")
  "steps": [
    { "type": "case", "caseId": "tc-create-order" }, (النوع: "حالة"، معرف الحالة: "tc-create-order")
    { "type": "case", "caseId": "tc-pay" }, (النوع: "حالة"، معرف الحالة: "tc-pay")
    { "type": "case", "caseId": "tc-001" }, (النوع: "حالة"، معرف الحالة: "tc-001")
    { "type": "case", "caseId": "tc-get-refund" } (النوع: "حالة"، معرف الحالة: "tc-get-refund")
  ]
}

التحقق قبل الكتابة:

apidog cli-schema validate test-scenario-update --file ./scenario-update.json

إنشاء سيناريو:

apidog test-scenario create --project <projectId> --file ./scenario-update.json

الخطوة 4: تشغيل التحقق

بعد أن تصبح حالات الاختبار والسيناريوهات جاهزة:

apidog run --project <projectId> \
  --test-scenario scenario-001 \
  --environment env-production \
  -r "cli,html,junit" \
  --out-dir ./apidog-reports

مخرجات CLI:

{
  "success": true,
  "stats": {
    "total": 4, (الإجمالي: 4)
    "passed": 4, (اجتاز: 4)
    "failed": 0 (فشل: 0)
  },
  "reportFiles": {
    "cli": "./apidog-reports/cli-report.txt",
    "html": "./apidog-reports/report.html",
    "junit": "./apidog-reports/junit.xml"
  },
  "agentHints": {
    "summary": "All tests passed. 4 steps executed successfully.", (ملخص: "اجتازت جميع الاختبارات. تم تنفيذ 4 خطوات بنجاح.")
    "nextSteps": [
      "Review the HTML report for detailed results.", (راجع تقرير HTML للحصول على نتائج مفصلة.)
      "If failures occurred, debug using CLI error details.", (إذا حدثت إخفاقات، قم بالتصحيح باستخدام تفاصيل أخطاء CLI.)
      "Integrate this test into CI pipeline." (ادمج هذا الاختبار في خط أنابيب CI.)
    ]
  }
}

السلسلة الكاملة

جميع العناصر متصلة الآن:

كل شيء قابل للتحقق والتتبع.

agentHints عبر التدفق

لاحظ كيف يوجه agentHints كل انتقال:

لا يضطر الوكيل أبدًا إلى تخمين ما يجب فعله بعد ذلك.

مقارنة: MCP مقابل CLI + SKILL لهذه المهمة

ماذا بعد؟

يوضح هذا المثال العملي كيف تعمل CLI + SKILL في سير عمل حقيقي.

ولكن هناك أساس تحت كل هذا: توافق CI/CD.

في الجزء 8، لماذا لا يمكن التنازل عن توافق CI/CD لأدوات الوكيل، سنستكشف لماذا يخدم apidog run كلاً من خطوط أنابيب CI ووكلاء الذكاء الاصطناعي - ولماذا يهم هذا الغرض المزدوج لتصميم الأدوات المستدامة.

النقاط الرئيسية

• سير عمل كامل: PRD ← OpenAPI ← استيراد ← حالات الاختبار ← سيناريو ← تحقق
• كل خطوة تحتوي على أمر CLI + التحقق + agentHints
• خطوات الاستيراد + القراءة مرة أخرى أكثر أمانًا من كتابة السيناريوهات يدويًا
• --with-case-detail يعطي هيكلًا حقيقيًا للتحديثات
• agentHints يوجه كل انتقال
• كل شيء قابل للتحقق والتتبع

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