Makrobenchmark yazın

Uygulamanızın daha büyük kullanım alanlarını test etmek için Macrobenchmark kitaplığını kullanın. Bu alanlara uygulama başlatma ve karmaşık kullanıcı arayüzü manipülasyonları (ör. LazyColumn kaydırma veya animasyon çalıştırma) dahildir. Kodunuzun daha küçük alanlarını test etmek istiyorsanız Mikro karşılaştırma testi başlıklı makaleyi inceleyin. Bu sayfada, Macrobenchmark kitaplığının nasıl ayarlanacağı gösterilmektedir.

Kitaplık, karşılaştırma sonuçlarını Android Studio konsoluna ve daha ayrıntılı bilgilerin yer aldığı bir JSON dosyasına aktarır. Ayrıca, Android Studio'da yükleyip analiz edebileceğiniz izleme dosyaları da sağlar.

Sürekli Entegrasyonda Karşılaştırma bölümünde açıklandığı gibi, Macrobenchmark kitaplığını sürekli entegrasyon (CI) ortamında kullanın.

Temel profiller oluşturmak için Macrobenchmark'ı kullanabilirsiniz. Önce Macrobenchmark kitaplığını ayarlayın. Ardından temel profil oluşturabilirsiniz.

Macrobenchmark, Jetpack Compose ile oluşturulan kullanıcı arayüzlerini test etmek için önerilen araçtır. Compose düğümlerinizle etkileşim kuran UI Automator testlerini nasıl yazacağınızı öğrenmek için Birlikte çalışabilirlik başlıklı makaleyi inceleyin.

Proje ayarlama

Macrobenchmark'ı Android Studio'nun en son sürümüyle kullanmanızı öneririz.

Macrobenchmark modülünü ayarlama

Makro karşılaştırmalar, uygulamanızı ölçen testleri çalıştırmaktan sorumlu olan ve uygulama kodunuzdan ayrı bir com.android.test modülü gerektirir.

Android Studio'da, Macrobenchmark modülü kurulumunu basitleştirmek için bir şablon bulunur. Karşılaştırma modülü şablonu, örnek bir başlangıç karşılaştırması da dahil olmak üzere bir uygulama modülü tarafından oluşturulan uygulamayı ölçmek için projenizde otomatik olarak bir modül oluşturur.

Yeni bir modül oluşturmak için modül şablonunu kullanmak üzere aşağıdakileri yapın:

1. Android Studio'daki Project (Proje) panelinde projenizi veya modülünüzü sağ tıklayın ve New > Module'ü (Yeni > Modül) seçin.

2. Şablonlar bölmesinde Karşılaştırma'yı seçin. Yeni Macrobenchmark modülünün paket ve modül adının yanı sıra hedef uygulamayı (yani karşılaştırma yapılacak uygulamayı) özelleştirebilirsiniz.

3. Son'u tıklayın.

Şekil 1. Karşılaştırma modülü şablonu.

Uygulamayı kurma

Makrobenchmark'ın hedefi olarak bilinen bir uygulamayı karşılaştırmak için uygulamanın profileable olması gerekir. Bu, performansı etkilemeden ayrıntılı izleme bilgilerinin okunmasını sağlar. Modül sihirbazı, <profileable> etiketini uygulamanın AndroidManifest.xml dosyasına otomatik olarak ekler.

Hedef uygulamanın, profil yakalama ve sıfırlama ile gölgelendirici önbelleğini temizlemeyi etkinleştirmek için Macrobenchmark kitaplığının ihtiyaç duyduğu ProfilerInstaller 1.3 veya sonraki sürümleri içerdiğinden emin olun.

Karşılaştırma yapılan uygulamayı, yayınlanan sürüme veya üretime mümkün olduğunca yakın şekilde yapılandırın. Hata ayıklanamaz olarak ve tercihen küçültme etkin şekilde ayarlayın. Bu, performansı artırır. Bu işlem genellikle yayın varyantının bir kopyası oluşturularak yapılır. Bu kopya, aynı işlevi görür ancak hata ayıklama anahtarlarıyla yerel olarak imzalanır. Alternatif olarak, Gradle'a bunu sizin için yapmasını söylemek üzere initWith kullanabilirsiniz:

Kotlin

buildTypes {
    getByName("release") {
        isMinifyEnabled = true
        isShrinkResources = true
        proguardFiles(getDefaultProguardFile("proguard-android-optimize.txt"))
    }

    create("benchmark") {
        initWith(getByName("release"))
        signingConfig = signingConfigs.getByName("debug")
    }
}

Modern

