تخطَّ إلى المحتوى
AsturAsturAstur

المتطلبات

على الرغم من أن Astur صُمم ليتجاوز خادم Appium كلياً، إلا أنه يعتمد في جوهره على أدوات المنصات الأصلية المدعومة رسمياً من قِبل Android وiOS.

الأنظمة المدعومة

Section titled “الأنظمة المدعومة”
نظام التشغيل Android (أجهزة ومحاكيات) محاكي iOS جهاز iOS حقيقي
macOS مدعوم مدعوم مدعوم
Linux مدعوم غير مدعوم غير مدعوم محلياً
Windows مدعوم غير مدعوم غير مدعوم محلياً

تتطلب الأتمتة المحلية لنظام iOS بيئة تشغيل macOS، وذلك لحصرية أدوات Apple مثل المحاكي، و Xcode، والأوامر (xcrun, simctl, xcodebuild)، وإطار XCTest على هذا النظام.

متطلبات عامة (لكافة المستخدمين)

Section titled “متطلبات عامة (لكافة المستخدمين)”
  • إصدار Node.js 18 أو ما بعده.
  • إصدار npm 9 أو ما بعده.
  • إطار Playwright Test (يُثبّت تلقائياً عبر الاعتمادية @astur-mobile/test).
  • طرفية (Terminal) تدعم الوصول لأدوات المنصة عبر متغير المسار PATH.

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

Terminal window
node --version
npm --version
npx astur-mobile doctor

متطلبات نظام Android

Section titled “متطلبات نظام Android”
  • حزمة Android SDK.
  • أدوات منصة أندرويد (Android SDK Platform Tools).
  • تضمين الأداة adb ضمن متغير PATH.
  • توفر محاكي Android واحد على الأقل أو جهاز فعلي متصل عبر USB.
  • تفعيل “تصحيح أخطاء USB” (USB debugging) عند العمل على الأجهزة الحقيقية.

إعدادات البيئة الموصى بها:

Terminal window
export ANDROID_HOME="$HOME/Library/Android/sdk"
export ANDROID_SDK_ROOT="$ANDROID_HOME"
export PATH="$ANDROID_HOME/platform-tools:$ANDROID_HOME/emulator:$PATH"

يتوجب على مستخدمي Linux و Windows تعديل المسارات السابقة لتتوافق مع مكان تثبيت Android SDK لديهم.

للتأكد من الإعداد السليم:

Terminal window
adb version
adb devices -l
npx astur-mobile devices --android

متطلبات نظام iOS

Section titled “متطلبات نظام iOS”

كما أشرنا، يتطلب iOS نظام التشغيل macOS. اطلع على الجدول التالي لتحديد متطلباتك؛ علماً أن أتمتة المحاكي لا تتطلب توقيعاً رقمياً من Apple، بعكس الأجهزة الحقيقية.

المتطلب محاكي iOS جهاز حقيقي (iPhone / iPad)
macOS مع Xcode (مفتوح مسبقاً والموافقة على الشروط) إلزامي إلزامي
أدوات Xcode المساعدة (xcrun, simctl, xcodebuild) إلزامي إلزامي
تثبيت بيئة تشغيل المحاكي من داخل Xcode إلزامي —
أداة devicectl (مرفقة مع Xcode) — إلزامي
التطبيق المستهدف ملف بصيغة .app ملف بصيغة .ipa (موقّع)
معرف فريق التطوير لدى Apple (ASTUR_IOS_DEVELOPMENT_TEAM) غير إلزامي إلزامي
الوثوق بالجهاز وتفعيل وضع المطور (Developer Mode) — إلزامي
وكيل XCUITest المرفق يُبنى ويُشغل تلقائياً بواسطة Astur يُبنى، ويُوقع، ويُشغل تلقائياً

لا تتدخل يدوياً لتثبيت الوكيل، فـ Astur يتكفل ببناء مشغل XCUITest بلغة Swift وتنفيذه في كل جلسة اختبار. وعلى الأجهزة الحقيقية يقوم أيضاً بتوقيعه باستخدام بيانات فريقك؛ وهي الخطوة الإضافية الوحيدة مقارنة بالمحاكيات.

للتحقق من أدوات iOS:

Terminal window
xcodebuild -version
xcrun simctl list devices available   # استعراض المحاكيات
xcrun devicectl list devices          # استعراض الأجهزة الحقيقية
npx astur-mobile devices --ios
npx astur-mobile doctor --verbose

قبل البدء بالإعداد، حدد المسار المناسب لطبيعة عملك:

الغرض هل أحتاج لبناء التطبيق أولاً؟ الملف المتوقع توقيع Apple أمر التشغيل المرجعي
استخدام أداة Inspector أو توليد الكود على محاكي لا (استخدم التطبيق التجريبي .app) Astur.app لا npx astur-mobile codegen --ios --simulator --app ./Astur.app --app-id com.astur.demo
اختبار تطبيقي الخاص على محاكي نعم التطبيق بصيغة .app لا عيّن app.path في الإعدادات وشغّل npx astur-mobile test
الاختبار على جهاز فعلي نعم التطبيق بصيغة .ipa (موقع) نعم (عبر ASTUR_IOS_DEVELOPMENT_TEAM) npx astur-mobile codegen --ios --real --device <device-udid> --app ./MyApp.ipa --app-id com.example.myapp

لتبسيط البداية، ننصح بالاعتماد على التطبيق التجريبي (Astur.app أو astur.demo.ios.ipa بمعرف com.astur.demo) المتاح ضمن أمثلة المستودع لتجربة الأتمتة قبل الخوض في إعداد تطبيقك الخاص.

الفارق الأبرز يكمن في نوع الملف المستهدف: المحاكي يعتمد على ملفات .app، بينما تحتاج الأجهزة الحقيقية إلى .ipa.

Astur يغنيك عن تجهيز خادم Appium المستقل أو ربط WebDriver وتثبيت XCTest بشكل يدوي؛ حيث يقوم آلياً بتجميع وكيل XCUITest المبرمج بـ Swift وتشغيله عند الحاجة.

إذا حاولت التشغيل بواسطة --app-id دون تحديد مسار التطبيق ولم يكن مثبتاً سلفاً، سينتهي الأمر بالخطأ IOS_APP_NOT_INSTALLED. لذا، أضف خيار --app متبوعاً بمسار تطبيقك في الجلسة الأولى ليتمكن الإطار من تنصيبه بسلاسة.

إضافة إلى ذلك، يلزمك في الأجهزة الحقيقية:

  • ربط حساب Apple Developer داخل Xcode.
  • جهاز موصول بالـ USB وموثوق.
  • تفعيل “وضع المطور” على الجهاز.
  • ملف تطبيق موقع لنفس الجهاز.
  • تحديد ASTUR_IOS_DEVELOPMENT_TEAM ليطابق معرف فريقك.

إعدادات البيئة المقترحة لجهاز فعلي:

Terminal window
export ASTUR_IOS_DEVELOPMENT_TEAM=ABCDE12345
# يُستخدم فقط للضرورة إن فشل الهاتف في التعرف على الجسر المحلي.
export ASTUR_IOS_AGENT_HOST=192.168.0.14

المحاكيات معفاة من إضافة ASTUR_IOS_DEVELOPMENT_TEAM وشهادات Apple.

على الرغم من قيام Astur بالتوقيع نيابة عنك، تفرض Apple جلب الاعتمادات من جهازك المحلي أو بيئة (CI). إذا كنت تختبر مباشرة من مصدر المشروع وكان معداً في Xcode، سيتمكن Astur من سحب بيانات التوقيع آلياً. خلاف ذلك، ستحتاج لتعيين ASTUR_IOS_DEVELOPMENT_TEAM.

يتم الاتصال عادةً بالأجهزة عبر منفذ CoreDevice. لذا، تجاوز تعيين ASTUR_IOS_AGENT_HOST ما لم يكن من الضروري توجيه الجهاز لعنوان شبكة محدد لجهاز الـ Mac.

التحكم بعناصر الويب (WebView) في iOS (خطوة إضافية)

Section titled “التحكم بعناصر الويب (WebView) في iOS (خطوة إضافية)”

تعتبر هذه الخطوة ضرورية فقط إذا رغبت بالتحكم الصريح في عناصر DOM لمحتوى الـ WebView عبر (device.webContext() / webview()) على نظام iOS. أما التفاعل مع المحددات الأصلية في صفحات الـ WebView فلا يتطلب أي إعداد إضافي.

  • تثبيت الأداة المساعدة brew install ios-webkit-debug-proxy (إصدار 1.9 فأعلى).
  • التأكد من إدراج الخيار WKWebView.isInspectable = true في الكود المصدري للتطبيق (متاح للإصدار iOS 16.4 وأحدث).
  • للأجهزة الحقيقية: اذهب إلى الإعدادات > Safari > متقدم، وفعّل “Web Inspector”.

يدعم هذا النظام كلا من الأجهزة الحقيقية والمحاكيات مع قدرة Astur على اكتشاف منفذ Web Inspector آلياً.

متطلبات التشغيل لتطبيقات Flutter

Section titled “متطلبات التشغيل لتطبيقات Flutter”

