عرض تقارير نسبة استخدام رموز الصفحة (باستخدام وكيل على الجهاز فقط)

يمكن لمكوّن إضافي لنظام Gradle المتوافق مع Android (AGP) إنشاء تقارير حول نسبة استخدام رموز الصفحة في اختبارات لقياس حالة التطبيق باستخدام وكيل تغطية على الجهاز فقط. يستخدم مكوّن AGP الإضافي تلقائيًا أداة JaCoCo لتجهيز فئات تطبيقك عند إنشائه، ما يعني أنّه يضيف رمزًا يسجّل أجزاء تطبيقك التي يتم تشغيل الاختبارات فيها. باستخدام وكيل التغطية على الجهاز فقط، ينشئ AGP تطبيقك بدون هذا الرمز الإضافي، ويزوّد الوكيل فئات تطبيقك بأدوات على الجهاز الاختباري أثناء تنفيذ الاختبارات. توضّح هذه الصفحة كيفية تفعيل نسبة استخدام رموز الصفحة على الجهاز فقط وإنشاء التقارير.

مقارنةً بنسبة استخدام رموز الصفحة في مدّة التصميم، توفّر نسبة استخدام رموز الصفحة على الجهاز فقط المزايا التالية:

  • عمليات إنشاء أسرع: لا يشغّل المكوّن الإضافي لنظام Gradle المتوافق مع Android خطوة قياس JaCoCo على فئات تطبيقك وتبعياتها، ما قد يقلّل من أوقات الإنشاء بنسبة تتراوح بين %10 و%20.
  • حِزم APK أصغر حجمًا لتصحيح الأخطاء: لا يضيف مكوّن AGP رمز تتبُّع التغطية إلى فئات تطبيقك، ما قد يؤدي إلى تقليل حجم حزمة APK لتصحيح الأخطاء بنسبة تتراوح بين %20 و%25.
  • عدم تضمين الفئات التي تم إنشاؤها وغير المستخدَمة في التقارير: لا تؤدي الفئات التي تم إنشاؤها ولا تستخدمها الاختبارات إلى خفض أرقام التغطية.

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

المتطلبات الأساسية

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

  • الإصدار 9.6.0-alpha01 من "مكوّن Android الإضافي لبرنامج Gradle" أو إصدار أحدث
  • جهاز أو محاكي يعمل بنظام التشغيل Android 9 (مستوى واجهة برمجة التطبيقات 28) أو إصدار أحدث
  • نوع إصدار قابل للتصحيح للصيغة التي تختبرها، مثل نوع الإصدار التلقائي debug. يمكن ربط الوكيل بالتطبيقات القابلة للتصحيح فقط.
  • الاختبارات لقياس حالة التطبيق التي يتم إجراؤها باستخدام AndroidJUnitRunner أو أداة تشغيل اختبارات مخصّصة تعمل على توسيع نطاقها.

تفعيل نسبة استخدام رموز الصفحة على الجهاز فقط

تستخدم نسبة استخدام رموز الصفحة على الجهاز فقط السمة enableAndroidTestCoverage نفسها التي تستخدمها نسبة استخدام رموز الصفحة في وقت الإنشاء. اضبط enableAndroidTestCoverage على true في ملفات التصميم على مستوى الوحدة لكل صيغة تريد الحصول على تقارير التغطية لها:

Kotlin

android {
    // ...
    buildTypes {
        debug {
            // Enable coverage for instrumentation tests
            enableAndroidTestCoverage = true
        }
    }
}

أنيق

android {
    // ...
    buildTypes {
        debug {
            // Enable coverage for instrumentation tests
            enableAndroidTestCoverage true
        }
    }
}

بعد ذلك، فعِّل وكيل التغطية على الجهاز فقط وتجميع التقارير في ملف gradle.properties الخاص بمشروعك:

android.experimental.androidTest.coverage.useOnDeviceAgent=true
android.experimental.reportAggregationSupport=true

تُنشئ ميزة "نسبة استخدام رموز الصفحة على الجهاز فقط" تقرير HTML باستخدام العارض نفسه المستخدَم في تقارير نسبة استخدام رموز الصفحة الموحّدة، لذا تتطلّب كلتا السمتَين.

