Metadata-Version: 2.5
Name: healwright
Version: 0.1.0
Summary: Autonomous self-healing Playwright test automation agent and MCP server.
Project-URL: Homepage, https://awarselabs.com
Project-URL: Documentation, https://awarselabs.com/docs/healwright
Project-URL: Repository, https://github.com/awarse-labs/healwright
Author-email: Sean Kildunne <skildunne@awarselabs.com>
License: Proprietary
Keywords: automation,mcp,playwright,qa,self-healing,testing
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.11
Requires-Dist: fastmcp>=0.1.0
Requires-Dist: playwright>=1.45.0
Requires-Dist: pydantic>=2.7.0
Requires-Dist: rich>=13.7.0
Requires-Dist: typer>=0.12.0
Description-Content-Type: text/markdown

# Healwright 🩹🎭

> **Self-Healing Playwright Selector Repair Engine and FastMCP Server**

Healwright is a Python library, Developer CLI, and FastMCP server that automatically detects broken web test locators (due to UI redesigns or DOM drift), extracts token-efficient interactive DOM snapshots, and computes similarity heuristic repairs to maintain resilient browser automation test runs.

---

## 💻 Developer CLI Usage

```bash
# Run pytest with self-healing interceptors enabled
uv run healwright test

# List pending selector patches generated during test runs
uv run healwright patch list

# Apply generated selector patches to disk (or simulate with --dry-run)
uv run healwright patch apply --dry-run
uv run healwright patch apply

# Start FastMCP server for IDE agent connections
uv run healwright serve --transport stdio
```

---

## 🏗️ Module Architecture

```
healwright/
├── .env.example
├── pyproject.toml
├── README.md
├── .github/
│   └── workflows/
│       └── ci.yml            # Autonomous CI & self-healing PR workflow
├── src/
│   └── healwright/
│       ├── __init__.py       # Package exports
│       ├── analyzer.py       # Selector repair & similarity heuristics
│       ├── cli.py            # Ergonomic Developer CLI
│       ├── interceptor.py    # ResilientPage wrapper & pytest fixture
│       ├── models.py         # Pydantic schemas (DOM snapshots, repair suggestions)
│       ├── runner.py         # Playwright session manager & live probe
│       └── server.py         # FastMCP entrypoint and tool registry
└── tests/
    ├── test_e2e_demo.py      # E2E demonstration suite
    └── test_server.py        # Pytest test suite
```

```mermaid
sequenceDiagram
    autonumber
    participant Test as Test Suite / Client
    participant Runner as PlaywrightRunner
    participant Page as Web Page (Chromium)
    participant Analyzer as SelectorAnalyzer
    participant MCP as FastMCP Server

    Test->>Runner: probe_and_repair(url, failed_selector="#submit-btn")
    Runner->>Page: execute_action("#submit-btn")
    
    alt Target Selector Fails / Times out
        Page-->>Runner: Timeout Exception
        Runner->>Page: capture_snapshot()
        Page-->>Runner: Interactive DOMSnapshot
        Runner->>Analyzer: analyze("#submit-btn", snapshot)
        Note over Analyzer: Computes ID, Class, Attribute & Text similarity scores
        Analyzer-->>Runner: RepairSuggestion("#healed-submit-action-button")
        Runner->>Page: execute_action("#healed-submit-action-button")
        Page-->>Runner: Success
        Runner-->>MCP: Log event & return HealResponse(success=True)
        MCP-->>Test: Return JSON HealResponse
    end
```

---

## ⚙️ MCP Server Configuration (`mcpServers`)

To register **Healwright** with Claude Desktop, Antigravity, or any MCP-compliant client, add the following configuration to your `mcp_config.json`:

```json
{
  "mcpServers": {
    "healwright": {
      "command": "uv",
      "args": [
        "run",
        "--project",
        "/absolute/path/to/healwright",
        "fastmcp",
        "run",
        "src/healwright/server.py"
      ]
    }
  }
}
```

---

## 🛠️ FastMCP Tools & Resources

### Tools
* `diagnose_selector_failure(context: FailedLocatorContext)`: Analyzes a failed Playwright selector error and extracts diagnostic clues.
* `propose_healed_selector(failed_selector, dom_snapshot, target_role, target_name)`: Generates resilient user-facing role locators (`page.get_by_role`) or data attribute fallbacks.
* `heal_and_verify_live(url, failed_selector, action, target_role, target_name)`: Inspects live DOM state, computes semantic alternatives, and runs a live verification trial in headless Chromium.
* `list_pending_patches()`: Returns all selectors healed during the last test execution.
* `apply_healed_patches(dry_run: bool = False)`: Applies generated selector patches to local test files.
* `heal_selector(url, failed_selector, action, value)`: Probes target page, detects locator failure, captures snapshot, repairs locator, and retries action.
* `capture_dom_snapshot(url)`: Returns structured JSON snapshot of interactive elements.
* `analyze_broken_selector(snapshot_json, failed_selector)`: Computes similarity heuristic scores against candidate elements.
* `get_healing_logs()`: Returns full history of selector repairs performed.

---

## 🚀 Development & Testing Commands

### Run Pytest Suite
```bash
uv run pytest
```

### Run Ruff Code Quality Check
```bash
uv run ruff check
```
