Healenium Web: self-healing para tus localizadores

Quiero compartirles el proyecto Healenium Web Automation, un repositorio que creé para demostrar cómo mejorar la estabilidad de las pruebas automatizadas en Selenium usando auto-healing de localizadores. Si alguna vez tus tests, web scraping o automatización de tareas fallaron porque un desarrollador cambió un ID o XPath en la página, esta guía es para vos. A continuación te explicaré qué es Healenium Web Automation, los problemas comunes que resuelve, sus beneficios clave y cómo usarlo paso a paso.

¿Qué es Healenium Web Automation?

Healenium Web Automation es un proyecto de ejemplo (open source) que integra la librería Healenium en una suite de pruebas Selenium. Healenium es una extensión de Selenium que actúa como un “curador” automático de localizadores rotos​. En otras palabras, si un elemento web cambia (por ejemplo, cambió su atributo id, nombre de campo, etc.) y tu script de Selenium no lo encuentra, Healenium detectará la falla en tiempo real y buscará el elemento correcto de forma inteligente, reemplazando el localizador quebrado por uno válido sobre la marcha​. Healenium Web Automation pone en práctica esta magia usando un formulario web como caso de prueba. El proyecto está escrito en Java con Maven y emplea Selenium WebDriver junto con el patrón Page Object Model para organizar los elementos de la página. En resumen, es una demo completa de cómo añadir Healenium a tus pruebas existentes para hacerlas más robustas ante cambios inesperados en la interfaz.

Problemas comunes en la automatización que resuelve

Seguro te resultan familiares estos dolores de cabeza, localizadores frágiles: Construimos nuestros tests identificando elementos por id, xpath, css, etc. Pero cuando la aplicación cambia (nuevas versiones, rediseños, cambios de etiquetas), esos selectores dejan de funcionar y los tests fallan​.

Mantenimiento constante: Pasas horas arreglando scripts rotos debido a cambios mínimos en la UI. Un simple cambio de texto o de atributo puede inutilizar decenas de pruebas, haciéndolas inestables y costosas de mantener.
Healenium aborda directamente estos problemas. En lugar de fallar inmediatamente cuando un elemento no coincide, intenta encontrar automáticamente el nuevo elemento equivalente. Esto significa menos tests fallidos por causas no relacionadas al producto, menos falsas alarmas, y una mayor confianza en tus suites de regresión aunque la aplicación evolucione.

Beneficios clave de Healenium Web

Implementar Healenium-Web en tus pruebas (tal como muestra Healenium Web Automation) trae múltiples beneficios:
Auto-healing de localizadores: Si un elemento cambia en la página, Healenium detecta el NoSuchElementException y busca un reemplazo apropiado en tiempo de ejecución​. Tus tests se “curan” solos en lugar de fallar, reduciendo la fragilidad.
Ejemplo listo para usar: Este proyecto sirve como plantilla práctica. Incluye todo lo necesario (configuraciones Maven, Docker, TestNG, estructura de código con Page Objects, etc.) para que puedas experimentar rápidamente. En lugar de configurar desde cero, tienes un entorno funcional donde puedes ver cómo se integra Healenium con Selenium de manera correcta.
Reportes automáticos detallados: Al finalizar la ejecución de pruebas, Healenium genera un informe visual de los localizadores curados. El reporte muestra qué selector falló y con cuál valor fue reemplazado, junto a capturas de pantalla del elemento en la página y un indicador de éxito​. Esto te permite verificar si la “curación” fue correcta y dar feedback para mejorar el algoritmo.
Integración sencilla y flexible: Añadir Healenium a un framework existente es muy fácil. Básicamente se agrega la dependencia al pom.xml

<!-- https://mvnrepository.com/artifact/com.epam.healenium/healenium-web -->
    <dependency>
        <groupId>com.epam.healenium</groupId>
        <artifactId>healenium-web</artifactId>
        <version>3.5.4</version>
    </dependency>

y se envuelve el WebDriver existente en un SelfHealingDriver con una línea de código. Por ejemplo:

WebDriver delegate = new ChromeDriver();
SelfHealingDriver driver = SelfHealingDriver.create(delegate);
//crear SelfHealingDriverWait - wrapper de WebDriverWait
WebElement element = new SelfHealingDriverWait(driver, Duration.ofSeconds(10))
            .until(ExpectedConditions.visibilityOfElementLocated(By.id("wait_new_element")));

