appium_failure_helper 0.6.6 → 0.6.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: af82bef9bc09a790faa2882a886325c2da1ae7cfbd4a25541b0025f0bb9bb479
-  data.tar.gz: 3fe174544dba0f9453d017900968fa84f07444337b4d910648f289a81e5fa5ef
+  metadata.gz: a599f36b97e9ca76cfe763ad26526ea1b80e829128e95667b1020bf29cb9cb41
+  data.tar.gz: 58f249a54a0410b9927bbb14b4551375cd77de49eb35db282cad16a9e0b7817d
 SHA512:
-  metadata.gz: 1c338bf9158ab769f74dbaa3be08a42581b8bcacdd997d61a27751a0cc5e4b349888e02124d8c70a2395643e46486e6213444e99a1b7222d231ed3ece9170cd4
-  data.tar.gz: fb6f836aa0ed1b947658b787fff8768cfff589356440137265d7cf8ffd3a8e33664c298e881fa1b1b2850c691f5df9434a71cbd602fc7b1b058677eccf51741e
+  metadata.gz: b9c4ab54799677d260fa7939705fc074a2e9233026b696d2d4548da344b0464f8dcbbda5016a735939819e04c2b06e700ed14d23cde1c8ac55cbfb844cae9b10
+  data.tar.gz: d076e206ca68bd47560a95162428b1dc090df4890934f535de0c68f98b17206adb7229980175c1773dd542e65ac01dd9accbf4da83104cbb68ad893c0df773e0

data/README.md

