الأدوات

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

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

start_browser

يطلق جلسة متصفح Chrome.

المعلمات

المعلمة	النوع	إلزامي	القيمة الافتراضية	الوصف
headless	boolean	لا	false	تشغيل Chrome في وضع بدون واجهة
windowWidth	number	لا	1920	عرض نافذة المتصفح (400-3840)
windowHeight	number	لا	1080	ارتفاع نافذة المتصفح (400-2160)
navigationUrl	string	لا	-	عنوان URL للانتقال إليه بعد بدء المتصفح

مثال

Start a browser with 1920x1080 resolution and navigate to webdriver.io

الدعم

• متصفحات سطح المكتب

---

start_app_session

يطلق جلسة تطبيق جوال على iOS أو Android عبر Appium.

المعلمات

المعلمة	النوع	إلزامي	القيمة الافتراضية	الوصف
platform	string	نعم	-	المنصة المراد أتمتتها: iOS أو Android
deviceName	string	نعم	-	اسم الجهاز أو المحاكي
appPath	string	لا*	-	مسار ملف التطبيق (.app أو .ipa أو .apk)
platformVersion	string	لا	-	إصدار نظام التشغيل (مثل 17.0، 14)
automationName	string	لا	Auto	XCUITest (iOS)، UiAutomator2 أو Espresso (Android)
udid	string	لا	-	معرف الجهاز الفريد (مطلوب لأجهزة iOS الحقيقية)
noReset	boolean	لا	false	الحفاظ على حالة التطبيق بين الجلسات
fullReset	boolean	لا	true	إلغاء التثبيت وإعادة تثبيت التطبيق قبل الجلسة
autoGrantPermissions	boolean	لا	true	منح أذونات التطبيق تلقائيًا
autoAcceptAlerts	boolean	لا	true	قبول تنبيهات النظام تلقائيًا
autoDismissAlerts	boolean	لا	false	رفض التنبيهات (بدلاً من قبولها)
appWaitActivity	string	لا	-	النشاط للانتظار عند التشغيل (Android فقط)
newCommandTimeout	number	لا	60	الثواني قبل انتهاء مهلة الجلسة بسبب عدم النشاط
appiumHost	string	لا	127.0.0.1	اسم مضيف خادم Appium
appiumPort	number	لا	4723	منفذ خادم Appium
appiumPath	string	لا	/	مسار خادم Appium

*إما يجب توفير appPath أو noReset: true للاتصال بتطبيق قيد التشغيل بالفعل.

مثال

Start an iOS app session on iPhone 15 simulator with my app at /path/to/app.app

الدعم

• محاكيات iOS
• أجهزة iOS الحقيقية
• محاكيات Android
• أجهزة Android الحقيقية

---

close_session

يغلق جلسة المتصفح أو التطبيق الحالية.

المعلمات

المعلمة	النوع	إلزامي	القيمة الافتراضية	الوصف
detach	boolean	لا	false	فصل الجلسة بدلاً من إغلاقها (يبقي المتصفح/التطبيق قيد التشغيل)

ملاحظات

الجلسات مع noReset: true أو بدون appPath تفصل تلقائيًا عند الإغلاق للحفاظ على الحالة.

الدعم

• متصفحات سطح المكتب
• تطبيقات الجوال

---

التنقل

navigate

ينتقل إلى عنوان URL.

المعلمات

المعلمة	النوع	إلزامي	الوصف
url	string	نعم	عنوان URL المراد الانتقال إليه

مثال

Navigate to https://webdriver.io

الدعم

• متصفحات سطح المكتب

---

التفاعل مع العناصر

click_element

ينقر على عنصر محدد بواسطة منتقي.

المعلمات

المعلمة	النوع	إلزامي	القيمة الافتراضية	الوصف
selector	string	نعم	-	منتقي CSS أو XPath أو منتقي جوال
scrollToView	boolean	لا	true	تمرير العنصر للعرض قبل النقر
timeout	number	لا	3000	الوقت الأقصى للانتظار للعنصر (بالملي ثانية)

ملاحظات

• يدعم منتقيات نصوص WebdriverIO: button=Exact text أو a*=Contains text
• يستخدم محاذاة المركز لوضع التمرير

مثال

Click the element with selector "#submit-button"

الدعم