¿Cómo funciona técnicamente Healenium?

Para lograr la magia del auto-healing, Healenium sigue una arquitectura cliente-servidor: Lado cliente (en tu prueba): Healenium proporciona un wrapper de WebDriver llamado SelfHealingDriver. Esta clase implementa la interfaz de Selenium WebDriver, pero internamente intercepta las llamadas a findElement. Cuando intentas encontrar un elemento y Selenium lanza una excepción de elemento no encontrado, el SelfHealingDriver interviene. ¿Qué hace? Ejecuta un algoritmo de comparación de árboles DOM (tree comparison) para analizar la página actual en busca de un elemento que coincida con el antiguo​. Utiliza heurísticas y criterios de similitud (incluso podría considerarse un enfoque de machine learning) para identificar el nuevo selector más parecido al original. Por ejemplo, si antes buscabas un botón por el texto "Continue to checkout" y ahora el botón dice "Checkout", Healenium es capaz de encontrarlo asumiendo que la posición en el DOM o vecinos cercanos son similares, obteniendo un score de similitud. Si el algoritmo encuentra un candidato confiable (por encima de un puntaje umbral configurable), devuelve ese elemento como si nada hubiera pasado. Tu script de automatización continúa con el elemento actualizado, ¡y probablemente ni notes la diferencia! Healenium incluso puede intentar múltiples estrategias (varios recovery-tries) hasta dar con el elemento correcto. Lado servidor (backend de Healenium): Paralelamente, el cliente se comunica con un servicio backend (que corre en un contenedor Docker) para registrar y obtener información de los localizadores. Este backend utiliza una base de datos PostgreSQL para almacenar los selectores antiguos y los nuevos encontrados, junto con metadatos útiles (DOM de la página, nombre de la clase y método de test donde ocurrió, captura de pantalla del estado, etc.)​. Gracias a esto, Healenium construye un historial de cambios de elementos. Al finalizar la ejecución, el backend es quien genera el reporte de resultados de curación al que hacíamos referencia en los beneficios. Ajustes y configuraciones: Puedes controlar el comportamiento de Healenium mediante un archivo de propiedades (healenium.properties). Por ejemplo:

recovery-tries = 1
score-cap = .6
heal-enabled = true
hlm.server.url = http://localhost:7878
hlm.imitator.url = http://localhost:8000

recovery-tries indica cuántas veces intentar curar un mismo elemento (por defecto 1).
score-cap es el puntaje mínimo de coincidencia requerido (0.5 sería 50% de similitud) para aceptar un nuevo localizador.
heal-enabled permite activar/desactivar la autocuración globalmente (útil para hacer pruebas comparativas).
hlm.server.url y hlm.imitator.url apuntan al servidor de Healenium (si lo corres local, normalmente localhost:7878).
Con esta arquitectura, Healenium actúa como un “seguro” para tus scripts automatizados. Si todo está bien, usa los localizadores tal cual los escribiste. Si algo cambió, entra en acción para salvar la prueba. Ahora que entendemos la teoría, pasemos a la práctica: ¿cómo puedes probar tú mismo Healenium Web Automation?

Guía paso a paso: Probando Healenium Web Automation

A continuación te presento una guía sencilla para poner en marcha el proyecto Healenium Web Automation y comprobar sus capacidades de auto-healing. Asumo que tienes conocimientos intermedios de Java/Selenium y un ambiente preparado con Java y Maven.

1. Clona el repositorio y prepara el entorno: Empieza por clonar el repositorio desde GitHub git clone https://github.com/jmr85/healenium-web-automation.git (o descargando el ZIP). Luego, abre el proyecto en tu IDE favorito (por ejemplo, IntelliJ IDEA o tambien VSC) y asegúrate de tener Java (JDK 8+, yo tengo 21) y Maven instalados. Este proyecto incluye un conjunto de pruebas de ejemplo y la configuración necesaria de Healenium.
2. Instala los prerrequisitos (Docker): Healenium requiere ejecutar un pequeño servidor backend y una base de datos PostgreSQL. Para facilitar esto, el repo incluye un archivo Docker Compose que levanta ambos servicios fácilmente. Asegúrate de tener Docker instalado y en ejecución en tu máquina​. No necesitas configurar nada manualmente en la base de datos; el Docker Compose ya contiene un script de inicialización para crear las tablas necesarias de Healenium.

