testmuai-selenium-bindings 0.1.0b1__tar.gz

testmuai_selenium_bindings-0.1.0b1/PKG-INFO

@@ -0,0 +1,59 @@
+Metadata-Version: 2.4
+Name: testmuai-selenium-bindings
+Version: 0.1.0b1
+Summary: Testmu binding for Selenium Python — thin test runtime for LambdaTest exports
+Author-email: LambdaTest <engineering@lambdatest.com>
+License-Expression: LicenseRef-Proprietary
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Framework :: Pytest
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: selenium>=4.17.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: tenacity>=8.5.0
+Requires-Dist: pyotp>=2.9.0
+Requires-Dist: requests>=2.28.0
+Requires-Dist: Pillow>=11.0.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: lambdatest-selenium-driver>=1.0.7
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-mock>=3.12; extra == "dev"
+Requires-Dist: respx>=0.20; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+
+# testmuai-selenium-bindings
+
+Python runtime bindings for Selenium-based generated tests.
+
+## Install
+
+```
+pip install testmuai-selenium-bindings
+```
+
+## Usage
+
+```python
+import testmu_selenium
+
+testmu_selenium.configure(build="my-build", name="my-test")
+
+@testmu_selenium.test
+def my_test(driver):
+    driver.get("https://example.com")
+    el = testmu_selenium.findElement(driver, [{"selector": "h1", "isXPath": False}])
+    assert el is not None
+
+if __name__ == "__main__":
+    testmu_selenium.run(my_test)
+```
+
+The PyPI distribution name is `testmuai-selenium-bindings`; the import name is `testmu_selenium`.

testmuai_selenium_bindings-0.1.0b1/README.md

@@ -0,0 +1,28 @@
+# testmuai-selenium-bindings
+
+Python runtime bindings for Selenium-based generated tests.
+
+## Install
+
+```
+pip install testmuai-selenium-bindings
+```
+
+## Usage
+
+```python
+import testmu_selenium
+
+testmu_selenium.configure(build="my-build", name="my-test")
+
+@testmu_selenium.test
+def my_test(driver):
+    driver.get("https://example.com")
+    el = testmu_selenium.findElement(driver, [{"selector": "h1", "isXPath": False}])
+    assert el is not None
+
+if __name__ == "__main__":
+    testmu_selenium.run(my_test)
+```
+
+The PyPI distribution name is `testmuai-selenium-bindings`; the import name is `testmu_selenium`.

