Bibliotecas e ferramentas para testar diferentes tamanhos de tela

O Android oferece várias ferramentas e APIs que podem ajudar você a criar testes para diferentes tamanhos de tela e janela.

DeviceConfigurationOverride

O elemento combinável DeviceConfigurationOverride permite substituir atributos de configuração para testar vários tamanhos de tela e janela em layouts do Compose. A substituição ForcedSize ajusta qualquer layout ao espaço disponível, o que permite executar qualquer teste de interface em qualquer tamanho de tela. Por exemplo, é possível usar um formato de smartphone pequeno para executar todos os testes de interface, incluindo testes de interface para smartphones grandes, dobráveis e tablets.

   DeviceConfigurationOverride(
        DeviceConfigurationOverride.ForcedSize(DpSize(1280.dp, 800.dp))
    ) {
        MyScreen() // Will be rendered in the space for 1280dp by 800dp without clipping.
    }
Figura 1. Usando DeviceConfigurationOverride para ajustar um layout de tablet em um dispositivo de formato menor, como em \*Now in Android*.

Além disso, é possível usar esse elemento combinável para definir a escala da fonte, os temas e outras propriedades que você queira testar em diferentes tamanhos de janela.

Robolectric

Use o Robolectric para executar testes de interface do Compose ou baseados em visualização na JVM localmente, sem precisar de dispositivos ou emuladores. É possível configurar o Robolectric para usar tamanhos de tela específicos, entre outras propriedades úteis.

No exemplo abaixo do Now in Android, o Robolectric está configurado para emular um tamanho de tela de 1.000 x 1.000 dp com uma resolução de 480 dpi:

@RunWith(RobolectricTestRunner::class)
// Configure Robolectric to use a very large screen size that can fit all of the test sizes.
// This allows enough room to render the content under test without clipping or scaling.
@Config(qualifiers = "w1000dp-h1000dp-480dpi")
class NiaAppScreenSizesScreenshotTests { ... }

Também é possível definir os qualificadores no corpo do teste, como feito neste snippet do exemplo Now in Android (link em inglês):

val (width, height, dpi) = ...

// Set qualifiers from specs.
RuntimeEnvironment.setQualifiers("w${width}dp-h${height}dp-${dpi}dpi")

Observe que RuntimeEnvironment.setQualifiers() atualiza os recursos do sistema e do aplicativo com a nova configuração, mas não aciona nenhuma ação em atividades ativas ou outros componentes.

Leia mais na documentação de configuração do dispositivo do Robolectric (link em inglês).

Dispositivos gerenciados pelo Gradle

O plug-in do Android para Gradle de dispositivos gerenciados pelo Gradle (GMD, na sigla em inglês) permite definir as especificações dos emuladores e dispositivos reais em que os testes instrumentados são executados. Crie especificações para dispositivos com tamanhos de tela diferentes para implementar uma estratégia de teste em que determinados testes precisam ser executados em determinados tamanhos de tela. Ao usar o GMD com a integração contínua (CI), é possível garantir que as execuções de teste adequadas sejam executadas quando necessário, provisionando e iniciando emuladores e simplificando a configuração de CI.

android {
    testOptions {
        managedDevices {
            devices {
                // Run with ./gradlew nexusOneApi30DebugAndroidTest.
                nexusOneApi30(com.android.build.api.dsl.ManagedVirtualDevice) {
                    device = "Nexus One"
                    apiLevel = 30
                    // Use the AOSP ATD image for better emulator performance
                    systemImageSource = "aosp-atd"
                }
                // Run with ./gradlew  foldApi34DebugAndroidTest.
                foldApi34(com.android.build.api.dsl.ManagedVirtualDevice) {
                    device = "Pixel Fold"
                    apiLevel = 34
                    systemImageSource = "aosp-atd"
                }
            }
        }
    }
}

Confira vários exemplos de GMD no projeto testing-samples (link em inglês).

