Appium Failure Helper: Diagnóstico Inteligente de Falhas

Uma GEM de diagnóstico para testes Appium em Ruby, projetada para transformar falhas de automação em insights acionáveis. Quando um teste falha por não encontrar um elemento, esta ferramenta gera um relatório HTML detalhado e interativo, identificando a causa provável e acelerando drasticamente o tempo de depuração.

• Triagem Inteligente de Erros: Identifica automaticamente o tipo de falha (NoSuchElementError, TimeoutError, NoMethodError, etc.) e decide se deve gerar um relatório de análise profunda ou um diagnóstico simples.
• Análise de Código-Fonte: Para erros "silenciosos" (onde a mensagem não contém o seletor), inspeciona o stack trace para encontrar o arquivo e a linha exatos do erro, extraindo o seletor diretamente do código.
• Análise Avançada (Atributos Ponderados): O "coração" da GEM. Em vez de uma simples comparação de strings, ela "desmonta" o seletor que falhou e o compara, atributo por atributo, com todos os elementos na tela. Ela dá pesos diferentes para resource-id, text, etc., para encontrar o "candidato mais provável" na tela.
• Fábrica de Estratégias de Reparo: Após identificar o "candidato mais provável", a XPathFactory gera uma lista rica (até 20) de seletores alternativos e robustos para aquele elemento, exibidos em um carrossel paginado.
• Busca Reversa no Código: A ferramenta varre seus arquivos .rb para encontrar definições de seletores que são parecidas com o que falhou, exibindo o trecho de código e o arquivo.
• Relatórios Ricos e Interativos: Gera um relatório HTML completo com:
  • Screenshot da falha.
  • Diagnóstico claro e sugestões acionáveis.
  • Abas com "Análise Avançada", "Estratégias de Reparo" e "Dump Completo" de todos os elementos da tela.
• Configuração Flexível: Permite a customização de caminhos de arquivos de elementos.

Adicione ao Gemfile do seu projeto de automação:

gem 'appium_failure_helper', git: 'URL_DO_SEU_REPOSITORIO_GIT'

Depois execute:

bundle install

A integração é feita em 3 etapas para garantir máxima eficiência.

No arquivo de inicialização (features/support/env.rb), carregue a GEM e, opcionalmente, configure os caminhos de elementos se eles forem diferentes do padrão.

require 'appium_failure_helper'

AppiumFailureHelper.configure do |config|
  # Caminho para a pasta que contém os arquivos de elementos.
  # Padrão: 'features/elements'
  config.elements_path = 'features/elements'

  # Nome do arquivo Ruby principal que define os elementos.
  # Padrão: 'elementLists.rb'
  config.elements_ruby_file = 'elementLists.rb'
end

Para que a GEM consiga analisar erros "silenciosos" (como TimeoutError ou falhas dentro de helpers), é essencial que seu framework de automação "enriqueça" a exceção antes de ela ser lançada.

Ajuste seus métodos de busca de elementos (ex: em features/support/appiumCustom.rb) para que eles capturem a falha e a relancem com uma mensagem detalhada no formato using "tipo" with value "valor".

# features/support/appiumCustom.rb

# --- MÉTODO DE ESPERA ENRIQUECIDO ---
def waitForElementExist(el, timeout = 30)
  wait = Selenium::WebDriver::Wait.new(timeout: timeout)

  begin
    wait.until do
      if el.is_a?(Hash)
        $driver.find_elements(el.keys.first, el.values.first).size > 0
      else
        # assume que é um ID simples (string)
        $driver.find_elements(:id, el).size > 0
      end
    end
  rescue Selenium::WebDriver::Error::TimeoutError => e
    locator_info = el.is_a?(Hash) ? "#{el.keys.first}: #{el.values.first}" : "using \"#{el}\""
    raise e.class, "Timeout de #{timeout}s esperando pelo elemento (#{locator_info})", e.backtrace
  end
end


# --- MÉTODO DE BUSCA ENRIQUECIDO ---
def find(el)
  waitForElementExist(el)
end

def clickElement(el)
  waitForElementExist(el).click
end

private

# Helper central que enriquece erros de 'find_element'
def find_element_with_enriched_error(el)
  begin
    return $driver.find_element(el)
  rescue Selenium::WebDriver::Error::NoSuchElementError => e
    new_message = "using \"#{el.keys.first}\""
    new_exception = e.class.new(new_message)
    new_exception.set_backtrace(e.backtrace)
    raise new_exception
  end
end

No hooks.rb, acione a GEM após cada cenário com falha:

# features/support/hooks.rb

After do |scenario|
  if scenario.failed? && $driver&.session_id
    AppiumFailureHelper.handler_failure($driver, scenario.exception)
  end
end

Você pode configurar sua GEM para publicar os relatórios HTML diretamente no painel do Jenkins. Isso dá visibilidade imediata para toda a equipe sobre a causa de um build quebrado, sem a necessidade de acessar logs ou baixar arquivos.

➡️ Guia Completo de Integração com Jenkins

A cada falha, a GEM cria uma pasta em reports_failure/ com:

1. Relatório Simples: Para falhas não relacionadas a seletores (ex: erro de código Ruby, falha de conexão). Mostra um diagnóstico direto, o erro original, o stack trace e o screenshot.
2. Relatório Detalhado: Gerado quando um problema de seletor é identificado.
   • Coluna Esquerda:
     • Elemento com Falha: O seletor exato que falhou (extraído da mensagem ou do código).
     • Sugestões Encontradas no Código: (Opcional) Sugestões de seletores parecidos encontrados no seu código-fonte.
     • Screenshot da Falha: A imagem da tela no momento do erro.
   • Coluna Direita (Abas):
     • Análise Avançada: O "candidato mais provável" encontrado na tela, com uma análise comparativa de seus atributos (resource-id, text, etc.) e uma sugestão acionável.
     • Estratégias de Reparo: Um carrossel paginado com até 20 estratégias de localização (XPaths, IDs) geradas pela XPathFactory para o candidato encontrado.
     • Dump Completo: A lista de todos os elementos visíveis na tela.

• Handler: O maestro que orquestra todo o fluxo de análise.
• Analyzer: O analista. Faz a triagem do erro e executa a "Análise Avançada" por atributos ponderados.
• SourceCodeAnalyzer: Especialista em ler o stack trace para extrair seletores de dentro do código-fonte.
• CodeSearcher: O detetive. Faz a busca reversa por strings de seletores similares em todo o projeto.
• ElementRepository: O repositório que carrega os mapas de elementos de arquivos .rb e .yaml (De/Para).
• PageAnalyzer: O leitor de tela. Processa o XML da página para extrair todos os elementos e seus atributos.
• XPathFactory: A fábrica que gera dezenas de estratégias de XPath (diretas, combinatórias, relacionais, etc.).
• ReportGenerator: O construtor. Renderiza os relatórios HTML (detalhado ou simples) com base nos dados da análise.
• Configuration: Gerencia as configurações da GEM.
• Utils: Funções auxiliares (Logger, etc.).

Pull requests e issues são bem-vindos! Abra uma Issue para bugs ou sugestões.

MIT License