appium_failure_helper 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 66dfd4d6024854d753fb469992d9d5ceacdceca467713f0c7ec7414c67c62acc
-  data.tar.gz: 378c3e552e1121c1634f12e22303d2194c85f6604663af6f3eeea1b0fe1092ea
+  metadata.gz: 995c0139fe92b684bf7133a42cc97c17620f59b6a827aa105d2360157c6c861f
+  data.tar.gz: cd712e634e60764c25d781f72caee2f6c4f2d7ee101e67c46a8eb021ac8cbd5b
 SHA512:
-  metadata.gz: 3725621316aec82bd374867a5ac36243b79593a0a32d9f60427032de427ae7d3764aa7460f3574480cd383a5e26acd8eb54844950ee935fd2beb447328d78b3f
-  data.tar.gz: 7c62240e427a0d612f10d6a7c2ec16d397307230a6295af6102d4eba4d41f457f22e9cc9b7347c6c52a569446829ca355a2f7d900af3e7c99fec59f0b08588c9
+  metadata.gz: d44e926ad1ae38a55f61b8dc8efa009385b91bbef5755339e08493fff6b3d0292f1524c51ead0f2753c5a480cb536cdf9abd8dc51ec9446bb126a2732ed2395b
+  data.tar.gz: 8c1855b1d74c7b0b574659b19e4dba1a0c35bac085c293a2033f536b6dfbb05765de513cedccbe4ad5780618eb2a43ca8e0278974f9f2efb09f31041ecc10b22

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 David Nascimento
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,53 @@
+# Appium Failure Helper
+
+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
+
+* **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 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:
+
+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, passando o objeto de driver do Appium.
+
+**`features/support/hooks.rb`**
+```ruby
+require 'appium_failure_helper'
+
+After do |scenario|
+  if scenario.failed?
+    AppiumFailureHelper::Capture.handler_failure(appium_driver)
+  end
+end
+
+```
+
+**Observação:** O nome da sua variável de driver pode variar. No exemplo, `appium_driver` deve ser o objeto de driver do seu teste.
+
+## Artefatos Gerados
+
+Após uma falha, os seguintes arquivos serão gerados na pasta `screenshots/`:
+
+* `screenshot_20231027_153045.png`
+
+* `page_source_20231027_153045.xml`
+
+* `element_suggestions_20231027_153045.yaml`
+
+O arquivo `.yaml` é um recurso valioso para inspecionar os elementos da tela e atualizar seus localizadores de forma eficiente.

data/Rakefile

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+task default: %i[]

data/lib/appium_failure_helper/capture.rb

