Çalışma anı tanılaması

Bazı kusurların neden yalnızca çalışan bir ekranda göründüğü, bunları yakalamak için kütüphanenin ne verdiği, bir uygulamanın tanılamayı yalnızca kendi debug derlemesinde nasıl açacağı ve bunun nasıl sınandığı. Sorun Pantrix'e özgü değildir: otomasyon etiketi, çalışma anında seçilen renkler ya da dışarıdan gelen metinler kullanan her Compose Multiplatform projesinde aynı şekilde görülür.

Compose hakkında burada söylenen her şey Compose Multiplatform 1.12.2'nin kaynaklarında okunmuş ya da bu depoda koşan bir testte görülmüştür. Kotlin ve Gradle eklentileri hakkında söylenenler Kotlin 2.4.21'in ve Compose Gradle eklentisi 1.12.2'nin kaynaklarında okunmuştur. Hangisinin nerede görüldüğü 7. ve 8. bölümlerde yazılıdır; doğrulanamayanlar 8. bölümde ayrıca sayılır.

1. Sorun

Belirti

• Bir test onNodeWithTag("Button_save") ile bir düğme arar ve "Expected exactly '1' node but found '2' nodes" der. Aynı anahtar iki yerde verilmiştir, ama ikisi ancak aynı anda ekrandayken çakışır: bir listenin satırı ile açılan ayrıntısı, bir katalog sayfasındaki iki örnek, bir geçişin iki sayfası.

• Bir markanın rengi sunucudan, bir temanın rengi kullanıcının seçiminden gelir. Ekran görüntüsü testi kendi renkleriyle çizer; çalışma anındaki rengin üstündeki yazının okunup okunmadığını hiçbir test görmez.

• Bir onay kutusu, onu tutan satır daha az yer verince sessizce küçülür. Ekran görüntüsünde kutu aynıdır; parmağın basabileceği alan daralmıştır.

• Bir ikon düğmesinin contentDescription'ı bir kaynaktan boş gelir. Ekran okuyucu düğmeye gelince hiçbir şey söylemez.

• Uygulama Almanca açılır, ama kütüphanenin Almanca sözleri yoktur: bileşenlerin kendi sözleri ("Kapat", "Temizle") İngilizce kalır.

• Bir ekranın kökü ve içindeki bir alan aynı kısayolu dinler. Tuşa basılınca dıştaki çalışır; içteki hiçbir zaman çalışmaz ve kimse fark etmez.

Neden

• Lint kaynağa bakar. Bir rengin çalışma anındaki değerini, bir kaynaktan gelen adı, aynı anda kaç düğümün aynı etiketi taşıdığını bilemez.

• Ekran görüntüsü yalnızca çizileni görür. Semantik adı, otomasyon etiketini ve basılabilen alanı görmez.

• Compose tekrara bakmaz. Modifier.testTag yalnızca semantiğe bir özellik ekler (TestTagElement, SemanticsModifierNode); iki düğüm aynı etiketi taşıyabilir. Test bulucuları ise ağaca bağlı ve devre dışı olmayan her düğümü sayar, yerleşmemiş olsa da, bütün köklerde (SemanticsOwner.getAllSemanticsNodes). Devre dışı bırakılan bir düğümün değiştiricileri ağaçtan ayrılır (onDetach), yeniden kullanılınca yeniden bağlanır (onAttach): kaydırılan bir listenin geri dönüştürdüğü satırlar sayılmaz.

• Bazı tekrarlar geçicidir. Bir sayfa geçişi birkaç kare boyunca iki sayfayı birlikte gösterir; açılan bir satır içindekini bir an sıkıştırır. Her kareye bakan bir denetim bunları da kusur sayar.

2. Çözüm: dört parça

Birinci parça olmadan ikincisi anlamsızdır: bileşenin dışından bakan bir denetim, bir düğmenin rengini ya da adını bilmez. Üçüncü parça olmadan ilk ikisi yalnızca bir testte işe yarar; dördüncüsü olmadan bir geçiş her seferinde bulgu üretir.

3. Pantrix ile

