الـ Inspector وتوليد الكود

الـ Inspector في Astur هو سطح التأليف المرئي لاختبارات الجوال. يبثّ شاشة الجهاز، ويقرأ شجرة الواجهة الدلالية عبر بيئة التشغيل نفسها التي تستخدمها الاختبارات، ويرتّب المحدِّدات، ويسجّل الإجراءات، ويصدّر كود @astur-mobile/test.

وخلافًا لأدوات الفحص العامة في WebDriver و Appium، بُني Astur Inspector حول بيئة تشغيل Astur نفسها. وهذا يمنحه ثلاث مزايا عملية:

• المحدِّدات المولَّدة تستخدم محرّك المحدِّدات نفسه الذي سيعمل في اختباراتك
• النقرات والتمرير والتعبئة وتشغيل التطبيق والأذونات والتدوير ولقطات الشاشة تمرّ جميعها عبر جلسة Android/iOS الأصلية نفسها التي يستخدمها @astur-mobile/test
• يستطيع الـ inspector ترتيب المحدِّدات الدلالية محليًا من الشجرة المخزّنة مؤقتًا، بدل انتظار جولة بعيدة كاملة بعد كل اختيار

والنتيجة حلقة تأليف أكثر ديناميكية: افحص، وتفاعل، وسجّل، وعدّل الخطوة المولَّدة، وبدّل الجهاز، وشغّل تطبيقًا آخر مثبّتًا، وتابع دون تغيير الأدوات.

شاهد الـ Inspector أثناء العمل

جولة في الـ INSPECTOR افحص، وتفاعل، وسجّل، وصدّر.

شاهد كيف يحوّل Astur Inspector جلسة جهاز حيّة إلى خطوات اختبار قابلة للصيانة بأسلوب Playwright.

شاهد على YouTube ↗

شغّله بـ:

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

الأمر المجرّد npx astur-mobile codegen --ios يجعل معرّف حزمة iOS الافتراضي com.astur.demo. ولتطبيق iOS الخاص بك مرّر --app و --app-id (أو اضبط ASTUR_IOS_BUNDLE_ID)، أو شغّل التطبيق من أدوات التحكم في الـ Inspector. ولتجربة Astur دون بناء أي شيء، استخدم تطبيق العرض من مستودع أمثلة Astur: --app ./Astur.app --app-id com.astur.demo.

أدوات التحكم في الترويسة

تضم الترويسة أداتين: شارة الجهاز الحالي وزر Controls.

تبديل الأجهزة

تعرض شارة الجهاز الجهازَ النشط. انقرها لفتح قائمة الأجهزة والانتقال إلى جهاز آخر دون إعادة تشغيل الـ Inspector — عبر الأنواع والمنصات: محاكي Android، أو جهاز Android حقيقي، أو محاكي iOS، أو جهاز iOS حقيقي.

عند التبديل، يفكّك Astur جلسة الجهاز الحالية بالكامل قبل الاتصال بالتالي، فلا تعمل جلستان أصليتان في الوقت نفسه أبدًا (وإلا تضاعفت الذاكرة — مشغّلا XCUITest، كلٌّ يحجز محاكيًا، أو وكيلا Android). وتعرض المرآة لوهلة Preparing device… ريثما يتصل الجهاز الجديد.

وتنتقل معاملات التشغيل الأصلية إلى الجهاز الجديد ما دامت منطبقة:

• ينتقل معرّف التطبيق (‏bundle id / package) داخل المنصة نفسها، بما في ذلك بين محاكي iOS والجهاز الحقيقي
• أما ملف --app فلا ينتقل إلا إذا طابق الهدف: ‏.apk لـ Android، و .app مبني للمحاكي لمحاكي iOS، و .ipa موقّع لجهاز iOS حقيقي

حدود التبديل

• بين محاكي iOS والجهاز الحقيقي يبقى معرّف الحزمة دون ملف التطبيق — فملف .app للمحاكي لا يمكن تثبيته على جهاز حقيقي (إذ يحتاج .ipa موقّعًا)، والعكس صحيح. فإن كان التطبيق مثبّتًا أصلًا على الهدف اتصل به التبديل؛ وإلا تعذّر الاتصال.
• التبديل بين المنصات (‏Android ↔ iOS) يُسقط ملف التطبيق كليًا ويفحص الحالة الراهنة للجهاز، لأن .apk و .app/.ipa غير متبادلة.
• التبديل الفاشل غير مدمّر. فإذا عجز Astur عن الاتصال بالجهاز المختار، أعاد الاتصال بالجهاز الذي كنت عليه وأبلغ Switch to <device> failed: … — stayed on <previous>، فتبقى الجلسة صالحة بدل أن تتركك على وكيل مغلق.
• أجهزة iOS الحقيقية ما زالت تتطلب توقيع Apple ووضع المطوّر وتطبيقًا مثبّتًا وموقّعًا للجهاز. ولا يستطيع الـ Inspector إنشاء بناء موقّع من ملف .app للمحاكي؛ فابدأ جلسة جهاز حقيقي بـ --ios --real --app <signed.ipa> للتحكم الكامل.

