DEV Community

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

Posted on • Originally published at apidog.com

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

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

جرّب Apidog اليوم

العنوان التركيز
1 بنينا 126 أداة MCP. ولكنها ليست الحل الأفضل للوكيل اكتشاف المشكلة
2 لماذا طورنا Apidog CLI الجديدة كليًا تطوير المعمارية
3 القاعدة الذهبية: CLI تنتج الحقائق، والنموذج يعمل بناءً على الحقائق الفلسفة الأساسية
4 agentHints: تعليم CLIs التحدث إلى الوكلاء مخرجات منظمة
5 المهارة (SKILL): شحن الخبرة التشغيلية ككود الخبرة التشغيلية
6 الأرقام لا تكذب: 30% مكالمات أدوات أقل، 25% رموز أقل نتائج كمية
7 من PRD إلى حلقة الاختبار: سير عمل وكيل كامل مع Apidog CLI برنامج تعليمي عملي
8 لماذا لا يمكن التنازل عن توافق CI/CD لأدوات الوكيل منظور DevOps
9 فرع الذكاء الاصطناعي: تغييرات مشروع أكثر أمانًا مع وكلاء الذكاء الاصطناعي طبقة الأمان
10 "Spec-First" كان بالأمس. مرحبًا بك في "Skill-First". الرؤية والمستقبل

في هذا الجزء، سنمر على مثال تنفيذي كامل: لديك PRD لوظيفة استرداد الطلبات، وقاعدة كود تحتوي على المسارات وControllers. المطلوب من الوكيل هو إنشاء OpenAPI، استيراده إلى Apidog، إنشاء حالات اختبار، بناء سيناريو تدفق كامل، ثم تشغيل التحقق.

السيناريو

السياق العملي:

  • الفريق أنهى PRD بعنوان: Order Refund.
  • قاعدة الكود تحتوي بالفعل على المسارات وControllers الخاصة بالاسترداد.
  • المطلوب هو تحويل المتطلبات إلى اختبارات API قابلة للتشغيل.

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

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

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

عند استخدام أدوات MCP كثيرة، يبدأ الوكيل بسلسلة قرارات غير واضحة قبل أن ينفّذ المهمة فعليًا:

نقطة القرار مصدر عدم اليقين
هل يستعلم عن المشروع أولًا؟ أم ينشئ نقطة النهاية مباشرة؟
هل يكتب حالة الاختبار أولًا؟ أم ينشئ Schema أولًا؟
هل يشغّل الاختبارات مباشرة؟ أم يقرأ الموارد الحالية؟
أي أداة يستخدم لكل خطوة؟ البحث داخل 126 أداة

المشكلة ليست في تنفيذ الاختبار نفسه، بل في أن الوكيل يستهلك وقتًا كبيرًا لاختيار المسار الصحيح.

مسار CLI + SKILL

باستخدام CLI + SKILL، يصبح المسار العملي واضحًا:

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

الفكرة الأساسية: كل خطوة تنتج بيانات قابلة للتحقق، ثم يستخدمها الوكيل في الخطوة التالية بدل التخمين.

الخطوة 1: إنشاء OpenAPI من PRD وقاعدة الكود

يبدأ الوكيل بقراءة 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
  }
Enter fullscreen mode Exit fullscreen mode

مثال OpenAPI ناتج:

{
  "openapi": "3.0.0",
  "info": {
    "title": "Order Refund API",
    "version": "1.0.0"
  },
  "paths": {
    "/api/orders/{orderId}/refund": {
      "post": {
        "summary": "Create refund request",
        "parameters": [
          {
            "name": "orderId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["reason", "amount"],
                "properties": {
                  "reason": {
                    "type": "string"
                  },
                  "amount": {
                    "type": "number"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Refund created"
          }
        }
      }
    },
    "/api/orders/{orderId}/refund/{refundId}": {
      "get": {
        "summary": "Get refund status",
        "parameters": [
          {
            "name": "orderId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "refundId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Refund status"
          }
        }
      }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

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

apidog import --project <projectId> --format openapi --file ./openapi.json
Enter fullscreen mode Exit fullscreen mode

مثال مخرجات CLI:

{
  "success": true,
  "data": {
    "importedEndpoints": [
      "POST /api/orders/{orderId}/refund",
      "GET /api/orders/{orderId}/refund/{refundId}"
    ],
    "endpointIds": ["ep-001", "ep-002"]
  },
  "agentHints": {
    "summary": "OpenAPI imported successfully. 2 endpoints created.",
    "nextSteps": [
      "List the imported endpoints to confirm structure.",
      "Add test cases for each endpoint.",
      "Create a test scenario for the complete refund flow."
    ]
  }
}
Enter fullscreen mode Exit fullscreen mode

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

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

نبدأ بنقطة النهاية الخاصة بإنشاء طلب استرداد:

apidog endpoint get ep-001 --project <projectId>
Enter fullscreen mode Exit fullscreen mode

مثال بنية نقطة النهاية التي تعيدها 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": {}
  }
}
Enter fullscreen mode Exit fullscreen mode

الآن ينشئ الوكيل ملف حالة اختبار، مثلًا: test-case-create.json.

{
  "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",
      "comparator": "equal",
      "target": "processed"
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

قبل الكتابة إلى Apidog، يتم التحقق محليًا من بنية الملف:

apidog cli-schema validate test-case-create --file ./test-case-create.json
Enter fullscreen mode Exit fullscreen mode

مثال نتيجة التحقق:

{
  "success": true,
  "agentHints": {
    "summary": "Test case structure is valid.",
    "nextSteps": [
      "Create the test case in Apidog.",
      "Read back the created test case to confirm.",
      "Add more assertions if needed."
    ]
  }
}
Enter fullscreen mode Exit fullscreen mode

بعد نجاح التحقق، ينشئ الوكيل حالة الاختبار:

apidog test-case create --project <projectId> --file ./test-case-create.json
Enter fullscreen mode Exit fullscreen mode

مثال مخرجات الإنشاء:

{
  "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.",
      "Create test case for GET /refund/{refundId}.",
      "Build test scenario for complete refund flow."
    ]
  }
}
Enter fullscreen mode Exit fullscreen mode

أفضل ممارسة هنا: اقرأ حالة الاختبار بعد إنشائها للتأكد من أن البنية والتأكيدات محفوظة كما هو متوقع.

apidog test-case get tc-001 --project <projectId>
Enter fullscreen mode Exit fullscreen mode

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

حسب PRD، تدفق العمل الكامل هو:

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

ينشئ الوكيل ملف سيناريو مثل: scenario-update.json.

{
  "name": "Order Refund Complete Flow",
  "steps": [
    {
      "type": "case",
      "caseId": "tc-create-order"
    },
    {
      "type": "case",
      "caseId": "tc-pay"
    },
    {
      "type": "case",
      "caseId": "tc-001"
    },
    {
      "type": "case",
      "caseId": "tc-get-refund"
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

قبل إنشاء السيناريو، يتم التحقق من الملف:

apidog cli-schema validate test-scenario-update --file ./scenario-update.json
Enter fullscreen mode Exit fullscreen mode

ثم يتم إنشاء السيناريو:

apidog test-scenario create --project <projectId> --file ./scenario-update.json
Enter fullscreen mode Exit fullscreen mode

إذا احتاج الوكيل إلى تحديث سيناريو موجود، فالأكثر أمانًا هو قراءة السيناريو أولًا بتفاصيل الحالات ثم تحديثه:

apidog test-scenario get scenario-001 \
  --project <projectId> \
  --with-case-detail
Enter fullscreen mode Exit fullscreen mode

بهذا يحصل الوكيل على البنية الفعلية بدل تخمين شكل الخطوات.

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

بعد إنشاء حالات الاختبار والسيناريو، يتم تشغيل الاختبارات:

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

مثال مخرجات CLI:

{
  "success": true,
  "stats": {
    "total": 4,
    "passed": 4,
    "failed": 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.",
    "nextSteps": [
      "Review the HTML report for detailed results.",
      "If failures occurred, debug using CLI error details.",
      "Integrate this test into CI pipeline."
    ]
  }
}
Enter fullscreen mode Exit fullscreen mode

المخرجات المهمة للفريق:

  • تقرير CLI سريع للمراجعة داخل الطرفية.
  • تقرير HTML للمراجعة اليدوية.
  • تقرير JUnit مناسب لخطوط CI/CD.

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

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

العنصر الحالة
PRD تمت قراءته ومعالجته
قاعدة الكود تم تحليلها لاستخراج المسارات والمنطق المرتبط بها
OpenAPI تم إنشاؤها واستيرادها
أصول نقاط النهاية تم إنشاؤها في Apidog
اختبارات نقطة النهاية الواحدة تم إنشاؤها والتحقق منها
سيناريو العمل تم بناؤه والتحقق منه
تشغيل الاختبارات تم عبر CLI مع تقارير قابلة للاستخدام

النتيجة: كل خطوة قابلة للتحقق، وكل مورد له معرف واضح، وكل انتقال موجه بمخرجات CLI.

دور agentHints عبر التدفق

agentHints لا تنفذ المهمة بدل الوكيل، لكنها تقلل التخمين. بعد كل أمر، يحصل الوكيل على اقتراحات عملية للخطوة التالية.

بعد ما يقترحه agentHints
استيراد نقاط النهاية سرد نقاط النهاية، ثم إضافة حالات اختبار
إنشاء حالة اختبار قراءة الحالة مرة أخرى، إنشاء المزيد من الحالات، بناء سيناريو
إنشاء سيناريو إضافة تأكيدات، التحقق، ثم التشغيل
تشغيل الاختبارات مراجعة التقرير، تصحيح الأخطاء عند الحاجة، التكامل مع CI

بدل أن يسأل الوكيل "ماذا أفعل الآن؟"، يصبح لديه مسار واضح مبني على الحالة الحالية.

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

البعد نهج MCP نهج CLI + SKILL
نقطة البداية يبحث الوكيل عن أدوات المشروع تحدد SKILL نوع المهمة وتوجه التسلسل
إنشاء نقطة النهاية يخمن الوكيل الأداة والحقول استيراد OpenAPI عبر CLI
إنشاء حالة الاختبار محاولات متعددة بسبب أخطاء الحقول تحقق محلي قبل الكتابة
بناء السيناريو كتابة يدوية للبنية قراءة، تحديث، تحقق، ثم كتابة
تشغيل الاختبارات يبحث الوكيل عن أداة التشغيل المناسبة agentHints تقترح التشغيل بعد السيناريو
إجمالي الخطوات حوالي 20-25 استدعاء مع محاولات فاشلة حوالي 10-12 استدعاءً تم التحقق منها

ماذا بعد؟

هذا المثال يوضح كيف تعمل CLI + SKILL في سير عمل API حقيقي: من PRD إلى اختبار قابل للتشغيل.

لكن هناك أساس مهم يجعل هذا الأسلوب قابلًا للاستخدام داخل فرق التطوير: توافق CI/CD.

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

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

  • سير العمل الكامل هو: PRD ← OpenAPI ← استيراد ← حالات اختبار ← سيناريو ← تحقق.
  • لا تكتب مباشرة إلى المشروع قبل التحقق من JSON محليًا.
  • استخدم apidog endpoint get وapidog test-case get للقراءة مرة أخرى بعد الإنشاء.
  • استخدم --with-case-detail عند تحديث السيناريوهات للحصول على البنية الفعلية.
  • agentHints توجه انتقالات الوكيل وتقلل التخمين.
  • مخرجات apidog run قابلة للاستخدام محليًا وفي CI/CD.

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

Top comments (0)