Kütüphane dört parçayı da verir (com.pantrixui.foundation.diagnostics; inspector'ı com.pantrixui.components.overlay.inspector):

3.1. Altı denetim

Temanın 34 çifti: altı rolün (primary, success, info, warning, danger, neutral) her biri için onColor color üstünde, onContainer container üstünde, color background ve surface üstünde; sayfanın onSurface, textPrimary ve textSecondary yazıları ile borderStrong ve focusRing işaretleri, background ve surface üstünde.

Dolgusuz zemin. Dolgusu olmayan bir düğmenin zemini gibi, altındakini gösteren bir zemin, bileşen temanın kendi zeminlerinden birinde duruyorsa temanın background'u ve surface'ı üstünde ölçülür ve düşük olanı sayılır. Bileşenin durduğu yer kendi içerik rengini veren başka renkte bir dolguysa (ProvidePantrixContentColor, koyu bir kartın yaptığı gibi) böyle bir çift ölçülmez: altında ne olduğu bilinmez.

3.2. Yalnızca debug derlemesinde

Pantrix hangi tür bir derlemede çalıştığını bilmez; bunu uygulama söyler. En sade yol, her platformun giriş noktasının ortak koda bir debug vermesidir:

// commonMain
@Composable
fun App(debug: Boolean) {
    val findings = remember { PantrixFindings(then = PantrixDiagnostics.Log) }
    PantrixTheme(diagnostics = if (debug) findings else PantrixDiagnostics.Off) {
        if (debug) PantrixDiagnosticsInspector(findings) { Screens() } else Screens()
    }
}

debug bir derlemenin ömrü boyunca değişmez; bu yüzden if burada güvenlidir. Çalışırken açılıp kapanan bir ayar için 7. bölümdeki ilk tuzağa bakın.

Her platform debug derlemesini kendi yolundan bilir:

3.3. Bir testte

@Test
fun the_checkout_screen_has_no_findings() = runComposeUiTest {
    val findings = PantrixFindings()
    setContent { PantrixTheme(diagnostics = findings) { CheckoutScreen() } }
    // Yerleşimin bulduğu yarım saniye, yinelenen bir etiket bir buçuk saniye sürünce bildirilir.
    mainClock.advanceTimeBy(2_000)
    assertEquals(emptyList(), findings.all)
}

Bir bulgunun message'ı testin hata iletisinde yeter: neyin yanlış olduğunu ve nasıl düzeleceğini İngilizce söyler. values ölçüleni taşır (LowContrast'ta ratio, needed, foreground, background ve ölçüldüyse ground; SmallTouchTarget'ta width, height, needed).

3.4. Kendi bileşenin

Uygulamanın kendi bileşeni de denetimlere katılır. Adı ve renkleri bileşenin kendisi bilir:

@Composable
fun Swatch(name: String, fill: Color, label: Color) {
    Column(
        modifier = Modifier
            .checkName("Swatch", name)
            .checkContrast("Swatch") { listOf(ContrastPair("label on fill", label, fill, ContrastNeed.Text)) }
            .background(fill)
            .padding(12.dp)
    ) {
        PantrixText(text = name, color = label)
    }
}

checkContrast'ın çiftleri yalnızca tanılama açıkken istenir; tanılama ya da temanın renkleri değişince yeniden. Devre dışı bir bileşen, kimsenin okuması beklenmediği için çift vermez.

3.5. Ayrı bir alıcısı olan bölüm

İçteki bir tema kendi alıcısını alabilir: PantrixTheme(diagnostics = own) { … }. O bölümün bulguları yalnızca own'a gider, dıştakine gitmez. Bu depodaki demo, "Tanılama" sayfasının örneklerini böyle gösterir: her örneğin kusuru kendi alıcısında toplanır ve uygulamanın kendi inspector'ına düşmez.

4. Pantrix olmadan

Bileşenin içinden yapılan denetimler (renk, ad, dokunma hedefi) bir kütüphane ya da uygulamanın kendi bileşen katmanı ister: dışarıdan bakan bir kod, bir düğmenin hangi rengi hangisinin üstüne çizdiğini bilmez. Aşağıdaki iki parça ise her projeye olduğu gibi kopyalanabilir.

4.1. Kontrast oranı (commonMain)

import androidx.compose.ui.graphics.Color
import androidx.compose.ui.graphics.compositeOver
import androidx.compose.ui.graphics.isSpecified
import androidx.compose.ui.graphics.luminance

/** WCAG 2.2: yazı 4.5 ve üstünde, büyük yazı ve bir kontrolün işareti 3 ve üstünde okunur. */
fun contrastRatio(foreground: Color, background: Color): Float {
    require(foreground.isSpecified && background.isSpecified) { "An unspecified colour has no contrast." }
    val drawn = if (foreground.alpha < 1f) foreground.compositeOver(background) else foreground
    val one = drawn.luminance() + 0.05f
    val other = background.luminance() + 0.05f
    return maxOf(one, other) / minOf(one, other)
}

Bu, kütüphanenin contrastRatio'sunun gövdesidir. Arkasını gösteren bir ön renk çizildiği gibi, zeminin üstüne konarak ölçülür; zemin verildiği gibi ölçülür.

4.2. Bir testte tekrar eden etiketler (commonTest)

import androidx.compose.ui.semantics.SemanticsProperties
import androidx.compose.ui.test.SemanticsMatcher
import androidx.compose.ui.test.SemanticsNodeInteractionsProvider

/** İki ya da daha çok düğümün taşıdığı etiketler ve her birini kaç düğümün taşıdığı. */
fun SemanticsNodeInteractionsProvider.repeatedTestTags(): Map<String, Int> =
    onAllNodes(SemanticsMatcher.keyIsDefined(SemanticsProperties.TestTag), useUnmergedTree = true)
        .fetchSemanticsNodes()
        .groupingBy { it.config[SemanticsProperties.TestTag] }
        .eachCount()
        .filterValues { it > 1 }

Bir ekran testinin sonunda assertEquals(emptyMap(), repeatedTestTags()). Test bulucularının saydığını sayar: yerleşmemiş düğümleri de, geri dönüştürülen satırları değil. Testin baktığı an tek bir andır; bir geçişin ortasında bakarsa geçici bir tekrarı da bulur.

5. Denetimlerin yapmadıkları

• Compose'un kendi Modifier.testTag'i sayılmaz. Yalnızca pantrixTestTag'in koyduğu etiketler kayda girer.

• minTouchTarget kullanmayan bir basılabilir alan ölçülmez. Uygulamanın kendi clickable'ı SmallTouchTarget bulmaz.

• Bir grafiğin kendi seri renkleri ölçülmez. Grafiklerde ölçülenler stilin ve renk sınıfının yazı ve işaret çiftleridir.

• iOS'un anahtar başparmağı ölçülmez. iOS stilinde (thumbAlwaysLight) başparmak hep açık renklidir ve izinden gölgesiyle ayrılır; renk oranı orada bir şey söylemez.

• Resimler, gradyanlar ve dolgulu bir zemindeki saydam renkler ölçülmez. Altlarında ne olduğu bilinmez.

• Kat yerine düşen bir overlay için denetim yoktur. Pantrix'in overlay'leri kat yerinin bir yanında kalır (ModalRoom); bu denetim Pantrix'in kendi overlay'lerinde hiç tetiklenmezdi.

• Seviye yoktur. Her bulgunun bir türü vardır; hangisinin yayını durduracağına uygulama karar verir.

• İletiler yalnızca İngilizcedir. Onları uygulamanın kullanıcısı değil bir geliştirici okur. Inspector'ın kendi sözleri (diagnostics, findingCount, notOnScreen) PantrixStrings'te Türkçe, İngilizce ve Arapçadır.

6. Test etmek

• Alıcı: her test kendi PantrixFindings'ini temaya verir ve all'a bakar. PantrixDiagnostics.Log bir testte gereksizdir.

• Saat: yerleşimin bulguları yarım saniye, yinelenen bir etiket bir buçuk saniye sürünce bildirilir. Saati kendiliğinden ilerleyen bir testte waitForIdle() yeter; mainClock.autoAdvance = false olan bir testte saat elle ilerletilir: yerleşimin bulguları için en az 500 ms, yinelenen etiket için en az 1500 ms. Kısa süren bir tekrarın bildirilmediği de böyle sınanır: tekrar süresi dolmadan kaldırılır.

• Bütün ekranlar: bu depodaki demo, DemoPagesTest'te her sayfayı iki dilde ve uygulamanın kendi kısayolunun altında çizer, bir örneğin koduna ve API sekmesine geçer ve sayfa başına bulguları toplar; hiçbir sayfada bulgu yoktur. DiagnosticsSamplesTest, iki tanılama sayfasının her örneğinin yalnızca kendi bulgularını gösterdiğine bakar: örneklerin kendi alıcıları vardır ve bulguları uygulamanınkine düşmez.

• Yer: boundsOf(finding) bulgunun düğümünün penceredeki yeridir; inspector'ın çerçevesi ondan çizilir. Düğümü olmayan bir bulgu (temanın renkleri, dil) null verir.

7. Tuzaklar

8. Doğrulama

Testler

Elle bozulan davranışlar

Her davranış bir kez elle bozuldu ve hangi testin kırmızı olduğuna bakıldı; sonra geri alındı.

• Demo: inspector'ın bir koşulla sarılması (DemoShellTest'in testi kırmızı); kapanınca bulguların silinmemesi (SettingsPageTest'in testi kırmızı); "Tanılama" sayfasının iki örneğinin eski hâli, ⌘K ve 32dp'lik kutu (DiagnosticsSamplesTest kırmızı: sıkışma sıfır, gölgelenen kısayol iki kez); "Diagnostics Inspector" sayfasının iki örneğinin aynı anahtarları paylaşması (DiagnosticsSamplesTest kırmızı: "Bulgular: 4").

• Zamanlama: yarım saniyenin sıfıra çekilmesi. Altı test kırmızı oldu: kısa süren tekrar, sıkışma ve şüphe, yarım saniye sonra gelen bildirim, etiketini değiştiren düğüm ve masanın kare istemesi.

• Kapalıyken bedava: Off'un da açık sayılması. Dört test kırmızı oldu: tema, etiket kaydı, sıkışan hedef ve kontrast.

• iOS'un günlüğü: NSLog("%@", line)'a dönülmesi. PantrixDiagnosticsOnIosTest'in süreci signal 11 ile çöktü.

• Dolgusuz zemin: altındakini gösteren zeminin her dolguda temanın zeminlerinde ölçülmesi. İlk hâliyle hiçbir test kırmızı olmadı: test, sayfada da okunan bir renk kullanıyordu. Test, sayfada okunmayan bir renkle yeniden yazıldı; bozma yeniden denenince kırmızı oldu.

Doğrulanmayanlar

• Platformların debug yolları. 3.2'deki tablonun kodu bu depoda derlenmedi ve çalıştırılmadı. Platform.isDebugBinary Kotlin/Native 2.4.21'in Platform.kt'sinde, Xcode yapılandırmasının okunuşu Kotlin Gradle eklentisi 2.4.21'in XcodeEnvironment.kt'sinde, run görevinin bir JavaExec olduğu Compose Gradle eklentisi 1.12.2'nin configureJvmApplication.kt'sinde okundu. Android'in FLAG_DEBUGGABLE'ı ve BuildConfig'in Android Gradle eklentisi 8'deki varsayılanı Android'in belgelerindendir.

• Gerçek günlükler. iOS simülatöründe birleşik günlükte (xcrun simctl spawn <udid> log stream) ve tarayıcının konsolunda bir uyarı olarak satırın kendisi görüldü. Logcat'e ve masaüstünün standart hatasına bakılmadı; testler orada günlük satırının metnine bakar.

• Ekran okuyucu. Inspector'ın ve listesinin sesli olarak nasıl okunduğu dinlenmedi.

9. Bu depoda nerede

10. Açık kalanlar

• Bir grafiğin kendi seri renkleri ölçülmez (bkz. 5. bölüm).

• Kat yerine düşen bir overlay için bir denetim yoktur; Pantrix'in kendi overlay'lerinde tetiklenmezdi.

• Gerçek cihazlarda ve tarayıcıda yalnızca demo'nun kendisine bakıldı (bkz. 8. bölüm).