infra\db\sql\init.sql

CREATE SCHEMA healenium AUTHORIZATION healenium_user;
GRANT USAGE ON SCHEMA healenium TO healenium_user;

1. Inicia el backend de Healenium: Abre una terminal en la carpeta del proyecto (donde esté el archivo docker-compose.yml provisto en el subdirectorio infra o en la raíz del repo). Ejecuta el comando:

docker-compose up -d

Esto descargará las imágenes Docker necesarias (el servidor de Healenium y Postgres) y levantará los contenedores en segundo plano​. Una vez terminado, puedes verificar que todo esté corriendo con docker ps: deberías ver dos contenedores, uno para hlm-backend de Healenium y otro para postgres.

1. Ejecuta los tests por primera vez: Con el backend listo, es momento de correr la suite de pruebas. Puedes hacerlo desde tu IDE (ejecutando la clase de pruebas principal o usando la configuración Maven) o directamente vía terminal con Maven: mvn clean install (descarga las dependencias y ejecuta el test). En esta ejecución inicial, los tests utilizarán los localizadores tal como están definidos y, si todo está correcto, deberían pasar sin problemas. Healenium en este primer recorrido almacenará la información base de los elementos en su base de datos (pero como no hubo cambios, en realidad no tendrá que “curar” nada aún). Observa la consola al final: verás un mensaje de BUILD SUCCESS si todo salió bien, junto a la URL donde estará disponible el reporte de Healenium, algo como: Report available at http://localhost:7878/healenium/report/.

Simula un cambio en la interfaz: Para apreciar el poder de Healenium, vamos a forzar un cambio de localizadores. Supongamos que estamos probando un formulario de registro (campos de da datos de una persona firstName, lastName, email, etc.) y el desarrollador decidió renombrar algunos IDs en el HTML. En nuestro ejemplo, abre el archivo de recursos HTML src\main\resources\form-web\index.html y modifica intencionalmente algunos identificadores. Por ejemplo, donde antes el campo tenía id="firstName" cámbialo a id="firstName1", o si un botón tenía el texto "Submit", cámbialo a "Save". (Estos cambios simulan una nueva versión de la página). Guarda los cambios.

1. Ejecuta los tests nuevamente con Healenium activo: Vuelve a correr el test esta vez con mvn clean test o mvn clean test -Dtest=FormTest. Esta vez, sin Healenium nuestros tests seguramente fallarían (porque los localizadores ya no coinciden con el DOM actualizado). Pero gracias a Healenium, la ejecución debería pasar exitosamente. El SelfHealingDriver detectará cada NoSuchElementException y buscará el elemento correcto en base a la info almacenada y el DOM actual. Por ejemplo, encontrará que el nuevo ID "firstName1" coincide con el antiguo "firstName" con alta probabilidad, lo usará, y la prueba continuará como si nada. Healenium registrará cada “curación” realizada en la base de datos y marcará la prueba como exitosa. Revisa el reporte de Healenium: Al finalizar esta segunda ejecución, deberías ir a la URL del Healing Report generado http://localhost:7878/healenium/report/. Copia ese enlace y ábrelo en tu navegador web.

Este reporte web muestra el detalle de todas las curaciones realizadas durante la prueba. Verás una lista de cada elemento (Element) con su contexto (por ejemplo, la página y el nombre del método de test donde ocurrió), el valor fallido del localizador y el nuevo valor curado, el tipo de selector (By) utilizado, una captura de pantalla en miniatura y una columna de Success con un interruptor. El interruptor te permite marcar manualmente si consideras que la curación fue correcta o no, lo cual es útil para retroalimentar y mejorar el algoritmo en futuras ejecuciones. Como puedes apreciar en el reporte, Healenium Web Automation logró reemplazar correctamente los selectores cambiados por los nuevos valores, permitiendo que el flujo del test no se detuviera.

Por otro lado, podemos ver el archivo de test.log (configurado en src\test\resources\simplelogger.properties) luego de ejecutar el test.

