Introducing MaxHeal: LLM-Powered Auto-Heal for Playwright

The Fragility of Automation Testing

UI automation has a dirty secret: it is incredibly fragile. You spend hours meticulously crafting your Playwright tests, selecting the perfect CSS or XPath locators, only for a minor UI tweak—a changed button class or a restructured DOM—to break everything. It's frustrating, time-consuming, and worst of all, it erodes trust in your test suite.

Today, we're thrilled to introduce MaxHeal, a powerful new Playwright wrapper for Python designed to eliminate flaky tests through LLM-powered auto-healing.

What is MaxHeal?

MaxHeal is a drop-in wrapper around your existing Playwright page object. When a selector fails or times out, MaxHeal doesn't just crash. Instead, it pauses, captures the current DOM state, and consults an LLM (Large Language Model) to understand the failure and auto-heal the broken selector at runtime.

Key features include:

• 🔧 Auto-heal: Automatically repairs broken selectors at runtime using an LLM via OpenRouter.
• 🔁 Flaky guard: A smart retry decorator designed for unstable asynchronous tests.
• 🪶 Zero friction: No code changes required to your native Playwright assertions—just wrap the page fixture globally.
• ⚡ Selector cache: Healed selectors are cached and reused within the session, preventing duplicate LLM calls and keeping tests fast.

Zero-Setup Integration

We built MaxHeal to seamlessly integrate into your existing codebase without rewriting your tests. Install it via pip:

pip install max-heal

Then, simply configure it in your conftest.py. MaxHeal will automatically intercept all playwright.sync_api.expect and playwright.async_api.expect calls across your framework.

import pytest
from playwright.sync_api import Page
from max_heal import MaxHealConfig, create_maxheal_page

# 1. Global AI Configuration
MAXHEAL_CONFIG = MaxHealConfig(
    api_key="sk-or-your-api-key",
    model="openai/gpt-4o-mini",
    max_retries=3
)

# 2. Wrap the global Playwright page fixture natively
@pytest.fixture
def page(page: Page):
    return create_maxheal_page(page, MAXHEAL_CONFIG)

# 3. Write tests normally — NO CODE CHANGES REQUIRED!
def test_login(page: Page):
    page.goto("https://example.com/login")
    
    # If the DOM changes and "#btn-signin" breaks, MaxHeal instantly freezes,
    # queries the LLM, injects the new selector, and retries the assert!
    from playwright.sync_api import expect
    expect(page.locator("#btn-signin")).to_be_visible(timeout=5000)
    page.locator("#btn-signin").click()

Providing "Intent" for Laser Precision (V2)

While MaxHeal is brilliant at figuring out broken selectors from the DOM context, it works even better when it knows your exact intent. We've built two ways to provide this context:

1. The max_step Context Manager

Wrap logical blocks of your tests in max_step. If any selector fails inside that block, the step description is routed to the LLM to help pinpoint the correct element.

from max_heal import max_step

def test_login(page):
    with max_step("User fills out the login form with admin credentials"):
        page.fill("#user", "admin")
        page.fill("#pass", "secret")

2. Native Allure Integration

Already using allure.step? MaxHeal ships with a native Allure plugin. Just enable use_allure=True in your config, and MaxHeal will automatically parse your existing Allure steps and feed them to the LLM. No code changes needed!

Get Started Today

Stop wasting hours updating brittle selectors. Let AI maintain your tests for you.

Check out MaxHeal on PyPI or view the source on GitHub.