Robolectric — o que é, princípios de funcionamento e testes unitários Android

O que é Robolectric

Robolectric é um framework de código aberto criado em 2010 para acelerar os testes de aplicações Android. Em vez de executar em um emulador ou dispositivo, o Robolectric fornece implementações shadow das classes do Android SDK que funcionam diretamente na Máquina Virtual Java (JVM). Isso permite executar milhares de testes em segundos.

O problema que o Robolectric resolve

Os testes tradicionais de Android exigem a execução da aplicação em um emulador, o que leva de 3 a 10 minutos para compilar o APK, instalar e iniciar. O Robolectric elimina esta etapa: os testes são compilados como testes Java/Kotlin comuns e executados via JUnit. Isso proporciona um ciclo de feedback de segundos em vez de minutos.

Versões do Android suportadas

O Robolectric suporta todas as versões do Android desde a API 16 (Android 4.1) até a versão estável mais recente. Para cada versão, é fornecido um conjunto correspondente de shadow-objects que emulam o comportamento da versão específica da plataforma na qual a aplicação está sendo testada.

Arquitetura e shadow-objects

A arquitetura do Robolectric é baseada na interceptação de chamadas através da substituição do classloader. Quando um teste chama um método do Android SDK, o Robolectric intercepta a chamada e a direciona para um shadow-object. Um shadow-object é uma classe Java que imita o comportamento real de um componente Android, mas funciona sem a plataforma nativa.

Como funcionam as shadows

Os shadow-objects implementam os métodos principais das classes originais do Android. Por exemplo, o ShadowTextView imita métodos como getText(), setText(), getCurrentTextColor() e outros. Quando textView.setText("Olá") é chamado, a shadow salva a string e a retorna quando getText() é invocado. Isso isola os testes da renderização real e dos serviços do sistema.

Hierarquia de shadows

O Robolectric suporta mais de 200 classes shadow que cobrem os principais componentes do Android SDK: Activity, Fragment, TextView, Button, RecyclerView, WebView, LocationManager, ConnectivityManager e muitos outros. Os shadow-objects seguem a mesma hierarquia de herança que as classes originais do Android.

Instalação e configuração do Robolectric

A instalação do Robolectric em um projeto Gradle requer adicionar a dependência testImplementation "org.robolectric:robolectric:4.x". Também é necessário especificar a configuração androidsdk no arquivo build.gradle e adicionar a resolução android:testInstrumentationRunner. Nenhum plugin de teste Android é necessário para trabalhar com o Robolectric.

Configuração básica do Gradle

Após adicionar a dependência, é necessário configurar o diretório para o manifesto, recursos e assets. O Robolectric encontra automaticamente o AndroidManifest.xml, mas pode ser necessário especificar o caminho manualmente através da anotação @Config ou propriedades do sistema. Para projetos multimódulo, a configuração é definida separadamente para cada módulo.

// build.gradle — configuração do Robolectric
android {
    testOptions {
        unitTests.includeAndroidResources = true
        unitTests.all {
            systemProperty 'robolectric.dependency.dir',
                project.rootDir.absolutePath + '/build/intermediates'
        }
    }
}

dependencies {
    testImplementation 'org.robolectric:robolectric:4.13'
    testImplementation 'org.junit.jupiter:junit-jupiter:5.10.0'
}

A anotação @Config

A anotação @Config permite sobrescrever os parâmetros do teste: sdk (versão da API), manifest (caminho para o manifesto), qualifiers (configuração de tela, idioma). Isso é útil para testar o comportamento da aplicação em diferentes versões do Android, orientações de tela e localizações.

Escrevendo testes com Robolectric

Os testes do Robolectric são escritos como testes unitários comuns com @RunWith(RobolectricTestRunner.class) para JUnit 4 ou através do RobolectricExtension para JUnit 5. O ActivityController gerencia o ciclo de vida da Activity: create(), start(), resume(), pause(), stop(), destroy(). Isso permite testar detalhadamente cada transição de estado.

Testando Activity

Para testar uma Activity, utiliza-se o ActivityController, que passa sequencialmente pelas etapas do ciclo de vida. O acesso à Activity é feito através de controller.get(). Todos os componentes de visualização são acessíveis através de findViewById, como em uma aplicação real. Os shadow-objects permitem verificar textos, visibilidade, cores e outros atributos das views.

@RunWith(RobolectricTestRunner.class)
@Config(sdk = BuildConfig.SDK_INT)
public class MainActivityTest {

    @Test
    public void testActivityDisplaysGreeting() {
        ActivityController<MainActivity> controller =
            Robolectric.buildActivity(MainActivity.class);
        controller.create().start().resume();

        MainActivity activity = controller.get();
        TextView greeting = activity.findViewById(R.id.greeting);
        ShadowTextView shadow = Shadows.shadowOf(greeting);

        assertEquals("Welcome!", shadow.getText());
    }
}

Testando intents e navegação

O Robolectric intercepta chamadas startActivity() e permite verificar os intents enviados através do ShadowActivity. Isso possibilita testar a navegação: verificar que ao clicar em um botão é enviado um Intent com o Action, Data e parâmetros Extra corretos.