buildTypes {
    release {
        isMinifyEnabled = true
        isShrinkResources = true
        proguardFiles(
            getDefaultProguardFile("proguard-android-optimize.txt"),
            "keep-rules.pro"
        )
        // In real app, this would use its own release keystore
        signingConfig = signingConfigs.getByName("debug")
        baselineProfile.automaticGenerationDuringBuild = true
    }
}
build.gradle.kts

Şekil 2'de gösterildiği gibi, karşılaştırmanın hem uygulamanızın doğru varyantını oluşturup hem de test etmesini sağlamak için aşağıdakileri yapın:

1. Gradle senkronizasyonu gerçekleştirin.
2. Build Variants (Derleme Varyantları) panelini açın.
3. Hem uygulamanın hem de Macrobenchmark modülünün karşılaştırma varyantını seçin.

Şekil 2. Karşılaştırma varyantını seçin.

Not: Projenizi Macrobenchmark'a hazır olacak şekilde ayarlama hakkında referans için örnek Macrobenchmark modülüne bakın.

(İsteğe bağlı) Çok modüllü uygulama oluşturma

Uygulamanızda birden fazla Gradle modülü varsa derleme komut dosyalarınızın hangi derleme varyantının derleneceğini bildiğinden emin olun. matchingFallbacks özelliğini :macrobenchmark ve :app modüllerinizin benchmark derleme türüne ekleyin. Gradle modüllerinizin geri kalanı, öncekiyle aynı yapılandırmaya sahip olabilir.

Kotlin

create("benchmark") {
    initWith(getByName("release"))
    signingConfig = signingConfigs.getByName("debug")

    matchingFallbacks += listOf("release")
 }

Modern

benchmark {
    initWith buildTypes.release
    signingConfig signingConfigs.debug

    matchingFallbacks = ['release']
 }

Bu olmadan, yeni eklenen benchmark derleme türü derlemenin başarısız olmasına neden olur ve aşağıdaki hata mesajını verir:

> Could not resolve project :shared.
     Required by:
         project :app
      > No matching variant of project :shared was found.
      ...