org.slf4j.simpleLogger.log.healenium=debug

org.slf4j.simpleLogger.logFile=test.log

org.slf4j.simpleLogger.defaultLogLevel=info
org.slf4j.simpleLogger.showDateTime=true
org.slf4j.simpleLogger.dateTimeFormat=yyyy-MM-dd HH:mm:ss

test.log

2025-03-31 15:06:34 [main] INFO com.web.healing.listeners.TestListener - Test suite started: Surefire test
2025-03-31 15:06:38 [main] DEBUG healenium - [Init] sessionKey: fdb944f9380f05c03e18096a35494b79, serverUrl: http://localhost:7878/healenium, imitateUrl: http://localhost:8000/imitate
2025-03-31 15:06:38 [main] DEBUG healenium - [Get Elements] Request: (GET) /elements
2025-03-31 15:06:38 [main] DEBUG healenium - [Init Report] Request: (POST) /report/init/fdb944f9380f05c03e18096a35494b79
2025-03-31 15:06:38 [main] INFO com.web.healing.listeners.TestListener - Test started: testFormWithAllFields
2025-03-31 15:06:38 [main] WARN healenium - Failed to find an element using locator By.id: firstName
2025-03-31 15:06:38 [main] WARN healenium - Reason: no such element: Unable to locate element: {"method":"css selector","selector":"#firstName"}
  (Session info: chrome=134.0.6998.178)