Firebase Test Lab

Use o Firebase Test Lab (FTL) ou um serviço de farm de dispositivos semelhante para executar seus testes em dispositivos reais específicos aos quais você talvez não tenha acesso, como dobráveis ou tablets de vários tamanhos. O Firebase Test Lab é um serviço pago com um nível sem custo financeiro. O FTL também é compatível com a execução de testes em emuladores. Esses serviços melhoram a confiabilidade e a velocidade dos testes de instrumentação porque podem provisionar dispositivos e emuladores com antecedência.

Para saber como usar o FTL com o GMD, consulte Escalonar seus testes com dispositivos gerenciados pelo Gradle.

Filtragem de testes com o executor de testes

Uma estratégia de teste ideal não deve verificar a mesma coisa duas vezes. Portanto, a maioria dos testes de interface não precisa ser executada em vários dispositivos. Normalmente, você filtra os testes de interface executando todos ou a maioria deles em um formato de smartphone e apenas um subconjunto em dispositivos com tamanhos de tela diferentes.

É possível anotar determinados testes para serem executados apenas com determinados dispositivos e, em seguida, transmitir um argumento para o AndroidJUnitRunner usando o comando que executa os testes.

Por exemplo, é possível criar anotações diferentes:

annotation class TestExpandedWidth
annotation class TestCompactWidth

E use-os em testes diferentes:

class MyTestClass {

    @Test
    @TestExpandedWidth
    fun myExample_worksOnTablet() {
        ...
    }

    @Test
    @TestCompactWidth
    fun myExample_worksOnPortraitPhone() {
        ...
    }

}

Em seguida, use a propriedade android.testInstrumentationRunnerArguments.annotation ao executar os testes para filtrar os específicos. Por exemplo, se você estiver usando dispositivos gerenciados pelo Gradle:

$ ./gradlew pixelTabletApi30DebugAndroidTest -Pandroid.testInstrumentationRunnerArguments.annotation='com.sample.TestExpandedWidth'

Se você não usa o GMD e gerencia emuladores na CI, primeiro verifique se o emulador ou dispositivo correto está pronto e conectado. Em seguida, transmita o parâmetro para um dos comandos do Gradle para executar testes de instrumentação:

$ ./gradlew connectedAndroidTest -Pandroid.testInstrumentationRunnerArguments.annotation='com.sample.TestExpandedWidth'

O Espresso Device (consulte a próxima seção) também pode filtrar testes usando propriedades do dispositivo.

Dispositivo Espresso

Use o Dispositivo Espresso para realizar ações em emuladores em testes usando qualquer tipo de teste de instrumentação, incluindo testes do Espresso, do Compose ou do UI Automator. Essas ações podem incluir a definição do tamanho da tela ou a alternância de estados ou posturas dobráveis. Por exemplo, é possível controlar um emulador dobrável e defini-lo para o modo de mesa. O Espresso Device também contém regras e anotações do JUnit para exigir determinados recursos:

@RunWith(AndroidJUnit4::class)
class OnDeviceTest {

    @get:Rule(order=1) val activityScenarioRule = activityScenarioRule<MainActivity>()

    @get:Rule(order=2) val screenOrientationRule: ScreenOrientationRule =
        ScreenOrientationRule(ScreenOrientation.PORTRAIT)

    @Test
    fun tabletopMode_playerIsDisplayed() {
        // Set the device to tabletop mode.
        onDevice().setTabletopMode()
        onView(withId(R.id.player)).check(matches(isDisplayed()))
    }
}

O Espresso Device ainda está na fase Alfa e tem os seguintes requisitos:

  • Plug-in do Android para Gradle 8.3 ou mais recente
  • Android Emulator 33.1.10 ou mais recente
  • Dispositivo virtual Android que executa o nível 24 ou mais recente da API.

Filtrar testes

