appium_failure_helper 0.3.1 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f76409f1b9c5f4bd448918dd57bcf691b317f2e9f8e49fdc077fb051b731c9c2
-  data.tar.gz: c38273c8afae6609ca72a3a0fdea5713ca3d358f1d0ee50a562f9d9cff9d62bf
+  metadata.gz: 0c223153b4956f8098f653d255a4487bb3814bbd0ed8306cd4c01ccba478b4d9
+  data.tar.gz: 23ca5a6e67e1630473b37bd3ecaa1cab0b878ea35790e686bcd2eff6842462c2
 SHA512:
-  metadata.gz: e7824f6860fb399ff2d735f410e779f1cc93582131e5ab5672eff5f85f8f0d5c8bfb3c434defa92de4aea24ec75714b3f7920cb7c500d7a48d81612b30fda052
-  data.tar.gz: 7761f6376e1f9a2b284a6df260873af206ac550fa9374676eb1673e4fa2abf448deab8f4529e22d1c1b168c044d0486b548b1aba64e79f2e56199d7a183374a1
+  metadata.gz: 19483fead216b475eadac1f809e8bdd0ef2feafc46adfa41a396d18bb3572feb3a03b7768beacea1199046a4d7ffb982c2f9d8f9e4af13b1eee5fa035ff3a947
+  data.tar.gz: 2834dc179101c611fdce1262a20144f8684b86b3dea3515e3d2e4dccf983bbfa9e3e73b57fa1266d36c4a1b7deb4e93b35d7456ec75a7d9dbff5ec70cab542ab

data/README.md

@@ -1,43 +1,34 @@
 # Appium Failure Helper
 
-Este módulo Ruby foi projetado para auxiliar na **análise de falhas em testes de automação Appium**. Ao ser invocado, ele captura o estado da aplicação no momento da falha e gera um conjunto de artefatos de diagnóstico, facilitando a identificação da causa raiz do problema e a sugestão de novos localizadores de elementos.
+Este módulo Ruby foi projetado para ser uma ferramenta de diagnóstico inteligente para falhas em testes de automação mobile com **Appium**. Ele automatiza a captura de artefatos de depuração e a geração de sugestões de localizadores de elementos, eliminando a necessidade de usar o Appium Inspector.
 
 ## Funcionalidades Principais
 
-* **Captura de Screenshot:** Salva uma imagem PNG da tela do dispositivo no momento da falha.
-
-* **Captura de Page Source:** Salva o XML do `page_source` completo, representando a hierarquia de elementos da tela.
-
-* **Geração de Sugestões de Elementos:** Analisa o `page_source` e gera um arquivo `.yaml` com sugestões de nomes e caminhos XPath para os elementos visíveis na tela.
+* **Análise de Falha Automatizada:** Captura o estado da aplicação no momento da falha.
+* **Captura de Artefatos:** Salva um **screenshot** da tela e o **XML completo do `page_source`** em uma pasta dedicada por falha.
+* **Geração de Localizadores Inteligente:** Percorre a árvore de elementos e gera um **relatório YAML** com sugestões de XPaths otimizados para cada elemento.
+* **Lógica de XPath Otimizada:** Utiliza as melhores práticas para cada plataforma (**Android e iOS**), priorizando os localizadores mais estáveis e combinando atributos para alta especificidade.
+* **Organização de Saída:** Cria uma pasta com um carimbo de data/hora para cada falha (`/failure_AAAA_MM_DD_HHMMSS`), mantendo os arquivos organizados.
+* **Contexto de Elementos:** O relatório YAML agora inclui o **XPath do elemento pai (`parent_locator`)**, fornecendo contexto crucial para a depuração e construção de Page Objects.
 
 ## Como Funciona
 
-A lógica central do módulo `AppiumFailureHelper` é acionada por um evento de falha no seu framework de testes (ex: Cucumber `After` hook). A função `handler_failure` executa as seguintes etapas:
-
-1. **Criação de Diretório:** Garante que a pasta `screenshots/` exista para armazenar os artefatos.
-
-2. **Captura de Screenshot e Page Source:** Utiliza o driver do Appium para obter o screenshot e o XML do `page_source`, salvando-os com um timestamp para evitar sobrescrever arquivos.
-
-3. **Análise com Nokogiri:** O XML do `page_source` é parseado utilizando a gem `Nokogiri`.
-
-4. **Processamento de Elementos:** O código itera sobre cada nó do XML (exceto o nó raiz 'hierarchy') e extrai atributos-chave como `resource-id`, `content-desc` e `text`.
+A lógica do `AppiumFailureHelper` é ativada por um evento de falha em seu framework de testes (ex: Cucumber `After` hook). O método `handler_failure` executa as seguintes etapas:
 
