O que é e como usar o capybara click na prática
Ao trabalhar com testes de integração em Ruby, quase todo mundo esbarra no capybara click quando precisa simular interações com a interface do navegador. O método é simples na teoria — você chama algo como click_on("Entrar") — mas o dia a dia mostra que existem várias situações onde ele se comporta de maneira inesperada. Eu passei umas boas horas debugging isso antes de entender o que estava acontecendo. O funcionamento básico é direto: o Capybara procura um elemento na página que corresponda ao texto, ID ou atributo passado e executa um clique nele. Por padrão, ele espera que o elemento esteja visível e clicável antes de prosseguir, o que é útil porque evita aqueles erros clássicos de tentar clicar em algo que ainda não carregou.
Por que o capybara click às vezes falha sem motivo aparente
A primeira coisa que muita gente não entende é que o click_on não encontra apenas links. Ele também captura botões, elementos com role="button", e até trechos de texto dentro de tags <a>. Isso parece útil no início, mas cria confusão quando dois elementos compartilham o mesmo texto. Já me deparei com um cenário onde existia um link e um botão com o rótulo "Salvar" na mesma tela, e o Capybara escolhia aleatoriamente um deles dependendo do estado do DOM no momento da execução. A solução foi usar seletores mais específicos, como find('button', text: "Salvar").click, que elimina essa ambiguidade. Outro problema recorrente é o timing. O Capybara espera por padrões automáticos, mas esses padrões têm limites. Se a sua aplicação faz uma requisição AJAX que demora mais de cinco segundos para completar, o teste pode falhar antes mesmo do elemento alvo estar disponível. Eu ajustei o Capybara.default_max_wait_time para 10 segundos em projetos com backends mais pesados, mas isso só resolve parte do problema — o ideal é garantir que o elemento esperado seja verificado antes do clique, usando expect(page).to have_selector('#botao-principal').
Métodos alternativos que valem a pena conhecer
Além do click_on, existem outras abordagens que funcionam melhor em cenários específicos. O click_link é mais restritivo — só encontra elementos <a> — o que pode ser vantagem quando você quer garantir que está clicando exatamente no tipo de elemento esperado. Já o click_button funciona com botões, inputs do tipo submit e elementos com role="button". Se o seu teste está batendo em elementos errados, restringir o tipo de seletor costuma resolver. Para cliques que exigem ações mais avançadas, como botão direito ou duplo clique, o Capybara oferece right_click e double_click através do módulo Capybara::Node::Actions. No entanto, a maioria dos navegadores modernos e frameworks front-end não responde bem a esses tipos de interação em testes automatizados. Testes que dependem de duplo clique frequentemente são sinais de que o teste está testando detalhes de implementação em vez de comportamento do usuário final, e nesses casos vale a pena repensar a estratégia.
👉 Clique no botão abaixo para saber mais sobre o assunto!
Problemas com elementos dinâmicos e soluções
Elementos que aparecem e desaparecem, como modais e tooltips, costumam ser a maior dor de cabeça. Um modal que é renderizado sob demanda pode estar presente no DOM mas invisível, e o Capybara ainda assim tenta clicar nele — ou falha porque o clique é interceptado por outra camada sobreposta. Eu resolvi esse problema em um projeto identificando que o modal precisava ser disparado primeiro por um botão "detalhes", e usei uma sequência de find('#botao-det', visible: true).click seguida de espera explícita pelo conteúdo do modal antes de qualquer interação com os elementos dentro dele. Scroll automático também é um fator que muitos ignoram. O Capybara tenta rolar a página para tornar o elemento visível antes de clicar, mas em páginas com layouts complexos ou containers com overflow interno, esse scroll pode não ser suficiente. Nesses casos, usar scroll_to antes do clique ou forçar a visibilidade com trigger('mouseover') pode ser necessário.
Limitações que ninguém menciona
O Capybara não é bala de prata. Ele opera no nível do navegador, o que significa que cada teste precisa iniciar uma sessão browser completa. Em pipelines de CI com dezenas de testes de integração, o tempo de execução pode ficar significativamente maior do que testes unitários ou de sistema. Além disso, testes que dependem muito de interações visuais são inherentemente mais frágeis — uma mudança no CSS ou no posicionamento de um elemento pode quebrar testes que antes passavam. Se o seu objetivo é testar lógica de negócio sem depender da interface, considere usar testes de controller ou requests instead. Eles são mais rápidos, mais estáveis e cobrem a maior parte do que realmente importa. O Capybara é adequado quando o comportamento do usuário na interface é o que está em jogo — fluxos de login, preenchimento de formulários, navegação entre páginas — e não quando você precisa validar regras de domínio ou integrações com APIs.
A combinação de seletores específicos, timeouts ajustados e uma compreensão clara do que cada método faz é o que separa testes que passam consistentemente daqueles que falham intermitentemente e gastam horas sendo investigados.