أدوات التحكم (Controls)

يحوي زر Controls إجراءات الجهاز والتطبيق والجلسة:

• تثبيت ملف APK، أو .app لمحاكي، أو .ipa لجهاز حقيقي
• تشغيل تطبيق مثبّت باسم الحزمة أو معرّفها
• منح الأذونات أو سحبها
• مسح بيانات التطبيق أو ذاكرته حيثما كان مدعومًا
• التدوير والتحديث والقفل وفتح القفل وإخفاء لوحة المفاتيح وإجراءات التنقّل في Android
• إنهاء الجلسة (صف Session — انظر أدناه)

كما يعيد تشغيل تطبيق iOS من Controls ربطَ وكيل XCUITest بمعرّف الحزمة المُدخَل، فتبدأ شجرة الواجهة والتفاعلات الأصلية بالعمل مع ذلك التطبيق.

إنهاء الجلسة

زر Terminate session (‏Controls ← Session) ينهي الـ Inspector بنظافة ويستعيد كل الموارد. وبعد تأكيدك يقوم Astur بـ:

• إغلاق جلسة الجهاز — بإيقاف الوكيل الأصلي أو مشغّل XCUITest كي تُحرَّر ذاكرة المضيف، و
• إطفاء المحاكي كي يتوقف الجهاز الافتراضي عن استهلاك الذاكرة.

أما الأجهزة الحقيقية فتُترك تعمل — إذ لا يُطفئ Astur عتادًا تملكه. ثم يعرض الـ Inspector طبقة Session terminated وتنتهي عملية codegen.

التسجيل

انقر Record، ثم تفاعل مع الشاشة المعروضة.

• تنفّذ النقرات نقرة إحداثية أصلية أولًا، ثم تسجّل أفضل محدِّد دلالي متى توفّر
• وإذا لم يوجد محدِّد ثابت، يسجّل Astur الأمر device.tap({ x, y })
• التمرير بعجلة الفأرة أو السحب فوق المرآة ينفّذ تمريرًا أصليًا
• التمرير متاح أثناء الفحص، ولا يُسجَّل إلا حين يكون Record نشطًا
• يستخدم + Fill و + Expect محرِّرات ضمنية، لا نوافذ المتصفح المنبثقة
• تدعم التأكيدات فحص الظهور والنص المطابق تمامًا والنص المتضمَّن والقيمة والتسمية والنوع

وتظهر كل عملية تفاعل في تبويب Recording Steps كصفّ إجراء + محدِّد قابل للتحرير:

ويحوّل تبويب Code تلك الخطوات إلى ملف اختبار @astur-mobile/test جاهز للتشغيل (بدّل بين TypeScript و JavaScript ثم انسخ):

والكود المصدَّر بسيط عن قصد:

import { test, expect } from '@astur-mobile/test';

test('recorded flow', async ({ device }) => {
  await device.getByLabel('Email').fill('qa@example.com');
  await device.getByRole('button', { name: 'Login' }).tap();
  await expect(device.getByText('Welcome')).toBeVisible();
});

متطلبات شجرة iOS

قد تظهر لقطات محاكي iOS قبل جاهزية الشجرة. وعلى أجهزة iOS الحقيقية يعتمد أول إطار معروض كذلك على وكيل XCUITest بلغة Swift، لأن Apple لا تكشف مسار لقطة شاشة قابلًا للبرمجة عبر devicectl.

ويتطلب فحص شجرة الواجهة والتفاعل الأصلي وكيل XCUITest بلغة Swift. فإذا أشارت اللوحة الجانبية إلى أن الشجرة غير متاحة:

1. تأكد من أن التطبيق مثبّت على المحاكي أو الجهاز المختار.
2. شغّله أو أعد ربطه من Controls بمعرّف حزمة التطبيق.
3. أو أعد تشغيل codegen بـ --ios --app-id <bundle-id>.
4. وللأجهزة الحقيقية، اضبط ASTUR_IOS_DEVELOPMENT_TEAM كي يمكن توقيع مشغّل XCUITest.
5. وإذا أظهرت الطرفية Password: مرارًا، فافتح قفل سلسلة مفاتيح الدخول في macOS أو اسمح لـ codesign بالوصول إلى شهادة Apple Development.
6. راجع npx astur-mobile doctor --verbose إذا فشل Xcode أو فشل بناء الوكيل.

‏Apple XCTest

هذا متطلب من Apple XCTest نفسها. وليس اعتمادًا على Appium أو WebDriver.

تأخّر التحديث

إذا كانت الشجرة ظاهرة لكن الترويسة أشارت لوهلة إلى UI tree refresh delayed، فإن Astur يُبقي آخر شجرة سليمة بينما لقطة XCUITest التالية ما زالت تعمل. وتبقى المرآة صالحة للاستخدام؛ ومن المفترض أن يزول التحذير بعد أول تحديث ناجح للشجرة.

