كتابة مقياس أداء مصغّر

للتعرّف على كيفية استخدام مكتبة مقاييس الأداء الجزئية من خلال إضافة تغييرات إلى رمز التطبيق، يمكنك الاطّلاع على القسم Quickstart. للتعرّف على كيفية إكمال عملية الإعداد الكاملة وإجراء تغييرات أكثر تعقيدًا على قاعدة الرموز، راجِع قسم الإعداد الكامل للمشروع

التشغيل السريع

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

لإجراء قياس الأداء لمرة واحدة، عليك اتّباع الخطوات التالية:

1. أضِف المكتبة إلى ملف build.gradle أو build.gradle.kts الخاص بالوحدة:

   Kotlin

   dependencies {
       implementation("androidx.benchmark:benchmark-junit4:1.2.4")
   }
   

   رائع

   dependencies {
       implementation 'androidx.benchmark:benchmark-junit4:1.2.4'
   }
   

   استخدام تبعية implementation بدلاً من androidTestImplementation والتبعية. في حال استخدام androidTestImplementation، يتعذّر تشغيل معايير الأداء لأنّه لم يتم دمج بيان المكتبة في بيان التطبيق.

2. عدِّل نوع إصدار debug كي لا يمكن تصحيح الأخطاء فيه:

   Kotlin

   android {
       ...
       buildTypes {
           debug {
               isDebuggable = false
           }
       }
   }
   

   رائع

   android {
       ...
       buildTypes {
           debug {
               debuggable false
           }
       }
   }
   

3. غيِّر testInstrumentationRunner إلى AndroidBenchmarkRunner:

   Kotlin

   android {
       ...
       defaultConfig {
           testInstrumentationRunner = "androidx.benchmark.junit4.AndroidBenchmarkRunner"
       }
   }
   

   رائع

   android {
       ...
       defaultConfig {
           testInstrumentationRunner "androidx.benchmark.junit4.AndroidBenchmarkRunner"
       }
   }
   

4. أضِف مثيلًا من BenchmarkRule في ملف اختباري في دليل androidTest لإضافة مقياس الأداء. لمزيد من المعلومات حول كتابة مقاييس الأداء، راجِع إنشاء فئة مقاييس أداء مصغَّرة.

   يوضّح مقتطف الرمز البرمجي التالي كيفية إضافة مقياس أداء إلى اختبار مزوّد بأدوات قياس الأداء:

   Kotlin

   @RunWith(AndroidJUnit4::class)
   class SampleBenchmark {
       @get:Rule
       val benchmarkRule = BenchmarkRule()
   
       @Test
       fun benchmarkSomeWork() {
           benchmarkRule.measureRepeated {
               doSomeWork()
           }
       }
   }
   SampleBenchmark.kt
   

   Java

   @RunWith(AndroidJUnit4.class)
   class SampleBenchmark {
       @Rule
       public BenchmarkRule benchmarkRule = new BenchmarkRule();
   
       @Test
       public void benchmarkSomeWork() {
               BenchmarkRuleKt.measureRepeated(
                   (Function1<BenchmarkRule.Scope, Unit>) scope -> doSomeWork()
               );
          }
       }
   }
   

للتعرّف على كيفية كتابة مقياس أداء، انتقِل إلى إنشاء فئة اختبار أداء صغير.

إعداد المشروع بالكامل

لإعداد قياس أداء منتظم بدلاً من قياس أداء لمرة واحدة، عزل ومقاييس الأداء في الوحدة الخاصة بها. يساعد ذلك في ضمان أن تكون الإعدادات، مثل ضبط debuggable على false، منفصلة عن الاختبارات العادية.

بما أنّ أداة Microbenchmark تُشغّل الرمز البرمجي مباشرةً، ضَع الرمز الذي تريد قياس أدائه في ملف Gradle منفصل واضبط الاعتماد على هذه الوحدة كما هو موضّح في الشكل 1.

لإضافة وحدة Gradle جديدة، يمكنك استخدام معالج الوحدات في "استوديو Android". تشير رسالة الأشكال البيانية وحدة قياس الأداء مُعدّة مسبقًا لقياس الأداء، تمت إضافة دليل قياس الأداء وضبط debuggable على false.

1. انقر بزر الماوس الأيمن على مشروعك أو وحدتك في لوحة المشروع في "استوديو Android"، ثم انقر على جديد > وحدة.

2. اختَر مقاييس الأداء في لوحة النماذج.

3. اختَر مقياس الأداء المصغَّر كنوع وحدة قياس الأداء.

4. اكتب "مقياس الأداء المصغَّر" لاسم الوحدة.

5. انقر على إنهاء.

بعد إنشاء الوحدة، غيِّر ملف build.gradle أو build.gradle.kts وأضِف androidTestImplementation إلى الوحدة التي تحتوي على الرمز البرمجي لقياس الأداء:

dependencies {
    // The module name might be different.
    androidTestImplementation(project(":benchmarkable"))
}

dependencies {
    // The module name might be different.
    androidTestImplementation project(':benchmarkable')
}

إنشاء فئة اختبار أداء صغير

المعايير هي اختبارات قياس حالة. لإنشاء مقياس أداء، استخدم صف واحد (BenchmarkRule) تقدّمه المكتبة. لمقارنة الأنشطة، استخدِم ActivityScenario أو ActivityScenarioRule. لقياس رمز واجهة المستخدم، استخدام @UiThreadTest

يعرض الرمز البرمجي التالي نموذجًا لمقياس الأداء:

@RunWith(AndroidJUnit4::class)
class SampleBenchmark {
    @get:Rule
    val benchmarkRule = BenchmarkRule()

    @Test
    fun benchmarkSomeWork() {
        benchmarkRule.measureRepeated {
            doSomeWork()
        }
    }
}
SampleBenchmark.kt
    