إنشاء تقارير حول نسبة استخدام رموز الصفحة على الجهاز فقط

لتشغيل اختبارات لقياس حالة التطبيق وإنشاء تقارير التغطية، عليك توصيل جهاز أو تشغيل محاكي، ثم تنفيذ المهمة التالية:

نطاق التغطية الأمر الإبلاغ عن الموقع الجغرافي
صيغة واحدة ./gradlew :module-name:createVariantNameAndroidTestCoverageReport path-to-your-project/module-name/build/reports/coverage/androidTest/variant/connected/index.html

الاختلافات عن نسبة استخدام رموز الصفحة في وقت الإنشاء

يمكن أن تعرض تقارير التغطية على الجهاز فقط وأثناء عملية الإنشاء نتائج مختلفة للاختبارات نفسها. يُرجى وضع نقاط الاختلاف التالية في الاعتبار عند مقارنة التقريرَين، أو عند نقل حدود التغطية من أحدهما إلى الآخر:

المنطقة نسبة استخدام رموز الصفحة في وقت الإنشاء نسبة استخدام رموز الصفحة على الجهاز فقط
حالات قياس أداء الفئات عندما ينشئ "المكوّن الإضافي لنظام Gradle المتوافق مع Android" تطبيقك، باستخدام JaCoCo على جهاز الاختبار أثناء إجراء الاختبارات، باستخدام وكيل التغطية
الفئات في التقرير جميع الصفوف في الوحدة الصفوف في مساحة الاسم الخاصة بالوحدة التي يتم تحميلها أثناء تشغيل الاختبارات فقط، وبالتالي يمكن أن تكون نِسب التغطية أعلى
Instruction counts تعليمات الرمز الثنائي في Java تعليمات رمز DEX الثنائي
Branch counts الفروع في رمز بايت Java الفروع في رمز بايت DEX يمكن لبرنامج D8 تجميع الشروط في فروع مختلفة، وتستبعد كل أداة فروعًا مختلفة من إنشاء برنامج التجميع، لذا يمكن أن تختلف الأعداد.
العدادات التعليمات والفروع والأسطر والتعقيد والطرق والفئات التعليمات والفروع والأسطر والطرق والفئات لا تتوفّر عدّادات التعقيد بعد.
الأجهزة الاختبارية جميع مستويات واجهة برمجة التطبيقات التي يتوافق معها تطبيقك الإصدار 9 من نظام التشغيل Android (المستوى 28 لواجهة برمجة التطبيقات) والإصدارات الأحدث
بيانات التغطية الأولية ‫.ec ملف ملفات coverage_metadata.pb وcoverage_hits.pb

للعودة إلى نسبة استخدام رموز الصفحة في وقت الإنشاء، اضبط android.experimental.androidTest.coverage.useOnDeviceAgent=false أو أزِل السمة. ولست بحاجة إلى تغيير ملفات الإصدار أو المهام التي تنفّذها.

المشاكل المعروفة

تتضمّن نسبة استخدام رموز الصفحة على الجهاز فقط المشاكل المعروفة التالية:

  • الفئات التي لا يتم تحميلها: لا تظهر في التقرير الفئات التي لا يتم تحميلها مطلقًا أثناء إجراء الاختبارات. وتدرجها تقارير نسبة استخدام رموز الصفحة في وقت الإنشاء بنسبة استخدام% 0.
  • التقارير المجمّعة: إذا كان مشروعك يجمع أيضًا بيانات التغطية من اختبارات المضيف، مثل اختبارات الوحدات، فإنّ تقرير التغطية المجمّع الذي تنشئه مهمتا testAllSuites وtestAllSuitesWithDependencies يجمع بين أعداد رموز Java الثنائية من هذه الاختبارات وأعداد رموز DEX الثنائية من الوكيل. بسبب الاختلافات بينهما، يمكن أن تختلف أرقام التعليمات والفروع المجمّعة عن الأرقام الواردة في تقارير نسبة استخدام رموز الصفحة في وقت الإصدار.

يمكنك الإبلاغ عن أي ملاحظات ومشاكل أخرى من خلال Issue Tracker.