حل المشكلات

كخطوة أولى دائماً، ابدأ بتشغيل أمر الفحص الخاص بـ Astur للتأكد من سلامة البيئة:

npx astur-mobile doctor

وإذا واجهتك مشكلة أثناء تنفيذ أمر معين، أضف المُعامل --verbose للحصول على تفاصيل دقيقة:

npx astur-mobile doctor --verbose

مشاكل Android

لم يُعثر على أداة ADB

رسالة الخطأ: ADB failed

الحل:

• تأكد من تثبيت أدوات المنصة (Android SDK Platform Tools).
• أضف مسار platform-tools إلى متغير البيئة PATH.

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

adb version

لم تُكتشف أي أجهزة Android

رسالة الخطأ: Android devices: No Android devices detected.

الحل:

• قم بتشغيل محاكي Android أو قم بتوصيل جهاز فعلي.
• تأكد من تفعيل “تنقيح USB” (USB Debugging) من خيارات المطور.
• وافق على رسالة التفويض التي تظهر على شاشة الجهاز.

للتحقق من الأجهزة المتصلة:

adb devices -l

جهاز Android غير مُصرّح (Unauthorized)

رسالة الخطأ: unauthorized

الحل:

• افتح قفل شاشة الهاتف.
• اقبل رسالة تفويض الـ USB التي تظهر على الشاشة (اختر “السماح دائماً” لتجنب تكرارها).
• إذا لم تظهر الرسالة، افصل الكابل وأعد توصيله، ثم أعد تشغيل خادم ADB:

adb kill-server && adb start-server

فشل استنتاج بيانات تطبيق Android

رسالة الخطأ: AAPT_NOT_FOUND

الحل:

• تأكد من تثبيت أدوات بناء Android SDK (Build Tools).
• اضبط متغيرات البيئة ANDROID_HOME أو ANDROID_SDK_ROOT بشكل صحيح.
• أو يمكنك تحديد مسار أداة aapt مباشرة عبر المتغير ASTUR_AAPT.

كحل بديل، يمكنك تمرير بيانات التطبيق يدوياً في إعدادات الاختبار:

app: {
  path: './apps/demo.apk',
  packageName: 'com.example',
  activity: '.MainActivity'
}

تشغيل Android يتطلب اسم الحزمة (Package Name)

رسالة الخطأ: Android launch requires app.packageName.

الحل: قم بتوفير packageName صراحةً في إعداداتك، أو تأكد من توفر أداة aapt ليتمكن Astur من استخراج هذا الاسم تلقائياً من ملف الـ APK.

---

مشاكل iOS و Xcode

لم يُعثر على Xcode

رسالة الخطأ: Xcode failed

الحل: قم بتوجيه النظام لمسار تثبيت Xcode الصحيح عبر:

sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
xcodebuild -version

لا توجد محاكيات iOS (Simulators)

رسالة الخطأ: iOS simulators: No iOS simulators were found.

الحل:

• افتح تطبيق Xcode.
• انتقل إلى Settings > Platforms وقم بتثبيت بيئة المحاكي المطلوبة (مثل iOS 17).

للتحقق من المحاكيات المتوفرة:

xcrun simctl list devices available

إجراءات iOS الأصلية تتطلب وكيل XCUITest

رسالة الخطأ: XCTEST_AGENT_REQUIRED

السبب: أوامر دورة حياة iOS ولقطات الشاشة قد تعمل محلياً عبر simctl، لكن التفاعل العميق (كالبحث عن العناصر الأصلية، والنقرات، والإيماءات) يتطلب تشغيل وكيل XCUITest المكتوب بـ Swift.

الحل:

• عند بدء توليد الكود أو تشغيل الاختبارات، قم بتمرير معرّف الحزمة: --app-id com.example.demo
• أو استخدم المتغير ASTUR_IOS_BUNDLE_ID=com.example.demo.
• داخل الـ Inspector، يمكنك استخدام قائمة Controls > App للتشغيل باستخدام معرّف الحزمة لربط الوكيل.
• لفحص سبب فشل بناء أو تسجيل الوكيل، استخدم npx astur-mobile doctor --verbose.

(ملاحظة: للتطبيق التجريبي المرفق، يستخدم Astur المُعرّف com.astur.demo بشكل افتراضي).

فشل بدء وكيل XCUITest على iOS

رسالة الخطأ: IOS_XCTEST_AGENT_START_FAILED

السبب: يحاول Astur تشغيل وكيل XCUITest وينتظر اتصاله بالجسر (Bridge). إذا استمر الفشل بعد استنفاد محاولات إعادة التشغيل، سيتم تضمين مخرجات xcodebuild لتشخيص المشكلة.

