# Robot Framework Self-Healing Library
🤖 **Automated test maintenance for Robot Framework + Selenium**
A powerful self-healing library that automatically detects and fixes broken locators in Robot Framework tests, reducing maintenance overhead and improving test reliability.
## ✨ Features
- 🔧 **Automatic Locator Healing**: Detects failed locators and suggests fixes using AI
- 🎯 **Smart Candidate Generation**: Analyzes DOM to find alternative locators
- 🧠 **AI-Powered Solutions**: Uses OpenAI GPT-4 for intelligent locator suggestions
- 📊 **Detailed Reporting**: Comprehensive healing reports in test results
- 🔄 **Seamless Integration**: Works transparently with existing Robot Framework tests
- 📝 **Code Updates**: Automatically updates PageObject files with healed locators
## 🚀 Installation
### From PyPI (Recommended)
```bash
pip install robot-selfheal
```
### From Source
```bash
git clone https://github.com/samarthindex9/selfhealing_library.git
cd selfhealing_library
pip install -e .
```
## ⚙️ Setup
### 1. Environment Configuration
Create an `.env` file in your `Environment` directory:
```bash
# Environment/.env
OPENAI_API_KEY=your_openai_api_key_here
```
### 2. Configuration File
Create `Environment/config.json`:
```json
{
"data_path": "locator_data",
"page_objects_dir": "PageObjects",
"page_sources_dir": "locator_data/page_sources",
"results_dir": "results",
"locator_data": {
"healing_prompts": "healing_prompts.json",
"healed_locators": "healed_locators.json",
"locator_failures": "locator_failures.json"
}
}
```
## 📖 Usage
### Method 1: Import as Library (Recommended)
Add to your Robot Framework test file:
```robot
*** Settings ***
Library robot_selfheal.SelfHealListener
*** Test Cases ***
Your Test Case
[Documentation] Your test with automatic self-healing
Open Browser https://example.com chrome
Click Element ${BROKEN_LOCATOR} # Will auto-heal if it fails
Close Browser
```
### Method 2: Listener Mode
Run your tests with the listener:
```bash
robot --listener robot_selfheal.SelfHealListener your_test.robot
```
### Method 3: Command Line Integration
```bash
# Run tests with self-healing enabled
robot-selfheal --suite your_test_suite --browser chrome
```
## 🏗️ Project Structure
Your Robot Framework project should follow this structure:
```
your_project/
├── Environment/
│ ├── config.json # Configuration file
│ └── .env # OpenAI API key
├── PageObjects/ # Page object files with locators
│ ├── login_page.py
│ └── dashboard_page.py
├── TestCases/ # Your test cases
│ └── login_tests.robot
└── results/ # Test results and reports
```
## 🔧 Configuration Options
The `config.json` file supports these options:
| Option | Description | Default |
|--------|-------------|---------|
| `data_path` | Directory for healing data | `"locator_data"` |
| `page_objects_dir` | PageObjects directory | `"PageObjects"` |
| `page_sources_dir` | HTML captures directory | `"locator_data/page_sources"` |
| `results_dir` | Test results directory | `"results"` |
## 📊 How It Works
1. **Detection**: Monitors test execution for locator failures
2. **Analysis**: Captures page source and analyzes DOM structure
3. **Generation**: Creates candidate alternative locators using smart algorithms
4. **AI Enhancement**: Uses OpenAI GPT-4 to select best healing solution
5. **Application**: Updates PageObject files with healed locators
6. **Reporting**: Adds healing summary to test reports
## 🎯 Supported Locator Types
- ✅ XPath expressions (`//div[@id='example']`)
- ✅ CSS selectors (`css=.my-class`)
- ✅ ID locators (`id=my-element`)
- ✅ Name locators (`name=my-input`)
- ✅ Class locators (`class=my-class`)
- ✅ Text-based locators (`//*[contains(text(), 'Click Me')]`)
## 📈 Example Output
When a locator fails, the library generates a detailed healing report:
```
🔧 Self-Healing Summary
┌─────────────────────────────────────────────────────────┐
│ Variable: ${LOGIN_BUTTON} │
│ Source: login_page.py │
│ Original: //button[@id='old-login-btn'] │
│ Healed: //button[@data-testid='login-submit'] │
│ Solution: Updated to use more stable data-testid │
└─────────────────────────────────────────────────────────┘
```
## 🔧 Advanced Configuration
### Custom Candidate Generation
```python
from robot_selfheal import generate_enhanced_candidates
# Generate candidates with custom settings
candidates = generate_enhanced_candidates(
locator="//button[@id='broken']",
mode="lenient", # strict, balanced, lenient
threshold=60 # similarity threshold
)
```
### Programmatic Healing
```python
from robot_selfheal import SelfHealingAgent
agent = SelfHealingAgent()
healed_data = agent.heal_locator("//broken[@locator='value']")
```
## 🤝 Contributing
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 🙋♂️ Support
- 📧 **Contact**:
- Project Manager: samarth.math@indexnine.com
- Development Team: vikas.gupta@indexnine.com, onkar.pawar@indexnine.com
- 🐛 Issues: [GitHub Issues](https://github.com/samarthindex9/selfhealing_library/issues)
- 📖 Documentation: [Wiki](https://github.com/samarthindex9/selfhealing_library/blob/pypi-packaging/README.md)
## 🏆 Acknowledgments
- **Project Team**:
- **Samarth Math** - Project Manager
- **Vikas Gupta** - Developer
- **Onkar Pawar** - Developer
- Robot Framework community for the excellent testing framework
- Selenium WebDriver for web automation capabilities
- OpenAI for providing the GPT-4 API
- BeautifulSoup and lxml for HTML parsing capabilities
---
**Made with ❤️ for the Robot Framework community**
Raw data
{
"_id": null,
"home_page": "https://github.com/samarthindex9/selfhealing_library/tree/pypi-packaging",
"name": "robot-selfheal",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "Samarth Math <samarth.math@indexnine.com>, Vikas Gupta <vikas.gupta@indexnine.com>, Onkar Pawar <onkar.pawar@indexnine.com>",
"keywords": "robotframework, selenium, testing, automation, self-healing, locator, web-testing, ai, machine-learning, test-automation, quality-assurance, xpath, ui-testing",
"author": "Samarth Math, Vikas Gupta, Onkar Pawar",
"author_email": "Samarth Math <samarth.math@indexnine.com>, Vikas Gupta <vikas.gupta@indexnine.com>, Onkar Pawar <onkar.pawar@indexnine.com>",
"download_url": "https://files.pythonhosted.org/packages/c3/ed/078c6ea67e020818949fedd4dc0e7d1f75d9b8b06dd6aa18fa4d679e26f8/robot_selfheal-2.1.0.tar.gz",
"platform": null,
"description": "# Robot Framework Self-Healing Library\r\n\r\n\ud83e\udd16 **Automated test maintenance for Robot Framework + Selenium**\r\n\r\nA powerful self-healing library that automatically detects and fixes broken locators in Robot Framework tests, reducing maintenance overhead and improving test reliability.\r\n\r\n## \u2728 Features\r\n\r\n- \ud83d\udd27 **Automatic Locator Healing**: Detects failed locators and suggests fixes using AI\r\n- \ud83c\udfaf **Smart Candidate Generation**: Analyzes DOM to find alternative locators\r\n- \ud83e\udde0 **AI-Powered Solutions**: Uses OpenAI GPT-4 for intelligent locator suggestions\r\n- \ud83d\udcca **Detailed Reporting**: Comprehensive healing reports in test results\r\n- \ud83d\udd04 **Seamless Integration**: Works transparently with existing Robot Framework tests\r\n- \ud83d\udcdd **Code Updates**: Automatically updates PageObject files with healed locators\r\n\r\n## \ud83d\ude80 Installation\r\n\r\n### From PyPI (Recommended)\r\n\r\n```bash\r\npip install robot-selfheal\r\n```\r\n\r\n### From Source\r\n\r\n```bash\r\ngit clone https://github.com/samarthindex9/selfhealing_library.git\r\ncd selfhealing_library\r\npip install -e .\r\n```\r\n\r\n## \u2699\ufe0f Setup\r\n\r\n### 1. Environment Configuration\r\n\r\nCreate an `.env` file in your `Environment` directory:\r\n\r\n```bash\r\n# Environment/.env\r\nOPENAI_API_KEY=your_openai_api_key_here\r\n```\r\n\r\n### 2. Configuration File\r\n\r\nCreate `Environment/config.json`:\r\n\r\n```json\r\n{\r\n \"data_path\": \"locator_data\",\r\n \"page_objects_dir\": \"PageObjects\", \r\n \"page_sources_dir\": \"locator_data/page_sources\",\r\n \"results_dir\": \"results\",\r\n \"locator_data\": {\r\n \"healing_prompts\": \"healing_prompts.json\",\r\n \"healed_locators\": \"healed_locators.json\", \r\n \"locator_failures\": \"locator_failures.json\"\r\n }\r\n}\r\n```\r\n\r\n## \ud83d\udcd6 Usage\r\n\r\n### Method 1: Import as Library (Recommended)\r\n\r\nAdd to your Robot Framework test file:\r\n\r\n```robot\r\n*** Settings ***\r\nLibrary robot_selfheal.SelfHealListener\r\n\r\n*** Test Cases ***\r\nYour Test Case\r\n [Documentation] Your test with automatic self-healing\r\n Open Browser https://example.com chrome\r\n Click Element ${BROKEN_LOCATOR} # Will auto-heal if it fails\r\n Close Browser\r\n```\r\n\r\n### Method 2: Listener Mode\r\n\r\nRun your tests with the listener:\r\n\r\n```bash\r\nrobot --listener robot_selfheal.SelfHealListener your_test.robot\r\n```\r\n\r\n### Method 3: Command Line Integration\r\n\r\n```bash\r\n# Run tests with self-healing enabled\r\nrobot-selfheal --suite your_test_suite --browser chrome\r\n```\r\n\r\n## \ud83c\udfd7\ufe0f Project Structure\r\n\r\nYour Robot Framework project should follow this structure:\r\n\r\n```\r\nyour_project/\r\n\u251c\u2500\u2500 Environment/\r\n\u2502 \u251c\u2500\u2500 config.json # Configuration file\r\n\u2502 \u2514\u2500\u2500 .env # OpenAI API key\r\n\u251c\u2500\u2500 PageObjects/ # Page object files with locators\r\n\u2502 \u251c\u2500\u2500 login_page.py\r\n\u2502 \u2514\u2500\u2500 dashboard_page.py\r\n\u251c\u2500\u2500 TestCases/ # Your test cases\r\n\u2502 \u2514\u2500\u2500 login_tests.robot\r\n\u2514\u2500\u2500 results/ # Test results and reports\r\n```\r\n\r\n## \ud83d\udd27 Configuration Options\r\n\r\nThe `config.json` file supports these options:\r\n\r\n| Option | Description | Default |\r\n|--------|-------------|---------|\r\n| `data_path` | Directory for healing data | `\"locator_data\"` |\r\n| `page_objects_dir` | PageObjects directory | `\"PageObjects\"` |\r\n| `page_sources_dir` | HTML captures directory | `\"locator_data/page_sources\"` |\r\n| `results_dir` | Test results directory | `\"results\"` |\r\n\r\n## \ud83d\udcca How It Works\r\n\r\n1. **Detection**: Monitors test execution for locator failures\r\n2. **Analysis**: Captures page source and analyzes DOM structure\r\n3. **Generation**: Creates candidate alternative locators using smart algorithms\r\n4. **AI Enhancement**: Uses OpenAI GPT-4 to select best healing solution\r\n5. **Application**: Updates PageObject files with healed locators\r\n6. **Reporting**: Adds healing summary to test reports\r\n\r\n## \ud83c\udfaf Supported Locator Types\r\n\r\n- \u2705 XPath expressions (`//div[@id='example']`)\r\n- \u2705 CSS selectors (`css=.my-class`)\r\n- \u2705 ID locators (`id=my-element`)\r\n- \u2705 Name locators (`name=my-input`)\r\n- \u2705 Class locators (`class=my-class`)\r\n- \u2705 Text-based locators (`//*[contains(text(), 'Click Me')]`)\r\n\r\n## \ud83d\udcc8 Example Output\r\n\r\nWhen a locator fails, the library generates a detailed healing report:\r\n\r\n```\r\n\ud83d\udd27 Self-Healing Summary\r\n\u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\r\n\u2502 Variable: ${LOGIN_BUTTON} \u2502\r\n\u2502 Source: login_page.py \u2502\r\n\u2502 Original: //button[@id='old-login-btn'] \u2502\r\n\u2502 Healed: //button[@data-testid='login-submit'] \u2502\r\n\u2502 Solution: Updated to use more stable data-testid \u2502\r\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\r\n```\r\n\r\n## \ud83d\udd27 Advanced Configuration\r\n\r\n### Custom Candidate Generation\r\n\r\n```python\r\nfrom robot_selfheal import generate_enhanced_candidates\r\n\r\n# Generate candidates with custom settings\r\ncandidates = generate_enhanced_candidates(\r\n locator=\"//button[@id='broken']\",\r\n mode=\"lenient\", # strict, balanced, lenient\r\n threshold=60 # similarity threshold\r\n)\r\n```\r\n\r\n### Programmatic Healing\r\n\r\n```python\r\nfrom robot_selfheal import SelfHealingAgent\r\n\r\nagent = SelfHealingAgent()\r\nhealed_data = agent.heal_locator(\"//broken[@locator='value']\")\r\n```\r\n\r\n## \ud83e\udd1d Contributing\r\n\r\n1. Fork the repository\r\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\r\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\r\n4. Push to the branch (`git push origin feature/amazing-feature`)\r\n5. Open a Pull Request\r\n\r\n## \ud83d\udcc4 License\r\n\r\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\r\n\r\n## \ud83d\ude4b\u200d\u2642\ufe0f Support\r\n\r\n- \ud83d\udce7 **Contact**: \r\n - Project Manager: samarth.math@indexnine.com\r\n - Development Team: vikas.gupta@indexnine.com, onkar.pawar@indexnine.com\r\n- \ud83d\udc1b Issues: [GitHub Issues](https://github.com/samarthindex9/selfhealing_library/issues)\r\n- \ud83d\udcd6 Documentation: [Wiki](https://github.com/samarthindex9/selfhealing_library/blob/pypi-packaging/README.md)\r\n\r\n## \ud83c\udfc6 Acknowledgments\r\n\r\n- **Project Team**: \r\n - **Samarth Math** - Project Manager\r\n - **Vikas Gupta** - Developer \r\n - **Onkar Pawar** - Developer\r\n- Robot Framework community for the excellent testing framework\r\n- Selenium WebDriver for web automation capabilities\r\n- OpenAI for providing the GPT-4 API\r\n- BeautifulSoup and lxml for HTML parsing capabilities\r\n\r\n---\r\n\r\n**Made with \u2764\ufe0f for the Robot Framework community** \r\n",
"bugtrack_url": null,
"license": null,
"summary": "Robot Framework Self-Healing Library for automated test maintenance",
"version": "2.1.0",
"project_urls": {
"Bug Tracker": "https://github.com/samarthindex9/selfhealing_library/issues",
"Documentation": "https://github.com/samarthindex9/selfhealing_library/blob/pypi-packaging/README.md",
"Homepage": "https://github.com/samarthindex9/selfhealing_library",
"Repository": "https://github.com/samarthindex9/selfhealing_library"
},
"split_keywords": [
"robotframework",
" selenium",
" testing",
" automation",
" self-healing",
" locator",
" web-testing",
" ai",
" machine-learning",
" test-automation",
" quality-assurance",
" xpath",
" ui-testing"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "fd2aa31d748069b140b2aec7b58ee462f68cd96aecc7a73380730d36f488cdce",
"md5": "f5b91ceb66152424d38cc599e8bb37e0",
"sha256": "8d353d3a079cf96662831fa3a04f4136d43079d07424333bd234ded6679f8f27"
},
"downloads": -1,
"filename": "robot_selfheal-2.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f5b91ceb66152424d38cc599e8bb37e0",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 40723,
"upload_time": "2025-07-11T10:23:06",
"upload_time_iso_8601": "2025-07-11T10:23:06.060468Z",
"url": "https://files.pythonhosted.org/packages/fd/2a/a31d748069b140b2aec7b58ee462f68cd96aecc7a73380730d36f488cdce/robot_selfheal-2.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "c3ed078c6ea67e020818949fedd4dc0e7d1f75d9b8b06dd6aa18fa4d679e26f8",
"md5": "e1ed1494835767fcb235df11f11f0ce5",
"sha256": "95485ab40744e4ba90efe134c6992ebe523461ec0cf462f687a1056d8896dc60"
},
"downloads": -1,
"filename": "robot_selfheal-2.1.0.tar.gz",
"has_sig": false,
"md5_digest": "e1ed1494835767fcb235df11f11f0ce5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 42625,
"upload_time": "2025-07-11T10:23:07",
"upload_time_iso_8601": "2025-07-11T10:23:07.198282Z",
"url": "https://files.pythonhosted.org/packages/c3/ed/078c6ea67e020818949fedd4dc0e7d1f75d9b8b06dd6aa18fa4d679e26f8/robot_selfheal-2.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-11 10:23:07",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "samarthindex9",
"github_project": "selfhealing_library",
"github_not_found": true,
"lcname": "robot-selfheal"
}
JSON
