appium_failure_helper 0.5.0 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c7344cd53f36a48ed0689b608758d04724a1f2dc122197171e5b875bb08615fb
-  data.tar.gz: acc66c6049fe82c85dc769591b7a81befda696cc5c4b02e8b8bd99ec60b643ac
+  metadata.gz: c0e272f2150ce88e42b3b414d0afeb9d4e2309311bd271d77bf912ac3967ad03
+  data.tar.gz: 982e97ea6c9a43da40ea9315f554bc734b076b20aaf68b61f1cef83bf3455349
 SHA512:
-  metadata.gz: 44d7f03b734112353b8c5c7f0db157f125d54e7d9065471e5caba380c44d851f6a8eb757d410ec0f6280b412fc6b442eeb3b303143e98c0599b7d5adcf3d7792
-  data.tar.gz: 48469708fd272ac232494b32bccbf1a99c4cc277a60cca1296eaf6d29128e55794a16987939a1f89fc3a9d8c2ec37ab9a56686a4edc80e4e4cd73de6948031cb
+  metadata.gz: 8d431703babb06ffde65176ec6b16233738790261efbee46376f2b6bb90f1fd42717505d4ab6c78b454bf61bc3e656c2f8e9e1ef3936ea8841b585ec152e51f3
+  data.tar.gz: d7df2cb2f3757ae8298ce7b8057e11ea66b0112ba38fb15e01e6e8bcb73b3dad26035bcfdeba8dc97e823bf608de787b2b47c3dceb28d0b988525812b4730ebd

data/README.md

@@ -1,32 +1,130 @@
 # 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.
