Metadata-Version: 2.4
Name: self-healer
Version: 1.0.1
Summary: AI-powered self-healing pytest plugin for Playwright — automatically fixes broken selectors using LLM reasoning
Project-URL: Homepage, https://github.com/your-username/self-healer
Project-URL: Issues, https://github.com/your-username/self-healer/issues
License: MIT
License-File: LICENSE
Keywords: ai,automation,langgraph,playwright,pytest,self-healing,testing
Classifier: Framework :: Pytest
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.10
Requires-Dist: beautifulsoup4>=4.12
Requires-Dist: bs4==0.0.2
Requires-Dist: build>=1.4.2
Requires-Dist: dotenv>=0.9.9
Requires-Dist: langchain-openai==1.1.11
Requires-Dist: langchain==1.2.12
Requires-Dist: langgraph==1.1.2
Requires-Dist: langsmith==0.7.20
Requires-Dist: lxml>=6.0.2
Requires-Dist: playwright==1.58.0
Requires-Dist: pytest==9.0.2
Requires-Dist: python-dotenv==1.2.2
Requires-Dist: rich>=13.0
Requires-Dist: textual==8.1.1
Provides-Extra: xpath-validation
Requires-Dist: lxml>=4.9; extra == 'xpath-validation'
Description-Content-Type: text/markdown

# 🩺 Self-Healer

**AI-powered self-healing pytest plugin for Playwright** — automatically detects broken selectors in your tests and uses LLM reasoning to suggest (and optionally apply) fixes.

[![PyPI version](https://badge.fury.io/py/self-healer.svg)](https://pypi.org/project/self-healer/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

---

## ✨ What It Does

When a Playwright test fails because a CSS selector or XPath no longer matches an element:

1. **Detects** the broken selector and extracts the relevant DOM context
2. **Reasons** about what the selector was supposed to do (using Groq/LLM)
3. **Suggests** a corrected selector with confidence score  
4. **Shows** a rich TUI panel with the suggestion
5. **Applies** the fix directly to your source code (with your approval!)

All of this happens **automatically** — just install and run your tests.

---

## 🚀 Quick Start

### Step 1: Install

```bash
pip install self-healer
```

### Step 2: Set Environment Variables

```python
# Required
API_KEY="sk_..."
LLM_MODEL="openai/gpt-4.1-mini"

# Optional (these have defaults)
BASE_URL="https://api.openai.com"
TEMPERATURE="0.4"
```

### Step 3: Add to your conftest.py

```python
# conftest.py
import pytest
from playwright.sync_api import sync_playwright

from dotenv import load_dotenv
load_dotenv()
from self_healer import enable_healing


@pytest.fixture(scope="session")
def page():
    with sync_playwright() as p:
        browser = p.chromium.launch(headless=False)
        page = browser.new_page()

        enable_healing(page)                    # ← Enable self-healing
        
        page.goto("https://www.your-app.com/")
        yield page
        browser.close()
```

### Step 4: Write Tests (normal Playwright)

```python
# tests/test_login.py
from playwright.sync_api import Page

def test_login(page: Page):
    page.fill("#user-name", "admin")
    page.fill("#password", "secret")
    page.click("#login-button")
    assert "dashboard" in page.url
```

### Step 5: Run

```bash
pytest -v
```

If `#login-button` changes to `#btn-login`, the agent will:
- Detect the failure
- Analyze the live DOM  
- Suggest `#btn-login` with high confidence
- Ask you to **Accept**, **Reject**, or **Copy** the fix

---

## ⚙️ Configuration

All configuration is via environment variables — no config files needed.

| Variable | Required | Default | Description |
|---|---|---|---|
| `API_KEY` | ✅ | — | Your API key |
| `LLM_MODEL` | ✅ | — | LLM model name |
| `BASE_URL` | ❌ | `https://api.openai.com` | API endpoint URL |
| `TEMPERATURE` | ❌ | `0.4` | LLM temperature (0.0–1.0) |

---

## 🏗️ How It Works

```
                Test Fails (broken selector)
                    │
                    ▼
            ┌─────────────────┐
            │  Detect Failure │  pytest hook intercepts the error
            └────────┬────────┘
            ┌────────┴─────────┐
            ▼                  ▼
┌─────────────────┐     ┌──────────────────┐
│  DOM Extractor  │     │   XPath Builder  │  (for dynamic sites)
└────────┬────────┘     └────────┬─────────┘
         └───────────┬───────────┘
                     ▼
            ┌──────────────────┐
            │  LLM Reasoning   │  Groq/LLaMA analyzes intent + DOM
            └────────┬─────────┘
                     ▼
            ┌──────────────────┐
            │  File Locator    │  Finds exact file:line of selector
            └────────┬─────────┘
                     ▼
            ┌──────────────────┐
            │ Human Approval   │  Rich TUI: Accept / Reject / Copy
            └────────┬─────────┘
            ┌────────┴─────────┐
           Yes                 No
            │                  │
            ▼                  ▼
    ┌────────────────┐ ┌───────────────┐
    │    Apply Fix   │ │  Reject Fix   │
    └────┬───────────┘ └───────┬───────┘
         └──────────┬──────────┘
                    ▼
                ┌─────────┐
                │   END   │
                └─────────┘
```

---

## 📦 For Package Developers

### Building from source

```bash
git clone https://github.com/ankan01-cbnits/self_healing_agent.git
cd self-healing_agent
uv sync
uv build
```

### Publishing to PyPI

```bash
# Test on TestPyPI first
pip install twine
twine upload --repository testpypi dist/*

# Then publish to real PyPI
twine upload dist/*
```

---

## 📄 License

MIT License — see [LICENSE](LICENSE) for details.