# healenium/healenium-web architecture

> Architecture diagram of the GitHub repository healenium/healenium-web, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/healenium/healenium-web
- Repository: https://github.com/healenium/healenium-web

## Overview

##### Project Type and Purpose
- This is a Java client-side library (“healenium-web”) that wraps Selenium WebDriver to provide self-healing of locators.
- It relies on an external healenium-backend (and optional imitator) service to fetch or compute alternative locators when a standard locator fails.
- Key use-case: integrate into existing Selenium test suites to transparently recover from broken locators.

##### File-Structure Analysis
- src/main/java/com/epam/healenium
- Core entrypoint: SelfHealingDriver, SelfHealingDriverWait
- Engine: SelfHealingEngine
- Handler/proxy layer: SelfHealingHandler, proxy invocation handlers (WebElementProxyHandler, TargetLocatorProxyInvocationHandler)
- Processor chain: BaseProcessor and its concrete implementations (FindElementProcessor, HealingProcessor, SaveHealingResultsProcessor, etc.)
- Client: RestClient
- Model/DTOs: RequestDto, ResponseDto, HealingResultDto, etc.
- Mapper: HealeniumMapper and by-strategy mappers under mapper/by
- Config: ProcessorConfig
- Utilities: ProxyFactory, ResourceReader, StackUtils
- src/main/resources: default configs (application.conf, simplelogger.properties), JS helper, index.html stub
- tests: integration tests bring up an embedded Jetty server (TestServer) to simulate backend, and use TestContainers (BackendContainer) for real-backend tests.

##### README Insights
- Expects a running healenium-backend at hlm.server.url
- Initialization via SelfHealingDriver.create(delegate)
- Configurable via healenium.properties (recovery-tries, score-cap, heal-enabled, backend URLs)
- Uses standard Selenium By or @FindBy annotations and an optional @DisableHealing

a. Main Components (rectangles)
- Test Code / User’s Test Suite
- SelfHealingLibrary (client)
- WebDriver Delegate (ChromeDriver or other)
- Proxy Layer (InvocationHandlers)
- SelfHealingEngine
- Processor Chain (FindElementProcessor → HealingProcessor → SaveHealingResultsProcessor, etc.)
- RestClient (HTTP client)
- Configuration Loader
- External Services
- healenium-backend (REST API)
- healenium-imitator (optional, for imitator calls)
1. Test invokes driver.findElement(By…) on SelfHealingDriver
2. SelfHealingDriver proxies call to WebElementProxyHandler
3. Handler delegates to SelfHealingEngine
4. Engine orchestrates Processor Chain
– FindElementProcessor tries standard locator → on failure → HealingProcessor
– HealingProcessor builds RequestDto and calls RestClient
5. RestClient → HTTP POST to healenium-backend API → returns HealingResultDto
6. Engine applies healed locator, invokes delegate.findElement(healedBy), returns WebElement proxy
7. SaveHealingResultsProcessor optionally sends metrics back to backend
c. Architectural Patterns & Principles
- Proxy Pattern: to intercept WebDriver and WebElement calls
- Chain of Responsibility: processors handle find, heal, save operations in sequence
- Dependency Injection (config loaded from properties & System properties)
- Strategy Pattern: different ByMapper implementations for locator strategies
d. Key Technologies/Frameworks
- Java 8+ with Maven (pom.xml)
- Selenium WebDriver
- REST client (e.g., OkHttp or Apache HTTP Client within RestClient)
- JSON (Jackson via NodeSerializer/NodeDeserializer)
- TestContainers/JUnit for integration tests
- Typesafe Config (application.conf)

##### Essential Architectural Elements to Capture
- Interception layer (proxies) around WebDriver and WebElement
- Engine coordinating processor chain
- Processor chain stages (find, heal, save)
- REST interaction with external services
- Configuration influence (recovery-tries, score-cap, heal-enabled)
- Mapping/serialization components (mappers, converters)

## Diagram (Mermaid)