+[![Ruby](https://img.shields.io/badge/language-ruby-red.svg)](https://www.ruby-lang.org/)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Status](https://img.shields.io/badge/status-beta-yellow.svg)]()
 
-## Funcionalidades Principais
+**Appium Failure Helper** é um módulo Ruby destinado a automatizar diagnóstico de falhas em testes de automação mobile com **Appium**. O objetivo é reduzir tempo de triagem, fornecer localizadores confiáveis e coletar artefatos de depuração sem depender do Appium Inspector.
 
-* **Diagnóstico de Falha Automatizado:** No momento de uma falha, a ferramenta captura automaticamente o estado da aplicação e gera um conjunto de artefatos de depuração.
+---
 
-* **Captura de Artefatos:** Salva um **screenshot** da tela, o **XML completo do `page_source`**, e um relatório de análise em uma pasta com carimbo de data e hora para cada falha.
+## Sumário
+- [Visão Geral](#visão-geral)
+- [Funcionalidades](#funcionalidades)
+- [Arquitetura e Fluxo](#arquitetura-e-fluxo)
+- [Instalação](#instalação)
+- [Configuração (opcional)](#configuração-opcional)
+- [API Pública / Integração](#api-pública--integração)
+- [Exemplos de Uso](#exemplos-de-uso)
+  - [Cucumber (hook After)](#cucumber-hook-after)
+  - [RSpec (after :each)](#rspec-after-each)
+- [Formato dos Artefatos Gerados](#formato-dos-artefatos-gerados)
+- [Lógica de Geração de XPaths (detalhada)](#lógica-de-geração-de-xpaths-detalhada)
+- [Tratamento de Dados e Deduplicação](#tratamento-de-dados-e-deduplicação)
+- [Relatório HTML Interativo](#relatório-html-interativo)
+- [Logging e Observabilidade](#logging-e-observabilidade)
+- [Testes e Qualidade](#testes-e-qualidade)
+- [Roadmap e Contribuição](#roadmap-e-contribuição)
+- [Licença](#licença)
 
-* **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.
+## Visão Geral
 
-* **Tratamento de Dados:** Trunca valores de atributos muito longos para evitar quebras no relatório e garante que não haja elementos duplicados.
+No momento em que um teste falha, o módulo realiza, de forma atômica e thread-safe:
+1. captura de screenshot,
+2. extração do `page_source` completo (XML),
+3. varredura da árvore de elementos para gerar localizadores sugeridos,
+4. escrita de dois YAMLs (focado e completo) e um relatório HTML que agrega tudo.
 
-* **Sistema de Logging:** Usa a biblioteca padrão `Logger` do Ruby para fornecer feedback detalhado e limpo no console.
+Todos os artefatos são salvos em uma pasta timestamped (formato `YYYY_MM_DD_HHMMSS`) dentro de `reports_failure/`.
 
-* **Múltiplos Relatórios:** Gera dois arquivos YAML: um **focado** no elemento que falhou e um **completo** com todos os elementos da tela.
+---
 
-* **Relatório HTML Interativo:** Cria um relatório HTML visualmente agradável que une o screenshot, o XML e os localizadores sugeridos em uma única página para fácil acesso e análise.
+## Funcionalidades
 
-## Como Funciona
+- Captura automática de screenshot PNG.
+- Export completo de `page_source` em XML.
+- Geração de `failure_analysis_*.yaml` (focado no elemento que falhou).
+- Geração de `all_elements_dump_*.yaml` (todos os elementos com localizadores sugeridos).
+- Relatório HTML interativo que combine screenshot, XML formatado e lista de localizadores.
+- Geração de XPaths otimizados para **Android** e **iOS**.
+- Truncamento de atributos longos (configurável).
+- Eliminação de elementos duplicados e normalização de atributos.
+- Logging via `Logger` do Ruby (Níveis: DEBUG/INFO/WARN/ERROR).
+- Configuração via bloco `configure` (opcional).
 
-O `AppiumFailureHelper` deve ser integrado ao seu framework de testes. Um exemplo comum é utilizá-lo em um hook `After` do Cucumber, passando o objeto de driver do Appium e a exceção do cenário.
+---
 
-**`features/support/hooks.rb`**
+## Arquitetura e Fluxo
+
+1. **Hook de Testes** (Cucumber/RSpec) → invoca `Capture.handler_failure(driver, exception)`
+2. **Capture.handler_failure**:
+   - estabelece pasta de saída com timestamp;
+   - chama `driver.screenshot` (salva PNG);
+   - chama `driver.page_source` (salva XML);
+   - percorre XML e cria árvore de elementos;
+   - para cada elemento gera candidate XPaths aplicando regras por plataforma;
+   - grava `failure_analysis_*.yaml` (prioriza elemento indicado) e `all_elements_dump_*.yaml`;
+   - monta `report_*.html` agregando tudo.
+3. Logs detalhados emitidos durante a execução.
+
+---
+
+## Instalação
+
+**Como gem (exemplo):**
+
+Adicione ao `Gemfile` do projeto:
+
+```ruby
+gem 'appium_failure_helper', '~> 0.1.0'
+```
+
+Depois:
+
+```bash
+bundle install
+```
+
+**Ou manual (para uso local):**
+
+Coloque o diretório `appium_failure_helper/` dentro do `lib/` do projeto e faça:
+
+```ruby
+require_relative 'lib/appium_failure_helper'
+```
+
+---
+
+## API Pública / Integração
+
+### `AppiumFailureHelper::Capture`
 
 ```ruby
+# handler_failure(driver, exception, options = {})
+# - driver: objeto de sessão Appium (Selenium::WebDriver / Appium::Driver)
+# - exception: exceção capturada no momento da falha
+# - options: hash com overrides (ex: output_dir:)
+AppiumFailureHelper::Capture.handler_failure(appium_driver, scenario.exception)
+```
+
+### Configuração global
+
+```ruby
+AppiumFailureHelper.configure do |c|
+  # ver bloco de configuração acima
+end
+```
+
+---
+
+## Exemplos de Uso
+
+### Cucumber (hook `After`)
+
+```ruby
+# features/support/hooks.rb
 require 'appium_failure_helper'
 
 After do |scenario|
@@ -34,19 +132,159 @@ After do |scenario|
     AppiumFailureHelper::Capture.handler_failure(appium_driver, scenario.exception)
   end
 end
+```
+
+---
+
+## Formato dos Artefatos Gerados
+
+**Pasta:** `reports_failure/<TIMESTAMP>/`
 
+Arquivos gerados (ex.: TIMESTAMP = `2025_09_23_173045`):
+
+```
+screenshot_2025_09_23_173045.png
+page_source_2025_09_23_173045.xml
+failure_analysis_2025_09_23_173045.yaml
+all_elements_dump_2025_09_23_173045.yaml
+report_2025_09_23_173045.html
+```
+
+### Exemplo (simplificado) de `failure_analysis_*.yaml`
+
+```yaml
+failed_element:
+  platform: android
+  summary:
+    class: android.widget.Button
+    resource_id: com.example:id/submit
+    text: "Enviar"
+  suggested_xpaths:
+    - "//android.widget.Button[@resource-id='com.example:id/submit']"
+    - "//android.widget.Button[contains(@text,'Enviar')]"
+  capture_metadata:
+    screenshot: screenshot_2025_09_23_173045.png
+    page_source: page_source_2025_09_23_173045.xml
+    timestamp: "2025-09-23T17:30:45Z"
+tips: "Priorize resource-id; se ausente, use accessibility id (content-desc) e class+text como fallback."
+```
+
+### Exemplo (simplificado) de `all_elements_dump_*.yaml`
+
+```yaml
+elements:
+  - id_hash: "a1b2c3..."
+    class: "android.widget.EditText"
+    resource_id: "com.example:id/input_email"
+    text: "example@example.com"
+    truncated_attributes:
+      hint: "Digite seu e-mail..."
+    suggested_xpaths:
+      - "//*[@resource-id='com.example:id/input_email']"
+      - "//android.widget.EditText[contains(@hint,'Digite seu e-mail')]"
+```
+
+---
+
+## Lógica de Geração de XPaths (detalhada)
+
+**Princípios gerais**
+1. Priorizar identificadores estáveis (resource-id no Android / accessibility id no iOS).
+2. Evitar XPaths com `index` como primeira opção (usado apenas como último recurso).
+3. Combinar atributos quando necessário para aumentar a especificidade e evitar colisões.
+4. Normalizar espaços e truncar textos longos.
+
+**Estratégias por plataforma (ordem de preferência)**
+
+- **Android**
+  1. `resource-id` → `//*[@resource-id='com.pkg:id/id']`
+  2. `content-desc` / `contentDescription` (accessibility) → `//*[@content-desc='x']`
+  3. `class` + `text` → `//android.widget.TextView[@class='...' and contains(normalize-space(@text),'...')]`
+  4. `class` + raça de atributos (combinações: enabled, clickable, package)
+  5. fallback: `//android.widget.Button[position()=n]` (último recurso)
+
+- **iOS**
+  1. `accessibility id` (nome accessibility) → `//*[@name='Submit']`
+  2. `label` / `value` → `//*[contains(@label,'...')]`
+  3. `type` + `label` → `//XCUIElementTypeButton[@label='OK']`
+  4. fallback: hierarquia / indices
+
+**Exemplo de XPath combinado (alta especificidade):**
+
+```xpath
+//android.widget.Button[@resource-id='com.example:id/submit' and contains(normalize-space(@text),'Enviar') and @clickable='true']
 ```
 
-**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.
+---
+
+## Tratamento de Dados e Deduplicação
+
+- **Truncamento**: atributos com comprimento acima de `attr_truncate_length` são truncados com sufixo `...` para evitar poluição do YAML.
+- **Hash único por elemento**: é gerado um hash (sha1) baseado em conjunto de atributos relevantes (class+resource-id+content-desc+text) para identificar duplicados.
+- **Remoção de nulos**: atributos vazios ou nulos são omitidos nos YAMLs.
+- **Ordenação**: elementos no `all_elements_dump` são ordenados por prioridade de localizador (resource-id primeiro).
+
+---
+
+## Relatório HTML Interativo
+
+O HTML gerado possui:
+- Visualização inline do `screenshot` (img tag),
+- Painel colapsável com o `page_source` (XML formatado e collapsible),
+- Lista navegável de elementos com seus `suggested_xpaths` (botões para copiar),
+- Ancoragem que permite focalizar: ao clicar em um XPath, realça o fragmento correspondente no XML (se possível),
+- Metadados e link rápido para os YAMLs.
+
+**Observação:** o HTML é gerado de forma estática — para realces dinâmicos é usado JavaScript simples embutido (sem dependências externas).
+
+---
+
+## Logging e Observabilidade
+
+- Usa `Logger` padrão do Ruby:
+  - `DEBUG` para detalhamento completo (padrão em modo dev).
+  - `INFO` para resumo das ações realizadas.
+  - `WARN/ERROR` para problemas durante captura/escrita.
+- Exemplos de mensagens:
+  - `[INFO] Creating failure report folder: reports_failure/2025_09_23_173045`
+  - `[DEBUG] Captured 4123 elements from page_source`
+  - `[ERROR] Failed to write screenshot: Permission denied`
+
+---
+
+## Testes e Qualidade
+
+- Estrutura de testes sugerida: RSpec + fixtures com dumps de `page_source` para validar a geração de XPaths.
+- Testes unitários para: truncamento, hash de deduplicação, geração de strategies, output YAML válido.
+- CI: incluir step que valide YAML/HTML gerados (lint) e execute testes RSpec.
+
+---
+
+## Roadmap e Contribuição
+
+**Funcionalidades previstas**
+- Suporte a mapeamento visual (overlay) para apontar elemento sobre screenshot.
+- Export para outros formatos (JSON/CSV).
+- Integração com ferramentas de observabilidade (Sentry, Datadog).
+- Modo headless para gerar relatórios offline em pipelines.
+
+**Como contribuir**
+1. Fork no repositório.
+2. Crie branch com feature/bugfix.
+3. Abra PR com descrição técnica das mudanças e testes.
+4. Mantenha o estilo Ruby (RuboCop) e documentação atualizada.
+
+---
 
-## Artefatos Gerados
+## Segurança e Privacidade
 
-Após uma falha, os seguintes arquivos serão gerados na pasta `screenshots/`:
+- Evite capturar dados sensíveis em ambientes com PII. Implementar filtro por regex para mascarar dados (ex.: emails/telefones) antes de salvar YAMLs.
+- Recomendado: executar limpeza em ambientes de produção.
 
-* `screenshot_20231027_153045.png`
+---
 
-* `page_source_20231027_153045.xml`
+## Licença
 
-* `element_suggestions_20231027_153045.yaml`
+MIT — veja o arquivo `LICENSE` para os termos.
 
-O arquivo `.yaml` é um recurso valioso para inspecionar os elementos da tela e atualizar seus localizadores de forma eficiente.
+---

data/lib/appium_failure_helper/capture.rb

@@ -39,7 +39,6 @@ module AppiumFailureHelper
       begin
         self.setup_logger unless @@logger
         
-        # Remove a pasta reports_failure ao iniciar uma nova execução
         FileUtils.rm_rf("reports_failure")
         @@logger.info("Pasta 'reports_failure' removida para uma nova execução.")
         
@@ -49,7 +48,6 @@ module AppiumFailureHelper
         FileUtils.mkdir_p(output_folder)
         @@logger.info("Pasta de saída criada: #{output_folder}")
         
-        # Captura o Base64 e salva o PNG
         screenshot_base64 = driver.screenshot_as(:base64)
         screenshot_path = "#{output_folder}/screenshot_#{timestamp}.png"
         File.open(screenshot_path, 'wb') do |f|
@@ -67,7 +65,6 @@ module AppiumFailureHelper
 
         failed_element_info = self.extract_info_from_exception(exception)
 
-        # --- Processamento de todos os elementos ---
         seen_elements = {}
         all_elements_suggestions = []
         doc.xpath('//*').each do |node|
@@ -85,7 +82,6 @@ module AppiumFailureHelper
           end
         end
 
-        # --- Geração do Relatório FOCADO (1) ---
         targeted_report = {
           failed_element: failed_element_info,
           similar_elements: [],
@@ -101,20 +97,17 @@ module AppiumFailureHelper
         end
         @@logger.info("Análise direcionada salva em #{targeted_yaml_path}")
 
-        # --- Geração do Relatório COMPLETO (2) ---
         full_dump_yaml_path = "#{output_folder}/all_elements_dump_#{timestamp}.yaml"
         File.open(full_dump_yaml_path, 'w') do |f|
           f.write(YAML.dump(all_elements_suggestions))
         end
         @@logger.info("Dump completo da página salvo em #{full_dump_yaml_path}")
 
-        # --- Geração do Relatório HTML (3) ---
         html_report_path = "#{output_folder}/report_#{timestamp}.html"
         html_content = self.generate_html_report(targeted_report, all_elements_suggestions, screenshot_base64, platform, timestamp)
         File.write(html_report_path, html_content)
         @@logger.info("Relatório HTML completo salvo em #{html_report_path}")
 
-
       rescue => e
         @@logger.error("Erro ao capturar detalhes da falha: #{e.message}\n#{e.backtrace.join("\n")}")
       end
@@ -123,148 +116,89 @@ module AppiumFailureHelper
     private
     
     def self.setup_logger
-      @@logger = Logger.new(STDOUT)
+      @@logger ||= Logger.new(STDOUT)
       @@logger.level = Logger::INFO
       @@logger.formatter = proc do |severity, datetime, progname, msg|
         "#{datetime.strftime('%Y-%m-%d %H:%M:%S')} [#{severity}] #{msg}\n"
       end
     end
+    
+  def self.extract_info_from_exception(exception)
+  message = exception.to_s
+  info = {}
+
+  # normaliza tipos capturados para nomes previsíveis
+  normalize_type = lambda do |t|
+    return 'unknown' unless t
+    t = t.to_s.downcase.strip
+    t = t.gsub(/["']/, '')
+    case t
+    when 'cssselector', 'css selector' then 'css'
+    when 'classname', 'class name' then 'class name'
+    when 'accessibilityid', 'accessibility-id', 'accessibility id' then 'accessibility-id'
+    when 'resourceid', 'resource-id', 'resource id', 'id' then 'resource-id'
+    when 'contentdesc', 'content-desc', 'content desc' then 'content-desc'
+    else
+      t.gsub(/\s+/, '_').gsub(/[^a-z0-9_\-]/, '')
+    end
+  end
 
-    # --- LÓGICA DE GERAÇÃO DE HTML ---
-    def self.generate_html_report(targeted_report, all_suggestions, screenshot_base64, platform, timestamp)
-      
-      # Helper para formatar localizadores
-      locators_html = lambda do |locators|
-        locators.map do |loc|
-          "<li class='flex justify-between items-center bg-gray-50 p-2 rounded-md mb-1 text-xs font-mono'><span class='font-bold text-indigo-600'>#{loc[:strategy].upcase.gsub('_', ' ')}:</span><span class='text-gray-700 ml-2 overflow-auto max-w-[70%]'>#{loc[:locator]}</span></li>"
-        end.join
-      end
-
-      # Helper para criar a lista de todos os elementos
-      all_elements_html = lambda do |elements|
-        elements.map do |el|
-          "<div class='border-b border-gray-200 py-3'><p class='font-semibold text-sm text-gray-800 mb-1'>#{el[:name]}</p><ul class='text-xs space-y-1'>#{locators_html.call(el[:locators])}</ul></div>"
-        end.join
-      end
-
-      # Template HTML usando um heredoc
-      <<~HTML_REPORT
-        <!DOCTYPE html>
-        <html lang="pt-BR">
-        <head>
-            <meta charset="UTF-8">
-            <meta name="viewport" content="width=device-width, initial-scale=1.0">
-            <title>Relatório de Falha Appium - #{timestamp}</title>
-            <script src="https://cdn.tailwindcss.com"></script>
-            <style>
-                body { font-family: ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, "Noto Sans", sans-serif; }
-                .tab-content { display: none; }
-                .tab-content.active { display: block; }
-                .tab-button.active { background-color: #4f46e5; color: white; }
-                .tab-button:not(.active):hover { background-color: #e0e7ff; }
-            </style>
-        </head>
-        <body class="bg-gray-50 p-8">
-            <div class="max-w-7xl mx-auto">
-                <header class="mb-8 pb-4 border-b border-gray-300">
-                    <h1 class="text-3xl font-bold text-gray-800">Diagnóstico de Falha Automatizada</h1>
-                    <p class="text-sm text-gray-500">Relatório gerado em: #{timestamp} | Plataforma: #{platform.upcase}</p>
-                </header>
-
-                <div class="grid grid-cols-1 lg:grid-cols-3 gap-8">
-                    <div class="lg:col-span-1">
-                        <div class="bg-white p-4 rounded-lg shadow-xl mb-6 border border-red-200">
-                            <h2 class="text-xl font-bold text-red-600 mb-4">Elemento com Falha</h2>
-                            <p class="text-sm text-gray-700 font-medium mb-2">Tipo de Seletor: <span class="font-mono text-xs bg-red-100 p-1 rounded">#{targeted_report[:failed_element][:selector_type] || 'Desconhecido'}</span></p>
-                            <p class="text-sm text-gray-700 font-medium">Valor Buscado: <span class="font-mono text-xs bg-red-100 p-1 rounded break-all">#{targeted_report[:failed_element][:selector_value] || 'N/A'}</span></p>
-                        </div>
+  patterns = [
+    # ChromeDriver/Selenium JSON style:
+    # no such element: Unable to locate element: {"method":"xpath","selector":"//..."}
+    /no such element: Unable to locate element:\s*\{\s*["']?method["']?\s*:\s*["']?([^"'\}]+)["']?\s*,\s*["']?selector["']?\s*:\s*["']?([^"']+)["']?\s*\}/i,
 
-                        <div class="bg-white p-4 rounded-lg shadow-xl">
-                            <h2 class="text-xl font-bold text-gray-800 mb-4">Screenshot da Falha</h2>
-                            <img src="data:image/png;base64,#{screenshot_base64}" alt="Screenshot da Falha" class="w-full rounded-md shadow-lg border border-gray-200">
-                        </div>
-                    </div>
+    # By.xpath: //..., By.id: "foo"
+    /By\.(xpath|id|css selector|cssSelector|name|class name|className):\s*['"]?(.+?)['"]?(?:\s|$)/i,
 
-                    <div class="lg:col-span-2">
-                        <div class="bg-white rounded-lg shadow-xl">
-                            <div class="flex border-b border-gray-200">
-                                <button class="tab-button active px-4 py-3 text-sm font-medium rounded-tl-lg" data-tab="similar">Sugestões de Reparo (#{targeted_report[:similar_elements].size})</button>
-                                <button class="tab-button px-4 py-3 text-sm font-medium text-gray-600" data-tab="all">Dump Completo da Página (#{all_suggestions.size} Elementos)</button>
-                            </div>
+    # Generic "using <type>=<value>" or using <type>: '<value>'
+    /using\s+([a-zA-Z0-9_\-:]+)\s*[=:]\s*['"]?(.+?)['"]?(?:\s|$)/i,
 
-                            <div class="p-6">
-                                <div id="similar" class="tab-content active">
-                                    <h3 class="text-lg font-semibold text-indigo-700 mb-4">Elementos Semelhantes (Melhores Alternativas)</h3>
-                                    #{"<p class='text-gray-500'>Nenhuma alternativa semelhante foi encontrada na página. O elemento pode ter sido removido ou o localizador está incorreto.</p>" if targeted_report[:similar_elements].empty?}
-                                    <div class="space-y-4">
-                                        #{targeted_report[:similar_elements].map { |el| "<div class='border border-indigo-100 p-3 rounded-lg bg-indigo-50'><p class='font-bold text-indigo-800 mb-2'>#{el[:name]}</p><ul>#{locators_html.call(el[:locators])}</ul></div>" }.join}
-                                    </div>
-                                </div>
+    # "An element with the selector '...' was not found"
+    /An element with (?:the )?selector ['"](.+?)['"] (?:could not be found|was not found|not found|not be located)/i,
 
-                                <div id="all" class="tab-content">
-                                    <h3 class="text-lg font-semibold text-indigo-700 mb-4">Dump Completo de Todos os Elementos da Tela</h3>
-                                    <div class="max-h-[600px] overflow-y-auto space-y-2">
-                                        #{all_elements_html.call(all_suggestions)}
-                                    </div>
-                                </div>
-                            </div>
-                        </div>
-                    </div>
-                </div>
-            </div>
+    # "with the resource-id 'xyz'" or "with the accessibility-id 'abc'"
+    /with the (resource-id|accessibility[- ]?id|content-?desc|label|name)\s*[:=]?\s*['"](.+?)['"]/i,
 
-            <script>
-                document.addEventListener('DOMContentLoaded', () => {
-                    const tabs = document.querySelectorAll('.tab-button');
-                    const contents = document.querySelectorAll('.tab-content');
+    # "Unable to find element by: id 'xyz'"
+    /Unable to find element by:\s*([a-zA-Z0-9_\- ]+)\s*[:=]?\s*['"]?(.+?)['"]?(?:\s|$)/i,
 
-                    tabs.forEach(tab => {
-                        tab.addEventListener('click', () => {
-                            const target = tab.getAttribute('data-tab');
+    # Fallback to any "selector: '...'" occurence
+    /selector['"]?\s*[:=]?\s*['"](.+?)['"]/i
+  ]
 
-                            tabs.forEach(t => t.classList.remove('active', 'text-white', 'text-gray-600', 'hover:bg-indigo-700'));
-                            contents.forEach(c => c.classList.remove('active'));
+  patterns.each do |pattern|
+      if (m = message.match(pattern))
+        caps = m.captures.compact
+        if caps.length >= 2
+          raw_type  = caps[0].to_s.strip
+          raw_value = caps[1].to_s.strip
+          info[:selector_type]  = normalize_type.call(raw_type)
+          info[:selector_value] = raw_value.gsub(/\A['"]|['"]\z/, '')
+        else
+          info[:selector_type]  = 'unknown'
+          info[:selector_value] = caps[0].to_s.strip.gsub(/\A['"]|['"]\z/, '')
+        end
+        info[:raw_message] = message[0, 1000]
+        return info
+      end
+    end
 
-                            tab.classList.add('active', 'text-white', 'bg-indigo-600');
-                            document.getElementById(target).classList.add('active');
-                        });
-                    });
-                     // Set initial active state for styling consistency
-                    const activeTab = document.querySelector('.tab-button[data-tab="similar"]');
-                    activeTab.classList.add('active', 'text-white', 'bg-indigo-600');
-                });
-            </script>
-        </body>
-        </html>
-      HTML_REPORT
+    # tentativa extra: By.<tipo>:<valor> em qualquer lugar da mensagem
+    if (m = message.match(/By\.([a-zA-Z0-9_\- ]+):\s*['"]?(.+?)['"]?/i))
+      info[:selector_type]  = normalize_type.call(m[1])
+      info[:selector_value] = m[2].to_s.strip
+      info[:raw_message] = message[0,1000]
+      return info
     end
 
-    # --- Métodos de Suporte Existentes ---
-    
-    # ... (métodos setup_logger, extract_info_from_exception, find_similar_elements, etc.)
+    # fallback final: retorna a mensagem inteira recortada (útil para debug)
+    info[:selector_type]  = 'unknown'
+    info[:selector_value] = message.strip[0, 500]
+    info[:raw_message]    = message[0,1000]
+    info
+  end
 
-    def self.extract_info_from_exception(exception)
-      message = exception.message
-      info = {}
-      
-      patterns = [
-        /(?:could not be found|cannot find element) using (.+)=['"](.+)['"]/i,
-        /no such element: Unable to locate element: {"method":"([^"]+)","selector":"([^"]+)"}/i
-      ]
-      
-      patterns.each do |pattern|
-        match = message.match(pattern)
-        if match
-          selector_type = match[1].strip
-          selector_value = match[2].strip
-          
-          info[:selector_type] = selector_type
-          info[:selector_value] = selector_value.gsub(/['"]/, '')
-          return info
-        end
-      end
-      info
-    end
 
     def self.find_similar_elements(doc, failed_info, platform)
       similar_elements = []
@@ -272,15 +206,17 @@ module AppiumFailureHelper
         next if node.name == 'hierarchy'
         attrs = node.attributes.transform_values(&:value)
         
+        selector_value = failed_info[:selector_value].to_s.downcase.strip
+        
         is_similar = case platform
         when 'android'
-          (attrs['resource-id']&.include?(failed_info[:selector_value]) ||
-           attrs['text']&.include?(failed_info[:selector_value]) ||
-           attrs['content-desc']&.include?(failed_info[:selector_value]))
+          (attrs['resource-id']&.downcase&.include?(selector_value) ||
+           attrs['text']&.downcase&.include?(selector_value) ||
+           attrs['content-desc']&.downcase&.include?(selector_value))
         when 'ios'
-          (attrs['accessibility-id']&.include?(failed_info[:selector_value]) ||
-           attrs['label']&.include?(failed_info[:selector_value]) ||
-           attrs['name']&.include?(failed_info[:selector_value]))
+          (attrs['accessibility-id']&.downcase&.include?(selector_value) ||
+           attrs['label']&.downcase&.include?(selector_value) ||
+           attrs['name']&.downcase&.include?(selector_value))
         else
           false
         end
@@ -400,13 +336,131 @@ module AppiumFailureHelper
       
       locators
     end
+    
+    def self.generate_html_report(targeted_report, all_suggestions, screenshot_base64, platform, timestamp)
+      
+      locators_html = lambda do |locators|
+        locators.map do |loc|
+          "<li class='flex justify-between items-center bg-gray-50 p-2 rounded-md mb-1 text-xs font-mono'><span class='font-bold text-indigo-600'>#{loc[:strategy].upcase.gsub('_', ' ')}:</span><span class='text-gray-700 ml-2 overflow-auto max-w-[70%]'>#{loc[:locator]}</span></li>"
+        end.join
+      end
 
-    def self.setup_logger
-      @@logger = Logger.new(STDOUT)
-      @@logger.level = Logger::INFO
-      @@logger.formatter = proc do |severity, datetime, progname, msg|
-        "#{datetime.strftime('%Y-%m-%d %H:%M:%S')} [#{severity}] #{msg}\n"
+      all_elements_html = lambda do |elements|
+        elements.map do |el|
+          "<details class='border-b border-gray-200 py-3'><summary class='font-semibold text-sm text-gray-800 cursor-pointer'>#{el[:name]}</summary><ul class='text-xs space-y-1 mt-2'>#{locators_html.call(el[:locators])}</ul></details>"
+        end.join
+      end
+
+      failed_info = targeted_report[:failed_element]
+      similar_elements = targeted_report[:similar_elements]
+      
+      similar_elements_content = similar_elements.empty? ? "<p class='text-gray-500'>Nenhuma alternativa semelhante foi encontrada. O elemento pode ter sido removido.</p>" : similar_elements.map { |el| "<div class='border border-indigo-100 p-3 rounded-lg bg-indigo-50'><p class='font-bold text-indigo-800 mb-2'>#{el[:name]}</p><ul>#{locators_html.call(el[:locators])}</ul></div>" }.join
+      
+      failed_info_content = if failed_info && failed_info[:selector_value]
+        "<p class='text-sm text-gray-700 font-medium mb-2'>Tipo de Seletor: <span class='font-mono text-xs bg-red-100 p-1 rounded'>#{failed_info[:selector_type]}</span></p><p class='text-sm text-gray-700 font-medium'>Valor Buscado: <span class='font-mono text-xs bg-red-100 p-1 rounded break-all'>#{failed_info[:selector_value]}</span></p>"
+      else
+        "<p class='text-sm text-gray-500'>O localizador exato não pôde ser extraído da mensagem de erro.</p>"
       end
+
+      # Template HTML usando um heredoc
+      <<~HTML_REPORT
+        <!DOCTYPE html>
+        <html lang="pt-BR">
+        <head>
+            <meta charset="UTF-8">
+            <meta name="viewport" content="width=device-width, initial-scale=1.0">
+            <title>Relatório de Falha Appium - #{timestamp}</title>
+            <script src="https://cdn.tailwindcss.com"></script>
+            <style>
+                body { font-family: ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, "Noto Sans", sans-serif; }
+                .tab-content { display: none; }
+                .tab-content.active { display: block; }
+                .tab-button.active { background-color: #4f46e5; color: white; }
+                .tab-button:not(.active):hover { background-color: #e0e7ff; }
+            </style>
+        </head>
+        <body class="bg-gray-50 p-8">
+            <div class="max-w-7xl mx-auto">
+                <header class="mb-8 pb-4 border-b border-gray-300">
+                    <h1 class="text-3xl font-bold text-gray-800">Diagnóstico de Falha Automatizada</h1>
+                    <p class="text-sm text-gray-500">Relatório gerado em: #{timestamp} | Plataforma: #{platform.upcase}</p>
+                </header>
+
+                <div class="grid grid-cols-1 lg:grid-cols-3 gap-8">
+                    <!-- Coluna de Screenshots e Falha -->
+                    <div class="lg:col-span-1">
+                        <div class="bg-white p-4 rounded-lg shadow-xl mb-6 border border-red-200">
+                            <h2 class="text-xl font-bold text-red-600 mb-4">Elemento com Falha</h2>
+                            #{failed_info_content}
+                        </div>
+
+                        <div class="bg-white p-4 rounded-lg shadow-xl">
+                            <h2 class="text-xl font-bold text-gray-800 mb-4">Screenshot da Falha</h2>
+                            <img src="data:image/png;base64,#{screenshot_base64}" alt="Screenshot da Falha" class="w-full rounded-md shadow-lg border border-gray-200">
+                        </div>
+                    </div>
+
+                    <!-- Coluna de Relatórios e Sugestões -->
+                    <div class="lg:col-span-2">
+                        <div class="bg-white rounded-lg shadow-xl">
+                            <!-- Abas de Navegação -->
+                            <div class="flex border-b border-gray-200">
+                                <button class="tab-button active px-4 py-3 text-sm font-medium rounded-tl-lg" data-tab="similar">Sugestões de Reparo (#{similar_elements.size})</button>
+                                <button class="tab-button px-4 py-3 text-sm font-medium text-gray-600" data-tab="all">Dump Completo da Página (#{all_suggestions.size} Elementos)</button>
+                            </div>
+
+                            <!-- Conteúdo das Abas -->
+                            <div class="p-6">
+                                <!-- Aba Sugestões de Reparo -->
+                                <div id="similar" class="tab-content active">
+                                    <h3 class="text-lg font-semibold text-indigo-700 mb-4">Elementos Semelhantes (Alternativas para o Localizador Falho)</h3>
+                                    <div class="space-y-4">
+                                        #{similar_elements_content}
+                                    </div>
+                                </div>
+
+                                <!-- Aba Dump Completo -->
+                                <div id="all" class="tab-content">
+                                    <h3 class="text-lg font-semibold text-indigo-700 mb-4">Dump Completo de Todos os Elementos da Tela</h3>
+                                    <div class="max-h-[600px] overflow-y-auto space-y-2">
+                                        #{all_elements_html.call(all_suggestions)}
+                                    </div>
+                                </div>
+                            </div>
+                        </div>
+                    </div>
+                </div>
+            </div>
+
+            <script>
+                document.addEventListener('DOMContentLoaded', () => {
+                    const tabs = document.querySelectorAll('.tab-button');
+                    const contents = document.querySelectorAll('.tab-content');
+
+                    tabs.forEach(tab => {
+                        tab.addEventListener('click', () => {
+                            const target = tab.getAttribute('data-tab');
+
+                            tabs.forEach(t => {
+                                t.classList.remove('active', 'text-white', 'bg-indigo-600');
+                                t.classList.add('text-gray-600');
+                            });
+                            contents.forEach(c => c.classList.remove('active'));
+
+                            tab.classList.add('active', 'text-white', 'bg-indigo-600');
+                            tab.classList.remove('text-gray-600');
+                            document.getElementById(target).classList.add('active');
+                        });
+                    });
+
+                    // Set initial active state for styling consistency
+                    const activeTab = document.querySelector('.tab-button[data-tab="similar"]');
+                    activeTab.classList.add('active', 'text-white', 'bg-indigo-600');
+                });
+            </script>
+        </body>
+        </html>
+      HTML_REPORT
     end
   end
 end

data/lib/appium_failure_helper/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: appium_failure_helper
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.1
 platform: ruby
 authors:
 - David Nascimento
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-09-23 00:00:00.000000000 Z
+date: 2025-09-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: nokogiri