@RunWith(AndroidJUnit4.class)
class SampleBenchmark {
    @Rule
    public BenchmarkRule benchmarkRule = new BenchmarkRule();

    @Test
    public void benchmarkSomeWork() {
        final BenchmarkState state = benchmarkRule.getState();
        while (state.keepRunning()) {
            doSomeWork();
        }
    }
}
    

إيقاف التوقيت لعملية الإعداد

يمكنك إيقاف ميزة قياس التوقيت لأجزاء من الرمز البرمجي التي لا تريد قياسها باستخدام العنصر runWithTimingDisabled{}. تمثل هذه الأقسام عادةً بعض الكود الذي تحتاج إلى تشغيله في كل تكرار لمقياس الأداء.

// using random with the same seed, so that it generates the same data every run
private val random = Random(0)

// create the array once and just copy it in benchmarks
private val unsorted = IntArray(10_000) { random.nextInt() }

@Test
fun benchmark_quickSort() {
    // ...
    benchmarkRule.measureRepeated {
        // copy the array with timing disabled to measure only the algorithm itself
        listToSort = runWithTimingDisabled { unsorted.copyOf() }

        // sort the array in place and measure how long it takes
        SortingAlgorithms.quickSort(listToSort)
    }

    // assert only once not to add overhead to the benchmarks
    assertTrue(listToSort.isSorted)
}
SortingBenchmarks.kt
    

private final int[] unsorted = new int[10000];

public SampleBenchmark() {
    // Use random with the same seed, so that it generates the same data every
    // run.
    Random random = new Random(0);

    // Create the array once and copy it in benchmarks.
    Arrays.setAll(unsorted, (index) -> random.nextInt());
}

@Test
public void benchmark_quickSort() {
    final BenchmarkState state = benchmarkRule.getState();

    int[] listToSort = new int[0];

    while (state.keepRunning()) {
        
        // Copy the array with timing disabled to measure only the algorithm
        // itself.
        state.pauseTiming();
        listToSort = Arrays.copyOf(unsorted, 10000);
        state.resumeTiming();
        
        // Sort the array in place and measure how long it takes.
        SortingAlgorithms.quickSort(listToSort);
    }

    // Assert only once, not to add overhead to the benchmarks.
    assertTrue(SortingAlgorithmsKt.isSorted(listToSort));
}
    

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

تنفيذ مقياس الأداء

في Android Studio، يمكنك تنفيذ اختبار الأداء كما تفعل مع أي @Test باستخدام إجراء الفاصل بجانب فئة الاختبار أو الطريقة، كما هو موضّح في الشكل 3.

بدلاً من ذلك، يمكنك تشغيل connectedCheck من سطر الأوامر لإجراء كل الاختبارات من وحدة Gradle المحدّدة:

./gradlew benchmark:connectedCheck

أو اختبار واحد:

./gradlew benchmark:connectedCheck -P android.testInstrumentationRunnerArguments.class=com.example.benchmark.SampleBenchmark#benchmarkSomeWork

نتائج قياس الأداء

بعد إجراء اختبار Microbenchmark بنجاح، يتم عرض المقاييس مباشرةً في Android IDE، ويتوفّر تقرير اختبار أداء كامل بتنسيق JSON يحتوي على مقاييس إضافية ومعلومات عن الجهاز.

تتم أيضًا نسخ تقارير JSON وأيّ عمليات تتبُّع لإعداد الملف الشخصي تلقائيًا من الجهاز إلى المضيف. وتكون هذه الأخطاء مكتوبة على الجهاز المضيف في المكان التالي:

project_root/module/build/outputs/connected_android_test_additional_output/debugAndroidTest/connected/device_id/

يتم تلقائيًا كتابة تقرير JSON على القرص على الجهاز في مجلد الوسائط المشتركة الخارجي لحزمة APK الاختبارية، والذي يقع عادةً في /storage/emulated/0/Android/media/**app_id**/**app_id**-benchmarkData.json.

أخطاء في الإعدادات

تكتشف المكتبة الشروط التالية للتأكد من أن مشروعك على مستوى الأداء على إصداره بدقة:

• تم ضبط خيار تصحيح الأخطاء على false.
• يتم استخدام جهاز مادي، وأدوات المحاكاة غير متوافقة.
• يتم قفل الساعات إذا كان الجهاز مزوّدًا بإذن الوصول إلى الجذر.
• مستوى شحن البطارية الكافي في الجهاز لا يقل عن 25%.

إذا تعذّر إجراء أيّ من عمليات التحقّق السابقة، يُبلغ مقياس الأداء عن خطأ بهدف تجنّب إجراء قياسات غير دقيقة.

لإخفاء أنواع أخطاء معيّنة كتحذيرات ومنعها من إيقاف الأداء مقارنةً بالمعايير، يمكنك تمرير نوع الخطأ في قائمة مفصولة بفواصل إلى مَعلمة القياس androidx.benchmark.suppressErrors.

يمكنك تعيين هذا من نص Gradle البرمجي، كما هو موضح في المثال التالي:

android {
    defaultConfig {
       …
      testInstrumentationRunnerArguments["androidx.benchmark.suppressErrors"] = "DEBUGGABLE,LOW-BATTERY"
    }
}

android {
    defaultConfig {
       …
      testInstrumentationRunnerArguments["androidx.benchmark.suppressErrors"] = "DEBUGGABLE,LOW-BATTERY"
    }
}

يمكنك أيضًا إخفاء الأخطاء من سطر الأوامر:

$ ./gradlew :benchmark:connectedCheck -P andoidtestInstrumentationRunnerArguments.androidx.benchmark.supperssErrors=DEBUGGABLE,LOW-BATTERY

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