أوامر سطر الأوامر Apidog و مهارات Claude: دمج اختبار API الآلي في سير عمل التطوير

توضح هذه المقالة كيفية دمج Apidog CLI مع مهارات Claude لبناء سير عمل فعال لـ اختبار أتمتة واجهة برمجة التطبيقات (API) المدفوع باللغة الطبيعية.

في سير العمل هذا، ما عليك سوى قول جملة واحدة لـ Claude Code في محطتك الطرفية، على سبيل المثال:

"شغّل اختبار تدفق طلب المستخدم في بيئة التطوير (dev)."

سيفهم Claude Code قصدك تلقائيًا، ويحدد سيناريو الاختبار أو مجموعة الاختبار المطابقة، وينفذ الاختبارات، ثم يلخص ويفسر النتائج لك.

نظرة عامة على الأدوات

يتكون سير العمل هذا من ثلاث أدوات:

1. Apidog CLI

واجهة سطر الأوامر التي يوفرها Apidog. تُستخدم لتنفيذ اختبارات أتمتة واجهة برمجة التطبيقات من الطرفية وتوليد تقارير الاختبار.

2. Claude Code

مساعد ذكاء اصطناعي لسطر الأوامر أصدرته Anthropic. يمكنه العمل على الملفات، وتشغيل الأوامر، وتنفيذ البرامج النصية، والتفاعل مع بيئة التطوير المحلية لديك.

3. مهارات Claude (Claude Skills)

تُعرف أيضًا باسم مهارات الوكيل (Agent Skills)، وهي آلية توسعة لـ Claude Code. تُعرّف المهارة كيف يجب على Claude إكمال مهمة محددة، وتعمل بشكل أساسي كمجموعة قابلة للتنفيذ من التعليمات التشغيلية.

في سير العمل هذا، يكون Claude Code مسؤولاً عن فهم تعليمات اللغة الطبيعية. عندما يتطابق طلب المستخدم مع مهارة Claude مُحددة مسبقًا، ينفذ Claude تلقائيًا أوامر Apidog CLI المقابلة ويحلل النتائج.

ما الذي يمكن أن يفعله سير العمل هذا

فيما يلي العديد من السيناريوهات الواقعية لتوضيح كيفية استخدام سير العمل هذا عمليًا.

تشغيل اختبار واحد

إذا كنت ترغب في تشغيل سيناريو اختبار محدد، يمكنك تسميته بوضوح. على سبيل المثال:

"شغّل اختبارات تسجيل الدخول في بيئة التطوير (dev)."

بعد اكتمال الاختبار، يحلل Claude النتائج ويقدم ملخصًا.

إدراج جميع الاختبارات المتاحة

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

"أرني الاختبارات المتاحة."

سينفذ Claude البرنامج النصي ذي الصلة ويسرد جميع الاختبارات.

تشغيل جميع الاختبارات لوحدة أعمال

إذا كنت ترغب في تنفيذ جميع الاختبارات لنطاق عمل محدد - مثل الاختبارات المتعلقة بالدفع - يمكنك أن تقول:

"شغّل جميع اختبارات الدفع في بيئة الاختبار (test env)."

سيحدد Claude تلقائيًا جميع ملفات الاختبار ذات الصلة وينفذها بالتتابع أو بالتوازي.

مقارنة نتائج الاختبار عبر البيئات

لمقارنة النتائج عبر البيئات، يمكنك أن تقول:

"شغّل اختبارات تسجيل الدخول في بيئة التطوير (dev) وبيئة الاختبار (test)."

سينفذ Claude الاختبارات في كلتا البيئتين ويحلل الاختلافات في النتائج.

تشغيل الاختبارات بناءً على تغييرات الكود

بعد تغييرات الكود، يمكنك أن تطلب من Claude تشغيل الاختبارات المتأثرة فقط:

"بناءً على تغييرات الكود الأخيرة، شغّل اختبارات API المتأثرة في بيئة التطوير (dev)."

سيحلل Claude تغييرات Git، ويحدد سيناريوهات الاختبار أو مجموعات الاختبار المتأثرة، وينفذ تلك الاختبارات فقط - مما يوفر الوقت والموارد.

المزيد من السيناريوهات تنتظرك لاستكشافها.

بعد ذلك، سنتناول كيفية تثبيت وتكوين Apidog CLI و Claude Code و Claude Skills، وكيفية دمجها في سير عمل كامل.