• متصفحات سطح المكتب
• تطبيقات الجوال الأصلية

---

set_value

يكتب نصًا في حقل إدخال.

المعلمات

المعلمة	النوع	إلزامي	القيمة الافتراضية	الوصف
selector	string	نعم	-	منتقي لعنصر الإدخال
value	string	نعم	-	النص المراد كتابته
scrollToView	boolean	لا	true	تمرير العنصر للعرض قبل الكتابة
timeout	number	لا	3000	الوقت الأقصى للانتظار للعنصر (بالملي ثانية)

ملاحظات

يمسح القيمة الموجودة قبل كتابة نص جديد.

مثال

Set the value "john@example.com" in the element with selector "#email"

الدعم

• متصفحات سطح المكتب
• تطبيقات الجوال الأصلية

---

تحليل الصفحة

get_visible_elements

يحصل على العناصر المرئية والقابلة للتفاعل في الصفحة الحالية أو الشاشة. هذه هي الأداة الأساسية لاكتشاف العناصر المتاحة للتفاعل.

المعلمات

المعلمة	النوع	إلزامي	القيمة الافتراضية	الوصف
elementType	string	لا	interactable	نوع العناصر: interactable (أزرار/روابط/حقول إدخال)، visual (صور/SVG)، أو all
inViewportOnly	boolean	لا	true	إرجاع العناصر المرئية فقط في منفذ العرض
includeContainers	boolean	لا	false	تضمين حاويات التخطيط (ViewGroup، ScrollView، إلخ)
includeBounds	boolean	لا	false	تضمين إحداثيات العنصر (x، y، العرض، الارتفاع)
limit	number	لا	0	الحد الأقصى للعناصر المراد إرجاعها (0 = غير محدود)
offset	number	لا	0	عدد العناصر المراد تخطيها (للتصفح)

العائد

{
  "total": 42,
  "showing": 20,
  "hasMore": true,
  "elements": [...]
}

عناصر الويب تشمل: tagName، type، id، className، textContent، value، placeholder، href، ariaLabel، role، cssSelector، isInViewport

عناصر الجوال تشمل: استراتيجيات تحديد متعددة (معرف إمكانية الوصول، معرف المورد، XPath، UiAutomator/predicates)، نوع العنصر، النص، واختياريًا الحدود

ملاحظات

• الويب: يستخدم نصًا برمجيًا محسّنًا للمتصفح لاكتشاف العناصر بسرعة
• الجوال: يستخدم تحليل مصدر صفحة XML بكفاءة (طلبان HTTP مقابل أكثر من 600 لاستعلامات العناصر)
• استخدم التصفح (limit و offset) للصفحات الكبيرة لتقليل استخدام الرموز

مثال

Get all visible elements on the page with their coordinates

الدعم

• متصفحات سطح المكتب
• تطبيقات الجوال

---

get_accessibility

يحصل على شجرة إمكانية الوصول للصفحة الحالية مع معلومات دلالية حول الأدوار والأسماء والحالات.

المعلمات

المعلمة	النوع	إلزامي	القيمة الافتراضية	الوصف
limit	number	لا	100	الحد الأقصى للعقد المراد إرجاعها (0 = غير محدود)
offset	number	لا	0	عدد العقد المراد تخطيها (للتصفح)
roles	string[]	لا	الكل	تصفية لأدوار محددة (مثل ["button", "link", "textbox"])
namedOnly	boolean	لا	true	إرجاع العقد ذات الاسم/التسمية فقط

العائد

{
  "total": 85,
  "showing": 100,
  "hasMore": false,
  "nodes": [
    { "role": "button", "name": "Submit" },
    { "role": "link", "name": "Home" }
  ]
}

ملاحظات

• للمتصفح فقط. لتطبيقات الجوال، استخدم get_visible_elements بدلاً من ذلك
• مفيد عندما لا يُرجع get_visible_elements العناصر المتوقعة
• namedOnly: true يصفي الحاويات المجهولة ويقلل الضوضاء

الدعم

• متصفحات سطح المكتب

---

لقطات الشاشة

take_screenshot

يلتقط لقطة شاشة لمنفذ العرض الحالي.

المعلمات

المعلمة	النوع	إلزامي	الوصف
outputPath	string	لا	مسار لحفظ ملف لقطة الشاشة. إذا تم حذفه، يتم إرجاع بيانات base64