testmuai_selenium_bindings-0.1.0b1/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "testmuai-selenium-bindings"
+version = "0.1.0b1"
+description = "Testmu binding for Selenium Python — thin test runtime for LambdaTest exports"
+requires-python = ">=3.11"
+license = "LicenseRef-Proprietary"
+authors = [{name = "LambdaTest", email = "engineering@lambdatest.com"}]
+readme = "README.md"
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Framework :: Pytest",
+    "Topic :: Software Development :: Testing",
+]
+dependencies = [
+    "selenium>=4.17.0",
+    "httpx>=0.27.0",
+    "tenacity>=8.5.0",
+    "pyotp>=2.9.0",
+    "requests>=2.28.0",
+    "Pillow>=11.0.0",
+    "python-dotenv>=1.0.0",
+    "lambdatest-selenium-driver>=1.0.7",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-mock>=3.12",
+    "respx>=0.20",
+    "build>=1.0",
+    "twine>=5.0",
+]
+
+[tool.setuptools.packages.find]
+include = ["testmu_selenium*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["."]

testmuai_selenium_bindings-0.1.0b1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

testmuai_selenium_bindings-0.1.0b1/testmu_selenium/__init__.py

@@ -0,0 +1,132 @@
+"""testmu_selenium — Selenium runtime bindings for generated tests.
+
+Public API (consumed by codegen-emitted test.py):
+    configure(**kwargs)           — set test config at module top
+    @testmu_selenium.test         — decorator for test function
+    testmu_selenium.run(fn)       — single-driver session lifecycle
+    testmu_selenium.step(...)     — step context manager
+    var(template), set_var(name, value) — variable store + template substitution
+    findElement, clickElement, input_value, executeJS, visionQuery — runtime helpers
+    _heal_cascade(...) → HealResult  — autoheal cascade dispatcher
+    Public exception classes: TestmuConfigError, AutohealExhausted, ClickAllMethodsFailed
+
+Sync API. Single driver per test. Selenium-only.
+"""
+from importlib.metadata import PackageNotFoundError, version as _pkg_version
+
+try:
+    __version__ = _pkg_version("testmuai-selenium-bindings")
+except PackageNotFoundError:
+    __version__ = "0.0.0+unknown"
+
+# Load .env BEFORE submodule imports so module-level os.getenv() in _config.py reads
+# values from a developer's local .env. On HyperExecute, env vars are platform-injected
+# and python-dotenv is absent — silent no-op.
+try:
+    from dotenv import load_dotenv as _load_dotenv
+    _load_dotenv()
+except ImportError:
+    pass
+
+from testmu_selenium._configure import configure
+from testmu_selenium._decorator import test
+from testmu_selenium._session import run
+from testmu_selenium._step import step
+from testmu_selenium._vars import var, set_var, get_variable_value, resolve_variable
+from testmu_selenium._heal_cascade import _heal_cascade, HealResult
+from testmu_selenium._route_failure import route_failure
+from testmu_selenium._test_config import load_test_config
+from testmu_selenium._errors import (
+    TestmuConfigError, AutohealExhausted, HealTierMiss, HealAuthError, ClickAllMethodsFailed,
+)
+
+# Helpers re-exported at top level (codegen emits these as bare names)
+from testmu_selenium._helpers.click import clickElement, add_clickElement_to_webelement
+from testmu_selenium._helpers.find_element import findElement
+from testmu_selenium._helpers.driver import get_driver
+from testmu_selenium._helpers.input_value import input_value
+from testmu_selenium._helpers.execute_js import executeJS
+from testmu_selenium._helpers.vision_query import visionQuery
+from testmu_selenium._helpers.textual_query import textualQuery
+from testmu_selenium._helpers.smartui import smartui_snapshot
+
+# Auto-monkey-patch WebElement on package import — generated test.py expects el.clickElement(...)
+add_clickElement_to_webelement()
+
+# Additional monkey-patches if available
+try:
+    from testmu_selenium._helpers.input_value import add_input_value_to_webelement
+    add_input_value_to_webelement()
+except ImportError:
+    pass
+
+try:
+    from testmu_selenium._helpers.clear_element import add_clear_element_to_webelement
+    add_clear_element_to_webelement()
+except ImportError:
+    pass
+
+# High-level action wrappers — single-call replacements for the codegen-emitted
+# retry+heal loops. Imported AFTER the WebElement monkey-patches so the runners
+# can rely on el.clickElement / el.input_value being present.
+from testmu_selenium._action_click import click
+from testmu_selenium._action_type import type as _type
+from testmu_selenium._action_textual_query import textual_query
+from testmu_selenium._action_search import search
+from testmu_selenium._action_hover import hover
+from testmu_selenium._action_clear import clear
+from testmu_selenium._action_set_input_files import set_input_files
+from testmu_selenium._action_scroll_into_view import scroll_into_view
+from testmu_selenium._action_scroll_until_element import scroll_until_element
+from testmu_selenium._action_drag_drop import drag_drop
+from testmu_selenium._action_element_drag import element_drag
+from testmu_selenium._helpers.drag_at_coordinate import drag_at_coordinate
+from testmu_selenium._helpers.clear_at_coordinate import clear_at_coordinate
+from testmu_selenium._helpers.navigate import navigate
+from testmu_selenium._helpers.wait import wait, wait_until, wait_for_load, check_until_condition
+
+# Codegen emits the bare camelCase name in test.py — alias matches the generated code convention.
+checkUntilCondition = check_until_condition
+from testmu_selenium._helpers.tabs import new_tab, switch_tab, close_tab
+from testmu_selenium._helpers.scroll import scroll
+from testmu_selenium._helpers.navigation import refresh, go_back, go_forward
+from testmu_selenium._helpers.dialog import handle_alert
+from testmu_selenium._helpers.url import get_url, get_title
+from testmu_selenium._helpers.math import evaluate_math
+from testmu_selenium._helpers.network import evaluate_network_assertion, network_query
+from testmu_selenium._helpers.execute_api import execute_api
+from testmu_selenium._helpers.execute_db import execute_db
+# Bind to the public name `type` at module level — note that this shadows the
+# builtin only when accessed via `from testmu_selenium import type`. Codegen
+# uses `testmu_selenium.type(...)` so no shadowing concern there.
+type = _type  # noqa: A001
+
+
+__all__ = [
+    # Lifecycle
+    "configure", "test", "run", "step",
+    # Failure routing
+    "route_failure",
+    # HyperExecute per-run test config (data-driven test_params)
+    "load_test_config",
+    # Variable store
+    "var", "set_var", "get_variable_value", "resolve_variable",
+    # Runtime helpers
+    "findElement", "get_driver", "clickElement", "input_value", "executeJS", "visionQuery", "textualQuery", "smartui_snapshot",
+    # High-level action wrappers — element-level (find + heal + act)
+    "click", "type", "search", "hover", "clear", "set_input_files", "scroll_into_view",
+    "drag_drop", "element_drag", "drag_at_coordinate", "clear_at_coordinate", "textual_query",
+    # High-level action wrappers — driver-level (no find, no heal)
+    "navigate", "wait", "wait_until", "wait_for_load", "check_until_condition", "checkUntilCondition",
+    "new_tab", "switch_tab", "close_tab",
+    "scroll", "scroll_until_element", "refresh", "go_back", "go_forward",
+    "handle_alert",
+    "get_url", "get_title",
+    # Driver-agnostic helpers
+    "evaluate_math", "evaluate_network_assertion", "network_query",
+    "execute_api", "execute_db",
+    # Heal
+    "_heal_cascade", "HealResult",
+    # Exceptions
+    "TestmuConfigError", "AutohealExhausted", "ClickAllMethodsFailed",
+]

testmuai_selenium_bindings-0.1.0b1/testmu_selenium/_action_clear.py

@@ -0,0 +1,77 @@
+"""High-level clear action — find element, clear field, heal on failure.
+
+Canvas-coordinate path.
+The selector-tier path uses element.clear() (Selenium native);
+the COORDINATE-tier fallback uses 3 sequential ActionBuilder instances:
+    1. move_to_location(x, y) + click + perform
+    2. key_down(CTRL) + send_keys('a') + key_up(CTRL) + perform
+    3. send_keys(Keys.DELETE) + perform
+"""
+from selenium.common.exceptions import InvalidElementStateException
+from selenium.webdriver.common.actions.action_builder import ActionBuilder
+from selenium.webdriver.common.keys import Keys
+
+from testmu_selenium._action_engine import _ActionSpec, _run_action
+
+
+def _clear_runner(element, ctx):
+    try:
+        element.clear()
+    except InvalidElementStateException:
+        # Native clear() enforces the W3C is-editable precondition and rejects
+        # masked/readonly inputs. Fall back to keystroke clearing (Ctrl+A +
+        # Delete) — the same select-all/delete sequence the COORDINATE tier
+        # uses, which the browser routes to the focused element without the
+        # editability gate.
+        _keystroke_clear(ctx['driver'], element)
+    return None
+
+
+def _keystroke_clear(driver, element):
+    try:
+        element.click()
+    except Exception:
+        driver.execute_script("arguments[0].focus();", element)
+
+    ab1 = ActionBuilder(driver)
+    ab1.key_action.key_down(Keys.CONTROL)
+    ab1.key_action.send_keys('a')
+    ab1.key_action.key_up(Keys.CONTROL)
+    ab1.perform()
+
+    ab2 = ActionBuilder(driver)
+    ab2.key_action.send_keys(Keys.DELETE)
+    ab2.perform()
+
+
+def _clear_coord_runner(driver, x, y, ctx):
+    ab1 = ActionBuilder(driver)
+    ab1.pointer_action.move_to_location(x, y)
+    ab1.pointer_action.click()
+    ab1.perform()
+
+    ab2 = ActionBuilder(driver)
+    ab2.key_action.key_down(Keys.CONTROL)
+    ab2.key_action.send_keys('a')
+    ab2.key_action.key_up(Keys.CONTROL)
+    ab2.perform()
+
+    ab3 = ActionBuilder(driver)
+    ab3.key_action.send_keys(Keys.DELETE)
+    ab3.perform()
+
+    return True
+
+
+_CLEAR_SPEC = _ActionSpec(runner=_clear_runner, coord_runner=_clear_coord_runner)
+
+
+def clear(driver, selector, *, description='', tiers=None, autoheal=True,
+          max_attempts=4, retry_delay=0.5, search_root=None):
+    """Find element and clear it, retrying with heal cascade on recoverable errors."""
+    return _run_action(
+        driver, _CLEAR_SPEC, selector,
+        description=description, tiers=tiers, autoheal=autoheal,
+        max_attempts=max_attempts, retry_delay=retry_delay,
+        search_root=search_root,
+    )

testmuai_selenium_bindings-0.1.0b1/testmu_selenium/_action_click.py

@@ -0,0 +1,54 @@
+"""High-level click action — find element, click with strategy, heal on failure."""
+from selenium.webdriver.common.actions.action_builder import ActionBuilder
+
+from testmu_selenium._action_engine import _ActionSpec, _run_action
+
+
+def _click_runner(element, ctx):
+    return element.clickElement(
+        ctx['driver'],
+        ctx.get('strategy', 'se_js_ac'),
+        ctx.get('modifiers'),
+    )
+
+
+# Coordinate-tier fallback. Heal cascade exhausted all selector-based tiers and
+# returned viewport pixel coords — i.e. a canvas/vision target with no DOM node
+# (a DOM target heals to a selector and never reaches here). REAL-click at those
+# coords via ActionBuilder pointer actions, NOT elementFromPoint(x,y).click():
+# a JS .click() synthesizes a MouseEvent with clientX/clientY = 0, so a canvas
+# onclick that reads e.clientX grounds to the wrong location. A real pointer
+# click carries the true coords. strategy/modifiers are not honoured on the
+# coord fallback — visual-location click only.
+def _click_coord_runner(driver, x, y, ctx):
+    _ = ctx  # strategy/modifiers ignored on coord-fallback — visual-location click only
+    ab = ActionBuilder(driver)
+    ab.pointer_action.move_to_location(x, y)
+    ab.pointer_action.click()
+    ab.perform()
+    return True
+
+
+# Recoverable set inherits the engine default — see _DEFAULT_RECOVERABLE
+# in _action_engine. Keeps click in lockstep with future additions/removals.
+_CLICK_SPEC = _ActionSpec(runner=_click_runner, coord_runner=_click_coord_runner)
+
+
+def click(driver, selector, *, strategy='se_js_ac', modifiers=None,
+          description='', tiers=None, autoheal=True,
+          max_attempts=4, retry_delay=0.5, search_root=None):
+    """Find element and click it, retrying with heal cascade on recoverable errors.
+
+    Equivalent to the codegen-emitted retry-loop pattern but encapsulated.
+
+    search_root: optional WebElement (e.g. a shadow-root child) to resolve the
+    selector against for shadow-DOM piercing. Only the element lookup uses it;
+    the click is always dispatched via driver. None = top-level document lookup.
+    """
+    return _run_action(
+        driver, _CLICK_SPEC, selector,
+        description=description, tiers=tiers, autoheal=autoheal,
+        max_attempts=max_attempts, retry_delay=retry_delay,
+        search_root=search_root,
+        strategy=strategy, modifiers=modifiers,
+    )

testmuai_selenium_bindings-0.1.0b1/testmu_selenium/_action_drag_drop.py

@@ -0,0 +1,32 @@
+"""drag_drop wrapper — element-pair drag.
+
+Wrapper takes already-resolved WebElements. Heal cascade lives upstream in
+FindElementNode's emit (findElement runtime helper). No _run_action wrap.
+
+Ported from the existing Selenium drag implementation.
+The (0.1, 0.1) move_by_offset before release is deliberate — some frameworks
+need to register an event that a draggable is hovering over the drop zone to
+activate it for the drop.
+"""
+from selenium.webdriver.common.action_chains import ActionChains
+
+# Drop-zone activation jiggle. Hardcoded.
+_DROP_ZONE_NUDGE_X = 0.1
+_DROP_ZONE_NUDGE_Y = 0.1
+
+
+def drag_drop(driver, source_element, target_element):
+    """Element-pair drag with drop-zone activation jiggle.
+
+    Args:
+        driver: Selenium WebDriver.
+        source_element: Already-resolved WebElement to drag from.
+        target_element: Already-resolved WebElement to drop onto.
+    """
+    ActionChains(driver) \
+        .move_to_element(source_element) \
+        .click_and_hold(source_element) \
+        .move_to_element(target_element) \
+        .move_by_offset(_DROP_ZONE_NUDGE_X, _DROP_ZONE_NUDGE_Y) \
+        .release() \
+        .perform()

testmuai_selenium_bindings-0.1.0b1/testmu_selenium/_action_element_drag.py

@@ -0,0 +1,59 @@
+"""element_drag wrapper — element-relative drag with integer step loop.
+
+Wrapper takes an already-resolved WebElement. Heal cascade lives upstream in
+FindElementNode's emit. No _run_action wrap.
+
+Ported from the existing Selenium drag implementation (non-canvas branch).
+The 5px step + 0.01s pause is required for sliders,
+scrubbers, and signature-pad-like UIs that fire oninput on motion samples.
+
+Selenium 4.x's PointerActions.move_by truncates both axes via int(x), int(y).
+A naive float step (dx/steps) therefore drops the fractional part on every
+iteration and the cumulative drag undershoots the target — e.g. (-352, -239)
+becomes 71 × (-4, -3) = (-284, -213), 60-70px short of the drop zone. Use
+integer ±5 step + remainder per the existing runtime.
+"""
+from selenium.webdriver.common.action_chains import ActionChains
+
+# Step granularity and inter-step pause. Hardcoded.
+_DRAG_STEP_PX = 5
+_DRAG_STEP_PAUSE = 0.01
+
+
+def element_drag(driver, element, dx, dy):
+    """Element-relative drag with integer 5px step + remainder loop.
+
+    Args:
+        driver: Selenium WebDriver.
+        element: Already-resolved source WebElement.
+        dx: X-axis delta in pixels.
+        dy: Y-axis delta in pixels.
+    """
+    dx = int(dx)
+    dy = int(dy)
+
+    actions = ActionChains(driver)
+    actions.click_and_hold(element)
+
+    remaining_x = dx
+    remaining_y = dy
+
+    while remaining_x != 0 or remaining_y != 0:
+        if abs(remaining_x) >= _DRAG_STEP_PX:
+            step_x = _DRAG_STEP_PX if remaining_x > 0 else -_DRAG_STEP_PX
+        else:
+            step_x = remaining_x
+
+        if abs(remaining_y) >= _DRAG_STEP_PX:
+            step_y = _DRAG_STEP_PX if remaining_y > 0 else -_DRAG_STEP_PX
+        else:
+            step_y = remaining_y
+
+        actions.move_by_offset(step_x, step_y)
+        actions.pause(_DRAG_STEP_PAUSE)
+
+        remaining_x -= step_x
+        remaining_y -= step_y
+
+    actions.release()
+    actions.perform()

testmuai_selenium_bindings-0.1.0b1/testmu_selenium/_action_engine.py

@@ -0,0 +1,171 @@
+"""Internal find+heal+act engine used by high-level action wrappers.
+
+Public API to the rest of the package: _ActionSpec dataclass + _run_action.
+Public API of the package: the per-verb wrappers in _action_click.py and
+_action_type.py — they're the only thing codegen and human test authors see.
+"""
+import logging
+import time
+from dataclasses import dataclass
+from typing import Any, Callable
+
+_log = logging.getLogger(__name__)
+
+from selenium.common.exceptions import (
+    NoSuchElementException, StaleElementReferenceException,
+    ElementClickInterceptedException, ElementNotInteractableException, TimeoutException,
+)
+
+from testmu_selenium._helpers.find_element import findElement
+from testmu_selenium._heal_cascade import _heal_cascade
+from testmu_selenium._helpers.smart_wait import SmartWait
+from testmu_selenium._step import _current_step
+
+
+# Relocate cascade for element actions (click/type/search/hover/...). TEXTUAL_QUERY
+# is intentionally absent: textual-query autoheal belongs only to the textual_query
+# action's _direct_textual_read (the textual_query endpoint read), not to the
+# relocate cascade — the endpoint returns a read value, not a locator.
+#
+# Tier order is COORDINATE → VISION_QUERY. Both are vision-grounded: they look at a
+# screenshot for the intent and fail honestly when the element is genuinely absent.
+# LIST_XPATHS was removed from the default cascade: as the only non-vision tier it
+# re-ranks xpaths from the DOM and returns *a* plausible match even when the real
+# target is gone, turning a real failure into a false PASS (COORDINATE + VISION_QUERY
+# both correctly missed the target element, then LIST_XPATHS relocated to an unrelated
+# banner and the step passed green). LIST_XPATHS only ever ran after both vision tiers
+# reported the element not visible — exactly when a structural xpath match is least
+# trustworthy. Dropping it matches the existing runtime's desktop-resolver policy, which fails honestly
+# with no legacy-xpath fallback. The LIST_XPATHS tier implementation still exists and
+# can be opted into via an explicit tiers= argument.
+_DEFAULT_HEAL_TIERS = ('COORDINATE', 'VISION_QUERY')
+
+# Default recoverable set — covers the common stale/intercepted/timeout cases
+# wrappers can extend or shrink this via their own _ActionSpec.
+_DEFAULT_RECOVERABLE = (
+    NoSuchElementException, StaleElementReferenceException,
+    ElementClickInterceptedException, ElementNotInteractableException,
+    TimeoutException,
+)
+
+
+@dataclass(frozen=True)
+class _ActionSpec:
+    """Describes how to run a single high-level action verb.
+
+    runner: takes (element, ctx_dict) and performs the verb. ctx_dict
+            includes 'driver' plus any wrapper-specific kwargs.
+    recoverable_exceptions: tuple of exception types that trigger a heal
+            attempt. Other exceptions propagate immediately.
+    coord_runner: optional fallback dispatched when the heal cascade
+            resolves to viewport pixel coordinates (HealResult.coordinates,
+            COORDINATE tier) rather than a real CSS/XPath. Signature:
+            coord_runner(driver, x, y, ctx) -> Any. Verbs that omit it
+            cause _run_action to raise NotImplementedError when COORDINATE
+            heal fires — preferred over silently propagating a placeholder
+            back into findElement (pre-2026-05-01 behaviour).
+    """
+    runner: Callable[[Any, dict], Any]
+    recoverable_exceptions: tuple = _DEFAULT_RECOVERABLE
+    coord_runner: Callable[[Any, int, int, dict], Any] | None = None
+    op_type: str = "click"
+
+
+def _run_action(
+    driver,
+    spec: _ActionSpec,
+    primary_selector,
+    *,
+    description: str = '',
+    tiers=None,
+    autoheal: bool = True,
+    max_attempts: int = 4,
+    retry_delay: float = 0.5,
+    search_root=None,
+    **runner_kwargs,
+):
+    """Find element → invoke spec.runner. On recoverable exception with
+    autoheal=True, run heal cascade and retry up to max_attempts.
+
+    Returns spec.runner's return value on success.
+    Raises spec's recoverable exception on final attempt failure.
+    Raises AutohealExhausted from heal_cascade if all tiers miss.
+    Non-recoverable exceptions propagate immediately.
+    """
+    if tiers is None:
+        tiers = list(_DEFAULT_HEAL_TIERS)
+    _log.info("    [AutoHeal] autoheal=%s", autoheal)
+    selector = primary_selector
+    frame_info = None
+    first_exc = None
+    SmartWait(driver).smart_wait(is_vision=False)
+    for attempt in range(max_attempts):
+        # Logged before findElement's own "Finding element..." trace.
+        _log.info("    is_retry: %s", attempt > 0)
+        try:
+            el = findElement(driver, selector, description=description, allow_autoheal=False,
+                             search_root=search_root)
+            ctx = {'driver': driver, 'frame_info': frame_info, **runner_kwargs}
+            return spec.runner(el, ctx)
+        except spec.recoverable_exceptions as exc:
+            if first_exc is None:
+                first_exc = exc
+            if not autoheal:
+                raise
+            if attempt == max_attempts - 1:
+                raise exc from first_exc
+            _log.info(
+                "    [retry] attempt %d/%d after %s: %s",
+                attempt + 1, max_attempts, type(exc).__name__, exc,
+            )
+            _active_step = _current_step.get(None)
+            if _active_step is not None:
+                _active_step.auto_heal = True
+            heal_result = _heal_cascade(
+                description=description,
+                current_selector=selector,
+                current_frame_info=frame_info,
+                tiers=tiers,
+                exception=exc,
+                driver=driver,
+                op_type=spec.op_type,
+            )
+            # COORDINATE-tier short-circuit — the cascade has no actionable
+            # selector but the vision/locate service returned viewport pixel coords. Dispatch
+            # via spec.coord_runner instead of re-entering findElement; doing
+            # otherwise crashes Chrome with InvalidSelectorException on a
+            # synthetic 'coord:x,y' placeholder.
+            if heal_result.coordinates is not None:
+                _log.info(
+                    "    [AutoHeal] relocated via %s -> coordinates %s",
+                    heal_result.tier_used, heal_result.coordinates,
+                )
+                if spec.coord_runner is None:
+                    raise NotImplementedError(
+                        f"heal cascade resolved to coordinates {heal_result.coordinates} "
+                        f"via tier {heal_result.tier_used!r}, but spec has no coord_runner. "
+                        f"Either provide one on _ActionSpec or drop COORDINATE from tiers."
+                    )
+                ctx = {'driver': driver, 'frame_info': heal_result.frame_info, **runner_kwargs}
+                x, y = heal_result.coordinates
+                return spec.coord_runner(driver, x, y, ctx)
+            # Belt+suspenders: synthetic 'coord:x,y' placeholders must never
+            # appear in HealResult.selectors. Pre-fix the COORDINATE tier
+            # produced them and Chrome rejected the next findElement with
+            # InvalidSelectorException. Surface future regressions here
+            # rather than in a cluster log.
+            for s in heal_result.selectors or []:
+                sel = s.get("selector") if isinstance(s, dict) else None
+                if isinstance(sel, str) and sel.startswith("coord:"):
+                    raise ValueError(
+                        f"HealResult.selectors contains synthetic 'coord:' placeholder: {s}. "
+                        f"COORDINATE tier must use HealResult.coordinates instead."
+                    )
+            selector = heal_result.selectors
+            frame_info = heal_result.frame_info
+            _log.info(
+                "    [AutoHeal] relocated via %s -> %s",
+                heal_result.tier_used,
+                [s.get("selector") for s in heal_result.selectors],
+            )
+            time.sleep(retry_delay)