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.
Java
Python
JavaScript
C#
String nodeURL = "http://localhost:8085";
ChromeOptions options = new ChromeOptions();
options.addArguments("--no-sandbox");
options.addArguments("--disable-dev-shm-usage");
WebDriver driver = new RemoteWebDriver(new URL(nodeURL), options);
copy
nodeURL = "http://localhost:8085"
options = webdriver.ChromeOptions()
options.add_argument('--no-sandbox')
current_webdriver = webdriver.Remote(
command_executor=nodeURL,
desired_capabilities=webdriver.DesiredCapabilities.CHROME,
options=options,
)
copy
nodeURL = "http://localhost:8085"
options = webdriver.ChromeOptions()
options.add_argument('--no-sandbox')
current_webdriver = webdriver.Remote(
command_executor=nodeURL,
desired_capabilities=webdriver.DesiredCapabilities.CHROME,
options=options,
)
const NODE_URL = "http://localhost:8085";

let args = [
  "--no-sandbox"
];

let chromeCapabilities = selenium.Capabilities.chrome()
    .set('chromeOptions', {args});

let builder = new selenium.Builder()
    .forBrowser('chrome')
    .withCapabilities(chromeCapabilities);

let driver = await builder.usingServer(NODE_URL).build();
String nodeURL = "http://localhost:8085";

ChromeOptions options = new ChromeOptions();
options.addArguments("--no-sandbox");
options.addArguments("--disable-dev-shm-usage");

WebDriver driver = new RemoteWebDriver(new URL(nodeURL), options);
String nodeURL = "http://localhost:8085";

ChromeOptions optionsChrome = new ChromeOptions();
optionsChrome.AddArguments("--no-sandbox");
    
RemoteWebDriver driverChrome = new RemoteWebDriver(new Uri(nodeURL), optionsChrome);
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.2.5</version>
</dependency>
Gradle
dependencies {
compile group: 'com.epam.healenium', name: 'healenium-web', version: '3.2.5'
}
3. Create healenium.properties file in resources folder in your project
Fill it with the following properties:

recovery-tries = 1
score-cap = 0.5
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 -o 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 -o init.sql