العائد

بيانات الصورة المشفرة بنظام Base64 (PNG أو JPEG) مع معلومات الحجم.

ملاحظات

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

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

الدعم

• متصفحات سطح المكتب
• تطبيقات الجوال

---

التمرير

scroll

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

المعلمات

المعلمة	النوع	إلزامي	القيمة الافتراضية	الوصف
direction	string	نعم	-	اتجاه التمرير: up أو down
pixels	number	لا	500	عدد البكسلات المراد التمرير

ملاحظات

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

الدعم

• متصفحات سطح المكتب

---

إدارة ملفات تعريف الارتباط

get_cookies

يحصل على ملفات تعريف الارتباط من الجلسة الحالية.

المعلمات

المعلمة	النوع	إلزامي	الوصف
name	string	لا	اسم ملف تعريف ارتباط محدد للحصول عليه (حذفه للحصول على جميع ملفات تعريف الارتباط)

العائد

كائنات ملفات تعريف الارتباط مع الاسم والقيمة والمجال والمسار وتاريخ انتهاء الصلاحية وآمن وhttpOnly.

الدعم

• متصفحات سطح المكتب

---

set_cookie

يعين ملف تعريف ارتباط في الجلسة الحالية.

المعلمات

المعلمة	النوع	إلزامي	القيمة الافتراضية	الوصف
name	string	نعم	-	اسم ملف تعريف الارتباط
value	string	نعم	-	قيمة ملف تعريف الارتباط
domain	string	لا	الحالي	مجال ملف تعريف الارتباط
path	string	لا	/	مسار ملف تعريف الارتباط
expiry	number	لا	-	تاريخ انتهاء الصلاحية كطابع زمني Unix (بالثواني)
secure	boolean	لا	-	علامة آمن
httpOnly	boolean	لا	-	علامة HttpOnly
sameSite	string	لا	-	سمة SameSite: strict أو lax أو none

الدعم

• متصفحات سطح المكتب

---

delete_cookies

يحذف ملفات تعريف الارتباط من الجلسة الحالية.

المعلمات

المعلمة	النوع	إلزامي	الوصف
name	string	لا	اسم ملف تعريف ارتباط محدد لحذفه (حذفه لحذف الكل)

الدعم

• متصفحات سطح المكتب

---

إيماءات اللمس (الجوال)

tap_element

ينقر على عنصر أو إحداثيات الشاشة.

المعلمات

المعلمة	النوع	إلزامي	الوصف
selector	string	لا*	منتقي للعنصر المراد النقر عليه
x	number	لا*	إحداثية X للنقر
y	number	لا*	إحداثية Y للنقر

*إما selector أو كلا من x و y مطلوبان.

الدعم

• تطبيقات الجوال

---

swipe

ينفذ إيماءة سحب في الاتجاه المحدد.

المعلمات

المعلمة	النوع	إلزامي	القيمة الافتراضية	الوصف
direction	string	نعم	-	اتجاه السحب: up أو down أو left أو right
duration	number	لا	500	مدة السحب بالملي ثانية (100-5000)
percent	number	لا	0.5/0.95	نسبة الشاشة المراد سحبها (0-1)

ملاحظات

• النسبة الافتراضية: 0.5 للسحب العمودي، 0.95 للسحب الأفقي
• يشير الاتجاه إلى حركة المحتوى: "سحب لأعلى" يمرر المحتوى لأعلى

مثال

Swipe up to scroll down the screen

الدعم

• تطبيقات الجوال

---

drag_and_drop

يسحب عنصرًا إلى عنصر آخر أو إحداثيات.

المعلمات

المعلمة	النوع	إلزامي	الوصف
sourceSelector	string	نعم	منتقي العنصر المصدر للسحب
targetSelector	string	لا*	منتقي العنصر الهدف للإسقاط عليه
x	number	لا*	إزاحة X الهدف (إذا لم يكن هناك targetSelector)
y	number	لا*	إزاحة Y الهدف (إذا لم يكن هناك targetSelector)
duration	number	لا	الافتراضي

*إما targetSelector أو كلا من x و y مطلوبان.

الدعم

• تطبيقات الجوال

---

دورة حياة التطبيق (الجوال)