Projenizdeki derleme varyantlarını seçerken benchmark ve :macrobenchmark modülleri için :app, uygulamanızda bulunan diğer modüller için ise release seçeneğini belirleyin (Şekil 3'te gösterildiği gibi):

Şekil 3. Yayın ve karşılaştırma derleme türlerinin seçildiği çok modüllü projeler için karşılaştırma varyantları.

Daha fazla bilgi için Varyant eşleştirme ile ilgili derleme hatalarını çözme başlıklı makaleyi inceleyin.

(İsteğe bağlı) Ürün çeşitlerini ayarlama

Uygulamanızda birden fazla ürün aroması ayarlanmışsa :macrobenchmark modülünü, uygulamanızın hangi ürün aromasının oluşturulacağını ve karşılaştırma ölçütü olarak kullanılacağını bilecek şekilde yapılandırın.

Bu sayfadaki örneklerde, aşağıdaki snippet'te gösterildiği gibi :app modülündeki iki ürün çeşidi (demo ve production) kullanılmaktadır:

Kotlin

flavorDimensions += "environment"
productFlavors {
    create("demo") {
        dimension = "environment"
        // ...
    }
    create("production") {
        dimension = "environment"
        // ...
    }
}

Modern

flavorDimensions 'environment'
productFlavors {
    demo {
        dimension 'environment'
        // ...
    }

    production {
        dimension 'environment'
        // ...
    }
}

Bu yapılandırma olmadan, birden fazla Gradle modülünün neden olduğu hataya benzer bir derleme hatası alabilirsiniz:

Could not determine the dependencies of task ':macrobenchmark:connectedBenchmarkAndroidTest'.
> Could not determine the dependencies of null.
   > Could not resolve all task dependencies for configuration ':macrobenchmark:benchmarkTestedApks'.
      > Could not resolve project :app.
        Required by:
            project :macrobenchmark
         > The consumer was configured to find a runtime of a component, as well as attribute 'com.android.build.api.attributes.BuildTypeAttr' with value 'benchmark', attribute 'com.android.build.api.attributes.AgpVersionAttr' with value '7.3.0'. However we cannot choose between the following variants of project :app:
             -   demoBenchmarkRuntimeElements
             -   productionBenchmarkRuntimeElements
           All of them match the consumer attributes:
           ...

Aşağıdaki iki bölümde, karşılaştırma özelliğini birden fazla ürün çeşidiyle yapılandırma yöntemleri açıklanmaktadır.

missingDimensionStrategy kullanma

:macrobenchmark modülünün defaultConfig bölümünde missingDimensionStrategy değerinin belirtilmesi, derleme sistemine aroma boyutuna geri dönmesini söyler. Boyutları modülde bulamazsanız hangi boyutların kullanılacağını belirtin. Aşağıdaki örnekte, varsayılan boyut olarak production aroması kullanılmaktadır:

Kotlin

defaultConfig {
    missingDimensionStrategy("environment", "production")
}

Modern

defaultConfig {
    missingDimensionStrategy "environment", "production"
}

Bu şekilde, :macrobenchmark modülü yalnızca belirtilen ürün çeşidini oluşturup karşılaştırma yapabilir. Bu, yalnızca bir ürün çeşidinin karşılaştırma için uygun yapılandırmaya sahip olduğunu biliyorsanız yararlıdır.

:macrobenchmark modülünde ürün çeşitlerini tanımlayın

Diğer ürün çeşitlerini oluşturup karşılaştırmak istiyorsanız bunları :macrobenchmark modülünde tanımlayın. :app modülündeki gibi belirtin ancak yalnızca productFlavors öğesini dimension öğesine atayın. Başka ayar gerekmez:

Kotlin

flavorDimensions += "environment"
productFlavors {
    create("demo") {
        dimension = "environment"
    }
    create("production") {
        dimension = "environment"
    }
}

Modern

flavorDimensions 'environment'
productFlavors {
    demo {
        dimension 'environment'
    }

    production {
        dimension 'environment'
    }
}

Projeyi tanımlayıp senkronize ettikten sonra, Şekil 4'te gösterildiği gibi Build Variants (Derleme Varyantları) bölmesinden ilgili derleme varyantını seçin:

Şekil 4. "productionBenchmark" ve "release" seçeneklerinin belirlendiği ürün aromalarını gösteren proje için karşılaştırma varyantları.

Daha fazla bilgi için Varyant eşleştirme ile ilgili derleme hatalarını çözme başlıklı makaleyi inceleyin.

Macrobenchmark sınıfı oluşturma

Karşılaştırma testi, Macrobenchmark kitaplığındaki MacrobenchmarkRule JUnit4 kuralı API'si aracılığıyla sağlanır. Bu yöntem, hedef uygulamayı çalıştırma ve karşılaştırma ile ilgili çeşitli koşulları belirtmenize olanak tanıyan bir measureRepeated yöntemi içerir.

En azından hedef uygulamanın packageName, ölçmek istediğiniz metrics ve karşılaştırmanın kaç iterations çalıştırılması gerektiğini belirtmeniz gerekir.

Kotlin

@LargeTest
@RunWith(AndroidJUnit4::class)
class SampleStartupBenchmark {
    @get:Rule
    val benchmarkRule = MacrobenchmarkRule()

    @Test
    fun startup() = benchmarkRule.measureRepeated(
        packageName = TARGET_PACKAGE,
        metrics = listOf(StartupTimingMetric()),
        iterations = DEFAULT_ITERATIONS,
    ) {
        // starts default launch activity
        uiAutomator { startApp(TARGET_PACKAGE) }
    }
}
SampleStartupBenchmark.kt

Karşılaştırmanızı özelleştirme ile ilgili tüm seçenekler için Karşılaştırmaları özelleştirme bölümüne bakın.

Not: measureBlock'niz kullanıcı arayüzü öğeleriyle etkileşim gerektiriyorsa (ör. FrameTimingMetric'yi ölçmek için listede kaydırma) UI Automator'ı kullanın. testTagAsResourceId seçeneğini etkinleştirerek Compose değiştiricileriyle etkileşim kurabilirsiniz.

Compose kullanıcı arayüzü etkileşimlerini karşılaştırma

Önceki örnekte uygulama başlatma süresi ölçülürken genellikle kullanıcı arayüzü performansını (ör. kaydırma sırasında kare düşmeleri [duraklama]) ölçmek istersiniz.

Bir Jetpack Compose uygulamasını karşılaştırmak için (ör. LazyColumn kaydırılırken FrameTimingMetric ölçmek) aşağıdaki snippet'te gösterildiği gibi Compose düğümlerinizle doğrudan etkileşim kurmak üzere UI Automator'ı kullanabilirsiniz.

İpucu: UI Automator'ın Compose öğelerinizi bulmasına izin vermek için üst düzey Compose öğenizin semantik değiştiricisinde testTagAsResourceId = true seçeneğini etkinleştirin.

@LargeTest
@RunWith(AndroidJUnit4::class)
class ComposeScrollBenchmark {
    @get:Rule
    val benchmarkRule = MacrobenchmarkRule()