```mermaid
flowchart TD
    TestSuite["Test Suite"]:::test
    subgraph "SelfHealing Library"
        SHDriver["SelfHealingDriver"]:::lib
        SHDriverWait["SelfHealingDriverWait"]:::lib
        SHEngine["SelfHealingEngine"]:::lib
        ConfigLoader["ProcessorConfig"]:::doc
        subgraph "Proxy Layer"
            SHHandler["SelfHealingHandler"]:::lib
            WEProxy["WebElementProxyHandler"]:::lib
            TLProxy["TargetLocatorProxyInvocationHandler"]:::lib
            BaseHandler["BaseHandler"]:::lib
            ProxyInvHandler["SelfHealingProxyInvocationHandler"]:::lib
        end
        subgraph "Processor Chain"
            BaseProc["BaseProcessor"]:::lib
            FindProc["FindElementProcessor"]:::lib
            HealProc["HealingProcessor"]:::lib
            SaveProc["SaveHealingResultsProcessor"]:::lib
        end
        RestClient["RestClient"]:::lib
        subgraph "Model / Mapper / Utils"
            RequestDto["RequestDto"]:::lib
            ResponseDto["ResponseDto"]:::lib
            HealingResultDto["HealingResultDto"]:::lib
            HealeniumMapper["HealeniumMapper"]:::lib
            ByMappersDir["mapper/by (strategy mappers)"]:::lib
            ProxyFactory["ProxyFactory"]:::lib
            ResourceReader["ResourceReader"]:::lib
            StackUtils["StackUtils"]:::lib
        end
    end
    Backend((healenium-backend REST API)):::external
    Imitator((healenium-imitator REST API)):::external

    TestSuite --> SHDriver
    TestSuite --> SHDriverWait
    SHDriver --> SHHandler
    SHHandler --> SHEngine
    ConfigLoader --> SHEngine
    SHEngine --> BaseProc
    BaseProc --> FindProc
    FindProc --> HealProc
    HealProc --> RestClient
    RestClient --> Backend
    RestClient --> Imitator
    SHEngine --> SaveProc
    SaveProc -.-> Backend
    HealProc --> RequestDto
    RestClient --> ResponseDto
    RestClient --> HealingResultDto
    SHEngine --> HealeniumMapper
    SHEngine --> ByMappersDir
    SHEngine --> ProxyFactory
    SHEngine --> ResourceReader
    SHEngine --> StackUtils

    click SHDriver "https://github.com/healenium/healenium-web/blob/master/src/main/java/com/epam/healenium/SelfHealingDriver.java"
    click SHDriverWait "https://github.com/healenium/healenium-web/blob/master/src/main/java/com/epam/healenium/SelfHealingDriverWait.java"
    click SHEngine "https://github.com/healenium/healenium-web/blob/master/src/main/java/com/epam/healenium/SelfHealingEngine.java"
    click SHHandler "https://github.com/healenium/healenium-web/blob/master/src/main/java/com/epam/healenium/handlers/SelfHealingHandler.java"
    click WEProxy "https://github.com/healenium/healenium-web/blob/master/src/main/java/com/epam/healenium/handlers/proxy/WebElementProxyHandler.java"
    click TLProxy "https://github.com/healenium/healenium-web/blob/master/src/main/java/com/epam/healenium/handlers/proxy/TargetLocatorProxyInvocationHandler.java"
    click BaseHandler "https://github.com/healenium/healenium-web/blob/master/src/main/java/com/epam/healenium/handlers/proxy/BaseHandler.java"
    click ProxyInvHandler "https://github.com/healenium/healenium-web/blob/master/src/main/java/com/epam/healenium/handlers/proxy/SelfHealingProxyInvocationHandler.java"
    click BaseProc "https://github.com/healenium/healenium-web/blob/master/src/main/java/com/epam/healenium/processor/BaseProcessor.java"
    click FindProc "https://github.com/healenium/healenium-web/blob/master/src/main/java/com/epam/healenium/processor/FindElementProcessor.java"
    click HealProc "https://github.com/healenium/healenium-web/blob/master/src/main/java/com/epam/healenium/processor/HealingProcessor.java"
    click SaveProc "https://github.com/healenium/healenium-web/blob/master/src/main/java/com/epam/healenium/processor/SaveHealingResultsProcessor.java"
    click RestClient "https://github.com/healenium/healenium-web/blob/master/src/main/java/com/epam/healenium/client/RestClient.java"
    click ConfigLoader "https://github.com/healenium/healenium-web/blob/master/src/main/java/com/epam/healenium/config/ProcessorConfig.java"
    click RequestDto "https://github.com/healenium/healenium-web/blob/master/src/main/java/com/epam/healenium/model/RequestDto.java"
    click ResponseDto "https://github.com/healenium/healenium-web/blob/master/src/main/java/com/epam/healenium/model/ResponseDto.java"
    click HealingResultDto "https://github.com/healenium/healenium-web/blob/master/src/main/java/com/epam/healenium/model/HealingResultDto.java"
    click HealeniumMapper "https://github.com/healenium/healenium-web/blob/master/src/main/java/com/epam/healenium/mapper/HealeniumMapper.java"
    click ByMappersDir "https://github.com/healenium/healenium-web/tree/master/src/main/java/com/epam/healenium/mapper/by"
    click ProxyFactory "https://github.com/healenium/healenium-web/blob/master/src/main/java/com/epam/healenium/utils/ProxyFactory.java"
    click ResourceReader "https://github.com/healenium/healenium-web/blob/master/src/main/java/com/epam/healenium/utils/ResourceReader.java"
    click StackUtils "https://github.com/healenium/healenium-web/blob/master/src/main/java/com/epam/healenium/utils/StackUtils.java"

    classDef lib fill:#AED6F1,stroke:#21618C
    classDef test fill:#ABEBC6,stroke:#1D8348
    classDef external fill:#FADBD8,stroke:#C0392B
    classDef doc fill:#F9E79F,stroke:#B7950B
```
