Detox: o que é, princípios de funcionamento e testes E2E

O que é Detox

Detox é um framework para testes de ponta a ponta (E2E) de aplicações móveis, desenvolvido pela Wix em 2017. É projetado para projetos React Native, mas também suporta aplicações puramente nativas em iOS e Android. O Detox funciona com um modelo gray-box, o que significa que tem acesso aos mecanismos internos da aplicação.

Diferença de outros frameworks E2E

A principal diferença entre Detox e Appium ou Calabash é a sincronização automática com a aplicação. O framework aguarda a conclusão de animações, requisições de rede e processamento de eventos antes de executar a próxima ação. Isso elimina completamente a necessidade de Thread.sleep() ou waitForElement, que retardam os testes.

Plataformas suportadas

Detox suporta iOS (através de XCTest e Xcode) e Android (através de Espresso e UI Automator). Para aplicações React Native, é fornecido suporte completo para Fabric e a arquitetura antiga. No iOS, os testes são executados no simulador; no Android, no emulador ou em um dispositivo real.

Arquitetura do Detox e modelo gray-box

A arquitetura do Detox consiste em três componentes-chave: Detox CLI, o executor de testes Detox e o Detox Native Driver. Detox CLI gerencia a compilação, instalação e execução de testes da aplicação. O executor de testes (Jest ou Mocha) executa os cenários de teste e se comunica com a aplicação via WebSocket.

Abordagem gray-box

Testes gray-box significam que o Detox tem acesso ao estado interno da aplicação através de uma ponte nativa. O framework monitora requisições de rede, animações, temporizadores e a fila de operações. Quando todas as filas estão vazias, o Detox considera a aplicação pronta para o próximo passo.

Mecanismo de sincronização

A sincronização é baseada no monitoramento da thread principal da aplicação. O Detox aguarda até que todas as animações sejam concluídas, requisições HTTP retornem respostas e os manipuladores de eventos terminem de executar. Se um teste travar devido a uma animação infinita, é possível desabilitar manualmente a sincronização para um bloco de código específico.

// Desabilitar a sincronização para uma seção problemática
await device.disableSynchronization();
// Ação com animação longa
await element(by.id('loader')).swipe('down');
await device.enableSynchronization();

Instalação e configuração do Detox

A instalação do Detox começa adicionando o pacote via npm ou yarn. Após a instalação, é necessário criar um arquivo de configuração .detoxrc.js, que descreve as configurações de compilação e execução para cada plataforma. O Detox usa seu próprio tipo de compilação para iOS, baseado na configuração do Xcode.

Configuração básica

A configuração inclui o caminho para a aplicação (app), o tipo de compilador (build), argumentos de compilação e configurações de dispositivo (device). Para iOS, é usado appleSimulator; para Android, androidEmulator. Você também pode especificar argumentos de inicialização como o idioma ou região do simulador.

// .detoxrc.js — exemplo de configuração
module.exports = {
  testRunner: { args: { '$0': 'jest', config: 'e2e/config.json' } },
  apps: {
    'ios.debug': { type: 'ios.app', build: 'xcodebuild ...' },
    'android.debug': { type: 'android.apk', build: 'cd android && ./gradlew ...' }
  },
  devices: {
    simulator: { type: 'ios.simulator', device: { type: 'iPhone 15' } },
    emulator: { type: 'android.emulator', device: { avdName: 'Pixel_4_API_34' } }
  }
};

Comandos de execução

Após a configuração, os seguintes comandos estão disponíveis: detox build — compila a aplicação com flags de teste, e detox test — executa os testes. O Detox suporta execução paralela em múltiplos dispositivos usando a flag --workers.

Escrita de testes com Detox

Os testes do Detox são escritos em JavaScript ou TypeScript usando uma API baseada em busca de elementos (matchers) e ações (actions). Os matchers permitem encontrar um elemento por identificador, texto, tipo ou posição na tela. As ações realizam toque, entrada de texto, deslize e rolagem.

Estrutura do cenário de teste

Um teste típico segue esta sequência: encontrar um elemento → realizar uma ação → verificar o resultado. Para verificações, a API expect é usada com matchers de presença, visibilidade ou texto do elemento. O Detox suporta a sintaxe describe/it através da integração com Jest.

describe('Login flow', () => {
  beforeEach(async () => {
    await device.reloadReactNative();
  });

  it('should log in with valid credentials', async () => {
    await element(by.id('emailInput')).typeText('user@test.com');
    await element(by.id('passwordInput')).typeText('password123');
    await element(by.id('loginButton')).tap();
    await expect(element(by.id('homeScreen'))).toBeVisible();
  });
});

Trabalhando com gestos

