تخطى إلى المحتوى الرئيسي

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

الأسئلة المتكررة حول WebdriverIO MCP.

عام​

ما هو MCP؟​

MCP (بروتوكول سياق النموذج) هو بروتوكول مفتوح يمكّن المساعدين الذكاء الاصطناعي مثل Claude من التفاعل مع الأدوات والخدمات الخارجية. يقوم WebdriverIO MCP بتنفيذ هذا البروتوكول لتوفير إمكانيات أتمتة المتصفح والجوال لـ Claude Desktop و Claude Code.

ما الذي يمكنني أتمتته باستخدام WebdriverIO MCP؟​

يمكنك أتمتة:

  • متصفحات سطح المكتب (Chrome) - التصفح، النقر، الكتابة، لقطات الشاشة
  • تطبيقات iOS - على المحاكيات أو الأجهزة الحقيقية
  • تطبيقات Android - على المحاكيات أو الأجهزة الحقيقية
  • التطبيقات الهجينة - التبديل بين السياقات الأصلية وسياقات الويب

هل أحتاج إلى كتابة التعليمات البرمجية؟​

لا! هذه هي الميزة الرئيسية لـ MCP. يمكنك وصف ما تريد القيام به بلغة طبيعية، وسيستخدم Claude الأدوات المناسبة لإنجاز المهمة.

أمثلة على الأوامر:

  • "افتح Chrome وانتقل إلى webdriver.io"
  • "انقر على زر البدء"
  • "التقط لقطة شاشة للصفحة الحالية"
  • "ابدأ تطبيق iOS الخاص بي وقم بتسجيل الدخول كمستخدم اختبار"

التثبيت والإعداد​

كيف أقوم بتثبيت WebdriverIO MCP؟​

لست بحاجة إلى تثبيته بشكل منفصل. يعمل خادم MCP تلقائيًا عبر npx عند تكوينه في Claude Desktop أو Claude Code.

أضف هذا إلى تكوين Claude Desktop الخاص بك:

{
    "mcpServers": {
        "wdio-mcp": {
            "command": "npx",
            "args": ["-y", "@wdio/mcp"]
        }
    }
}

أين يوجد ملف تكوين Claude Desktop؟​

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json

هل أحتاج إلى Appium لأتمتة المتصفح؟​

لا. تتطلب أتمتة المتصفح تثبيت Chrome فقط. يتعامل WebdriverIO مع ChromeDriver تلقائيًا.

هل أحتاج إلى Appium لأتمتة الأجهزة المحمولة؟​

نعم. تتطلب أتمتة الأجهزة المحمولة:

  1. تشغيل خادم Appium (npm install -g appium && appium)
  2. تثبيت برامج تشغيل المنصة (appium driver install xcuitest لـ iOS، appium driver install uiautomator2 لـ Android)
  3. أدوات التطوير المناسبة (Xcode لـ iOS، Android SDK لـ Android)

أتمتة المتصفح​

ما هي المتصفحات المدعومة؟​

حاليًا، يتم دعم Chrome فقط. قد تتم إضافة دعم للمتصفحات الأخرى في الإصدارات المستقبلية.

هل يمكنني تشغيل Chrome في وضع بدون واجهة (headless)؟​

نعم! اطلب من Claude بدء المتصفح في وضع بدون واجهة:

"ابدأ Chrome في وضع بدون واجهة"

أو سيستخدم Claude هذا الخيار عند الحاجة (مثلاً في سياقات CI/CD).

هل يمكنني تعيين حجم نافذة المتصفح؟​

نعم. يمكنك تحديد الأبعاد عند بدء المتصفح:

"ابدأ Chrome بحجم نافذة 1920×1080"

الأبعاد المدعومة: 400-3840 بكسل عرضًا، 400-2160 بكسل ارتفاعًا. الافتراضي هو 1920×1080.

هل يمكنني بدء المتصفح والانتقال في خطوة واحدة؟​

نعم! استخدم معلمة navigationUrl:

"ابدأ Chrome وانتقل إلى https://webdriver.io"

هذا أكثر كفاءة من بدء المتصفح ثم التصفح بشكل منفصل.

كيف يمكنني التقاط لقطات الشاشة؟​

ما عليك سوى أن تطلب من Claude:

"التقط لقطة شاشة للصفحة الحالية"

يتم تحسين لقطات الشاشة تلقائيًا:

  • تقييس الحجم إلى أقصى بعد 2000 بكسل
  • ضغط إلى حجم ملف أقصى 1 ميجابايت
  • التنسيق: PNG أو JPEG (يتم اختياره تلقائيًا للحصول على الجودة المثلى)

