مقدمة
@powerduck/openapi-cli أداة سطر أوامر تختبر مستند OpenAPI 3.2 على دفعات مقابل خادم فعلي. حدّد ملف مواصفات أو عنوان URL، وستنفّذ الأداة عمليات المستند، وتتحقق من كل استجابة باستخدام التأكيدات، وتنتج تقارير بثلاث صيغ.
تعتمد على @powerduck/openapi-request لتنفيذ الطلبات، وعلى @powerduck/openapi-parser لحل مراجع $ref.
لماذا تستخدم openapi-cli؟
- جاهزة للتكامل المستمر — افتراضيًا، يشير رمز خروج غير صفري إلى فشل اختبار أو خطأ تنفيذ، مما يتيح دمج الأداة مباشرة في GitHub Actions أو GitLab CI أو أي مسار عمل آخر.
- دعم مدمج لعدة بروتوكولات — يمكن لمواصفات واحدة وصف عمليات HTTP وSSE وWebSocket وGraphQL وgRPC وMCP، ويتعامل معها المشغّل نفسه.
- أسلوبان للتحقق — مصفوفات
x-testsالتصريحية للفحوص البسيطة، وبرامج نصية بأسلوب Postman تستخدمpm.test()/pm.expect()للحالات المعقدة. - ثلاث صيغ للتقارير — JSON قابل للمعالجة آليًا، ومخرجات CLI ملوّنة سهلة القراءة، وتقرير HTML تفاعلي مستقل.
- مواصفات محلية أو بعيدة — تحميل المستند من مسار ملف أو عنوان
http(s)://، مع اتباع إعادة التوجيه وفرض مهلة زمنية. - تصفية مرنة — اختيار العمليات حسب الطريقة أو المسار أو الوسم أو operationId، مع تحديد عدد العمليات المتزامنة.
البروتوكولات المدعومة
يتعرف المشغّل على بروتوكول كل عملية من امتدادات OpenAPI أو أنواع محتوى الاستجابات:
| البروتوكول | المعرّف | طريقة الاختيار |
|---|---|---|
| HTTP | http | الافتراضي للعمليات القياسية |
| الأحداث المرسلة من الخادم | sse | نوع محتوى الاستجابة text/event-stream أو x-response-stream: true |
| WebSocket | websocket | x-protocol: "websocket" |
| GraphQL | graphql | x-protocol: "graphql" |
| gRPC | grpc | x-protocol: "grpc" |
| MCP | mcp | x-protocol: "mcp" |
يمكن أيضًا تحديد البروتوكول صراحةً باستخدام الامتداد x-protocol على العملية أو عنصر المسار.
التقارير
بعد التشغيل، تنتج الأداة المخرجات التالية، وتُحفظ الملفات افتراضيًا في ./openapi-cli-report:
report.json— كائنTestReportكامل بصيغة JSON منسقة للقراءة.report.html— تقرير HTML مستقل بلا تبعيات، مع شريط ملخص وشريط تقدم وأزرار تصفية وصفوف اختبارات قابلة للتوسيع.- المخرجات القياسية — ملخص CLI ملوّن يتضمن شريط تقدم وتأكيدات كل اختبار.
الاستخدام من داخل الشيفرة
يتوفر مسار العمل نفسه كمكتبة. حُلّ الإعدادات، وشغّل الاختبارات، ثم اختر مولّدات التقارير المطلوبة:
import { resolveConfig, runTests, printCliReport, generateJsonReport } from "@powerduck/openapi-cli";
const config = resolveConfig({ spec: "./openapi.json" });
const report = await runTests(config);
printCliReport(report);
generateJsonReport(report, "./reports");