appium_failure_helper 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7d0e003d2181e4acd5e7a6b8800050ed5d4b58ba8f2b1b6bad77f44f5c952c39
+  data.tar.gz: 14c6708100bb1f3651bcdaae8576459637b87b3bbf9cb6f19e8bf3a8cf29fafc
+SHA512:
+  metadata.gz: 67f9453d58528ee83c56ad0da163256ca850c70c68490515b5ce837089aba77849dde082016c382ac7c6bb38fe520f42b4f495c9efa946a4e36d82b42958bc1d
+  data.tar.gz: '0477783e4d83ad5590634bcb3379f332d371426f5c10a52a49b2774a104669c63491ad5920b4d9fe5de6a1e812262d7e01de07cce0175d1f439c9d296308fa5e'

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,62 @@
+# 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.
+
+## 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.
+
+## 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`.
+
+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"]`.
+
+## Uso
+
+Para usar este helper, integre-o ao seu framework de testes. Um exemplo comum é utilizá-lo em um hook `After` do Cucumber:
+
+**`features/support/hooks.rb`**
+
+```
+require 'caminho/para/o/seu/modulo' # Ajuste o caminho
+
+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,77 @@
+require 'nokogiri'
+require 'fileutils'
+require 'base64'
+
+module AppiumFailureHelper
+  class Capture
+    def self.handler_failure(driver)
+      begin
+        timestamp = Time.now.strftime('%Y%m%d_%H%M%S')
+        folder_path = "screenshots"
+        
+        # Lógica melhorada para criar a pasta.
+        # O método mkdir_p cria a pasta apenas se ela não existir,
+        # tornando a verificação Dir.exist? desnecessária.
+        FileUtils.mkdir_p(folder_path)
+        
+        screenshot_path = "#{folder_path}/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"
+        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',
+        }
+
+        def suggest_name(tag, attrs, prefix)
+          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}#{name}"
+        end
+
+        def 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']}']"
+          else
+            "//#{type}"
+          end
+        end
+
+        line = doc.xpath('//*').map do |node|
+          next if node.name == 'hierarchy'
+          attrs = node.attributes.transform_values(&:value)
+          name = suggest_name(node.name, attrs, prefix)
+          xpath = xpath_generator(node.name, attrs)
+          "[\"#{name}\", \"xpath\", \"#{xpath}\"]"
+        end
+
+        yaml_path = "#{folder_path}/element_suggestions_#{timestamp}.yaml"
+        File.open(yaml_path, 'w') {|f| f.puts(line.compact.join("\n"))}
+
+        puts "Element suggestions saved to #{yaml_path}"
+      rescue => e
+        puts "Error capturing failure details: #{e.message}"
+      end
+    end
+  end
+end

data/lib/appium_failure_helper/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module AppiumFailureHelper
+  VERSION = "0.1.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

@@ -0,0 +1,54 @@
+--- !ruby/object:Gem::Specification
+name: appium_failure_helper
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- David Nascimento
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2025-09-23 00:00:00.000000000 Z
+dependencies: []
+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
+  and analysis.
+email:
+- halison700@gmail.com
+executables: []
+extensions: []
+extra_rdoc_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
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.27
+signing_key:
+specification_version: 4
+summary: Helper to capture Appium failure and extract elements information from page
+  source
+test_files: []