هل يمكنني التفاعل مع الإطارات المضمنة (iframes)؟​

حاليًا، يعمل خادم MCP على المستند الرئيسي. قد تتم إضافة التفاعل مع الإطارات المضمنة في الإصدارات المستقبلية.

هل يمكنني تنفيذ JavaScript مخصص؟​

نعم! استخدم أداة execute_script:

"نفذ برنامج نصي للحصول على عنوان الصفحة" "نفذ برنامج نصي: return document.querySelectorAll('button').length"

أتمتة الأجهزة المحمولة​

كيف أبدأ تطبيق iOS؟​

اسأل Claude مع التفاصيل الضرورية:

"ابدأ تطبيق iOS الخاص بي الموجود في /path/to/MyApp.app على محاكي iPhone 15"

أو للتطبيق المثبت:

"ابدأ التطبيق مع تمكين noReset على محاكي iPhone 15"

كيف أبدأ تطبيق Android؟​

"ابدأ تطبيق Android الخاص بي في /path/to/app.apk على محاكي Pixel 7"

أو للتطبيق المثبت:

"ابدأ التطبيق مع تمكين noReset على محاكي Pixel 7"

هل يمكنني الاختبار على أجهزة حقيقية؟​

نعم! للأجهزة الحقيقية، ستحتاج إلى UDID للجهاز:

  • iOS: قم بتوصيل الجهاز، افتح Finder، انقر على الجهاز، انقر على الرقم التسلسلي لإظهار UDID
  • Android: قم بتشغيل adb devices في الطرفية

ثم اسأل Claude:

"ابدأ تطبيق iOS الخاص بي على الجهاز الحقيقي مع UDID abc123..."

كيف أتعامل مع مربعات حوار الأذونات؟​

افتراضيًا، يتم منح الأذونات تلقائيًا (autoGrantPermissions: true). إذا كنت بحاجة إلى اختبار تدفقات الأذونات، يمكنك تعطيل هذا:

"ابدأ تطبيقي بدون منح الأذونات تلقائيًا"

ما هي الإيماءات المدعومة؟​

  • النقر: النقر على العناصر أو الإحداثيات
  • السحب: السحب للأعلى، للأسفل، لليسار، أو لليمين
  • السحب والإفلات: السحب من عنصر إلى آخر أو إلى إحداثيات

ملاحظة: الضغط الطويل متاح من خلال execute_script مع أوامر Appium للجوال.

كيف يمكنني التمرير في تطبيقات الجوال؟​

استخدم إيماءات السحب:

"اسحب للأعلى للتمرير للأسفل" "اسحب للأسفل للتمرير للأعلى"

هل يمكنني تدوير الجهاز؟​

نعم:

"قم بتدوير الجهاز إلى الوضع الأفقي" "قم بتدوير الجهاز إلى الوضع الرأسي"

كيف أتعامل مع التطبيقات الهجينة؟​

للتطبيقات التي تحتوي على عرض ويب، يمكنك تبديل السياقات:

"احصل على السياقات المتاحة" "انتقل إلى سياق عرض الويب" "عد إلى السياق الأصلي"

هل يمكنني تنفيذ أوامر Appium للجوال؟​

نعم! استخدم أداة execute_script:

Execute script "mobile: pressKey" with args [{ keycode: 4 }]  // اضغط BACK على Android
Execute script "mobile: activateApp" with args [{ appId: "com.example.app" }]
Execute script "mobile: terminateApp" with args [{ bundleId: "com.example.app" }]

اختيار العناصر​

كيف يعرف Claude أي عنصر للتفاعل معه؟​

يستخدم Claude أداة get_visible_elements لتحديد العناصر التفاعلية على الصفحة/الشاشة. يأتي كل عنصر مع استراتيجيات محدد متعددة.

ماذا لو كان هناك الكثير من العناصر على الصفحة؟​

استخدم التقسيم إلى صفحات لإدارة قوائم العناصر الكبيرة:

"احصل على أول 20 عنصرًا مرئيًا" "احصل على العناصر المرئية بإزاحة 20 وحد 20"

تتضمن الاستجابة total و showing و hasMore للمساعدة في التنقل عبر العناصر.

هل يمكنني الحصول على أنواع محددة من العناصر فقط؟​

نعم! استخدم معلمة elementType:

  • interactable (افتراضي): الأزرار، الروابط، حقول الإدخال
  • visual: الصور، SVG
  • all: كلا النوعين

"احصل على العناصر المرئية البصرية في الصفحة"

ماذا لو نقر Claude على العنصر الخطأ؟​