‏DOM داخل WebView

حين يحتوي الجهاز على WebView قابل للفحص داخل التطبيق، يدمج الـ inspector شجرة DOM الخاصة به داخل شجرة الواجهة تحت العقدة الأصلية المضيفة لـ WebView. ويعرض كل عنصر ويب المحدِّد الثابت نفسه الذي يولّده Astur للاختبارات (getByTestId / getById / getByRole / getByText)، وتقود أداتا Fill و Tap عناصر الويب عبر محدِّد DOM الخاص بها — دون تخمين إحداثيات.

وهذا يعيد استخدام device.webContext()، فيعمل مع WebView في ‏Flutter و React Native على Android (‏Chromium WebView/CDP) وعلى iOS — على المحاكي والأجهزة الحقيقية معًا — عبر ios-webkit-debug-proxy. وتُستطلَع شجرة DOM بوتيرة خلفية ولا تحجب الشجرة الأصلية أبدًا. راجع WebViews (DOM) للإعداد ومصفوفة دعم المنصات.

حدود المنصات

التشغيل على أجهزة iOS الحقيقية مدعوم للأجهزة الموصولة بـ USB والموثوقة مع تفعيل وضع المطوّر. وما زال يحتاج توقيع Apple: اضبط ASTUR_IOS_DEVELOPMENT_TEAM، واستخدم تطبيقًا موقّعًا للجهاز، ولا تضبط ASTUR_IOS_AGENT_HOST إلا إذا عجز الهاتف عن الوصول إلى عنوان Mac الذي يكتشفه Astur تلقائيًا.

وعلى أجهزة iOS الحقيقية تستخدم الاختبارات أوامر أصلية موجّهة، وهي المسار الموثوق. أما رسم شجرة الـ Inspector فما زال يعتمد على لقطات إمكانية وصول عريضة من XCTest، فتصبح الشاشة المعروضة صالحة للاستخدام حالما يستطيع الوكيل إعادة الإطارات، بينما قد تصل الشجرة لاحقًا أو تتحدّث ببطء على الشاشات الكبيرة. فضّل محاكي iOS للتأليف وتوليد الكود حين تحتاج شجرة حيّة سريعة؛ واستخدم الأجهزة الحقيقية للتحقق النهائي السريع، ريثما يحصل الـ Inspector على بثّ مضغوط للشجرة الأصلية.

والتعامل مع تنبيهات النظام محدود بما يكشفه XCTest. فيستطيع Astur الاستعلام عن التنبيهات التي يراها XCTest والتفاعل معها، لكن iOS لا يكشف كل نافذة نظام أو لوحة أذونات عبر استعلامات التطبيق العادية بشكل ثابت عبر الإصدارات.

ومسح بيانات أو ذاكرة تطبيق على محاكي iOS يتم عمدًا بإعادة التثبيت. فالأمر simctl يدعم التثبيت وإلغاء التثبيت والتشغيل والإنهاء وضوابط الخصوصية، لكنه لا يكشف واجهة مباشرة لمسح بيانات أو ذاكرة تطبيق بعينه كما يوفّر Android عبر أوامر مدير الحِزم.

والمصدر في agents/ios-xctest-agent/ هو وكيل XCUITest المرفق بلغة Swift. وهو جانب iOS الأصلي من Astur: يرتبط بمعرّف حزمة التطبيق، ويقرأ شجرة إمكانية الوصول، وينفّذ النقر والتعبئة والتمرير أصليًا، ويلتقط لقطات شاشة الأجهزة الحقيقية، ويعيد نتائج JSON مضغوطة إلى بيئة Node.js. وهو لا يزيل قيود Apple في التوقيع والـ provisioning وواجهات النظام على الأجهزة الحقيقية.

ملاحظات الأداء

يستخدم اختيار العناصر في الـ Inspector الشجرة الدلالية المخزّنة مؤقتًا لترتيب المحدِّدات، فلا ينبغي أن يستدعي النقر على العناصر قراءة كاملة للشجرة في كل اختيار. وتُنفَّذ إجراءات التسجيل عبر إيماءات إحداثية أصلية أولًا، تفاديًا لإعادة المحاولات البطيئة على المحدِّدات أثناء تفاعل المستخدم مع المرآة.

وإيماءات التمرير محدودة المعدّل على جانبي المتصفح والخادم. فالتمرير السريع بلوحة اللمس يُجمَّع في تمريرات أصلية محدودة، كي لا يستقبل الجهاز طابورًا غير محدود من الإيماءات.

ويرتبط خادم الـ inspector بالعنوان 127.0.0.1 فقط. فهو يمنح تحكمًا كاملًا بالجهاز عبر اتصال محلي دون مصادقة، ولذلك لا يمكن الوصول إليه عمدًا من أجهزة أخرى على الشبكة. افتح الرابط المطبوع http://localhost:<port> على جهاز Mac نفسه الذي بدأ الجلسة.