مرجع واجهة الأوامر

يتم توزيع Astur من خلال الحزمة astur-mobile لأن الاسم المختصر astur كان محجوزاً مسبقاً على npm. ولكن، لا يزال الملف التنفيذي نفسه يحمل الاسم astur.

عند العمل من داخل هذا المستودع، استخدم:

npx astur-mobile <command>

أما بعد التثبيت المحلي، تتيح لك npm أيضاً استخدام الأمر المختصر:

npx astur <command>

doctor

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

npx astur-mobile doctor
npx astur-mobile doctor --verbose

تقوم المخرجات الافتراضية بإخفاء الأخطاء الطويلة الناتجة عن الأوامر. يمكنك استخدام خيار --verbose لعرض المخرجات الكاملة الصادرة من الـ ADB أو Xcode أو المحاكي.

devices

يستعرض هذا الأمر قائمة شاملة بأجهزة Android، محاكيات iOS، وأجهزة iOS الفعلية المتصلة بجهازك.

npx astur-mobile devices
npx astur-mobile devices --android
npx astur-mobile devices --ios

استخدم قيمة id الظاهرة في المخرجات ضمن المتغير use.astur.device.id في ملف إعداداتك playwright.config.ts.

• على Android: تُمثل هذه القيمة الرقم التسلسلي لجهاز الـ ADB، مثلاً emulator-5554 للمحاكي، أو رقم الـ USB التسلسلي للهاتف الفعلي.
• على iOS: تُمثل مُعرف الـ UDID الخاص بالمحاكي (من خلال simctl) أو مُعرف الـ UDID للجهاز الفعلي (من خلال devicectl).

يحدد platform نوع المُشغل المستخدم (Android أم iOS). أما الخيار device.kind فهو مجرد فلتر اختيار غير مُلزم، مثل تحديد “أي محاكي” أو “أي جهاز Android فعلي”. وعند تمرير id محدد، فلن تحتاج عادةً لاستخدام kind.

أمثلة الاستخدام:

// محاكي Android قيد التشغيل بالفعل.
device: { id: 'emulator-5554' }

// جهاز Android فعلي ظهر في قائمة adb devices -l.
device: { id: 'R5CT123456A' }

// محاكي iOS باستخدام الـ UDID.
device: { id: '4E2F2A1D-9B8A-4D41-8E5F-123456789ABC' }

// محاكي iOS باستخدام الاسم التجاري.
device: { name: 'iPhone 16 Pro' }

// جهاز iOS فعلي باستخدام الـ UDID.
device: { kind: 'real', id: '00008030-000548220EF0802E' }

// محدد مرن: أي محاكي Android متصل حالياً.
device: { kind: 'emulator' }

ملاحظة: عند تشغيل --ios على أنظمة Linux و Windows، سيعرض النظام رسالة توضح قيود المنصة بدلاً من إنهاء العملية بخطأ.

init

يبدأ معالج الإعداد التفاعلي ليساعدك في توليد ملفات المشروع الأساسية:

npx astur-mobile init

إذا كنت تعمل في بيئات التكامل المستمر (CI)، أو إعدادات العرض التوضيحي، أو من خلال أوامر غير تفاعلية، يمكنك استخدام خيار --yes لتبني الإعدادات الافتراضية لمحاكي Android:

npx astur-mobile init --yes

سيطرح عليك معالج الإعداد بضعة أسئلة:

• هل ترغب بالعمل على Android، أو iOS، أو كليهما؟
• هل تستهدف محاكي Android، أم محاكي iOS، أم جهازاً فعلياً، أم إعداد BrowserStack المبدئي؟
• هل لديك مسار لتطبيق محلي، أم رابط تنزيل، أم حزمة/مُعرف لتطبيق مثبت بالفعل؟
• ما هي المهلة الزمنية الافتراضية (Timeout) لعناصر الواجهة؟
• هل تفضل تقارير HTML أم JUnit؟
• ما هي إعداداتك لالتقاط صور الشاشة، وتسجيل الفيديو الأصلي، وتتبّع Playwright؟

الملفات التي سيتم إنشاؤها:

• playwright.config.ts
• tests/example.test.ts
• .gitignore
• ASTUR_SETUP.md

لا تقلق، لن يقوم Astur بالكتابة فوق أي ملفات موجودة بالفعل.

تنويه: يتم إعداد BrowserStack بمتغيرات البيئة اللازمة، لكن التنفيذ الفعلي على السحابة غير متوفر في الإصدار التجريبي الحالي. في المقابل، العمل على المحاكيات المحلية والأجهزة الفعلية مدعوم بالكامل ومتاح للاستخدام الفوري.

test

يُشغل إطار عمل Playwright Test لاختباراتك:

npx astur-mobile test
npx astur-mobile test tests/login.test.ts
npx astur-mobile test --project android-pixel

يُمكنك الاعتماد على ملف playwright.config.ts للتحكم في كيفية عمل الوكيل الأصلي وسلوك نقطة الاتصال:

• استخدم agent.mode: 'auto' في المراحل الانتقالية والبيئات المزدوجة.
• استخدم agent.mode: 'required' لفرض قيود صارمة في بيئات الـ CI.
• استخدم agent.mode: 'off' لإجبار النظام على استخدام أدوات المنصة البديلة.

متغيرات البيئة للتحكم في نقاط الاتصال (Endpoints) حسب المنصة:

• ASTUR_ANDROID_AGENT_ENDPOINT
• ASTUR_IOS_AGENT_ENDPOINT

codegen

يطلق هذا الأمر جلسة حية للـ Inspector وتوليد الكود، مدعومة ببيئة التشغيل الفعلية، وتستخدم ذات محرك المحددات (Selectors Engine) المتوفر في @astur-mobile/core.

npx astur-mobile codegen
npx astur-mobile codegen --android --device emulator-5554 --app ./MyApp.apk --app-id com.example.myapp
npx astur-mobile codegen --ios --simulator --app ./MyApp.app --app-id com.example.myapp
npx astur-mobile codegen --ios --real --device <device-udid> --app ./MyApp.ipa --app-id com.example.myapp

مميزات وسلوك الإصدار التجريبي الحالي:

• يكتشف تلقائياً أي جهاز متصل أو محاكي قيد التشغيل (أو يمكنك تحديده عبر --device).
• يتكفل بتثبيت التطبيق وتشغيله في حال تم تزويده بالخيارات --app و/أو --app-id.
• يفتح واجهة الـ Inspector الحية في المتصفح بشكل افتراضي.
• يبث لقطات شاشة متزامنة وتحديثات فورية لشجرة الواجهة الدلالية من الجلسة النشطة.
• يُنظم اقتراحات المحددات من الشجرة المخزنة لضمان استجابة سريعة للاختيار.
• يُترجم النقرات على الشاشة كأحداث إحداثية حقيقية، ويُلحق بها أفضل محدد دلالي فور توفره.
• يرصد حركات التمرير (Scroll) بالماوس ويحولها إلى أوامر device.swipe(...).
• يُتيح التبديل بين الأجهزة بكل بساطة من خلال الترويسة دون الحاجة لإعادة تشغيل الـ codegen.
• يضع أدوات التحكم الأساسية للتطبيق والجهاز بين يديك في قائمة Controls.
• يوفر إمكانية تثبيت حزم الـ APK، أو .app للمحاكيات، أو .ipa للأجهزة الفعلية، وتشغيل التطبيقات المثبتة مسبقاً، وإدارة الأذونات، ومسح البيانات الخاصة بالتطبيقات في حال كانت المنصة تدعم ذلك.
• يتيح لك تصدير الأكواد بصيغتي TypeScript أو JavaScript بتوافق تام مع @astur-mobile/test.

قد يُلاحظ تأخر طفيف لظهور الشجرة بعد عرض الشاشة، وهو أمر اعتيادي. يتطلب أخذ اللقطات وفحص الشجرة وإجراءات الأجهزة الفعلية وجود وكيل iOS صحي متصل بمُعرف التطبيق. عند تشغيل أمر npx astur-mobile codegen --ios مجرداً، سيُعتمد المُعرف الافتراضي com.astur.demo؛ لذا استعمل --app-id (أو المتغير ASTUR_IOS_BUNDLE_ID) لتحديد تطبيقك. يُرجى أيضاً التأكد دائماً من تمرير مسار ملف الـ .app أو الـ .ipa مع الخيار --app في أول تشغيل لكي يستطيع Astur تثبيته — وإلا ستحصل على الخطأ IOS_APP_NOT_INSTALLED. ولتشغيل أجهزة iOS الفعلية، يجب ضبط المتغير ASTUR_IOS_DEVELOPMENT_TEAM ليسمح لـ Xcode بتوقيع الوكيل XCUITest، مع التأكد من أن سلسلة المفاتيح (Keychain) في الـ macOS مفتوحة ومتاحة للاستخدام. أخيراً، في حالة تعذر قراءة الشجرة، سيعرض الـ Inspector رسالة توضيحية للخطأ في شريط الحالة العلوي بدلاً من عرض مساحة فارغة مُبهمة.

الخيارات المتاحة (Flags):

• --android أو --ios
• --platform android|ios
• --device <id>
• --app <path>
• --app-id <package-or-bundle-id>
• --ui (الوضع الافتراضي)
• --no-ui
• --no-launch
• --json

screenshot

يلتقط شاشة جهاز متصل ويحفظها بصيغة PNG، دون كتابة أي اختبار.

npx astur-mobile screenshot
npx astur-mobile screenshot -o home.png
npx astur-mobile screenshot --android --device emulator-5554

يقبل خيارات اختيار الجهاز نفسها التي يقبلها codegen. ولا يثبّت شيئاً ولا يشغّل شيئاً — فالتقاط الشاشة يجب ألا يغيّر ما عليها.

inspect

اسم رديف (Alias) يُستخدم كبديل للأمر codegen.