@@ -0,0 +1,181 @@
+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
+
+    def self.handler_failure(driver)
+      begin
+        timestamp = Time.now.strftime('%Y%m%d_%H%M%S')
+        output_folder = "screenshots/failure_#{timestamp}"
+        
+        FileUtils.mkdir_p(output_folder)
+        
+        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 = "#{output_folder}/page_source_#{timestamp}.xml"
+        File.write(xml_path, page_source)
+
+        doc = Nokogiri::XML(page_source)
+
+        platform = driver.capabilities['platformName']&.downcase || 'unknown'
+
+        yaml_path = "#{output_folder}/element_suggestions_#{timestamp}.yaml"
+        File.open(yaml_path, 'w') do |f|
+          suggestions = doc.xpath('//*').map do |node|
+            next if node.name == 'hierarchy'
+            attrs = node.attributes.transform_values(&:value)
+            
+            name = self.suggest_name(node.name, attrs)
+            xpath = self.xpath_generator(node.name, attrs, platform)
+
+            parent_node = node.parent
+            parent_xpath = parent_node ? parent_node.path : nil
+            
+            { 
+              name: name, 
+              type: 'xpath', 
+              locator: xpath,
+              parent_locator: parent_xpath
+            }
+          end.compact
+
+          f.write(YAML.dump(suggestions))
+        end
+
+        puts "Element suggestions saved to #{yaml_path}"
+      rescue => e
+        puts "Error capturing failure details: #{e.message}\n#{e.backtrace.join("\n")}"
+      end
+    end
+
+    private
+    
+    def self.suggest_name(tag, attrs)
+      type = tag.split('.').last
+      pfx = PREFIX[tag] || PREFIX[type] || 'elm'
+      name = attrs['content-desc'] || attrs['text'] || attrs['resource-id'] || attrs['label'] || attrs['name'] || 'unknown' || type
+      name = name.strip.gsub(/[^0-9a-z]/, '').split.map(&:capitalize).join
+      "#{pfx}#{name}"
+    end
+
+    def self.xpath_generator(tag, attrs, platform)
+      case platform
+      when 'android'
+        self.generate_android_xpath(tag, attrs)
+      when 'ios'
+        self.generate_ios_xpath(tag, attrs)
+      else
+        self.generate_unknown_xpath(tag, attrs)
+      end
+    end
+
+    def self.generate_android_xpath(tag, attrs)
+      strategies = [
+        # Estratégia 1: Combinação de resource-id e text/content-desc
+        -> {
+          if attrs['resource-id'] && !attrs['resource-id'].empty?
+            if attrs['text'] && !attrs['text'].empty?
+              return "//#{tag}[@resource-id='#{attrs['resource-id']}' and @text='#{attrs['text']}']"
+            elsif attrs['content-desc'] && !attrs['content-desc'].empty?
+              return "//#{tag}[@resource-id='#{attrs['resource-id']}' and @content-desc='#{attrs['content-desc']}']"
+            end
+          end
+          nil
+        },
+        # Estratégia 2: resource-id único
+        -> { "//#{tag}[@resource-id='#{attrs['resource-id']}']" if attrs['resource-id'] && !attrs['resource-id'].empty? },
+        # Estratégia 3: starts-with para resource-id dinâmico
+        -> {
+          if attrs['resource-id'] && attrs['resource-id'].include?(':id/')
+            id_part = attrs['resource-id'].split(':id/').last
+            return "//#{tag}[starts-with(@resource-id, '#{id_part}')]"
+          end
+          nil
+        },
+        # Estratégia 4: text como identificador
+        -> { "//#{tag}[@text='#{attrs['text']}']" if attrs['text'] && !attrs['text'].empty? },
+        # Estratégia 5: content-desc como identificador
+        -> { "//#{tag}[@content-desc='#{attrs['content-desc']}']" if attrs['content-desc'] && !attrs['content-desc'].empty? },
+        # Estratégia 6: Fallback genérico
+        -> { "//#{tag}" }
+      ]
+
+      strategies.each do |strategy|
+        result = strategy.call
+        return result if result
+      end
+    end
+
+    def self.generate_ios_xpath(tag, attrs)
+      strategies = [
+        # Estratégia 1: Combinação de accessibility-id e label
+        -> {
+          if attrs['accessibility-id'] && !attrs['accessibility-id'].empty?
+            if attrs['label'] && !attrs['label'].empty?
+              return "//#{tag}[@accessibility-id='#{attrs['accessibility-id']}' and @label='#{attrs['label']}']"
+            end
+          end
+          nil
+        },
+        # Estratégia 2: accessibility-id como identificador
+        -> { "//#{tag}[@accessibility-id='#{attrs['accessibility-id']}']" if attrs['accessibility-id'] && !attrs['accessibility-id'].empty? },
+        # Estratégia 3: label como identificador
+        -> { "//#{tag}[@label='#{attrs['label']}']" if attrs['label'] && !attrs['label'].empty? },
+        # Estratégia 4: name como identificador
+        -> { "//#{tag}[@name='#{attrs['name']}']" if attrs['name'] && !attrs['name'].empty? },
+        # Estratégia 5: Fallback genérico
+        -> { "//#{tag}" }
+      ]
+
+      strategies.each do |strategy|
+        result = strategy.call
+        return result if result
+      end
+    end
+
+    def self.generate_unknown_xpath(tag, attrs)
+      if attrs['resource-id'] && !attrs['resource-id'].empty?
+        "//#{tag}[@resource-id='#{attrs['resource-id']}']"
+      elsif attrs['content-desc'] && !attrs['content-desc'].empty?
+        "//#{tag}[@content-desc='#{attrs['content-desc']}']"
+      elsif attrs['text'] && !attrs['text'].empty?
+        "//#{tag}[@text='#{attrs['text']}']"
+      else
+        "//#{tag}"
+      end
+    end
+  end
+end

data/lib/appium_failure_helper/version.rb

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

data/lib/appium_failure_helper.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require_relative "appium_failure_helper/version"
+require_relative "appium_failure_helper/capture"
+module AppiumFailureHelper
+  class Error < StandardError; end
+  # Your code goes here...
+end

data/sig/appium_failure_helper.rbs

@@ -0,0 +1,4 @@
+module AppiumFailureHelper
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: appium_failure_helper
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - David Nascimento
@@ -9,7 +9,77 @@ autorequire:
 bindir: exe
 cert_chain: []
 date: 2025-09-23 00:00:00.000000000 Z
-dependencies: []
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: nokogiri
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.15'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.15'
+- !ruby/object:Gem::Dependency
+  name: appium_lib
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
 description: Appium Failure Helper is a Ruby gem that provides utilities to capture
   failures during Appium test executions. It extracts and saves relevant information
   from the page source, including screenshots and element details, to aid in debugging
@@ -19,7 +89,14 @@ email:
 executables: []
 extensions: []
 extra_rdoc_files: []
-files: []
+files:
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/appium_failure_helper.rb
+- lib/appium_failure_helper/capture.rb
+- lib/appium_failure_helper/version.rb
+- sig/appium_failure_helper.rbs
 homepage: https://github.com/David-Nascimento/Appium_failure_helper
 licenses:
 - MIT