Detox suporta todos os gestos populares: tap, longPress, swipe, scroll, pinch, multiTap. Para scroll, você pode especificar a direção, velocidade e posição de parada. Isso permite testar cenários complexos como pull-to-refresh ou carrosseis.

Integração do Detox em CI/CD

Detox integra-se bem com sistemas CI populares: GitHub Actions, CircleCI, Bitrise e Jenkins. Para execução em CI, é necessário configurar um simulador iOS virtual (sem GUI) e um emulador Android com aceleração de hardware. O Detox fornece artefatos — capturas de tela e logs — para analisar testes com falha.

Recomendações para CI

Para acelerar a execução de testes em CI, recomenda-se usar sharding (paralelização) com a flag --workers. O Detox distribui automaticamente os arquivos de teste entre vários simuladores. Também é útil armazenar em cache as compilações da aplicação entre execuções para reduzir o tempo de compilação.

# GitHub Actions — executar Detox no iOS
- name: Install Dependencies
  run: npm ci

- name: Build Detox App
  run: npx detox build --configuration ios.sim

- name: Run Detox Tests
  run: npx detox test --configuration ios.sim --workers 2
  timeout-minutes: 30

Melhores práticas do Detox

Para testes E2E estáveis e rápidos, recomenda-se seguir várias regras. Evite sleep() — o Detox fornece sincronização automática, e atrasos explícitos só retardam os testes e os tornam instáveis. Se um teste falhar devido a problemas de tempo, primeiro verifique se a sincronização está desabilitada. Também é útil agrupar testes por funcionalidade e executá-los independentemente — isso simplifica a busca pela causa da falha.

Uso de métodos de device

Detox fornece vários métodos de device para gerenciamento de estado: device.reloadReactNative() recarrega o bundle, device.launchNewApp() inicia a aplicação com novos parâmetros, device.sendToHome() minimiza a aplicação. device.setURLBlacklist() permite excluir certas URLs da sincronização, o que é útil para análises e conexões long-polling.

Organização de dados de teste

Para cada teste, recomenda-se criar um estado isolado. Use beforeEach para recarregar a aplicação via device.reloadReactNative(). Para testes que exigem dados específicos, crie fábricas ou clientes de API para preparar dados no servidor. Evite dependências entre testes — cada teste deve ser independente.

Trabalhando com WebView

Detox suporta teste de WebView através dos métodos web.element() e web.invoke(). Para interagir com elementos web, by.web](:id, css ou className é usado. É importante lembrar que o WebView requer tempo adicional de carregamento — se a sincronização não funcionar, adicione uma espera de carregamento usando waitFor.

// Teste de WebView no Detox
const webView = web(by.id('webview'));
await webView.element(by.web.cssSelector('#submit-btn')).tap();
const result = await webView.element(
  by.web.cssSelector('.result-text')
).getText();
await expect(result).toEqual('Success');

Teste de captura de tela

Detox suporta comparação de capturas de tela através do plugin detox-image-matching. As capturas de tela permitem detectar regressões visuais: elementos deslocados, cores incorretas, ícones ausentes. Para capturas estáveis, desative animações e use um tamanho fixo de simulador.

Diagnóstico de problemas do Detox

Os problemas mais comuns do Detox estão relacionados à sincronização: animações infinitas, requisições de rede longas ou temporizadores travados. O log com a flag --loglevel trace mostra quais recursos o Detox está aguardando. Se o Detox travar, use device.disableSynchronization() para o bloco de código problemático.

Problemas com o simulador

No simulador iOS, o Detox exige que a aplicação seja compilada primeiro via xcodebuild com a configuração iphonesimulator. Um erro comum é usar um esquema Release em vez de Debug, o que desativa as flags de teste. Para Android, certifique-se de que o AVD foi criado com uma API compatível com sua aplicação e que a aceleração Intel HAXM está ativada. Para ambientes CI no macOS, é conveniente usar GitHub Actions com um runner macOS, onde Xcode e simuladores já estão pré-instalados.

Timeouts de teste

Se os testes falharem regularmente por timeout, verifique: se a sincronização está desabilitada globalmente, se setTimeout ou setInterval estão sendo usados no código da aplicação sem limpeza, e se a thread principal está bloqueada por uma operação longa. Às vezes, aumentar o timeout no detoxrc.js via testRunner.args.jest.$.testTimeout ajuda. Para encontrar áreas problemáticas, ative o log de rastreamento do Detox — ele mostra quais recursos e temporizadores o framework está aguardando atualmente.

Artefatos e relatórios

Após a execução dos testes, o Detox cria artefatos: capturas de tela de testes com falha, logs da aplicação e relatórios XML JUnit. As capturas de tela são feitas automaticamente quando um teste falha e ajudam a identificar visualmente o problema. Para CI, os artefatos são enviados para armazenamento em nuvem e ficam disponíveis através de uma interface web para analisar as causas da falha.