التحضير

متطلبات البيئة

تأكد من تثبيت Node.js على جهازك. تحقق من ذلك في محطتك الطرفية:

node -v
npm -v

تثبيت Apidog CLI (التثبيت عبر npm):

npm install -g apidog-cli

تحقق من التثبيت:

apidog --version

إذا تم عرض رقم إصدار، فقد نجح التثبيت.
يمكنك نسخ أمر CLI لـ سيناريو اختبار أو مجموعة اختبار من Apidog ← الاختبارات ← CI/CD، إضافة رمز الوصول (Access Token) الخاص بك، وتشغيله في الطرفية.

إذا ظهر مخرج الاختبار، فإن Apidog CLI يعمل بشكل صحيح.

تثبيت Claude

Code (التثبيت عبر npm):

npm install -g @anthropic-ai/claude-code

التحقق:

claude --version

عند التشغيل لأول مرة، تحتاج إلى تسجيل الدخول:

claude

اتبع خطوات التفويض. يتطلب حساب Claude. بعد تسجيل الدخول، ستدخل الواجهة التفاعلية ويمكنك طرح أسئلة أساسية.

في هذه المرحلة، لا يعرف Claude بعد كيفية تشغيل اختبارات Apidog. بعد ذلك، سنعلمه باستخدام مهارات Claude (Claude Skills).

بناء مهارات Claude (Claude Skills)

فهم كيفية عمل المهارات

عند استخدام Claude Code، لا تختار مهارة يدويًا. ما عليك سوى وصف ما تريد القيام به باللغة الطبيعية.

إذا تطابق طلبك مع وصف المهارة، يقوم Claude تلقائيًا بتحميل تلك المهارة وينفذ سير العمل المحدد.

الخطوة 1: إنشاء مجلد المهارة

توجد جميع تكوينات المهارات تحت المجلد .claude/skills/. كل مهارة لها مجلد فرعي خاص بها.

أنشئ مجلد مهارة مصغر لاختبار أتمتة Apidog في جذر المشروع:

mkdir -p .claude/skills/apidog-tests

التركيب الناتج:

.claude/skills/apidog-tests/

سنقوم تدريجيًا بإضافة ملفات الإدخال والبرامج النصية هنا.

الخطوة 2: إنشاء SKILL.md

تتطلب كل مهارة ملف SKILL.md يحدد كيف يجب على Claude تنفيذ المهمة بمجرد تشغيل المهارة.

يبدأ الملف ببيانات وصفية YAML محاطة بـ ---. حقلا name و description مطلوبان.

يُعد description مهمًا بشكل خاص - فهو يحدد متى يجب على Claude تفعيل هذه المهارة.

أسفل كتلة YAML، يُحدد محتوى Markdown منطق التنفيذ وقواعد القرار والبرامج النصية التي يجب استدعاؤها والقيود.

مثال SKILL.md لاختبار أتمتة Apidog

---
name: apidog-tests
description: ينفذ ويفسر اختبارات Apidog الآلية لواجهة برمجة التطبيقات (API) عبر Apidog CLI. قم بتشغيل هذه المهارة عندما يطلب المستخدم صراحةً تشغيل الاختبارات، حالات الاختبار، سيناريوهات الاختبار، أو مجموعات الاختبار، بما في ذلك طلبات تنفيذ الاختبارات في بيئة محددة مثل dev، test، أو prod، للتحقق من سلوك API بعد تغييرات الكود، لإجراء اختبار الانحدار أو ما قبل الإصدار، أو لتشغيل فحوصات API قبل git commit، push، أو merge. حتى لو لم يذكر المستخدم صراحة "Apidog" أو "API"، افترض أن هذه الطلبات تشير إلى اختبارات Apidog الآلية عندما يكون تنفيذ الاختبار ضمنيًا. يجب أن تختار المهارة سيناريو الاختبار أو مجموعة الاختبار المناسبة، وتنفذ الاختبارات، وتشرح النتائج دون تعديل تعريفات الاختبار أو الأوامر نفسها.
---

# اختبارات Apidog

ينفذ اختبارات Apidog الآلية ويفسر النتائج.

## سير العمل

1. **اختيار الاختبار**:

- إذا قدم المستخدم صراحة:
  - مسار ملف الاختبار
  - اسم ملف الاختبار
  - أو اسم اختبار واضح ومطابق بشكل فريد
