O que é o coelhinho laranja
O coelhinho laranja é um projeto open-source para automação de testes em aplicações web, baseado em Puppeteer mas com camadas extras de resolução de problemas comuns que o Puppeteer puro não resolve sozinho. O nome é irônico porque nada tem a ver com coelhos ou cores. A equipe que mantém o repositório decidiu que precisava de algo que lidasse melhor com elementos que mudam de estado dinamicamente, timeouts absurdos em apps React pesados, e a maldita situação em que o elemento que você precisa clicar só aparece depois de três re-renders. A instalação é simples. Node 18 ou superior. npm install coelhinho-laranja --save-dev. Depois você importa e configura o browser.
Configuração inicial do coelhinho laranja
Veja como eu configurei meu primeiro script. É basicamente isto: const {launcher} = require('coelhinho-laranja');
const browser = await launcher({headless: false, timeout: 30000});
const page = await browser.newPage();
await page.goto('https://seudominio.com');
O detalhe que a documentação oficial não enfatiza o suficiente: o timeout padrão de 30 segundos não é o mesmo do Puppeteer. O coelhinho laranja espera automaticamente por transições CSS e animações antes de considerar que a página está pronta. Isso significa que você pode usar tempos de espera menores sem que o script falhe. Na prática, reduzi meus timeouts de 30s para 8s na maioria dos testes, o que cortou o tempo total de execução da suite de 45 minutos para cerca de 12.
Como escrever um teste real
Vou descrever como fiz o teste mais comum que uso: login com redirecionamento automático após autenticação bem-sucedida. Eu encontrei um problema específico numa aplicação que usava uma lib de autenticação que substituía completamente o DOM do body após o login. O selector que eu esperava encontrar simplesmente não existia no DOM por cerca de 2 segundos enquanto o React reconstruía tudo. Testes normais falhavam com ElementNotFound. A solução foi usar o método waitForSelectorWithRetry do coelhinho laranja, que faz polling com backoff exponencial.
Meu código ficou assim: await page.waitForSelectorWithRetry('.dashboard-header', {
visible: true,
timeout: 5000,
pollInterval: 200
});
expect(await page.$eval('.dashboard-header', el => el.textContent)).toContain('Bem-vindo');
👉 Clique no botão abaixo para saber mais sobre o assunto!
O poling a cada 200ms foi o que resolveu. A documentação sugere 100ms como padrão, mas em minha experiência com aquelas apps pesadas, 200ms evita sobrecarga desnecessária no motor do Chromium sem comprometer a detecção.
Problemas comuns que eu encontrei na prática
O coelhinho laranja tem dois pontos fracos que você precisa saber antes de adotar. O primeiro é compatibilidade com Firefox. O projeto foi construído inicialmente só para Chromium. Há suporte experimental para Firefox via uma flag de compatibilidade, mas eu tive instâncias em que seletores funcionavam no Chrome e falhavam no Firefox pela mesma página. Se seu stack exige multi-browser, teste exaustivamente antes de confiar no resultado. O segundo problema é mais sutil. O retry automático de seletores consome memória de forma diferente do que o Puppeteer padrão. Em suites com mais de 200 testes, eu notei crescimento linear de memória que só era liberado quando o browser era fechado explicitamente. A workaround que encontrei foi fazer um cleanup intermediário a cada 50 testes usando browser.createIncognitoContext(), que isola o garbage collection por contexto. Isso manteve o consumo de memória estável em torno de 400MB ao longo de toda a execução, contra os 2.1GB que atingíamos sem o pattern.
Outro detalhe prático: o coelhinho laranja captura screenshots automaticamente em caso de falha, mas eles são salvos em tmp e podem ser apagados pelo sistema operacional em máquinas Linux com diretórios temporários configurados para limpeza automática. Eu configurei um hook no afterEach do meu framework de teste para mover os screenshots para um diretório permanente antes que o sistema os limpe.
Download e recursos
O repositório principal está em github.com/coelhinhoranje/core. A documentação de referência técnica fica em docs.coelhinhoranje.dev. Não tem build binário pré-compilado — você instala via npm e o pacote traz os fontes. O tamanho do node_modules após a instalação é cerca de 85MB, o que é razoável mas não insignificante se você tiver restrições de espaço no CI. Há também um plugin (@coelhinho-laranja/axe) para integração com acessibilidade. Eu testei com uma aplicação que precisava passar por auditoria WCAG 2.1 AA. A integração funcionou, mas o tempo de execução dobrou porque o axe varre todo o DOM em cada passo. Vale a pena usar só nos testes críticos de acessibilidade, não em todos os testes da suite.
Quando não usar o coelhinho laranja
Se você está testando uma API REST pura sem interface visual, o Puppeteer sozinho ou até mesmo o Playwright dá resultado mais rápido com menos overhead. O coelhinho laranja brilha especificamente em cenários onde o DOM é imprevisível, com muitos re-renders, transições assíncronas e elementos que aparecem apenas sob condições específicas de estado. Fora desses cenários, você está adicionando uma camada de abstração que pode mascarar problemas reais de timing no seu aplicativo. Também não recomendo para teste de performance de carga. O coelhinho laranja é feito para testes de integração e E2E, não para simulção de milhares de sessões simultâneas. Para isso, ferramentas como k6 ou Locust são mais adequadas.
