v2 test API'lerine geçiş yapma

Coroutine yürütme üzerinde daha fazla kontrol sağlamak için Compose test API'lerinin v2 sürümleri (createComposeRule, createAndroidComposeRule, runComposeUiTest, runAndroidComposeUiTest vb.) kullanıma sunuldu. Bu güncelleme, API yüzeyinin tamamını kopyalamaz. Yalnızca test ortamını oluşturan API'ler güncellenmiştir.

v1 API'leri kullanımdan kaldırıldı. Yeni API'lere geçiş yapmanız önemle tavsiye edilir. Taşıma işlemi, testlerinizin standart eşzamanlı rutin davranışıyla uyumlu olduğunu doğrular ve gelecekteki uyumluluk sorunlarını önler. Desteği sonlandırılan v1 API'lerinin listesi için API eşlemeleri'ne bakın.

Bu değişiklikler androidx.compose.ui:ui-test-junit4:1.11.0-alpha03+ ve androidx.compose.ui:ui-test:1.11.0-alpha03+'de yer almaktadır.

v1 API'leri UnconfinedTestDispatcher kullanırken v2 API'leri, çalışan kompozisyon için varsayılan olarak StandardTestDispatcher kullanır. Bu değişiklik, Compose test davranışını standart runTest API'lerle uyumlu hale getirir ve eşzamanlı rutin yürütme sırası üzerinde açık kontrol sağlar.

API eşlemeleri

v2 API'lerine yükseltirken paket içe aktarmalarını güncellemek ve yeni dağıtıcı değişikliklerini uygulamak için genellikle Bul + Değiştir'i kullanabilirsiniz.

Alternatif olarak, Gemini'dan aşağıdaki istemle Compose test API'lerinin 2. sürümüne geçiş yapmasını isteyin:

Migrate to Compose testing v2 APIs using the official
migration guide.

Kullanımdan kaldırılan v1 API'lerini v2'deki karşılıklarıyla eşlemek için aşağıdaki tabloyu kullanın:

Geriye dönük uyumluluk ve istisnalar

Mevcut v1 API'lerin desteği sonlandırıldı ancak mevcut davranışı korumak ve değişikliklerin bozulmasını önlemek için UnconfinedTestDispatcher kullanmaya devam edin.

Varsayılan davranışın değiştiği tek istisna aşağıda verilmiştir:

AndroidComposeUiTestEnvironment sınıfında kompozisyon çalıştırmak için kullanılan varsayılan test dağıtıcı, UnconfinedTestDispatcher yerine StandardTestDispatcher olarak değiştirildi. Bu durum, oluşturucuyu kullanarak bir örnek oluşturduğunuz veya AndroidComposeUiTestEnvironment alt sınıfını oluşturup bu oluşturucuyu çağırdığınız durumları etkiler.

Önemli değişiklik: Eşzamanlı rutin yürütme üzerindeki etki

API'lerin v1 ve v2 sürümleri arasındaki temel fark, eşzamanlı rutinlerin gönderilme şeklidir:

• v1 API'leri (UnconfinedTestDispatcher): Bir ortak rutin başlatıldığında, mevcut iş parçacığında hemen yürütülür ve genellikle test kodunun bir sonraki satırı çalıştırılmadan önce tamamlanırdı. Üretim davranışının aksine, bu anında yürütme, canlı bir uygulamada meydana gelecek gerçek zamanlama sorunlarını veya yarış durumlarını istemeden maskeleyebilir.
• v2 API'leri (StandardTestDispatcher): Bir eşzamanlı rutin başlatıldığında sıraya alınır ve test, sanal saati açıkça ilerletene kadar yürütülmez. Standart Compose test API'leri (ör. waitForIdle()) bu senkronizasyonu zaten işlediğinden bu standart API'leri kullanan çoğu test, herhangi bir değişiklik yapılmadan çalışmaya devam edecektir.

Sık karşılaşılan hatalar ve bunları düzeltme

v2'ye yükselttikten sonra testleriniz başarısız olursa büyük olasılıkla aşağıdaki kalıbı gösterirler:

• Başarısızlık: Bir görevi başlatırsınız (örneğin, ViewModel verileri yükler) ancak veriler hâlâ "Yükleniyor" durumunda olduğundan onayınız hemen başarısız olur.
• Neden: v2 API'lerde eş yordamlar hemen yürütülmek yerine sıraya alınır. Görev sıraya alındı ancak sonuç kontrol edilmeden önce hiç çalıştırılmadı.
• Düzeltme: Zamanı açıkça ilerletin. Çalışmanın ne zaman yürütüleceğini v2 dağıtıcıya açıkça söylemeniz gerekir.