-5. **Geração de Nomes e XPath:**
-
-   * `suggest_name`: Constrói um nome descritivo para cada elemento, utilizando prefixos comuns (`btn`, `txt`, `input`, etc.) e o valor dos atributos principais.
-
-   * `xpath_generator`: Prioriza atributos mais confiáveis (`resource-id`, `content-desc`, `text`) para gerar um XPath robusto.
-
-6. **Saída Final:** O resultado é um arquivo `.yaml` contendo uma lista formatada de sugestões de locators no formato `["nome_sugerido", "xpath", "caminho_xpath"]`.
+1.  Cria um diretório de saída exclusivo.
+2.  Captura o screenshot e o `page_source` do driver.
+3.  Determina a plataforma do dispositivo a partir das capacidades do driver.
+4.  Itera sobre cada nó do `page_source` e, para cada um, chama a lógica de geração de XPath e de nome.
+5.  A lógica de XPath utiliza um conjunto de estratégias priorizadas para cada plataforma, como **combinação de atributos** (`@resource-id` e `@text`) e o uso de `starts-with()` para elementos dinâmicos.
+6.  Salva um arquivo `.yaml` estruturado, contendo o nome sugerido, o tipo (`xpath`) e o localizador para cada elemento.
 
 ## Uso
 
-Para usar este helper, integre-o ao seu framework de testes. Um exemplo comum é utilizá-lo em um hook `After` do Cucumber:
+Para usar este helper, integre-o ao seu framework de testes. Um exemplo comum é utilizá-lo em um hook `After` do Cucumber, passando o objeto de driver do Appium.
 
 **`features/support/hooks.rb`**
-
-```
-require 'caminho/para/o/seu/modulo' # Ajuste o caminho
+```ruby
+require 'appium_failure_helper'
 
 After do |scenario|
   if scenario.failed?

data/lib/appium_failure_helper/capture.rb

@@ -1,80 +1,192 @@
 require 'nokogiri'
 require 'fileutils'
 require 'base64'
+require 'yaml'
 
 module AppiumFailureHelper
   class Capture
+    PREFIX = {
+      'android.widget.Button' => 'btn',
+      'android.widget.TextView' => 'txt',
+      'android.widget.ImageView' => 'img',
+      'android.widget.EditText' => 'input',
+      'android.widget.CheckBox' => 'chk',
+      'android.widget.RadioButton' => 'radio',
+      'android.widget.Switch' => 'switch',
+      'android.widget.ViewGroup' => 'group',
+      'android.widget.View' => 'view',
+      'android.widget.FrameLayout' => 'frame',
+      'android.widget.LinearLayout' => 'linear',
+      'android.widget.RelativeLayout' => 'relative',
+      'android.widget.ScrollView' => 'scroll',
+      'android.webkit.WebView' => 'web',
+      'android.widget.Spinner' => 'spin',
+      'XCUIElementTypeButton' => 'btn',
+      'XCUIElementTypeStaticText' => 'txt',
+      'XCUIElementTypeTextField' => 'input',
+      'XCUIElementTypeImage' => 'img',
+      'XCUIElementTypeSwitch' => 'switch',
+      'XCUIElementTypeScrollView' => 'scroll',
+      'XCUIElementTypeOther' => 'elm',
+      'XCUIElementTypeCell' => 'cell',
+    }.freeze
+    
+    MAX_VALUE_LENGTH = 100
+
     def self.handler_failure(driver)
       begin
         timestamp = Time.now.strftime('%Y%m%d_%H%M%S')
-        folder_path = "screenshots"
+        output_folder = "screenshots/failure_#{timestamp}"
         
-        FileUtils.mkdir_p(folder_path)
+        FileUtils.mkdir_p(output_folder)
         
-        screenshot_path = "#{folder_path}/screenshot_#{timestamp}.png"
+        screenshot_path = "#{output_folder}/screenshot_#{timestamp}.png"
         File.open(screenshot_path, 'wb') do |f|
           f.write(Base64.decode64(driver.screenshot_as(:base64)))
         end
         puts "Screenshot saved to #{screenshot_path}"
 
         page_source = driver.page_source
