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

# 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

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:

{
  "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

uv run pytest

Run Ruff Code Quality Check

uv run ruff check