Önceki yaklaşım

v1'de görev hemen başlatılıp tamamlanıyordu. v2'de aşağıdaki kod, loadData() henüz gerçekten çalıştırılmadığı için başarısız olur.

// In v1, this launched and finished immediately.
viewModel.loadData()

// In v2, this fails because loadData() hasn't actually run yet!
assertEquals(Success, viewModel.state.value)

Önerilen yaklaşım

Sıraya alınmış görevleri onaylamadan önce yürütmek için waitForIdle veya runOnIdle kullanın.

1. seçenek: waitForIdle kullanıldığında, kullanıcı arayüzü boşta kalana kadar saat ilerletilir ve böylece coroutine'in çalıştığı doğrulanır.

viewModel.loadData()

// Explicitly run all queued tasks
composeTestRule.waitForIdle()

assertEquals(Success, viewModel.state.value)

2. seçenek: runOnIdle kullanıldığında, kullanıcı arayüzü boşta kaldıktan sonra kod bloğu kullanıcı arayüzü iş parçacığında yürütülür.

viewModel.loadData()

// Run the assertion after the UI is idle
composeTestRule.runOnIdle {
    assertEquals(Success, viewModel.state.value)
}

Manuel senkronizasyon

Otomatik ilerlemenin devre dışı bırakıldığı durumlar gibi manuel senkronizasyonun söz konusu olduğu senaryolarda, test saati duraklatıldığı için bir eş yordamın başlatılması hemen yürütülmeyle sonuçlanmaz. Sanal saati ilerletmeden sıradaki eşzamanlı rutinleri yürütmek için runCurrent() API'sini kullanın. Bu, mevcut sanal zaman için planlanan görevleri çalıştırır.

composeTestRule.mainClock.scheduler.runCurrent()

waitForIdle(), test saatini kullanıcı arayüzü sabitlenene kadar ilerletirken runCurrent(), bekleyen görevleri mevcut sanal zamanı koruyarak yürütür. Bu davranış, saat boşta kalma durumuna ilerletilseydi atlanacak olan ara durumların doğrulanmasını sağlar.

Test ortamında kullanılan temel test planlayıcı kullanıma sunulur. Bu zamanlayıcı, test saatini senkronize etmek için Kotlin runTest API'siyle birlikte kullanılabilir.

runComposeUiTest'e taşıma

Kotlin runTest API'si ile birlikte Compose test API'lerini kullanıyorsanız runComposeUiTest'ye geçmeniz önemle tavsiye edilir.

Önceki yaklaşım

createComposeRule ile runTest birlikte kullanıldığında iki ayrı saat oluşturulur: biri Compose, diğeri ise test coroutine kapsamı için. Bu yapılandırma, test planlayıcıyı manuel olarak senkronize etmenize neden olabilir.

@get:Rule
val composeTestRule = createComposeRule()

@Test
fun testWithCoroutines() {
    composeTestRule.setContent {
        var status by remember { mutableStateOf("Loading...") }
        LaunchedEffect(Unit) {
            delay(1000)
            status = "Done!"
        }
        Text(text = status)
    }

    // NOT RECOMMENDED
    // Fails: runTest creates a new, separate scheduler.
    // Advancing time here does NOT advance the compose clock.
    // To fix this without migrating, you would need to share the scheduler
    // by passing 'composeTestRule.mainClock.scheduler' to runTest.
    runTest {
        composeTestRule.onNodeWithText("Loading...").assertIsDisplayed()
        advanceTimeBy(1000)
        composeTestRule.onNodeWithText("Done!").assertIsDisplayed()
    }
}
TestSnippets.kt

Önerilen yaklaşım

runComposeUiTest API, test bloğunuzu kendi kapsamı içinde otomatik olarak yürütür.runTest Test saati, Oluşturma ortamıyla senkronize edildiğinden artık planlayıcıyı manuel olarak yönetmeniz gerekmez.

    @Test
    fun testWithCoroutines() = runComposeUiTest {
        setContent {
            var status by remember { mutableStateOf("Loading...") }
            LaunchedEffect(Unit) {
                delay(1000)
                status = "Done!"
            }
            Text(text = status)
        }

        onNodeWithText("Loading...").assertIsDisplayed()
        mainClock.advanceTimeBy(1000 + 16 /* Frame buffer */)
        onNodeWithText("Done!").assertIsDisplayed()
    }
}
TestSnippets.kt