O Espresso Device pode ler as propriedades dos dispositivos conectados para que você possa filtrar testes usando anotações. Se os requisitos anotados não forem atendidos, os testes serão ignorados.

Anotação RequiresDeviceMode

A anotação RequiresDeviceMode pode ser usada várias vezes para indicar um teste que será executado apenas se todos os valores de DeviceMode forem compatíveis com o dispositivo.

class OnDeviceTest {
    ...
    @Test
    @RequiresDeviceMode(TABLETOP)
    @RequiresDeviceMode(BOOK)
    fun tabletopMode_playerIdDisplayed() {
        // Set the device to tabletop mode.
        onDevice().setTabletopMode()
        onView(withId(R.id.player)).check(matches(isDisplayed()))
    }
}

Anotação RequiresDisplay

A anotação RequiresDisplay permite especificar a largura e a altura da tela do dispositivo usando classes de tamanho, que definem buckets de dimensão seguindo as classes de tamanho de janela oficiais.

class OnDeviceTest {
    ...
    @Test
    @RequiresDisplay(EXPANDED, COMPACT)
    fun myScreen_expandedWidthCompactHeight() {
        ...
    }
}

Redimensionar telas

Use o método setDisplaySize() para redimensionar as dimensões da tela no ambiente de execução. Use o método em conjunto com a classe DisplaySizeRule, que garante que todas as mudanças feitas durante os testes sejam desfeitas antes do próximo teste.

@RunWith(AndroidJUnit4::class)
class ResizeDisplayTest {

    @get:Rule(order = 1) val activityScenarioRule = activityScenarioRule<MainActivity>()

    // Test rule for restoring device to its starting display size when a test case finishes.
    @get:Rule(order = 2) val displaySizeRule: DisplaySizeRule = DisplaySizeRule()

    @Test
    fun resizeWindow_compact() {
        onDevice().setDisplaySize(
            widthSizeClass = WidthSizeClass.COMPACT,
            heightSizeClass = HeightSizeClass.COMPACT
        )
        // Verify visual attributes or state restoration.
    }
}

Quando você redimensiona uma tela com setDisplaySize(), a densidade do dispositivo não é afetada. Portanto, se uma dimensão não couber no dispositivo de destino, o teste vai falhar com um UnsupportedDeviceOperationException. Para evitar que os testes sejam executados nesse caso, use a anotação RequiresDisplay para filtrá-los:

@RunWith(AndroidJUnit4::class)
class ResizeDisplayTest {

    @get:Rule(order = 1) var activityScenarioRule = activityScenarioRule<MainActivity>()

    // Test rule for restoring device to its starting display size when a test case finishes.
    @get:Rule(order = 2) var displaySizeRule: DisplaySizeRule = DisplaySizeRule()

    /**
     * Setting the display size to EXPANDED would fail in small devices, so the [RequiresDisplay]
     * annotation prevents this test from being run on devices outside the EXPANDED buckets.
     */
    @RequiresDisplay(
        widthSizeClass = WidthSizeClassEnum.EXPANDED,
        heightSizeClass = HeightSizeClassEnum.EXPANDED
    )
    @Test
    fun resizeWindow_expanded() {
        onDevice().setDisplaySize(
            widthSizeClass = WidthSizeClass.EXPANDED,
            heightSizeClass = HeightSizeClass.EXPANDED
        )
        // Verify visual attributes or state restoration.
    }
}

StateRestorationTester

A classe StateRestorationTester é usada para testar a restauração de estado de componentes combináveis sem recriar atividades. Isso torna os testes mais rápidos e confiáveis, já que a recriação de atividades é um processo complexo com vários mecanismos de sincronização:

@Test
fun compactDevice_selectedEmailEmailRetained_afterConfigChange() {
    val stateRestorationTester = StateRestorationTester(composeTestRule)

    // Set content through the StateRestorationTester object.
    stateRestorationTester.setContent {
        MyApp()
    }

    // Simulate a config change.
    stateRestorationTester.emulateSavedInstanceStateRestore()
}