For documentation on this error, please visit: https://www.selenium.dev/documentation/webdriver/troubleshooting/errors#no-such-element-exception
Build info: version: '4.25.0', revision: '8a8aea2337'
System info: os.name: 'Windows 11', os.arch: 'amd64', os.version: '10.0', java.version: '21.0.6'
Driver info: org.openqa.selenium.chrome.ChromeDriver
Command: [fdb944f9380f05c03e18096a35494b79, findElement {value=firstName, using=id}]
Capabilities {acceptInsecureCerts: false, browserName: chrome, browserVersion: 134.0.6998.178, chrome: {chromedriverVersion: 134.0.6998.165 (fd886e2cb29..., userDataDir: C:\Users\juani\AppData\Loca...}, fedcm:accounts: true, goog:chromeOptions: {debuggerAddress: localhost:61872}, networkConnectionEnabled: false, pageLoadStrategy: normal, platformName: windows, proxy: Proxy(), se:cdp: ws://localhost:61872/devtoo..., se:cdpVersion: 134.0.6998.178, setWindowRect: true, strictFileInteractability: false, timeouts: {implicit: 0, pageLoad: 300000, script: 30000}, unhandledPromptBehavior: dismiss and notify, webauthn:extension:credBlob: true, webauthn:extension:largeBlob: true, webauthn:extension:minPinLength: true, webauthn:extension:prf: true, webauthn:virtualAuthenticators: true}
Session ID: fdb944f9380f05c03e18096a35494b79
2025-03-31 15:06:38 [main] DEBUG healenium - [Get Reference Elements] Request. Locator: firstName, Command: findElement, Url: file:///C:/Dev/Java/Healenium/healenium-web-automation/target/classes/form-web/index.html
2025-03-31 15:06:39 [main] WARN healenium - Trying to heal...
2025-03-31 15:06:39 [main] WARN healenium - Using healed locator: Scored(score=0.9857142857142858, value=By.cssSelector: input#firstName1)
2025-03-31 15:06:39 [main] DEBUG healenium - [Save Healed Elements] Locator(value=input#firstName1, type=By.cssSelector)
2025-03-31 15:06:41 [main] DEBUG healenium - [Save Elements] By: By.id, Locator: lastName, Command: findElement, URL: file:///C:/Dev/Java/Healenium/healenium-web-automation/target/classes/form-web/index.html
2025-03-31 15:06:41 [main] DEBUG healenium - [Save Elements] By: By.id, Locator: email, Command: findElement, URL: file:///C:/Dev/Java/Healenium/healenium-web-automation/target/classes/form-web/index.html
2025-03-31 15:06:41 [main] DEBUG healenium - [Save Elements] By: By.id, Locator: male, Command: findElement, URL: file:///C:/Dev/Java/Healenium/healenium-web-automation/target/classes/form-web/index.html
2025-03-31 15:06:41 [main] DEBUG healenium - [Save Elements] By: By.id, Locator: mobile, Command: findElement, URL: file:///C:/Dev/Java/Healenium/healenium-web-automation/target/classes/form-web/index.html
2025-03-31 15:06:41 [main] DEBUG healenium - [Save Elements] By: By.id, Locator: dateOfBirth, Command: findElement, URL: file:///C:/Dev/Java/Healenium/healenium-web-automation/target/classes/form-web/index.html
2025-03-31 15:06:41 [main] DEBUG healenium - [Save Elements] By: By.id, Locator: subjects, Command: findElement, URL: file:///C:/Dev/Java/Healenium/healenium-web-automation/target/classes/form-web/index.html
2025-03-31 15:06:41 [main] DEBUG healenium - [Save Elements] By: By.id, Locator: currentAddress, Command: findElement, URL: file:///C:/Dev/Java/Healenium/healenium-web-automation/target/classes/form-web/index.html
2025-03-31 15:06:42 [main] DEBUG healenium - [Save Elements] By: By.id, Locator: country, Command: findElement, URL: file:///C:/Dev/Java/Healenium/healenium-web-automation/target/classes/form-web/index.html
2025-03-31 15:06:42 [main] DEBUG healenium - [Save Elements] By: [By.xpath, Locator: .//option[normalize-space(.) = "Argentina"]] on page null, Command: findElements, URL: file:///C:/Dev/Java/Healenium/healenium-web-automation/target/classes/form-web/index.html
2025-03-31 15:06:42 [main] DEBUG healenium - [Save Elements] By: By.xpath, Locator: //button[text()='Submit'], Command: findElement, URL: file:///C:/Dev/Java/Healenium/healenium-web-automation/target/classes/form-web/index.html
2025-03-31 15:06:42 [main] INFO com.web.healing.listeners.TestListener - Test passed: testFormWithAllFields
2025-03-31 15:06:42 [main] INFO com.web.healing.listeners.TestListener - Test suite finished: Surefire test

Explora el reporte Allure (adicional): Además del reporte de curación propio de Healenium, el proyecto incluye integración con Allure para reportar la ejecución general de las pruebas. Puedes generar el reporte con el historial de pasos de test, screenshots, etc. Ejecuta el comando allure serve target/allure-results una vez finalizados los tests. Se abrirá un informe interactivo donde podrás ver cada caso de prueba, incluyendo las acciones realizadas y evidencias. Es otra forma de inspeccionar que las pruebas corrieron correctamente. Ten en cuenta que Allure mostrará los pasos tal cual están en el código; la “curación” sucede tras bambalinas, pero podrás ver que no hubo errores en los pasos gracias a Healenium​.

Personalmente, desarrollar Healenium Web Automation ha sido una experiencia muy gratificante. Me permitió comprobar de primera mano cómo una herramienta de auto-healing puede reducir drásticamente la fragilidad de nuestras pruebas Selenium. Ya no tengo que temer que un simple cambio de ID derrumbe mi suite de regresión: Healenium actúa como un escudero fiel, adaptándose a los cambios de la UI en tiempo real y manteniendo mis tests en verde. Te animo a que pruebes este proyecto y, más importante, que consideres integrar Healenium (o una solución similar) en tus propios frameworks de automatización. El repositorio está disponible en GitHub para que curiosees el código y lo adaptes a tus necesidades: https://github.com/jmr85/healenium-web-automation

Si integras Healenium, recuerda igualmente mantener buenas prácticas en tus localizadores (usar atributos estables cuando sea posible, evitar selectores extremadamente frágiles, etc.). Healenium es una red de seguridad, pero un código bien diseñado siempre es la primera línea de defensa. También puedes aprovechar el plugin de Healenium para IntelliJ: este te permite actualizar automáticamente tus selectores en el código con solo un click, tomando los valores curados desde el reporte (muy útil para refactorizar rápidamente). Espero que esta guía te haya resultado útil. Healenium Web es tan solo un paso hacia pruebas más resilientes. Con herramientas así, podemos dedicar más tiempo a crear nuevos tests (o scripts de automatización) y menos a reparar los existentes.