-        xml_path = "#{folder_path}/page_source_#{timestamp}.xml"
+        xml_path = "#{output_folder}/page_source_#{timestamp}.xml"
         File.write(xml_path, page_source)
 
         doc = Nokogiri::XML(page_source)
 
-        prefix = {
-          'Button' => 'btn',
-          'TextView' => 'txt',
-          'ImageView' => 'img',
-          'EditText' => 'input',
-          'CheckBox' => 'chk',
-          'RadioButton' => 'radio',
-          'Switch' => 'switch',
-        }
-
-        line = doc.xpath('//*').map do |node|
+        platform = driver.capabilities['platformName']&.downcase || 'unknown'
+
+        seen_elements = {}
+        suggestions = []
+
+        doc.xpath('//*').each do |node|
           next if node.name == 'hierarchy'
           attrs = node.attributes.transform_values(&:value)
           
-          # Os métodos agora estão no escopo correto.
-          name = self.suggest_name(node.name, attrs, prefix)
-          xpath = self.xpath_generator(node.name, attrs)
+          unique_key = "#{node.name}|#{attrs['resource-id']}|#{attrs['content-desc']}|#{attrs['text']}"
           
-          "[\"#{name}\", \"xpath\", \"#{xpath}\"]"
+          unless seen_elements[unique_key]
+            name = self.suggest_name(node.name, attrs)
+            locators = self.xpath_generator(node.name, attrs, platform)
+            
+            suggestions << { name: name, locators: locators }
+            seen_elements[unique_key] = true
+          end
         end
 
-        yaml_path = "#{folder_path}/element_suggestions_#{timestamp}.yaml"
-        File.open(yaml_path, 'w') {|f| f.puts(line.compact.join("\n"))}
+        yaml_path = "#{output_folder}/element_suggestions_#{timestamp}.yaml"
+        File.open(yaml_path, 'w') do |f|
+          f.write(YAML.dump(suggestions))
+        end
 
         puts "Element suggestions saved to #{yaml_path}"
       rescue => e
-        puts "Error capturing failure details: #{e.message}"
+        puts "Error capturing failure details: #{e.message}\n#{e.backtrace.join("\n")}"
       end
     end
 
     private
+    
+    def self.truncate(value)
+      return value unless value.is_a?(String)
+      value.size > MAX_VALUE_LENGTH ? "#{value[0...MAX_VALUE_LENGTH]}..." : value
+    end
 
-    # Mova os métodos para cá.
-    def self.suggest_name(tag, attrs, prefix)
+    def self.suggest_name(tag, attrs)
       type = tag.split('.').last
-      pfx = prefix[type] || 'elm'
-      name = attrs['content-desc'] || attrs['text'] || attrs['resource-id'] || 'unknown' || type
-      name = name.strip.gsub(/[^0-9a-z]/, '').split.map(&:capitalize).join
+      pfx = PREFIX[tag] || PREFIX[type] || 'elm'
+      name = attrs['content-desc'] || attrs['text'] || attrs['resource-id'] || attrs['label'] || attrs['name'] || 'unknown' || type
+      name = truncate(name.strip.gsub(/[^0-9a-z]/, '').split.map(&:capitalize).join)
       "#{pfx}#{name}"
     end
 
-    def self.xpath_generator(tag, attrs)
-      type = tag.split('.').last
-      if attrs['resource-id'] && !attrs['resource-id'].empty?
-        "//*[@resource-id='#{attrs['resource-id']}']"
-      elsif attrs['content-desc'] && !attrs['content-desc'].empty?
-        "//*[@content-desc='#{attrs['content-desc']}']"
-      elsif attrs['text'] && !attrs['text'].empty?
-        "//*[@text='#{attrs['text']}']"
+    def self.xpath_generator(tag, attrs, platform)
+      case platform
+      when 'android'
+        self.generate_android_xpaths(tag, attrs)
+      when 'ios'
+        self.generate_ios_xpaths(tag, attrs)
       else