get_app_state

يحصل على الحالة الحالية للتطبيق.

المعلمات

المعلمة	النوع	إلزامي	الوصف
bundleId	string	نعم	معرف التطبيق (معرف الحزمة لنظام iOS، اسم الحزمة لنظام Android)

العائد

حالة التطبيق: not installed أو not running أو running in background (suspended) أو running in background أو running in foreground.

الدعم

• تطبيقات الجوال

---

تبديل السياق (التطبيقات الهجينة)

get_contexts

يسرد جميع السياقات المتاحة (الأصلية والعرض الويب).

المعلمات

لا شيء

العائد

مصفوفة أسماء السياقات (مثل ["NATIVE_APP", "WEBVIEW_com.example.app"]).

الدعم

• تطبيقات الجوال الهجينة

---

get_current_context

يحصل على السياق النشط حاليًا.

المعلمات

لا شيء

العائد

اسم السياق الحالي (مثل NATIVE_APP أو WEBVIEW_*).

الدعم

• تطبيقات الجوال الهجينة

---

switch_context

يتبدل بين سياقات التطبيق الأصلي وعرض الويب.

المعلمات

المعلمة	النوع	إلزامي	الوصف
context	string	نعم	اسم السياق أو الفهرس (1-based) من get_contexts

مثال

Switch to the WEBVIEW_com.example.app context

الدعم

• تطبيقات الجوال الهجينة

---

التحكم بالجهاز (الجوال)

rotate_device

يدور الجهاز إلى اتجاه محدد.

المعلمات

المعلمة	النوع	إلزامي	الوصف
orientation	string	نعم	PORTRAIT أو LANDSCAPE

الدعم

• تطبيقات الجوال

---

hide_keyboard

يخفي لوحة المفاتيح على الشاشة.

المعلمات

لا شيء

الدعم

• تطبيقات الجوال

---

get_geolocation

يحصل على إحداثيات GPS الحالية.

المعلمات

لا شيء

العائد

كائن مع latitude و longitude و altitude.

الدعم

• تطبيقات الجوال

---

set_geolocation

يعين إحداثيات GPS للجهاز.

المعلمات

المعلمة	النوع	إلزامي	الوصف
latitude	number	نعم	إحداثية خط العرض (-90 إلى 90)
longitude	number	نعم	إحداثية خط الطول (-180 إلى 180)
altitude	number	لا	الارتفاع بالأمتار

مثال

Set geolocation to San Francisco (37.7749, -122.4194)

الدعم

• تطبيقات الجوال

---

تنفيذ النصوص البرمجية

execute_script

ينفذ JavaScript في المتصفح أو أوامر الجوال عبر Appium.

المعلمات

المعلمة	النوع	إلزامي	الوصف
script	string	نعم	كود JavaScript (المتصفح) أو أمر الجوال (مثل mobile: pressKey)
args	array	لا	وسيطات للنص البرمجي

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

// Get page title
execute_script({ script: "return document.title" })

// Get scroll position
execute_script({ script: "return window.scrollY" })

// Click element by selector
execute_script({ script: "arguments[0].click()", args: ["#myButton"] })

أمثلة الجوال (Appium)

// Press back key (Android)
execute_script({ script: "mobile: pressKey", args: [{ keycode: 4 }] })

// Activate app
execute_script({ script: "mobile: activateApp", args: [{ appId: "com.example" }] })

// Terminate app
execute_script({ script: "mobile: terminateApp", args: [{ appId: "com.example" }] })

// Deep link
execute_script({ script: "mobile: deepLink", args: [{ url: "myapp://screen", package: "com.example" }] })

// Shell command (Android)
execute_script({ script: "mobile: shell", args: [{ command: "dumpsys", args: ["battery"] }] })

رموز مفاتيح Android الشائعة

المفتاح	الرمز
BACK	4
HOME	3
ENTER	66
MENU	82
SEARCH	84

المزيد من أوامر الجوال

للحصول على قائمة كاملة بأوامر Appium المتاحة للجوال، راجع:

• أوامر XCUITest المحمولة (iOS)
• أوامر UiAutomator2 المحمولة (Android)

الدعم

• متصفحات سطح المكتب
• تطبيقات الجوال (عبر أوامر Appium المحمولة)