@Test
public void testNavigationToDetails() {
    controller.create().start().resume();
    MainActivity activity = controller.get();

    activity.findViewById(R.id.detailsButton).performClick();

    ShadowActivity shadowActivity = Shadows.shadowOf(activity);
    Intent intent = shadowActivity.getNextStartedActivity();
    assertEquals(
        DetailsActivity.class.getName(),
        intent.getComponent().getClassName()
    );
}

Robolectric vs. emulador

O Robolectric e o emulador resolvem tarefas diferentes. O Robolectric é ideal para testes unitários rápidos, verificação de lógica de UI, componentes de negócio e repositórios. O emulador é necessário para testes de instrumentação, verificação de integração com API, testes de câmera, sensores e desempenho.

Testando ViewModel e Repository

O Robolectric é excelente para testar ViewModel, Repository e UseCase — componentes que usam o Android SDK mas não requerem uma UI real. O ViewModel é testado através de um teste JUnit comum com RobolectricExtension, enquanto os componentes de ciclo de vida (LiveData, StateFlow) funcionam no ambiente shadow sem mocks.

Testando LiveData

O Robolectric suporta LiveData diretamente: você pode se inscrever no LiveData no teste, alterar o estado através do ViewModel e verificar o valor emitido. Para operações assíncronas, utiliza-se InstantTaskExecutorRule ou runBlocking para corrotinas. Isso elimina a necessidade de simular componentes arquiteturais.

@RunWith(RobolectricTestRunner::class)
@Config(sdk = [BuildConfig.SDK_INT])
class ProfileViewModelTest {

    private val repository = FakeUserRepository()
    private val viewModel = ProfileViewModel(repository)

    @Test
    fun `loading profile sets state to success`() = runBlocking {
        viewModel.loadProfile("user123")
        val state = viewModel.profileState.getOrAwaitValue()
        Assertions.assertTrue(state is UiState.Success)
    }
}

Shadow-objects personalizados

Se os shadow-objects padrão do Robolectric não cobrirem uma classe necessária do Android SDK, você pode criar um Shadow personalizado. Para isso, crie uma classe com a anotação @Implements(ClassName.class) e implemente os métodos necessários com @Implementation. Shadows personalizados são registrados através de @Config(shadows = [CustomShadow::class]).

Testando ContentProvider e Resources

O Robolectric suporta testes de ContentProvider através de Robolectric.buildContentProvider(). Você pode verificar operações CRUD, consultas com correspondência de URI e gerenciamento de permissões. Os recursos (strings, cores, dimensões) também são acessíveis através de RuntimeEnvironment.application.resources, permitindo testar código que depende de recursos.

Migrando do emulador para o Robolectric

A transição de testes de instrumentação para o Robolectric requer uma mudança de abordagem. Os testes de instrumentação (AndroidJUnit4) verificam o comportamento real no emulador, enquanto o Robolectric verifica a lógica isolada em um ambiente shadow. Recomenda-se cobrir a lógica de negócio com testes Robolectric e deixar os testes de instrumentação para cenários de integração.

Adaptando testes existentes

Ao migrar, é necessário: substituir AndroidJUnit4 por RobolectricTestRunner, adicionar @Config com a versão de SDK alvo, substituir ActivityTestRule por ActivityController, e mover as dependências de androidTestImplementation para testImplementation. Os mocks (MockK, Mockito) funcionam com o Robolectric sem alterações — são independentes de plataforma.

Limitações da migração

O Robolectric não suporta: testes de câmera (CameraX), NFC, Bluetooth, biometria, trabalho com arquivos reais e bibliotecas nativas. Esses cenários requerem testes de instrumentação no emulador. O Robolectric também não reproduz a renderização real — testes de layout são melhores via Compose Test Rule ou Espresso. No entanto, para verificar lógica de negócio, navegação e estados do ViewModel, o Robolectric substitui completamente o emulador com aceleração de 10x.

Compatibilidade com versões Java e Kotlin

O Robolectric requer JDK 11 ou superior e é compatível com AGP (Android Gradle Plugin) desde 7.0 até a versão estável mais recente. O SDK Manager do Robolectric baixa automaticamente as versões necessárias da Android API na primeira execução — é uma operação única. Para servidores CI, recomenda-se pré-carregar o SDK via sdkmanager para evitar atrasos na primeira execução dos testes. A atualização do Robolectric para uma nova versão geralmente não requer alterações no código dos testes, apenas a atualização do número da dependência no build.gradle.

Integração com MockK e Mockito

O Robolectric é compatível com frameworks de mocking populares: MockK para Kotlin e Mockito para Java. Mocks são usados para isolar dependências: repositórios, clientes de API, SharedPreferences. A regra principal é não simular classes do Android SDK — para isso existem os shadow-objects. Simule apenas as camadas da aplicação: UseCase, Repository, DataSource e outros componentes de lógica de negócio. Esta combinação de shadow-objects e mocks proporciona máxima flexibilidade com mínimo esforço de escrita de testes.