@@ -1,7 +1,7 @@
 # Diagnóstico Inteligente de Falhas Appium
 
 ![Build Status](https://img.shields.io/badge/build-passing-brightgreen)
-![Gem Version](https://img.shields.io/badge/gem-v1.0.0-blue)
+![Gem Version](https://img.shields.io/badge/gem-v1.1.0-blue)
 ![License](https://img.shields.io/badge/license-MIT-lightgrey)
 
 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ê.
@@ -10,9 +10,10 @@ Uma ferramenta robusta para diagnosticar falhas em testes automatizados com Appi
 
 * **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.
+    * **Arquivos `.yaml`** gerados dinamicamente.
+    * **Arquivos de elementos Ruby (`.rb`)** customizáveis.
+* **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.
+* **Altamente Configurável:** Permite que os projetos definam seus próprios caminhos e nomes de arquivos de elementos, tornando a ferramenta totalmente reutilizável.
 * **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**.
 
@@ -30,12 +31,36 @@ E então execute no seu terminal:
 bundle install
 ```
 
-## ⚙️ Configuração e Uso
+## ⚙️ Configuração (Opcional)
 
-A integração com projetos baseados em **Cucumber** é extremamente simples.
+Para tornar a ferramenta flexível e adaptável a diferentes projetos, você pode configurar os caminhos onde os elementos são buscados. Crie um bloco de configuração no seu arquivo de inicialização (ex: `features/support/env.rb`).
 
-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.
+**Se nenhuma configuração for fornecida, a ferramenta usará os valores padrão.**
+
+```ruby
+# Em features/support/env.rb
+
+AppiumFailureHelper.configure do |config|
+  # Caminho para a pasta que contém os arquivos de elementos.
+  # Padrão: 'features/elements'
+  config.elements_path = 'caminho/para/sua/pasta/de/elementos'
+
+  # Nome do arquivo principal de elementos Ruby.
+  # Padrão: 'elementLists.rb'
+  config.elements_ruby_file = 'meu_arquivo_de_elementos.rb'
+end
+```
+
+### Opções Disponíveis
+
+| Parâmetro             | Descrição                                                                      | Valor Padrão             |
+| --------------------- | ------------------------------------------------------------------------------ | ------------------------ |
+| `elements_path`       | Path relativo à raiz do projeto para a pasta que contém os arquivos de elementos. | `'features/elements'`    |
+| `elements_ruby_file`  | Nome do arquivo Ruby principal que define os elementos dentro da `elements_path`. | `'elementLists.rb'`      |
+
+## 🛠️ Uso no Cucumber
+
+A integração é feita através de um hook `After` no seu ambiente de testes.
 
 **Exemplo completo para `features/support/env.rb`:**
 
@@ -45,52 +70,39 @@ A integração com projetos baseados em **Cucumber** é extremamente simples.
 require 'appium_lib'
 require 'cucumber'
 
-# 1. Carrega a sua ferramenta com uma única linha
+# 1. Carrega a sua ferramenta
 require 'appium_failure_helper'
 
-# ... (outras configurações do seu ambiente) ...
+# 2. (Opcional) Configura os caminhos se forem diferentes do padrão
+AppiumFailureHelper.configure do |config|
+  config.elements_path = 'features/elements'
+  config.elements_ruby_file = 'elementLists.rb'
+end
 
-# 2. Hook que executa após cada cenário de teste
+# 3. 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.)
+    # A chamada ao helper utiliza automaticamente as configurações definidas acima.
     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
+Após uma falha, uma nova pasta será criada na raiz do seu projeto: `reports_failure/failure_[timestamp]`. Dentro dela, o arquivo mais importante é o `report_[...].html`.
 
-Este é o principal artefato. Ele é dividido em seções claras para um diagnóstico rápido:
+O relatório HTML é 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.
+#### Análise de Mapeamento (Bloco Verde/Amarelo)
+Informa se o elemento que falhou foi encontrado nos seus arquivos de mapeamento (`.rb` ou `.yaml`).
+* **Bloco Verde (Sucesso):** Confirma que o elemento foi encontrado. Isso sugere que a definição está correta, e o problema pode ser de timing ou visibilidade na tela.
+* **Bloco Amarelo (Aviso):** Informa que o elemento **não foi encontrado**. 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.
@@ -99,21 +111,22 @@ Mostra exatamente qual `Tipo de Seletor` e `Valor Buscado` o Appium usou quando
 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.
+Lista os elementos na tela com localizadores parecidos com o que falhou, com uma pontuação de similaridade. Ideal para corrigir erros de digitação nos 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.
+Uma lista interativa de **todos os elementos** visíveis na tela, com todos os seus possíveis localizadores.
 
 ## 🏛️ Arquitetura do Código
 
-O código foi reestruturado em módulos com responsabilidades únicas para facilitar a manutenção e a extensibilidade.
+O código é modular 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.
+* `configuration.rb`: Classe que armazena as opções configuráveis e seus valores padrão.
+* `handler.rb`: O **Maestro**. Orquestra as chamadas para os outros módulos.
+* `analyzer.rb`: O **Analista**. Processa a mensagem de erro e calcula a similaridade.
+* `element_repository.rb`: O **Repositório**. Encontra e carrega as definições de elementos de arquivos `.yaml` e `.rb` usando os caminhos configurados.
+* `page_analyzer.rb`: O **Leitor de Tela**. Processa o XML da página para extrair elementos e sugerir nomes/localizadores.
+* `report_generator.rb`: O **Gerador**. Consolida todos os dados e cria os arquivos de relatório.
+* `utils.rb`: Funções auxiliares (Logger, etc.).
 
 ## 🤝 Como Contribuir
 
@@ -121,4 +134,4 @@ Encontrou um bug ou tem uma ideia para uma nova funcionalidade? Abra uma *Issue*
 
 ## 📜 Licença
 
-Este projeto é distribuído sob a licença MIT. Veja o arquivo `LICENSE` para mais detalhes.
+Este projeto é distribuído sob a licença MIT.

data/lib/appium_failure_helper/configuration.rb

@@ -0,0 +1,13 @@
+module AppiumFailureHelper
+  class Configuration
+    # Define as opções que o usuário poderá configurar
+    attr_accessor :elements_path, :elements_ruby_file
+
+    def initialize
+      # Define os valores PADRÃO.
+      # Se o usuário não configurar nada, a GEM usará estes valores.
+      @elements_path = 'features/elements'
+      @elements_ruby_file = 'elementLists.rb'
+    end
+  end
+end

data/lib/appium_failure_helper/element_repository.rb

@@ -1,49 +1,57 @@
 module AppiumFailureHelper
   module ElementRepository
+  
+    def self.load_all
+      elements_map = load_from_ruby_file
+      elements_map.merge!(load_all_from_yaml)
+      elements_map
+    end
+
+    private
+
+    def self.load_from_ruby_file
+      map = {}
+      # ALTERADO: Lê os caminhos a partir da configuração central.
+      config = AppiumFailureHelper.configuration
+      file_path = File.join(Dir.pwd, config.elements_path, config.elements_ruby_file)
+      
+      return map unless File.exist?(file_path)
+
+      # ... (o resto do método continua igual)
+      begin
+        require file_path
+        instance = OnboardingElementLists.new
+        unless instance.respond_to?(:elements)
+          Utils.logger.warn("AVISO: A classe OnboardingElementLists não expõe um `attr_reader :elements`.")
+          return map
+        end
+        instance.elements.each do |key, value|
+          map[key.to_s] = { 'tipoBusca' => value[0], 'valor' => value[1] }
+        end
+      rescue => e
+        Utils.logger.warn("AVISO: Erro ao processar o arquivo #{file_path}: #{e.message}")
+      end
+      
+      map
+    end
+    
     def self.load_all_from_yaml
       elements_map = {}
-      # Procura em todo o diretório de trabalho atual por arquivos .yaml
-      glob_path = File.join(Dir.pwd, '**', '*.yaml')
+      # ALTERADO: Lê o caminho base da configuração central.
+      config = AppiumFailureHelper.configuration
+      glob_path = File.join(Dir.pwd, config.elements_path, '**', '*.yaml')
       
       Dir.glob(glob_path).each do |file|
-        # Evita ler os próprios relatórios gerados
+        # ... (o resto do método continua igual) ...
         next if file.include?('reports_failure')
-        
         begin
           data = YAML.load_file(file)
-          if data.is_a?(Hash)
-            data.each do |key, value|
-              if value.is_a?(Hash) && value['tipoBusca'] && value['value']
-                elements_map[key] = value
-              end
-            end
-          end
+          elements_map.merge!(data) if data.is_a?(Hash)
         rescue => e
           Utils.logger.warn("Aviso: Erro ao carregar o arquivo YAML #{file}: #{e.message}")
         end
       end
       elements_map
     end
-
-    # NOVO: Método para verificar a existência de um elemento em um arquivo .rb
-    def self.find_in_ruby_file(element_name, path = 'elements/elements.rb')
-      return { found: false, path: path, reason: "Arquivo não encontrado" } unless File.exist?(path)
-
-      begin
-        content = File.read(path)
-        # Regex flexível para encontrar definições como:
-        # def nome_do_elemento
-        # element :nome_do_elemento
-        # element('nome_do_elemento')
-        if content.match?(/def #{element_name}|element[ |\(]['|:]#{element_name}/)
-          return { found: true, path: path }
-        else
-          return { found: false, path: path, reason: "Definição não encontrada" }
-        end
-      rescue => e
-        Utils.logger.warn("Aviso: Erro ao ler o arquivo Ruby #{path}: #{e.message}")
-        return { found: false, path: path, reason: "Erro de leitura" }
-      end
-    end
   end
 end

data/lib/appium_failure_helper/handler.rb

@@ -17,28 +17,17 @@ module AppiumFailureHelper
       platform = @driver.capabilities['platformName']&.downcase || 'unknown'
 
       failed_info = Analyzer.extract_failure_details(@exception)
-      
-      # ALTERADO: Agora busca em todas as fontes de dados
-      logical_name_key = failed_info[:selector_value].to_s.gsub(/^#/, '')
-      
-      # 1. Busca nos arquivos YAML dinâmicos
-      element_map_yaml = ElementRepository.load_all_from_yaml
-      de_para_yaml_result = Analyzer.find_de_para_match(failed_info, element_map_yaml)
+      unified_element_map = ElementRepository.load_all
+      de_para_result = Analyzer.find_de_para_match(failed_info, unified_element_map)
 
-      # 2. Busca no arquivo Ruby
-      de_para_rb_result = ElementRepository.find_in_ruby_file(logical_name_key)
-
-      # 3. Analisa a tela atual
       page_analyzer = PageAnalyzer.new(page_source, platform)
       all_page_elements = page_analyzer.analyze
       similar_elements = Analyzer.find_similar_elements(failed_info, all_page_elements)
 
-      # Organiza TODOS os resultados para o relatório
       report_data = {
         failed_element: failed_info,
         similar_elements: similar_elements,
-        de_para_yaml_analysis: de_para_yaml_result, # Resultado da análise YAML
-        de_para_rb_analysis: de_para_rb_result,   # Resultado da análise Ruby
+        de_para_analysis: de_para_result,
         all_page_elements: all_page_elements,
         screenshot_base64: @driver.screenshot_as(:base64),
         platform: platform,
@@ -46,7 +35,7 @@ module AppiumFailureHelper
       }
 
       ReportGenerator.new(@output_folder, page_source, report_data).generate_all
-      
+
       Utils.logger.info("Relatórios gerados com sucesso em: #{@output_folder}")
     rescue => e
       Utils.logger.error("Erro ao capturar detalhes da falha: #{e.message}\n#{e.backtrace.join("\n")}")

data/lib/appium_failure_helper/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module AppiumFailureHelper
-  VERSION = "0.6.6"
+  VERSION = "0.6.8"
 end

data/lib/appium_failure_helper.rb

@@ -15,8 +15,22 @@ require_relative 'appium_failure_helper/element_repository'
 require_relative 'appium_failure_helper/page_analyzer'
 require_relative 'appium_failure_helper/report_generator'
 require_relative 'appium_failure_helper/handler'
+require_relative 'appium_failure_helper/configuration'
+
 module AppiumFailureHelper
   class Error < StandardError; end
+  class << self
+    attr_writer :configuration
+  end
+
+  def self.configuration
+    @configuration ||= Configuration.new
+  end
+
+  def self.configure
+    yield(configuration)
+  end
+
   def self.handler_failure(driver, exception)
     Handler.call(driver, exception)
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: appium_failure_helper
 version: !ruby/object:Gem::Version
-  version: 0.6.6
+  version: 0.6.8
 platform: ruby
 authors:
 - David Nascimento
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-09-24 00:00:00.000000000 Z
+date: 2025-09-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: nokogiri
@@ -95,6 +95,7 @@ files:
 - Rakefile
 - lib/appium_failure_helper.rb
 - lib/appium_failure_helper/analyzer.rb
+- lib/appium_failure_helper/configuration.rb
 - lib/appium_failure_helper/element_repository.rb
 - lib/appium_failure_helper/handler.rb
 - lib/appium_failure_helper/page_analyzer.rb