- استخدم هذا الاختبار مباشرة دون اختيار تلقائي.
- إذا كانت المعلومات غير واضحة، فقم بإعطاء الأولوية لتشغيل البرنامج النصي `node ./.claude/skills/apidog-tests/scripts/list-tests.js` لاسترداد جميع مسارات ملفات الاختبار وأوصافها بسرعة.
- تجنب البحث الشامل الأعمى في أدلة المشاريع الكبيرة؛ بدلاً من ذلك، حدد دليل ملف الاختبار `./.claude/skills/apidog-tests/tests/` المخصص لهذه المهارة.

2. **قواعد تنفيذ الاختبار المتعددة**

- بشكل افتراضي، قم بتنفيذ اختبار واحد فقط، ولكن قدم خيار التنفيذ دفعة واحدة.
- إذا ذكر المستخدم صراحة:
  - "شغّل هذه القليلة"
  - "شغّلهم جميعًا"
- ادخل إلى **وضع التنفيذ دفعة واحدة**.

في وضع التنفيذ دفعة واحدة:
- ادرج بوضوح الاختبارات التي سيتم تنفيذها.
- **اطلب طريقة التنفيذ**: دع المستخدم يختار بين "التنفيذ المتسلسل" (قابلية قراءة أفضل) أو "التنفيذ المتوازي" (أسرع).
  - **التنفيذ المتسلسل**: تشغيل الاختبارات واحدًا تلو الآخر والتحليل فورًا، مناسب للتصحيح.
  - **التنفيذ المتوازي**: بدء عدة اختبارات في وقت واحد (باستخدام `&` أو برامج نصية متزامنة)، مناسب للانحدار السريع، على الرغم من أن السجلات قد تتداخل.
- اطلب تأكيد المستخدم لطريقة التنفيذ وقائمة الاختبارات (نعم / لا).
- نفذ الاختبارات وفقًا للطريقة المختارة.
- أخيرًا، لخص أو اشرح بشكل فردي نتائج كل اختبار.

3. **تأكيد البيئة**:
- البيئات المدعومة تشمل:
  - `dev` (تطوير)
  - `test` (اختبار)
  - `prod` (إنتاج)
- إذا لم يحدد المستخدم بيئة:
  - ادرج أسماء البيئات أعلاه.
  - اطلب من المستخدم تأكيد أي منها سيتم استخدامه.

4. **تنفيذ الاختبار**:
- نفذ الاختبار بمجرد أن تصبح المعلومات التالية واضحة:
  - مسار ملف الاختبار
  - اسم البيئة (dev / test / prod)
```bash
node ./.claude/skills/apidog-tests/scripts/run-cli.js <test_file_path> <env_name>
```

5. **تفسير النتائج**: حلل مخرج Apidog CLI واشرح أسباب الفشل.

## معالجة الفشل

- لا تعدل ملفات الاختبار.
- لا تعدل أوامر التنفيذ.
- اشرح أسباب الفشل بناءً على أسماء الاختبارات ودلالات API ومخرج CLI.

الخطوة 3: الملفات المساعدة

في الخطوات السابقة، أنشأنا ملف SKILL.md، والذي يحدد شروط التشغيل وسير العمل التنفيذي العام لهذه المهارة.

بناءً على هذا الأساس، تعمل جميع الملفات المتبقية فقط كمكونات مساعدة لـ SKILL.md. يتم تقديم ملفات إضافية عند الطلب، فقط عندما يتطلب سير العمل معلومات إضافية - مثل بيئات وقت التشغيل، أو أوامر التنفيذ، أو تعريفات الاختبار.

التركيب النهائي للمجلد:

.claude/skills/apidog-tests/
├── SKILL.md
├── env/
│   ├── dev.env
│   ├── test.env
│   └── prod.env
├── scripts/
│   ├── list-tests.js
│   └── run-cli.js
└── tests/
    ├── payment-flow.md
    └── refund-flow.md

فيما يلي، سنستعرض كل ملف مساعد، موضحين الغرض منه ومقدمين أمثلة.

تكوين البيئة (env)

يستخدم المجلد env/ لتخزين تكوينات متغيرات البيئة، مثل رمز الوصول Apidog (Apidog access token) و معرف البيئة (environment ID).

من خلال استخراج معرف البيئة إلى متغير، يمكننا التبديل بسرعة بين بيئة تنفيذ الاختبار (مثل التطوير، الاختبار، الإنتاج) دون تعديل أي أوامر أو برامج نصية.