يدير Astur اختبار تطبيقات Flutter دون وساطة Appium ودون الحاجة لمشغل خارجي:

  • نظام Android: وجه إعداداتك لملف APK من نوع debug (أو profile)، نظراً لافتقار إصدارات release لخدمة Dart VM. ستحتاج كذلك لتوافر أداة flutter في المتغير PATH (أو ASTUR_FLUTTER_PATH) مع تعيين المسار الرئيسي لمشروعك عبر المتغير ASTUR_FLUTTER_PROJECT.
  • نظام iOS: تُفحص الواجهة من خلال شجرة الوصول المدعومة في XCUITest (بسبب غياب Dart VM). وفر تطبيق Runner.app مُعدّاً للمحاكي وتأكد من تفعيل خواص الوصول (semantics) حتى يتسنى قراءة التسميات.
  • يوصى باستخدام معرفات ثابتة على شكل Semantics(identifier: 'login-email-input') لتمكين getById() من التعرف عليها؛ حيث تعمل الأوامر getByText و getByLabel بالاعتماد على النصوص المرئية وتسميات العناصر.

للمزيد من الإرشادات المفصلة حول أطر العمل، راجع الدليل المخصص في Flutter و React Native وكذلك قسم حدود المنصات لفهم الاختلافات التقنية.

قيود النسخة التجريبية الحالية

Section titled “قيود النسخة التجريبية الحالية”
  • تعتمد الأتمتة الأساسية على نظام Android على وكيل Kotlin UIAutomator، ليتولى فحص الشجرة الحية، وإدارة المحددات، والانتظار، والتحكم بلوحة المفاتيح.
  • يحتفظ ADB بصلاحياته على نظام Android في إجراءات دورة حياة التطبيق، مثل: التثبيت، والتشغيل، وتمرير المنافذ، وجمع السجلات واللقطات المرئية.
  • المسار البديل (ADB/UIAutomator XML) ما زال متاحاً لأغراض الانتقال، إلا أنه لم يعد المسار الأساسي.
  • تُجرى أتمتة الـ DOM لتطبيقات WebView في Android بالاعتماد على “Chrome DevTools Protocol” بمجرد تفعيل المُطور لخيار التصحيح.
  • تستند أتمتة iOS، في كل من المحاكي والجهاز الفعلي، إلى وكيل XCUITest المبني بلغة Swift.
  • تستخدم محاكيات iOS أمر simctl، بينما تعتمد الأجهزة الحقيقية على أمر devicectl في مهام الإدارة الأساسية.
  • الأجهزة الحقيقية في iOS تلزم مطوريها بتوقيع التطبيقات يدوياً عبر ASTUR_IOS_DEVELOPMENT_TEAM.
  • تخضع الأذونات المتقدمة في الأجهزة الحقيقية لنظام iOS لقيود منصات Apple العامة؛ ما يفرض الاعتماد على تقنية “إعادة التثبيت” لمسح البيانات أو الاعتماد على التوافر. إذا لم يتوفر التسجيل الأصلي سيُرفق تحذير بدلاً من إفشال الاختبار.
  • تتطلب أتمتة الـ DOM عبر WKWebView في iOS أداة ios-webkit-debug-proxy وتفعيل التصحيح كلياً في كود التطبيق، بينما تظل المحددات الأصلية فاعلة ومستقلة.

إعدادات إضافية اختيارية (نقطة اتصال الوكيل)

Section titled “إعدادات إضافية اختيارية (نقطة اتصال الوكيل)”

بفضل مرونة Astur، تُدار كافة الوكلاء في البيئة المحلية بصورة ذاتية، ولا يستلزم تخصيص نقطة اتصال إلا إذا كنت تدير وكيل المنصة بنفسك في بيئة تشغيل مفصولة.

  • تأمين الوصول لنقطة اتصال مرتبطة بوكيل المنصة المطلوبة.
  • تحديد الوكيل المتوافق بناءً على المنصة (مثلاً نقطة اتصال android للاختبار على الأندرويد، وهكذا).
  • تخصيص أوقات المهلة (Timeouts) بما يخدم بيئة الشبكة لديك متى دعت الحاجة.

إليك كيفية ضبط المتغيرات:

Terminal window
export ASTUR_ANDROID_AGENT_ENDPOINT=tcp:127.0.0.1:8787
export ASTUR_IOS_AGENT_ENDPOINT=http://127.0.0.1:8788

السياسة الافتراضية لمنصات التشغيل تعتمد على منهج “الوكيل أولاً”:

  • نظام Android: automation.engine: 'agent', agent.mode: 'required', legacyFallback: 'never', startupTimeoutMs: 30_000, commandTimeoutMs: 20_000
  • نظام iOS: automation.engine: 'agent', agent.mode: 'required', legacyFallback: 'never', startupTimeoutMs: 60_000, commandTimeoutMs: 15_000

إذا رغبت في العودة للمسار الأقدم ADB/UIAutomator، يمكنك تعيين automation.engine: 'auto'. ويظل الخيار لك لتخصيص هذه القيم من خلال use.astur.automation أو use.astur.agent ضمن ملف الإعدادات؛ على الرغم من أن السلوك الافتراضي يعد كافياً ومناسباً للغالبية العظمى من المشاريع.

ادعم Asturكن راعياً