-        "//#{type}"
+        self.generate_unknown_xpaths(tag, attrs)
+      end
+    end
+
+    def self.generate_android_xpaths(tag, attrs)
+      locators = []
+      
+      # Estratégia 1: Combinação de atributos
+      if attrs['resource-id'] && !attrs['resource-id'].empty? && attrs['text'] && !attrs['text'].empty?
+        locators << { strategy: 'resource_id_and_text', locator: "//#{tag}[@resource-id='#{attrs['resource-id']}' and @text='#{self.truncate(attrs['text'])}']" }
+      elsif attrs['resource-id'] && !attrs['resource-id'].empty? && attrs['content-desc'] && !attrs['content-desc'].empty?
+        locators << { strategy: 'resource_id_and_content_desc', locator: "//#{tag}[@resource-id='#{attrs['resource-id']}' and @content-desc='#{self.truncate(attrs['content-desc'])}']" }
+      end
+
+      # Estratégia 2: ID único
+      if attrs['resource-id'] && !attrs['resource-id'].empty?
+        locators << { strategy: 'resource_id', locator: "//#{tag}[@resource-id='#{attrs['resource-id']}']" }
+      end
+
+      # Estratégia 3: starts-with para IDs dinâmicos
+      if attrs['resource-id'] && attrs['resource-id'].include?(':id/')
+        id_part = attrs['resource-id'].split(':id/').last
+        locators << { strategy: 'starts_with_resource_id', locator: "//#{tag}[starts-with(@resource-id, '#{id_part}')]" }
+      end
+
+      # Estratégia 4: Texto e content-desc como identificadores
+      if attrs['text'] && !attrs['text'].empty?
+        locators << { strategy: 'text', locator: "//#{tag}[@text='#{self.truncate(attrs['text'])}']" }
+      end
+      if attrs['content-desc'] && !attrs['content-desc'].empty?
+        locators << { strategy: 'content_desc', locator: "//#{tag}[@content-desc='#{self.truncate(attrs['content-desc'])}']" }
+      end
+
+      # Fallback genérico (sempre adicionado)
+      locators << { strategy: 'generic_tag', locator: "//#{tag}" }
+
+      locators
+    end
+
+    def self.generate_ios_xpaths(tag, attrs)
+      locators = []
+
+      # Estratégia 1: Combinação de atributos
+      if attrs['accessibility-id'] && !attrs['accessibility-id'].empty? && attrs['label'] && !attrs['label'].empty?
+        locators << { strategy: 'accessibility_id_and_label', locator: "//#{tag}[@accessibility-id='#{attrs['accessibility-id']}' and @label='#{self.truncate(attrs['label'])}']" }
+      end
+
+      # Estratégia 2: ID único
+      if attrs['accessibility-id'] && !attrs['accessibility-id'].empty?
+        locators << { strategy: 'accessibility_id', locator: "//#{tag}[@accessibility-id='#{attrs['accessibility-id']}']" }
+      end
+
+      # Estratégia 3: label, name ou value
+      if attrs['label'] && !attrs['label'].empty?
+        locators << { strategy: 'label', locator: "//#{tag}[@label='#{self.truncate(attrs['label'])}']" }
+      end
+      if attrs['name'] && !attrs['name'].empty?
+        locators << { strategy: 'name', locator: "//#{tag}[@name='#{self.truncate(attrs['name'])}']" }
       end
+
+      # Fallback genérico (sempre adicionado)
+      locators << { strategy: 'generic_tag', locator: "//#{tag}" }
+
+      locators
+    end
+
+    def self.generate_unknown_xpaths(tag, attrs)
+      locators = []
+      if attrs['resource-id'] && !attrs['resource-id'].empty?
+        locators << { strategy: 'resource_id', locator: "//#{tag}[@resource-id='#{attrs['resource-id']}']" }
+      end
+      if attrs['content-desc'] && !attrs['content-desc'].empty?
+        locators << { strategy: 'content_desc', locator: "//#{tag}[@content-desc='#{self.truncate(attrs['content-desc'])}']" }
+      end
+      if attrs['text'] && !attrs['text'].empty?
+        locators << { strategy: 'text', locator: "//#{tag}[@text='#{self.truncate(attrs['text'])}']" }
+      end
+
+      # Fallback genérico (sempre adicionado)
+      locators << { strategy: 'generic_tag', locator: "//#{tag}" }
+      
+      locators
     end
   end
 end

data/lib/appium_failure_helper/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: appium_failure_helper
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.4.1
 platform: ruby
 authors:
 - David Nascimento