Diagnóstico Inteligente de Falhas Appium

Uma ferramenta robusta para diagnosticar falhas em testes automatizados com Appium, transformando erros de NoSuchElementException em relatórios interativos e inteligentes. Chega de perder tempo depurando seletores quebrados; deixe que a análise automatizada faça o trabalho pesado por você.

✨ Principais Funcionalidades

• Relatório HTML Interativo: Gera um relatório visual completo a cada falha, com screenshot, análise detalhada e dump de todos os elementos da tela.
• Análise de Mapeamento ("De/Para"): Verifica automaticamente se o elemento que falhou está definido em alguma fonte de dados do projeto, como:
  • Arquivos .yaml gerados dinamicamente durante a execução.
  • Arquivos de elementos Ruby (.rb) estáticos.
• Sugestão por Similaridade: Utiliza o algoritmo de Levenshtein para encontrar elementos na tela que são "parecidos" com o localizador que falhou, sugerindo correções para erros de digitação.
• Arquitetura Modular: O código é limpo, organizado e fácil de estender, seguindo o Princípio da Responsabilidade Única.
• Suporte Multiplataforma: A lógica de análise e sugestão funciona tanto para Android quanto para iOS.

🚀 Instalação

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

gem 'appium_failure_helper' # (ou o nome que você der para a sua gem)

E então execute no seu terminal:

bundle install

⚙️ Configuração e Uso

A integração com projetos baseados em Cucumber é extremamente simples.

1. No seu arquivo features/support/env.rb, adicione o require para carregar a ferramenta.
2. Dentro do hook After, adicione um bloco condicional para chamar o helper sempre que um cenário falhar.

Exemplo completo para features/support/env.rb:

# features/support/env.rb

require 'appium_lib'
require 'cucumber'

# 1. Carrega a sua ferramenta com uma única linha
require 'appium_failure_helper'

# ... (outras configurações do seu ambiente) ...

# 2. Hook que executa após cada cenário de teste
After do |scenario|
  # Se o cenário falhou, aciona o seu helper
  if scenario.failed?
    puts "\n--- CENÁRIO FALHOU! ACIONANDO O DIAGNÓSTICO INTELIGENTE ---"

    # A chamada é simples e direta.
    # Use a variável do seu driver (pode ser @driver, $driver, etc.)
    AppiumFailureHelper.handler_failure(@driver, scenario.exception)

    puts "--- HELPER FINALIZOU. VERIFIQUE A PASTA 'reports_failure' ---"
  end
end

# ... (código para fechar o driver, etc.) ...

E é isso! A ferramenta está pronta para agir.

📄 Entendendo o Relatório Gerado

Após uma falha, uma nova pasta será criada na raiz do seu projeto, seguindo o padrão: reports_failure/failure_[timestamp].

Dentro dela, você encontrará 4 arquivos:

reports_failure/failure_20250924_154010/
|-- all_elements_dump_20250924_154010.yaml  # Dump de todos os elementos da tela.
|-- failure_analysis_20250924_154010.yaml   # Resumo da análise em formato YAML.
|-- page_source_20250924_154010.xml        # O XML completo da tela no momento da falha.
`-- report_20250924_154010.html             # O relatório interativo para abrir no navegador.

O Relatório HTML Interativo

Este é o principal artefato. Ele é dividido em seções claras para um diagnóstico rápido:

Análise de Mapeamento (Blocos Verde/Amarelo)

Estes blocos aparecem no topo e informam se o elemento que falhou foi encontrado nos arquivos de mapeamento do seu projeto.

• Bloco Verde (Sucesso): Confirma que o elemento foi encontrado em um arquivo .yaml ou .rb, mostrando o caminho e/ou o localizador correto. Isso geralmente indica um problema de timing ou de visibilidade do elemento na tela, já que a definição dele está correta.
• Bloco Amarelo (Aviso): Informa que o elemento não foi encontrado nos arquivos de mapeamento. Isso geralmente aponta para um erro de digitação no nome do elemento no seu código de teste.

Elemento com Falha (Bloco Vermelho)

Mostra exatamente qual Tipo de Seletor e Valor Buscado o Appium usou quando a falha ocorreu.

Screenshot da Falha

Uma imagem exata da tela no momento do erro.

Sugestões de Reparo (Análise de Similaridade)

Se houver elementos na tela com localizadores parecidos com o que falhou, eles serão listados aqui com uma pontuação de similaridade. É extremamente útil para corrigir pequenos erros de digitação nos seus seletores.

Dump Completo da Página

Uma lista interativa de todos os elementos visíveis na tela, com todos os seus possíveis localizadores. Útil para explorar a tela e encontrar seletores alternativos.

🏛️ Arquitetura do Código

O código foi reestruturado em módulos com responsabilidades únicas para facilitar a manutenção e a extensibilidade.

• handler.rb: O Maestro. Orquestra as chamadas para os outros módulos na ordem correta.
• analyzer.rb: O Analista. Processa a mensagem de erro e calcula a similaridade dos elementos.
• element_repository.rb: O Repositório. É responsável por encontrar e carregar as definições de elementos de arquivos .yaml e .rb.
• page_analyzer.rb: O Leitor de Tela. Processa o XML da página para extrair todos os elementos, sugerir nomes e gerar localizadores.
• report_generator.rb: O Gerador. Consolida todos os dados analisados e cria os 4 arquivos de relatório.
• utils.rb: Funções auxiliares, como o Logger.

🤝 Como Contribuir

Encontrou um bug ou tem uma ideia para uma nova funcionalidade? Abra uma Issue no repositório do projeto. Pull Requests são sempre bem-vindos!

📜 Licença

Este projeto é distribuído sob a licença MIT. Veja o arquivo LICENSE para mais detalhes.