    @Test
    fun scrollLazyColumn() = benchmarkRule.measureRepeated(
        packageName = "com.example.compose.app",
        metrics = listOf(FrameTimingMetric()),
        iterations = 5,
        startupMode = StartupMode.WARM,
        setupBlock = { pressHome() }
    ) {
        startActivityAndWait()

        // Find the Compose node using the testTag defined in your app
        val lazyColumn = device.findObject(By.res("my_lazy_column"))

        // Simulate a scroll gesture to measure FrameTimingMetric
        lazyColumn.setGestureMargin(device.displayWidth / 5)
        lazyColumn.fling(Direction.DOWN)
    }
}

Karşılaştırmayı çalıştırma

Not: Karşılaştırma yaparken durumu kalıcı hale getirmek için Android 14 (API düzeyi 34) veya sonraki sürümleri kullanın. Macrobenchmark kitaplığı, her derleme için derleme durumunu tamamen sıfırlar. Bu işlem, Android 14'ten önceki sürümlerde APK'nın yeniden yüklenmesini gerektirir. Geçici çözüm olarak, uygulama derlemesini ayrı ayrı kontrol edin ve CompilationMode.Ignore kullanarak derlemeyi atlayın.

Uygulamanızın cihazınızdaki performansını ölçmek için testi Android Studio'dan çalıştırın. Şekil 5'te gösterildiği gibi, test sınıfınızın veya yönteminizin yanındaki oluk işlemini kullanarak diğer tüm @Test karşılaştırmalarını aynı şekilde çalıştırabilirsiniz.

Şekil 5. Test sınıfının yanındaki oluk işlemiyle Macrobenchmark'ı çalıştırın.

Ayrıca, connectedCheck komutunu çalıştırarak bir Gradle modülündeki tüm karşılaştırmaları komut satırından da çalıştırabilirsiniz:

./gradlew :macrobenchmark:connectedCheck

Aşağıdaki kodu çalıştırarak tek bir test yapabilirsiniz:

./gradlew :macrobenchmark:connectedCheck -P android.testInstrumentationRunnerArguments.class=com.example.macrobenchmark.startup.SampleStartupBenchmark#startup

Not: Emülatörlerde karşılaştırma testleri yapılması önerilmez. Bu testler, son kullanıcı deneyimini yansıtan performans sayıları üretmez.

Sürekli entegrasyonda karşılaştırmaları çalıştırma ve izleme hakkında bilgi edinmek için Sürekli Entegrasyonda Karşılaştırma başlıklı makaleyi inceleyin.

Karşılaştırma sonuçları

Başarılı bir karşılaştırma çalıştırmasından sonra metrikler doğrudan Android Studio'da gösterilir ve CI kullanımına yönelik olarak JSON dosyasına aktarılır. Ölçülen her yineleme ayrı bir sistem izi yakalar. Şekil 6'da gösterildiği gibi, Test Sonuçları bölmesindeki bağlantıları tıklayarak bu izleme sonuçlarını açabilirsiniz:

Şekil 6. Macrobenchmark başlangıç sonuçları.

İzleme yüklendiğinde Android Studio, analiz edilecek işlemi seçmenizi ister. Şekil 7'de gösterildiği gibi, hedef uygulama işlemiyle önceden doldurulmuş seçim:

Şekil 7. Studio izleme süreci seçimi.

İzleme dosyası yüklendikten sonra Studio, sonuçları CPU profiler aracında gösterir:

Şekil 8. Studio trace.

JSON raporları ve profil oluşturma izleri de cihazdan ana makineye otomatik olarak kopyalanır. Bunlar, ana makineye aşağıdaki konumda yazılır:

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

İzleme dosyalarına manuel olarak erişme

Bir izleme dosyasını analiz etmek için Perfetto aracını kullanmak istiyorsanız ek adımlar uygulamanız gerekir. Perfetto, izleme sırasında cihazda gerçekleşen tüm işlemleri incelemenize olanak tanırken Android Studio'nun CPU profil aracı incelemeyi tek bir işlemle sınırlar.

Testleri Android Studio'dan veya Gradle komut satırından çağırırsanız izleme dosyaları cihazdan ana makineye otomatik olarak kopyalanır. Bunlar, ana makinede aşağıdaki konumda yazılır:

project_root/module/build/outputs/connected_android_test_additional_output/debugAndroidTest/connected/device_id/TrivialStartupBenchmark_startup[mode=COLD]_iter002.perfetto-trace