يمكنك أن تكون أكثر تحديدًا:

  • قدم النص بالضبط: "انقر على الزر الذي يقول 'إرسال الطلب'"
  • قدم المحدد: "انقر على العنصر بمحدد #submit-btn"
  • قدم معرف إمكانية الوصول: "انقر على العنصر بمعرف إمكانية الوصول loginButton"

ما هي أفضل استراتيجية محدد للجوال؟​

  1. معرف إمكانية الوصول (الأفضل) - ~loginButton
  2. معرف المورد (Android) - id=login_button
  3. سلسلة المسند (iOS) - -ios predicate string:label == "Login"
  4. XPath (الملاذ الأخير) - أبطأ ولكن يعمل في كل مكان

ما هي شجرة إمكانية الوصول ومتى يجب أن أستخدمها؟​

توفر شجرة إمكانية الوصول معلومات دلالية حول عناصر الصفحة (الأدوار، الأسماء، الحالات). استخدم get_accessibility عندما:

  • لا تُرجع get_visible_elements العناصر المتوقعة
  • تحتاج إلى العثور على العناصر حسب دور إمكانية الوصول (زر، رابط، مربع نص، إلخ)
  • تحتاج إلى معلومات دلالية مفصلة حول العناصر

"احصل على شجرة إمكانية الوصول مفلترة إلى أدوار الزر والرابط"

إدارة الجلسة​

هل يمكنني أن يكون لدي جلسات متعددة في وقت واحد؟​

لا. يستخدم خادم MCP نموذج الجلسة الفردية. يمكن أن تكون جلسة متصفح أو تطبيق واحدة فقط نشطة في وقت واحد.

ماذا يحدث عندما أغلق جلسة؟​

يعتمد ذلك على نوع الجلسة والإعدادات:

  • المتصفح: يغلق Chrome تمامًا
  • الجوال مع noReset: false: ينتهي التطبيق
  • الجوال مع noReset: true أو بدون appPath: يبقى التطبيق مفتوحًا (تنفصل الجلسة تلقائيًا)

هل يمكنني الحفاظ على حالة التطبيق بين الجلسات؟​

نعم! استخدم خيار noReset:

"ابدأ تطبيقي مع تمكين noReset"

هذا يحفظ حالة تسجيل الدخول، والتفضيلات، وبيانات التطبيق الأخرى.

ما هو الفرق بين الإغلاق والانفصال؟​

  • الإغلاق: ينهي المتصفح/التطبيق تمامًا
  • الانفصال: يقطع الاتصال بالأتمتة ولكن يبقي المتصفح/التطبيق قيد التشغيل

الانفصال مفيد عندما تريد فحص الحالة يدويًا بعد الأتمتة.

جلستي تستمر في انتهاء الوقت أثناء التصحيح​

زيادة مهلة الأمر:

"ابدأ تطبيقي بـ newCommandTimeout من 300 ثانية"

الافتراضي هو 60 ثانية. لجلسات التصحيح الطويلة، جرب 300-600 ثانية.

استكشاف الأخطاء وإصلاحها​

خطأ "الجلسة غير موجودة"​

هذا يعني عدم وجود جلسة نشطة. ابدأ جلسة متصفح أو تطبيق أولاً:

"ابدأ Chrome وانتقل إلى google.com"

خطأ "العنصر غير موجود"​

قد لا يكون العنصر مرئيًا أو قد يكون له محدد مختلف. حاول:

  1. الطلب من Claude الحصول على جميع العناصر المرئية أولاً
  2. تقديم محدد أكثر تحديدًا
  3. الانتظار حتى يتم تحميل الصفحة/التطبيق بالكامل
  4. استخدام inViewportOnly: false للعثور على العناصر خارج الشاشة

المتصفح لن يبدأ​

  1. تأكد من تثبيت Chrome
  2. تحقق مما إذا كانت عملية أخرى تستخدم منفذ التصحيح (9222)
  3. جرب وضع بدون واجهة

فشل اتصال Appium​

هذه هي المشكلة الأكثر شيوعًا عند بدء أتمتة الجوال.

  1. تحقق من تشغيل Appium: curl http://localhost:4723/status
  2. ابدأ Appium إذا لزم الأمر: appium
  3. تحقق من أن تكوين عنوان URL الخاص بـ Appium يتطابق مع الخادم
  4. تأكد من تثبيت برامج التشغيل: appium driver list --installed
نصيحة

يتطلب خادم MCP تشغيل Appium قبل بدء جلسات الجوال. تأكد من بدء Appium أولاً:

appium

قد تتضمن الإصدارات المستقبلية إدارة خدمة Appium التلقائية.

محاكي iOS لن يبدأ​

  1. تأكد من تثبيت Xcode: xcode-select --install
  2. اعرض المحاكيات المتاحة: xcrun simctl list devices
  3. تحقق من أخطاء المحاكي المحددة في Console.app