الحل:

• تأكد من تشغيل المحاكي عبر: xcrun simctl list devices booted.
• تأكد من تثبيت التطبيق وتطابق app.bundleId.
• أحياناً يكون التشغيل الأول (البارد) من Xcode بطيئاً. أعد المحاولة، فالتشغيل الثاني يستفيد من ذاكرة التخزين (DerivedData) وسيكون أسرع.
• في بيئات التكامل المستمر (CI) البطيئة، قد تحتاج لزيادة agent.launchTimeout أو ضبط محاولات البدء ASTUR_IOS_AGENT_START_ATTEMPTS=3.

---

مشاكل أجهزة iOS الفعلية (Real Devices)

يتطلب فريق توقيع التطوير (Development Team)

رسالة الخطأ: IOS_DEVELOPMENT_TEAM_REQUIRED

السبب: اكتشف Astur جهاز iPhone حقيقي وحاول بدء مشغل XCUITest، لكن Xcode يفتقر إلى حساب مطور لتوقيع هذا المشغل.

الحل:

• أضف حساب Apple Developer الخاص بك في إعدادات Xcode.
• افتح قفل الـ iPhone ووافق على رسالة “الوثوق بهذا الكمبيوتر”.
• فعّل وضع المطور (Developer Mode) من إعدادات الـ iPhone.
• حدد فريق التطوير عبر المتغير: ASTUR_IOS_DEVELOPMENT_TEAM=<team_id>.
• يجب التأكد من توقيع ملف الـ IPA بشكل صحيح لنفس الجهاز.

(ملاحظة: عند العمل على المصدر المحلي، يمكن تحديد الفريق مباشرة داخل مشروع agents/ios-xctest-agent. أما في بيئات الـ CI أو حزم NPM، فيجب الاعتماد على المتغير).

توقيع تطبيق iOS غير موثوق أو غير صالح

رسالة الخطأ: IOS_APP_SIGNATURE_NOT_TRUSTED أو IOS_APP_INSTALL_SIGNATURE_INVALID (أو قد يعرض الهاتف رسالة: Astur is no longer available)

السبب: مشكلة تتعلق بـ (Provisioning Profile) أو عدم الوثوق بشهادة المطور، مما يمنع نظام iOS من إطلاق التطبيق أو تثبيته.

الحل:

• تأكد أن ملف الـ IPA مُوقّع لرقم المُعرّف (UDID) الخاص بالجهاز المتصل.
• انتقل إلى إعدادات الـ iPhone (Settings > General > VPN & Device Management) وقم بالوثوق بشهادة المطور الخاصة بك.
• في حال انتهاء صلاحية الـ Provisioning Profile، ستحتاج لإعادة بناء التطبيق.
• تأكد من توافق app.bundleId مع التطبيق.
• لفرض تحديث التطبيق عبر المُولد، استخدم المُعامل --app <path-to.ipa>.
• إذا اختلف فريق التوقيع، احذف التطبيق القديم من الجهاز قبل محاولة تثبيت الجديد.

سلسلة مفاتيح جهاز iOS الحقيقي مقفلة (Keychain Locked)

رسالة الخطأ: IOS_SIGNING_KEYCHAIN_LOCKED (أو ظهور طلب مستمر لـ Password: في الطرفية).

السبب: يحاول Xcode الوصول لشهادة توقيع Apple Development، لكن نظام macOS ينتظر إدخال كلمة مرور سلسلة المفاتيح.

الحل:

• افتح قفل سلسلة المفاتيح (Keychain) قبل بدء Astur.
• في تطبيق Keychain Access، افتح إعدادات شهادة التطوير الخاصة بك واسمح لـ codesign أو Xcode بالوصول دائماً.
• تجنب تشغيل الـ Inspector من واجهة طرفية تمنع انبثاق واجهة المستخدم لإدخال كلمة المرور.
• في أنظمة CI، قم باستيراد الشهادة إلى سلسلة مفاتيح مؤقتة ومفتوحة قبل التشغيل.

جسر جهاز iOS الحقيقي لا يستطيع التسجيل

رسالة الخطأ: IOS_XCTEST_AGENT_START_FAILED (مع مخرجات توضح بدء المشغل وفشله في التسجيل).

الحل:

• ابقِ الهاتف مفتوح القفل أثناء البدء.
• وافق على أي نوافذ جدار حماية (Firewall) في macOS تطلب السماح لاتصالات Node.js.
• يُفضل إبقاء الجهاز متصلاً عبر كابل USB للاستفادة من نفق Xcode/CoreDevice.
• ألغِ تعيين ASTUR_IOS_AGENT_HOST إذا كان يجبر الاتصال عبر شبكة محلية مقيدة.
• تجنب استخدام شبكات VPN أو ميزات عزل الشبكة (Network Isolation) بين الكمبيوتر والهاتف.
• إذا أظهرت السجلات NSURLErrorDomain Code=-1009 أو Local network prohibited، فهذا يعني أن iOS يمنع الاتصال، واستخدام كابل USB هو الحل الأمثل.

---

مشاكل الـ Inspector وشجرة الواجهة

الـ Inspector لا يصبح جاهزاً أبداً

الأعراض: يفتح الـ Inspector، لكن عجلة التحميل تستمر بالدوران إلى الأبد والشارة تعرض Connecting…. شجرة الواجهة فارغة.

التحقق والحلول:

• تبويب متصفح قديم: كل تشغيل جديد لـ codegen يفتح تبويباً جديداً ويستخدم منفذاً مختلفاً. إذا حاولت استخدام تبويب قديم من جلسة سابقة، فلن يتصل أبداً. أغلق التبويبات القديمة وركز على التبويب الجديد.
• تطبيق متبقّي يعيق الاتصال: عادةً يُنظف Astur الجلسات السابقة، لكن إن تعطلت هذه الميزة، ابحث عن عملية XCUITest عالقة وأنهها يدوياً:

  pkill -f "xcodebuild.*AsturIOSAgent"

• حالة التطبيق: إذا كان الـ Inspector يتصل لكن لا تظهر الشجرة، فتأكد أن التطبيق ليس في حالة لا-خمول (Non-idle)، مثل تشغيل فيديو مستمر أو رسوم متحركة لا-منتهية (راجع قسم “أداء iOS واستقراره”).

شجرة الواجهة فارغة في الـ Inspector على iOS

رسالة الخطأ: UI tree unavailable

السبب والحل: تظهر لقطة الشاشة لكن بدون شجرة عناصر؟

• تأكد من تحميل المحاكي وتثبيت التطبيق.
• حدد app.bundleId بشكل صحيح.
• في بيئات التشغيل البطيئة جداً، قد يحتاج Xcode لوقت أطول لبدء الوكيل؛ حاول زيادة agent.launchTimeout.

---

مشاكل وكلاء الاتصال (Agents) الإلزامية

وضع الوكيل الإلزامي على Android بلا نقطة نهاية

رسالة الخطأ: ANDROID_AGENT_ENDPOINT_REQUIRED

الحل:

• اضبط إعداد use.astur.agent.endpoint.
• أو استخدم متغير البيئة ASTUR_ANDROID_AGENT_ENDPOINT.
• إذا كنت في مرحلة انتقالية، استخدم agent.mode: 'auto'.

وضع الوكيل الإلزامي على iOS بلا نقطة نهاية

رسالة الخطأ: IOS_XCTEST_AGENT_ENDPOINT_REQUIRED

الحل: (نفس حلول الـ Android أعلاه، مع استخدام ASTUR_IOS_AGENT_ENDPOINT).

فشل مصافحة الوكيل (Handshake) في الوضع الإلزامي

رسالة الخطأ: ANDROID_AGENT_CONNECT_FAILED أو IOS_XCTEST_AGENT_CONNECT_FAILED

الحل:

• تأكد من صحة الرابط (URL) والمنفذ لنقطة النهاية.
• تحقق من أن نقطة النهاية تدعم بروتوكول HTTP POST لمغلفات الأوامر.
• هل تتطابق منصة نقطة النهاية (Android/iOS) مع جلسة الاختبار الحالية؟

فشل أمر الوكيل في الوضع الإلزامي

رسالة الخطأ: ANDROID_AGENT_COMMAND_FAILED أو IOS_XCTEST_AGENT_COMMAND_FAILED

الحل:

• تحقق من الأمر المُرسل؛ هل هو متوافق مع المخطط المُتوقع من قبل تطبيق الوكيل على الجهاز؟
• راجع سجلات الوكيل على الخادم لمعرفة تفاصيل الفشل الدقيقة.

---

ملاحظة لبيئات Linux و Windows

رسالة: SKIP iOS platform

تفسير: هذه رسالة طبيعية. عملية أتمتة تطبيقات iOS بشكل محلي تتطلب نظام macOS وXcode. إذا كنت تستخدم Linux أو Windows، سيقوم Astur بتخطي اختبارات iOS تلقائياً.