Ana makine sisteminizde izleme dosyası olduğunda, menüde File > Open (Dosya > Aç) seçeneğini kullanarak dosyayı Android Studio'da açabilirsiniz. Bu, önceki bölümde gösterilen profil oluşturucu aracı görünümünü gösterir.

Yapılandırma hataları

Uygulama yanlış yapılandırılmışsa (hata ayıklanabilir veya profillendirilemez) Macrobenchmark, yanlış ya da eksik bir ölçüm raporlamak yerine hata döndürür. Bu hataları androidx.benchmark.suppressErrors bağımsız değişkeniyle bastırabilirsiniz.

Macrobenchmark, bir emülatörü veya temel kullanılabilirliği ve saat hızını tehlikeye atabilecek düşük pil seviyesine sahip bir cihazı ölçmeye çalışırken de hatalar döndürür.

Karşılaştırma ölçütlerini özelleştirme

measureRepeated işlevi, kitaplığın hangi metrikleri topladığını, uygulamanızın nasıl başlatılıp derlendiğini veya karşılaştırmanın kaç yineleme çalıştırdığını etkileyen çeşitli parametreleri kabul eder.

Metrikleri yakalama

Metrikler, karşılaştırmalarınızdan çıkarılan temel bilgi türüdür. Aşağıdaki metrikler kullanılabilir:

• StartupTimingMetric
• FrameTimingMetric
• TraceSectionMetric

Metrikler hakkında daha fazla bilgi için Makro Karşılaştırma Testi metriklerini yakalama başlıklı makaleyi inceleyin.

Özel etkinliklerle izleme verilerini iyileştirme

Uygulamanızı, izleme raporunun geri kalanında görünen ve uygulamanıza özgü sorunları belirlemeye yardımcı olabilecek özel izleme etkinlikleriyle donatmak faydalı olabilir. Özel izleme etkinlikleri oluşturma hakkında daha fazla bilgi edinmek için Özel etkinlikleri tanımlama başlıklı makaleyi inceleyin.

CompilationMode

Makro karşılaştırmalar, uygulamanın ne kadarının DEX bayt kodundan (APK'daki bayt kodu biçimi) makine koduna (önceden derlenmiş C++'ya benzer) önceden derlenmesi gerektiğini tanımlayan bir CompilationMode belirtebilir.

Macrobenchmark'lar varsayılan olarak CompilationMode.DEFAULT ile çalıştırılır. Bu, Android 7 (API düzeyi 24) ve sonraki sürümlerde varsa bir temel profil yükler. Android 6 (API düzeyi 23) veya daha eski bir sürüm kullanıyorsanız derleme modu, varsayılan sistem davranışı olarak APK'yı tamamen derler.

Hedef uygulamada hem Baseline Profile hem de ProfileInstaller kitaplığı varsa Baseline Profile yükleyebilirsiniz.

Android 7 ve sonraki sürümlerde, CompilationMode değerini özelleştirerek cihaz üzerinde önceden derleme miktarını etkileyebilir ve farklı erken derleme (AOT) veya JIT önbelleğe alma düzeylerini taklit edebilirsiniz. CompilationMode.Full, CompilationMode.Partial, CompilationMode.None ve CompilationMode.Ignore sayfalarına göz atın.

Bu özellik, ART derleme komutları üzerine kurulmuştur. Her bir karşılaştırma testi, testler arasında müdahale olmaması için başlamadan önce profil verilerini temizler.

StartupMode

Bir etkinlik başlatmak için önceden tanımlanmış bir başlangıç modu iletebilirsiniz: COLD, WARM veya HOT. Bu parametre, etkinliğin nasıl başlatıldığını ve testin başlangıcındaki süreç durumunu değiştirir.

Uyarı: StartupMode.COLD kullanılırsa uygulama sürecinin başlatılmadan hazırlanmasına olanak tanımak için setupBlock ve measureBlock yürütülürken uygulama süreci sonlandırılır. İşlemin etkin kalması gerekiyorsa StartupMode.WARM komutunu kullanın. Bu komut, işlemi yeniden başlatmadan etkinlikleri yeniden başlatır. Alternatif olarak, startupMode değerini null olarak ayarlayıp setupBlock içinde killProcess komutunu çağırın.

Başlatma türleri hakkında daha fazla bilgi edinmek için Uygulama başlatma süresi başlıklı makaleyi inceleyin.

Örnekler

Örnek proje, GitHub'daki deponun Macrobenchmark Sample bölümünde yer almaktadır.

Geri bildirim gönderme

Jetpack Macrobenchmark ile ilgili sorunları bildirmek veya özellik istekleri göndermek için Herkese açık sorun izleyiciye bakın.