As a result, you'll have the same structure:
your_project
    |__db
        |__sql
            |__init.sql
    docker-compose.yaml
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
0. Recommended version: 3.2.3+
1. Start PostgeSql server.
  • Create user 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. Download jar from releases https://github.com/healenium/healenium-backend/releases or Download and build healenium-backend repository https://github.com/healenium/healenium-backend
  • Run command:
    java -jar hlm-backend.jar --SPRING_POSTGRES_DB=healenium --SPRING_POSTGRES_SCHEMA=healenium --SPRING_POSTGRES_USER=healenium_user --SPRING_POSTGRES_PASSWORD=YDk2nmNs4s9aCP6K
    Note: database, schema, user and password can be overridden. Such names have been chosen as an example.

    3. Download healenium-selector-imitator repository (https://github.com/healenium/healenium-selector-imitator)
    • Run: pip install -r requirements.txt
    • Run: python app.py
    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, .NET-based, Python-based, JavaScript-based projects
      You can try to start with Healenium-Proxy from GitHub.
      Installation for projects using Docker.
      1. Make sure you have the recent Docker version installed.
      2. Add files into your test project, for Healenium, Selenium, Selenoid.
      To work with Healenium and Selenoid plus Selenoid Ui
      To download docker-compose.yaml file into your project use this link or command:
      https://raw.githubusercontent.com/healenium/healenium/master/docker-compose.yaml
        curl https://raw.githubusercontent.com/healenium/healenium/master/docker-compose.yaml -o docker-compose.yaml
        Additionally downlod browsers.json file into you project use this link or command:
        https://raw.githubusercontent.com/healenium/healenium/master/browsers.json
          curl curl https://raw.githubusercontent.com/healenium/healenium/master/browsers.json -o browsers.json
          Manually pull docker images with specific versions from browsers.json
            docker pull selenoid/vnc:chrome_102.0

            docker pull selenoid/vnc:chrome_101.0

            docker pull selenoid/vnc:firefox_101.0

            docker pull selenoid/vnc:firefox_100.0
            To run execute command
              docker-compose up -d
              To work with Healenium and standard Selenium hub with nodes
              To download docker-compose-selenium-v3.yaml file into your project use this link or command:
              https://raw.githubusercontent.com/healenium/healenium/master/docker-compose-selenium-v3.yaml
                curl https://raw.githubusercontent.com/healenium/healenium/master/docker-compose-selenium-v3.yaml -o docker-compose-selenium-v3.yaml
                To run execute command
                  docker-compose -f docker-compose-selenium-v3.yaml up -d
                  Create /db/sql folder on the same level in your project
                  Add init.sql file into ./db/sql/init.sql folder in your project, use this link or command:
                  https://raw.githubusercontent.com/healenium/healenium/master/db/sql/init.sql
                    curl https://raw.githubusercontent.com/healenium/healenium/master/db/sql/init.sql -o init.sql
                    As a result, you'll have the same structure:
                      your-project-name
                          |__infra
                              |__db
                                  |__sql
                                      |__init.sql
                              |__browsers.json
                              |__docker-compose.yaml
                              |__docker-compose-selenium-v3.yaml
                      Create RemoteWebDriver Initialize your WebDriver as a RemoteWebDriver using port=8085, host=your_host. In example, host=localhost.

                        For Chrome:


                        var optionsChrome = new ChromeOptions();

                        optionsChrome.AddArguments("--no-sandbox");

                        _driver = new RemoteWebDriver(new Uri("http://localhost:8085"), optionsChrome);


                        For Chrome:


                        from selenium import webdriver

                        options = webdriver.ChromeOptions()

                        options.add_argument('--no-sandbox')

                        options.add_argument('--disable-dev-shm-usage')

                        browser = webdriver.Remote(

                                command_executor="http://localhost:8085",

                                desired_capabilities=webdriver.DesiredCapabilities.CHROME,

                                options=options,

                        )


                        For Chrome:


                        const {By,Key,Builder} = require("selenium-webdriver");

                        const selenium = require("selenium-webdriver");


                        const NODE_URL = "http://localhost:8085";


                        let args = [

                                "--no-sandbox"

                        ];


                        let chromeCapabilities = selenium.Capabilities.chrome()

                                .set('chromeOptions', { args });


                        let builder = new selenium.Builder()

                                .forBrowser('chrome')

                                .withCapabilities(chromeCapabilities);


                        let driver = await builder.usingServer(NODE_URL).build();

                        Monitoring results of run. You can monitor tests running. To do this go to http://localhost:8080. Here you'll see current test session and window with logs.

                          Results Report

                          As in non-proxy usage, healing results report would be generated. However, proxy doesn't require installation of any report plugins. To investigate healing results, follow the steps below:

                          1. Install Healenium-Proxy to your project
                          2. Run your tests
                          3. Check generated report
                          3.1 Find report in docker
                          In hlm-proxy container logs you can find a link for generated report. First time it's generated before tests start; second after running.
                          Healing result value also will be available in this logs.

                          3.2 Find report on logs
                          The same logs as in container are in VNC by link http://localhost:8086 at the bottom

                          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
                          1. Using IDE built-in plugin system on Windows:
                            File > Settings > Plugins > Browse repositories... > Search for "Locator Updater" > Install Plugin
                          2. Using IDE built-in plugin system on MacOs:
                            Preferences > Settings > Plugins > Browse repositories... > Search for "Locator Updater" > Install Plugin
                          3. 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.
                          1. Clone current repository for plugin
                          2. Checkout source code
                          3. Move to root project folder and open console here
                          4. 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

                          Release Notes
                          Healenium-Web

                          v.3.2.5
                          Changes:
                          • Add ability to use custom server url
                          Maven central: https://search.maven.org/artifact/com.epam.healenium/healenium-web/3.2.5/jar
                          Date: 21-June-2022

                          v.3.2.4
                          Changes:
                          • Support parent-child healing on Proxy
                          Maven central: https://search.maven.org/artifact/com.epam.healeni...
                          Date: 24-Mar-2022

                          v.3.2.3
                          Changes:
                          • Restore MobileDriver for Appium instance
                          Maven central: https://search.maven.org/artifact/com.epam.healeni...
                          Date: 09-Mar-2022

                            v.3.2.2
                            Changes:
                            • Update jackson version
                            • Add Appium support
                            • Add Healenium properties:
                            • Proxy
                            • ImitateHost
                            Maven central: https://search.maven.org/artifact/com.epam.healenium/healenium-web/3.2.2/jar
                            Date: 10-Feb-2022


                            v.3.2.1
                            Changes:
                            • Extend web to support healenium-appium
                            • Add logs
                            Maven central: https://search.maven.org/artifact/com.epam.healenium/healenium-web/3.2.1/jar
                            Date: 18-Jan-2022


                            v.3.2.0
                            Changes:
                            • Support Selenium 4
                            • Improve Healing performance
                            • Fix bugs
                            Maven central: https://search.maven.org/artifact/com.epam.healenium/healenium-web/3.2.0/jar
                            Date: 14-Jan-2022


                            v.3.1.7
                            Changes:
                            • Fix explicit wait issue
                            Maven central: https://search.maven.org/artifact/com.epam.healenium/healenium-web/3.1.7/jar
                            Date: 12-Nov-2021


                            v.3.1.6
                            Changes:
                            • Fix findElements issues
                            Maven central: https://search.maven.org/artifact/com.epam.healenium/healenium-web/3.1.6/jar
                            Date: 21-Sep-2021
                            Healenium-Backend

                            v.3.2.3

                            Changes:
                            • Fix bud/Setup hlm-backed to database connection without docker
                            • Fix bug/Report element title has incorrect name for Proxy findElements operation
                            • Fix bug/Session key is can't be found.
                            Docker Hub: docker pull healenium/hlm-backend:3.2.3
                            Date: 24-Jun-2022

                            v.3.2.2
                            Changes:
                            • Update proxy class path
                            Docker Hub: docker pull healenium/hlm-backend:3.2.2
                            Date: 20-Apr-2022

                            v.3.2.1
                            Changes:
                            • Restore MobileDriver for Appium instance
                            Docker Hub: docker pull healenium/hlm-backend:3.2.1
                            Date: 11-Mar-2022

                            v.3.2.0
                            Changes:
                            • Update tables to store appropriate URL for selector
                            • Support Selenium 4
                            Docker Hub: docker pull healenium/hlm-backend:3.2.0
                            Date: 17-Jan-2022


                            v.3.1.5
                            Changes:
                            • Use selenium session id
                            Docker Hub: docker pull healenium/hlm-backend:3.1.5
                            Date: Dec-2021


                            v.3.1.4
                            Changes:
                            • Upload metrics to S3 through AWS lambda
                            Docker Hub: docker pull healenium/hlm-backend:3.1.4
                            Date: Nov-2021


                            v.3.1.3
                            Changes:
                            • Update using session cache
                            Docker Hub: docker pull healenium/hlm-backend:3.1.3
                            Date: Oct-2021
                            Healenium-Proxy

                            v.0.2.5
                            Changes:
                            • Update
                            Docker Hub: docker pull healenium/hlm-proxy:0.2.5
                            Date: 24-Apr-2022

                            v.0.2.4
                            Changes:
                            • Support parent - child healing on proxy
                            Docker Hub: docker pull healenium/hlm-proxy:0.2.4
                            Date: 28-Mar-2022

                            v.0.2.3
                            Changes:
                            • Restore MobileDriver for Appium instance
                            Docker Hub: docker pull healenium/hlm-proxy:0.2.3
                            Date: 15-Mar-2022

                            v.0.2.1
                            Changes:
                            • Update healenium-web version to 3.2.1
                            • Available Selenium 4
                            Docker Hub: docker pull healenium/hlm-proxy:0.2.1
                            Date: 20-Jan-2022


                            v.0.2.0
                            Changes:
                            • Make container with selenium-standalone unified naming hlm-selenium-webview
                            • Update version of xppa to 1.0
                            • Update version of tiger vnc to 0.1.2
                            • Extend SelfHealingDriver methods for Appium instance
                            Docker Hub: docker pull healenium/hlm-proxy:0.2.0
                            Date: 21-Dec-2021


                            v.0.1.0
                            Changes:
                            • First version of Healenium-Proxy to make available Healenium features on different platforms
                            Docker Hub: docker pull healenium/hlm-proxy:0.1.0
                            Date: 3-Nov-2021
                            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-back 3.1.4
                            hlm-back 3.1.5
                            hlm-back 3.2.0
                            hlm-back 3.2.1
                            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
                            hlm-back 3.1.4
                            hlm-back 3.1.5
                            hlm-back 3.2.0
                            hlm-back 3.2.1
                            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.43
                            proxy 0.2.1
                            hlm-web 3.2.1
                            proxy 0.2.0
                            hlm-web 3.1.6
                            proxy 0.1.0
                            hlm-web 3.1.6
                            Get started with Healenium, it's open-sourced and free
                            Contacts
                            In case you want to learn more about Healenium,
                            our team will help you with any questions or requests.
                            curl https://raw.githubusercontent.com/healenium/healenium/master/docker-compose.yaml -o docker-compose.yaml
                            curl https://raw.githubusercontent.com/healenium/healenium/master/browsers.json -o browsers.json
                            docker pull selenoid/vnc:chrome_102.0
                            docker pull selenoid/vnc:chrome_101.0
                            docker pull selenoid/vnc:firefox_101.0
                            docker pull selenoid/vnc:chrome_100.0
                            docker-compose up -d
                            curl https://raw.githubusercontent.com/healenium/healenium/master/docker-compose-selenium-v3.yaml -o docker-compose-selenium-v3.yaml
                            curl https://raw.githubusercontent.com/healenium/healenium/master/db/sql/init.sql -o init.sql

                            5. Create RemoteWebDriver Initialize your WebDriver as a RemoteWebDriver using port=8085, host=your_host. In example, host=localhost.

                            For Chrome:

                            6. Monitoring results of run. You can monitor tests running. To do this go to http://localhost:8080. Here you'll see current test session and window with logs.

                            5. Create RemoteWebDriver Initialize your WebDriver as a RemoteWebDriver using port=8085, host=your_host. In example, host=localhost.
                            For Chrome:
                            from selenium import webdriver
                            options = webdriver.ChromeOptions()
                            options.add_argument('--no-sandbox')
                            options.add_argument('--disable-dev-shm-usage')
                            browser = webdriver.Remote(
                                command_executor="http://localhost:8085",
                                desired_capabilities=webdriver.DesiredCapabilities.CHROME,
                                options=options,
                            )
                            6. Monitoring results of run. You can monitor tests running. To do this go to http://localhost:8080. Here you'll see current test session and window with logs.
                            5. Create RemoteWebDriver Initialize your WebDriver as a RemoteWebDriver using port=8085, host=your_host. In example, host=localhost.
                            For Chrome:
                            6. Monitoring results of run. You can monitor tests running. To do this go to http://localhost:8080. Here you'll see current test session and window with logs.
                            About Healenium
                            Contacts
                            • Anna_Chernyshova@epam.com - Project Manager
                            • Dmitriy_Gumeniuk@epam.com - Project Supervisor