Biblioteca Window Testing

A biblioteca Window Testing contém utilitários para ajudar você a criar testes que dependem ou verificam recursos relacionados ao gerenciamento de janelas, como incorporação de atividades ou recursos dobráveis. O artefato está disponível no repositório Maven do Google.

Por exemplo, use a função FoldingFeature() para gerar um FoldingFeature personalizado, que pode ser usado em pré-lançamentos do Compose. Em Java, use a função createFoldingFeature().

Em uma prévia do Compose, você pode implementar FoldingFeature da seguinte maneira:

@Preview(showBackground = true, widthDp = 480, heightDp = 480)
@Composable private fun FoldablePreview() =
    MyApplicationTheme {
        ExampleScreen(
            displayFeatures = listOf(FoldingFeature(Rect(0, 240, 480, 240)))
        )
 }

Também é possível emular recursos de tela em testes de interface usando a função TestWindowLayoutInfo(). O exemplo a seguir simula um FoldingFeature com uma articulação vertical HALF_OPENED no centro da tela e verifica se o layout está de acordo com o esperado:

Escrever

import androidx.window.layout.FoldingFeature.Orientation.Companion.VERTICAL
import androidx.window.layout.FoldingFeature.State.Companion.HALF_OPENED
import androidx.window.testing.layout.FoldingFeature
import androidx.window.testing.layout.TestWindowLayoutInfo
import androidx.window.testing.layout.WindowLayoutInfoPublisherRule

@RunWith(AndroidJUnit4::class)
class MediaControlsFoldingFeatureTest {

    @get:Rule(order=1)
    val composeTestRule = createAndroidComposeRule<ComponentActivity>()

    @get:Rule(order=2)
    val windowLayoutInfoPublisherRule = WindowLayoutInfoPublisherRule()

    @Test
    fun foldedWithHinge_foldableUiDisplayed() {
        composeTestRule.setContent {
            MediaPlayerScreen()
        }

        val hinge = FoldingFeature(
            activity = composeTestRule.activity,
            state = HALF_OPENED,
            orientation = VERTICAL,
            size = 2
        )

        val expected = TestWindowLayoutInfo(listOf(hinge))
        windowLayoutInfoPublisherRule.overrideWindowLayoutInfo(expected)

        composeTestRule.waitForIdle()

        // Verify that the folding feature is detected and media controls shown.
        composeTestRule.onNodeWithTag("MEDIA_CONTROLS").assertExists()
    }
}

Visualizações

import androidx.window.layout.FoldingFeature.Orientation
import androidx.window.layout.FoldingFeature.State
import androidx.window.testing.layout.FoldingFeature
import androidx.window.testing.layout.TestWindowLayoutInfo
import androidx.window.testing.layout.WindowLayoutInfoPublisherRule

@RunWith(AndroidJUnit4::class)
class MediaControlsFoldingFeatureTest {

    @get:Rule(order=1)
    val activityRule = ActivityScenarioRule(MediaPlayerActivity::class.java)

    @get:Rule(order=2)
    val windowLayoutInfoPublisherRule = WindowLayoutInfoPublisherRule()

    @Test
    fun foldedWithHinge_foldableUiDisplayed() {
        activityRule.scenario.onActivity { activity ->
            val feature = FoldingFeature(
                activity = activity,
                state = State.HALF_OPENED,
                orientation = Orientation.VERTICAL)
            val expected = TestWindowLayoutInfo(listOf(feature))
            windowLayoutInfoPublisherRule.overrideWindowLayoutInfo(expected)
        }

        // Verify that the folding feature is detected and media controls shown.
        onView(withId(R.id.media_controls)).check(matches(isDisplayed()))
    }
}

Confira mais exemplos no projeto WindowManager (link em inglês).

Outros recursos

Documentação

Amostras

Codelabs