على سبيل المثال، قم بإنشاء ملف dev.env تحت المجلد env/:

APIDOG_ACCESS_TOKEN=APS-your-access-token
APIDOG_ENV_ID=your-environment-id

إذا كانت هناك حاجة إلى بيئات متعددة، يمكنك إنشاء ملفات إضافية بنفس الطريقة:

• test.env
• prod.env
• …

يحتاج كل ملف فقط إلى الحفاظ على المتغيرات لبيئته المقابلة.

يتوافق معرف البيئة مع القيمة الرقمية التي يتم تمريرها إلى المعلمة -e في أمر Apidog CLI. كل بيئة تشغيل (مثل التطوير أو الاختبار أو الإنتاج) لها معرف بيئة فريد في Apidog.

برامج التنفيذ النصية (scripts)

يحتوي المجلد scripts/ على برامج نصية قابلة للتنفيذ مسؤولة عن تحويل تعريفات الاختبار إلى أوامر Apidog CLI قابلة للتشغيل فعليًا، وحقن متغيرات البيئة، وتنفيذ الاختبارات.

في هذه المهارة، تم اختيار Node.js لسببين رئيسيين:

1. يعتمد Apidog CLI نفسه على Node.jsإعادة استخدام نفس وقت التشغيل يتجنب الحاجة إلى تثبيت أوقات تشغيل إضافية مثل Python.
2. تقليل الحمل الزائد للسياق واستهلاك الرمز المميزمن خلال التعامل مع تحليل الأوامر، وحقن المتغيرات، ومنطق التنفيذ داخل البرامج النصية، لا يحتاج Claude إلى إنشاء أوامر CLI الكاملة بشكل متكرر أثناء المحادثة، مما يقلل بشكل كبير من استخدام السياق.

إذا لم تكن على دراية بالبرمجة النصية، فقد تختار عدم استخدام البرامج النصية على الإطلاق. بدلاً من ذلك، يمكنك السماح لـ Claude بتجميع وتنفيذ أوامر CLI مباشرة في SKILL.md.

ومع ذلك، يأتي هذا النهج بتكاليف سياق ورمز مميز أعلى.
أنشئ run-cli.js تحت المجلد scripts/. مسؤولياته الأساسية هي:

• استخراج أمر Apidog CLI من ملف اختبار Markdown محدد
• تحميل ملف .env المقابل بناءً على البيئة المختارة (على سبيل المثال، dev / test)
• حقن متغيرات البيئة وتنفيذ الاختبار

يوضح المثال التالي برنامجًا نصيًا جاهزًا للاستخدام:

import fs from "fs";
import path from "path";
import { execSync } from "child_process";
import dotenv from "dotenv";
import { fileURLToPath } from "url";

const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

// الوسائط
const mdPath = process.argv[2];
const envName = process.argv[3] || "local";

if (!mdPath) {
    console.error("❌ مسار ملف الاختبار .md مفقود");
    process.exit(1);
}

// مسار البيئة: دائمًا نسبيًا لمجلد المهارة
const envPath = path.join(__dirname, "..", "env", `${envName}.env`);

if (!fs.existsSync(envPath)) {
    console.error(`❌ لم يتم العثور على تكوين البيئة: ${envPath}`);
    process.exit(1);
}

dotenv.config({ path: envPath });

// قراءة ملف markdown
const content = fs.readFileSync(mdPath, "utf-8");
const match = content.match(/```bash([\s\S]*?)```/);

if (!match) {
    console.error("❌ لم يتم العثور على كتلة أمر Bash");
    process.exit(1);
}

let command = match[1].trim();

// استبدال المتغيرات
command = command
    .replaceAll("$APIDOG_ACCESS_TOKEN", process.env.APIDOG_ACCESS_TOKEN)
    .replaceAll("$APIDOG_ENV_ID", process.env.APIDOG_ENV_ID);

console.log(`▶ تشغيل (${envName})`);
console.log(command);

// التنفيذ
try {
    execSync(command, { stdio: "inherit" });
} catch (e) {
    // Apidog CLI يعيد رمز الخروج 1 عندما تفشل الاختبارات
    process.exit(1);
}

أنشئ أيضًا list-tests.js تحت المجلد scripts/. يستخدم هذا لـ:

• مسح مجلد tests/ بشكل متكرر
• تحديد موقع جميع ملفات اختبار Markdown
• استخراج الوصف من السطر الأول
• إخراج قائمة بجميع اختبارات Apidog الآلية المتاحة

يوضح المثال التالي برنامجًا نصيًا جاهزًا للاستخدام:

import fs from "fs";
import path from "path";
import { fileURLToPath } from "url";

const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);
const testsDir = path.join(__dirname, "..", "tests");

function scan(dir, relativePath = "") {
    const items = fs.readdirSync(dir, { withFileTypes: true });
    
    for (const item of items) {
        const fullPath = path.join(dir, item.name);
        const relPath = path.join(relativePath, item.name);
        
        if (item.isDirectory()) { // تم تصحيح isfolder() إلى isDirectory()
            scan(fullPath, relPath);
        } else if (item.name.endsWith(".md")) {
            try {
                const content = fs.readFileSync(fullPath, "utf-8");
                const firstLine = content.split("\n")[0].trim();
                const description = firstLine.startsWith(">")
                    ? firstLine.replace(/^>\s*/, "").trim()
                    : "لا يوجد وصف";
                const displayPath = path.join(
                    "./.claude/skills/apidog-tests/tests",
                    relPath
                );
                console.log(`[${displayPath}] - ${description}`);
            } catch (err) {
                console.log(`[${relPath}] - (تعذر قراءة الملف)`);
            }
        }
    }
}

console.log("🔍 اختبارات Apidog الآلية المتاحة:");
if (fs.existsSync(testsDir)) {
    scan(testsDir);
} else {
    console.log("❌ لم يتم العثور على مجلد الاختبارات");
}

تعريفات الاختبار (tests)

يخزن المجلد tests/ تعريفات الاختبار المكتوبة بتنسيق Markdown.

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

يحتاج كل ملف Markdown فقط إلى جزأين:

1. وصف قصير للاختبار
2. أمر Apidog CLI واحد يمكن تنفيذه مباشرة

في أمر Apidog CLI:

• يتم استبدال رمز الوصول بـ $APIDOG_ACCESS_TOKEN
• يتم استبدال معرف البيئة الذي يتم تمريره إلى -e بـ $APIDOG_ENV_ID

يتم تكوين كلا المتغيرين مركزيًا في ملفات .env. يمنع هذا النهج تسرب الرمز المميز ويسمح بتبديل مرن للبيئة.

مثال: login-auth-flow.md

> يتحقق من واجهات برمجة التطبيقات الأساسية مثل تسجيل الدخول وتحديث الرمز المميز وتسجيل الخروج.

```bash
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 5564xxx -e $APIDOG_ENV_ID -n 1 -r html,cli
```

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

استخدام سير العمل في Claude Code

شغّل claude في مجلد المشروع. يقوم Claude تلقائيًا بمسح .claude/skills/ ويحمّل مهارة apidog-tests.

يمكنك إدراج المهارات المحملة باستخدام /skills.

ثم جرب أمرًا باللغة الطبيعية:

"شغّل اختبارات تسجيل الدخول في بيئة التطوير (dev)."

سيحدد Claude الاختبار، وينفذه عبر Apidog CLI، ويحلل المخرجات، ويلخص النتائج.

الملخص

أوضحت هذه المقالة كيفية بناء سير عمل اختبار آلي لواجهة برمجة التطبيقات باستخدام Claude Code و Apidog CLI و Claude Skills.

الفكرة الأساسية هي جعل Claude الجسر بين البشر والأدوات:

• تصف النية باللغة الطبيعية
• يفهم Claude ويستدعي البرامج النصية
• تنفذ البرامج النصية Apidog CLI
• يحلل Claude ويقدم النتائج بطريقة سهلة القراءة للبشر

لجعل سير العمل هذا فعالًا حقًا، يجب عليك تكييفه مع مشروعك - يمكن تخصيص تنظيم الاختبار، واستراتيجية البيئة، ومنطق تحليل النتائج بالكامل.

إذا كان فريقك يجري اختبارات واجهة برمجة التطبيقات بشكل متكرر ويريد تجربة أكثر أتمتة وذكاءً، فإن هذا النهج يستحق المحاولة. يتطلب بعض الإعداد الأولي، ولكن بمجرد إنشائه، يمكنه تحسين الكفاءة بشكل كبير - ويستمر في التحسن كلما قمت بتحسينه.