Documentation

Healenium Docs

EPAM Healenium is a testing framework extension that improves stability of Selenium-based test cases, handling changes of updated web elements.

Self-healing capabilities allows to replace "broken" locator with a new value and fix test in runtime.
It is open-sourced and available in GitHub.

It can be used with:

FindElement method
FindElements method; also using under parent element parent.findElements()
@FindBy and PageFactory
CssSelector
Using semantic locators like Id, Name, ClassName, LinkText, PartialLinkText, TagName
Inside conditional wait
Selenium 4

Quick start

This section describes the steps to integrate Healenium with your project. It can be integrated with different platforms. In this section there will be consider how to setup Healenium with Java, Cucumber, C#, Python and JavaScript.

Note: healing for changed locators will appear only if at least once this locator has been found on page and it was correct.

Option 1: you have Docker

Installation

You can try to start with healenium java example from GitHub.

Installation for Java-based project using Docker.

1. Make sure you have the recent Docker version installed.
2. Add Healenium dependency into project

Maven


<dependency>
<groupId>com.epam.healenium</groupId>
<artifactId>healenium-web</artifactId>
<version>3.3.1</version>
</dependency>

Gradle


dependencies {
compile group: 'com.epam.healenium', name: 'healenium-web', version: '3.3.1'
}

3. Create healenium.properties file in resources folder in your project
Fill it with the following properties:


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

4. Add Healenium-backend settings
Download Example of compose descriptor into your test project


$ curl https://raw.githubusercontent.com/healenium/healenium-client/master/example/docker-compose.yaml

Create /db/sql folder on the same level in your project. Add init.sql file into ./db/sql/init.sql folder in your project


$ curl https://raw.githubusercontent.com/healenium/healenium-client/master/example/init.sql

5. Delegate SelfHealingDriver
Change your driver delegating it to SelfHealingDriver as in example:
WebDriver delegate = new ChromeDriver(options); driver = SelfHealingDriver.create(delegate);

6. Run tests
Run your tests using JUnit, TestNG or Maven command.
Check logs after running to see which locators were changed and healed. To run tests via Maven you can use command mvn clean test

For more information, please see Setup Integration with Java video.

Results report

Report plugin for Maven project

1. Add plugin
Into your pom.xml file add healenium results plugin. It should be under <plugins> group. If you already have <pluginManagement> group add in <build> new <plugins> and insert healenium plugin into this group.


           <plugin> 
                <groupId>com.epam.healenium</groupId> 
                <artifactId>hlm-report-mvn</artifactId> 
                <version>1.1</version> 
                <executions> 
                    <execution> 
                        <id>hlmReport</id> 
                        <phase>compile</phase> 
                        <goals> 
                            <goal>initReport</goal> 
                        </goals> 
                    </execution> 
                    <execution> 
                        <id>hlmReportB</id> 
                        <phase>test</phase> 
                        <goals> 
                            <goal>buildReport</goal> 
                        </goals> 
                    </execution> 
                </executions> 
            </plugin>

2. Run tests via Maven
Run mvn clean test command to run tests and see generated report.

3. Check generated healing results report
Find report in logs
After successfully running a test with appeared healing will be generated healing results report. You can find it at the end of logs.

Notes: report will be empty if no healing has been provided.
Report will not be generated if tests fail.

4. What report contains
By going to the generated link will be provided generated report with the next items:

path to healed locator
failed locator value
healed locator value
screenshot of healed locator on page
correct or not correct healing slider

Install report plugin for Gradle project

Healenium gradle plugin to listen test actions and generate report https://plugins.gradle.org/plugin/com.epam.healenium.hlm-report


plugins { id "com.epam.healenium.hlm-report" version "1.1.2"}

InitReport task will generate sessionKey before test run. BuildReport task will generate link to the healing report after test run automatically.

Disabled healing

For some tests according to business logic it can be not necessary to use self-healing. In this case you can use @DisabledHealing annotation. Using this annotation healing for appropriate method will be turned off. However, for other methods using locators will still be available.

It can be used for separate method or for the full test method.

For more information, please see Features: report and disabled healing video.

Option 2: no Docker

Download Healenium project or clone using command:


git clone https://github.com/healenium/healenium.git

1. Start PostgeSql server.

Create user (healenium_user/YDk2nmNs4s9aCP6K)
Set attribute 'Can Login' (true) to user
Create database (healenium) and set owner healenium_user
Create schema (healenium) and set owner healenium_user

2. Go to /shell-installatio/locally and specify your db user and password data in the bash script 'start_healenium.sh'
3. Setup selenium server (selenium-grid)
4. Run bash script 'download_services.sh' to download healenium services:


./download_services.sh

5. Launch healenium components:


./start_healenium.sh

Note: database, schema, user and password can be overridden. Such names have been chosen as an example.

Proxy

Healenium-Proxy is a cross-platform framework realizing self-healing test automation. It has the same functionality as during using Maven dependency.

Note: Healenium-Proxy can be used with Java-based projects as well.

Documentation about Healenium-Proxy you can find here: Healenium-Proxy docs

Plugins

IntelliJ IDEA

Plugin ID: com.epam.healenium.hlm-idea

To perform updates in code just click with right button on failed locator and select Healing results action. After this select new locator with highest score in dropdown list.

Last version (1.0.5) released on 25.01.2021
Install it automatically from IntelliJ Idea plugin repository.
Tested and supports IntelliJ versions: 2020.1

Plugin Installation

Using IDE built-in plugin system on Windows:
File > Settings > Plugins > Browse repositories... > Search for "Locator Updater" > Install Plugin
Using IDE built-in plugin system on MacOs:
Preferences > Settings > Plugins > Browse repositories... > Search for "Locator Updater" > Install Plugin
Restart IDE.

Report Portal

Healenium plugin for ReportPortal is an easy way to sort your test results to analyze changes in design locators for a time.

Clone current repository for plugin
Checkout source code
Move to root project folder and open console here
Perform command gradlew clean build
Command should successfully build the project:

5. As a result, new healenium-plugin-reportportal-1.0.jar file appeared in build/libs/ directory
6. Upload received file to Report Portal using following instruction: https://reportportal.io/docs/Plugins
7. Also, you can find helpful instructions for uploading jar files into Report Portal here: https://github.com/reportportal/reportportal/issues/680

How to use:

Make Healenium plugin Enabled on Report Portal

Than it will be available for your project

Run your automation tests
In case when healing has been run and passed test attributes on RP will be like on picture

In case when healing has been run and failed test attributes on RP will be like on picture
In case if healing is not necessary there will be no related attributes

Version compatibility

Here you can find the latest healenium-web, healenium-back and healenium-proxy versions and their compatibility. If you are not sure with versions you should use, just use components from this table.

Healenium-Web + Healenium-Back for Java based projects

hlm-web 3.2.4

hlm-web 3.2.3

hlm-web 3.2.2

hlm-web 3.2.1

hlm-web 3.2.0

hlm-web 3.1.7

hlm-web 3.1.6

Healenium-Back + Healenium-Proxy for .NET, Python, JavaScript based projects

proxy 0.2.4
hlm-web 3.2.4
hlm appium 1.2.4

proxy 0.2.3
hlm-web 3.2.3
hlm appium 1.2.3

proxy 0.2.1
hlm-web 3.2.1