محاكي Android لن يبدأ​

  1. قم بتعيين ANDROID_HOME: export ANDROID_HOME=$HOME/Library/Android/sdk
  2. تحقق من المحاكيات: emulator -list-avds
  3. ابدأ المحاكي يدويًا: emulator -avd <avd-name>
  4. تحقق من اتصال الجهاز: adb devices

لقطات الشاشة لا تعمل​

  1. بالنسبة للجوال، تأكد من أن الجلسة نشطة
  2. بالنسبة للمتصفح، جرب صفحة مختلفة (بعض الصفحات تمنع لقطات الشاشة)
  3. تحقق من سجلات Claude Desktop للأخطاء

يتم ضغط لقطات الشاشة تلقائيًا إلى حد أقصى 1 ميجابايت، لذلك ستعمل لقطات الشاشة الكبيرة ولكن قد تكون بجودة أقل.

الأداء​

لماذا أتمتة الجوال بطيئة؟​

تتضمن أتمتة الجوال:

  1. اتصال الشبكة مع خادم Appium
  2. تواصل Appium مع الجهاز/المحاكي
  3. عرض الجهاز والاستجابة

نصائح لأتمتة أسرع:

  • استخدم المحاكيات بدلاً من الأجهزة الحقيقية للتطوير
  • استخدم معرفات إمكانية الوصول بدلاً من XPath
  • قم بتمكين inViewportOnly: true لاكتشاف العنصر
  • استخدم التقسيم إلى صفحات (limit) لتقليل استخدام الرمز المميز

كيف يمكنني تسريع اكتشاف العنصر؟​

يقوم خادم MCP بالفعل بتحسين اكتشاف العنصر باستخدام تحليل مصدر الصفحة XML (مكالمتان HTTP مقابل أكثر من 600 لاستعلامات العنصر التقليدية). نصائح إضافية:

  • احتفظ بـ inViewportOnly: true (افتراضي)
  • قم بتعيين includeContainers: false (افتراضي)
  • استخدم limit و offset للتقسيم إلى صفحات على الشاشات الكبيرة
  • استخدم محددات محددة بدلاً من العثور على جميع العناصر

لقطات الشاشة بطيئة أو فاشلة​

يتم تحسين لقطات الشاشة تلقائيًا:

  • يتم تغيير حجمها إذا كانت أكبر من 2000 بكسل
  • يتم ضغطها للبقاء أقل من 1 ميجابايت
  • يتم تحويلها إلى JPEG إذا كان PNG كبيرًا جدًا

يقلل هذا التحسين من وقت المعالجة ويضمن قدرة Claude على التعامل مع الصورة.

القيود​

ما هي القيود الحالية؟​

  • جلسة واحدة: متصفح/تطبيق واحد فقط في كل مرة
  • دعم المتصفح: Chrome فقط (في الوقت الحالي)
  • دعم iframe: دعم محدود للإطارات المضمنة
  • تحميل الملفات: غير مدعوم مباشرة عبر الأدوات
  • الصوت/الفيديو: لا يمكن التفاعل مع تشغيل الوسائط
  • امتدادات المتصفح: غير مدعومة

هل يمكنني استخدام هذا للاختبار الإنتاجي؟​

تم تصميم WebdriverIO MCP للأتمتة التفاعلية بمساعدة الذكاء الاصطناعي. للاختبار الإنتاجي CI/CD، فكر في استخدام مشغل اختبار WebdriverIO التقليدي مع التحكم البرمجي الكامل.

الأمان​

هل بياناتي آمنة؟​

يعمل خادم MCP محليًا على جهازك. تحدث جميع عمليات الأتمتة من خلال اتصالات المتصفح/Appium المحلية. لا يتم إرسال أي بيانات إلى خوادم خارجية بخلاف ما تنتقل إليه صراحة.

هل يمكن لـ Claude الوصول إلى كلمات المرور الخاصة بي؟​

يمكن لـ Claude رؤية محتوى الصفحة والتفاعل مع العناصر، ولكن:

  • يتم إخفاء كلمات المرور في حقول <input type="password">
  • يجب تجنب أتمتة بيانات الاعتماد الحساسة
  • استخدم حسابات اختبار للأتمتة

المساهمة​

كيف يمكنني المساهمة؟​

قم بزيارة مستودع GitHub من أجل:

  • الإبلاغ عن الأخطاء
  • طلب الميزات
  • تقديم طلبات السحب

أين يمكنني الحصول على المساعدة؟​

Welcome! How can I help?

WebdriverIO AI Copilot