selenium-python-ai-agent 0.2.0__py3-none-any.whl

selenium_agent/selenium/error_map.py

@@ -0,0 +1,235 @@
+"""
+SELENIUM ERROR MAP
+==================
+Maps known Selenium exceptions to root causes and exact fixes.
+
+The Healer Agent uses this to:
+- Identify error type from pytest output
+- Apply targeted fix before asking the LLM
+- Reduce LLM calls for common/known errors
+
+This is what makes the Healer truly Selenium-specific,
+not just a generic "ask LLM to fix" agent.
+"""
+
+from __future__ import annotations
+from dataclasses import dataclass
+
+
+@dataclass
+class ErrorFix:
+    """A known Selenium error with its cause and fix."""
+    exception: str          # Exception class name
+    pattern: str            # String to search for in error output
+    cause: str              # What causes this error
+    fix: str                # How to fix it in code
+    code_before: str        # Example of broken code
+    code_after: str         # Example of fixed code
+    severity: str           # low | medium | high
+
+
+class SeleniumErrorMap:
+    """
+    Lookup table of known Selenium errors → targeted fixes.
+
+    Used by the Healer Agent to apply precise fixes
+    before falling back to LLM healing.
+    """
+
+    KNOWN_ERRORS: list[ErrorFix] = [
+
+        ErrorFix(
+            exception="NoSuchElementException",
+            pattern="no such element",
+            cause="Element not found in DOM — wrong locator or page not loaded",
+            fix="Add WebDriverWait for element presence, or fix the locator",
+            code_before='driver.find_element(By.ID, "username")',
+            code_after='WebDriverWait(driver, 10).until(EC.presence_of_element_located((By.ID, "username")))',
+            severity="high",
+        ),
+
+        ErrorFix(
+            exception="TimeoutException (wait_for_url)",
+            pattern="wait_for_url",
+            cause="The URL never changed after the action — many SPAs show the result "
+                  "on the SAME page (status badge, toast, message) without navigating",
+            fix="Do NOT increase the timeout. Remove wait_for_url and instead assert an "
+                "in-page success indicator from the DOM scan (a status element whose text "
+                "changes, a success message, etc.)",
+            code_before="page.click(page.LOGIN_BUTTON)\npage.wait_for_url('dashboard')",
+            code_after="page.click(page.LOGIN_BUTTON)\n"
+                       "# SPA: success shows on the same page — assert the status element\n"
+                       "page.wait_for_text(page.LOGIN_STATUS, 'AUTHENTICATED')\n"
+                       "assert 'AUTHENTICATED' in page.get_text(page.LOGIN_STATUS)",
+            severity="high",
+        ),
+
+        ErrorFix(
+            exception="TimeoutException",
+            pattern="timeout",
+            cause="Element did not appear within the wait timeout",
+            fix="Increase timeout, verify locator is correct, or check if page loaded",
+            code_before='WebDriverWait(driver, 5).until(EC.visibility_of_element_located((By.ID, "result")))',
+            code_after='WebDriverWait(driver, 15).until(EC.visibility_of_element_located((By.ID, "result")))',
+            severity="medium",
+        ),
+
+        ErrorFix(
+            exception="StaleElementReferenceException",
+            pattern="stale element reference",
+            cause="Element was found, then DOM was refreshed/updated — reference is now stale",
+            fix="Re-fetch the element inside the action, or use a retry wrapper",
+            code_before="""element = driver.find_element(By.ID, "btn")
+page.load_more()
+element.click()  # stale!""",
+            code_after="""page.load_more()
+# Re-fetch after DOM change
+WebDriverWait(driver, 10).until(EC.element_to_be_clickable((By.ID, "btn"))).click()""",
+            severity="high",
+        ),
+
+        ErrorFix(
+            exception="ElementNotInteractableException",
+            pattern="element not interactable",
+            cause="Element exists but is hidden, disabled, or off-screen",
+            fix="Scroll element into view, wait for it to be visible, or use JS click",
+            code_before='driver.find_element(By.ID, "submit").click()',
+            code_after="""element = WebDriverWait(driver, 10).until(
+    EC.element_to_be_clickable((By.ID, "submit"))
+)
+driver.execute_script("arguments[0].scrollIntoView(true);", element)
+element.click()""",
+            severity="medium",
+        ),
+
+        ErrorFix(
+            exception="ElementClickInterceptedException",
+            pattern="element click intercepted",
+            cause="Another element (overlay, modal, cookie banner) is blocking the click",
+            fix="Dismiss the overlay first, or use JS click as fallback",
+            code_before='driver.find_element(By.ID, "checkout").click()',
+            code_after="""# Option 1: Dismiss overlay if present
+try:
+    WebDriverWait(driver, 3).until(
+        EC.element_to_be_clickable((By.CSS_SELECTOR, ".cookie-accept"))
+    ).click()
+except TimeoutException:
+    pass
+
+# Option 2: JS click fallback
+element = WebDriverWait(driver, 10).until(
+    EC.presence_of_element_located((By.ID, "checkout"))
+)
+driver.execute_script("arguments[0].click();", element)""",
+            severity="medium",
+        ),
+
+        ErrorFix(
+            exception="MoveTargetOutOfBoundsException",
+            pattern="move target out of bounds",
+            cause="Element is outside the current viewport",
+            fix="Scroll element into view before hover/click",
+            code_before='ActionChains(driver).move_to_element(element).perform()',
+            code_after="""driver.execute_script("arguments[0].scrollIntoView({block: 'center'});", element)
+ActionChains(driver).move_to_element(element).perform()""",
+            severity="low",
+        ),
+
+        ErrorFix(
+            exception="WebDriverException (session)",
+            pattern="invalid session id",
+            cause="WebDriver session was closed or crashed",
+            fix="Ensure driver.quit() is in teardown, add session check in fixture",
+            code_before="""# Missing teardown
+def test_login(driver):
+    driver.get("https://example.com")""",
+            code_after="""@pytest.fixture
+def driver():
+    d = DriverFactory.create(browser="chrome", headless=True)
+    yield d
+    d.quit()  # Always called, even on failure""",
+            severity="high",
+        ),
+
+        ErrorFix(
+            exception="ImplicitWaitConflict",
+            pattern="implicit wait",
+            cause="Mixing implicit and explicit waits causes unpredictable timeouts",
+            fix="Remove implicit waits — use only WebDriverWait (explicit) everywhere",
+            code_before='driver.implicitly_wait(10)  # conflicts with WebDriverWait',
+            code_after="""# Remove implicit wait
+# Use explicit wait everywhere:
+WebDriverWait(driver, 10).until(EC.visibility_of_element_located(locator))""",
+            severity="medium",
+        ),
+
+        ErrorFix(
+            exception="NoAlertPresentException",
+            pattern="no alert",
+            cause="Trying to switch to alert before it appears",
+            fix="Wait for alert to be present using EC.alert_is_present()",
+            code_before='alert = driver.switch_to.alert',
+            code_after="""WebDriverWait(driver, 5).until(EC.alert_is_present())
+alert = driver.switch_to.alert""",
+            severity="low",
+        ),
+
+        ErrorFix(
+            exception="UnexpectedAlertPresentException",
+            pattern="unexpected alert",
+            cause="An unexpected JS alert appeared and blocked the driver",
+            fix="Handle alert in teardown or dismiss it before continuing",
+            code_before="# No alert handling",
+            code_after="""try:
+    WebDriverWait(driver, 2).until(EC.alert_is_present())
+    driver.switch_to.alert.dismiss()
+except TimeoutException:
+    pass""",
+            severity="medium",
+        ),
+    ]
+
+    @classmethod
+    def find_fix(cls, error_output: str) -> ErrorFix | None:
+        """
+        Search error output for known patterns and return fix.
+
+        Args:
+            error_output: Full pytest error/traceback string
+
+        Returns:
+            ErrorFix if a known error is found, None otherwise
+        """
+        lower_output = error_output.lower()
+        for error in cls.KNOWN_ERRORS:
+            if error.pattern.lower() in lower_output:
+                return error
+        return None
+
+    @classmethod
+    def find_all_fixes(cls, error_output: str) -> list[ErrorFix]:
+        """Find ALL matching errors in the output."""
+        lower_output = error_output.lower()
+        return [e for e in cls.KNOWN_ERRORS if e.pattern.lower() in lower_output]
+
+    @classmethod
+    def get_fix_summary(cls, error_output: str) -> str:
+        """Return a human-readable fix summary for the Healer Agent prompt."""
+        fixes = cls.find_all_fixes(error_output)
+        if not fixes:
+            return "No known Selenium error pattern matched. LLM analysis required."
+
+        lines = ["KNOWN SELENIUM ERRORS DETECTED:\n"]
+        for fix in fixes:
+            lines.append(f"❌ {fix.exception}")
+            lines.append(f"   Cause: {fix.cause}")
+            lines.append(f"   Fix:   {fix.fix}")
+            lines.append(f"   Before:\n{fix.code_before}")
+            lines.append(f"   After:\n{fix.code_after}\n")
+
+        return "\n".join(lines)
+
+    @classmethod
+    def list_all(cls) -> list[str]:
+        """Return list of all known exception names."""
+        return [e.exception for e in cls.KNOWN_ERRORS]

selenium_agent/selenium/locator_advisor.py

@@ -0,0 +1,247 @@
+"""
+LOCATOR ADVISOR
+===============
+Selenium-specific intelligence for choosing the best locator strategy.
+
+The Planner and Coder agents use this to:
+- Rank locator strategies by reliability
+- Detect anti-patterns in XPath/CSS
+- Suggest better alternatives
+- Embed locator guidance in generated code
+
+Locator Priority (most → least reliable):
+  1. By.ID           — unique, fast, stable
+  2. By.NAME         — good for form fields
+  3. By.CSS_SELECTOR — flexible, fast, readable
+  4. By.XPATH        — powerful but fragile if absolute
+  5. By.LINK_TEXT    — brittle, language-dependent
+  6. By.CLASS_NAME   — often not unique
+  7. By.TAG_NAME     — almost never unique
+"""
+
+from __future__ import annotations
+from dataclasses import dataclass
+from enum import IntEnum
+
+
+class LocatorScore(IntEnum):
+    """Reliability score for locator strategies (higher = better)."""
+    ID = 100
+    NAME = 90
+    CSS_SELECTOR = 80
+    XPATH_RELATIVE = 70
+    DATA_TESTID = 95       # data-testid is best practice
+    ARIA_LABEL = 75
+    LINK_TEXT = 50
+    PARTIAL_LINK_TEXT = 45
+    CLASS_NAME = 40
+    TAG_NAME = 10
+    XPATH_ABSOLUTE = 5     # Absolute XPath — worst
+
+
+@dataclass
+class LocatorSuggestion:
+    """A single locator suggestion with explanation."""
+    strategy: str          # By.ID, By.CSS_SELECTOR, etc.
+    value: str             # The locator value
+    score: int             # Reliability score
+    reason: str            # Why this was suggested
+    warning: str = ""      # Any anti-pattern warning
+
+
+class LocatorAdvisor:
+    """
+    Advises on the best Selenium locator strategy.
+
+    Used by Planner Agent to embed locator guidance in test plans,
+    and by Coder Agent to generate reliable locators.
+    """
+
+    # Anti-patterns to warn about
+    ANTI_PATTERNS = {
+        "absolute_xpath": {
+            "pattern": r"^/html/body",
+            "warning": "Absolute XPath is extremely fragile — breaks on any DOM change.",
+            "suggestion": "Use By.ID or By.CSS_SELECTOR instead."
+        },
+        "index_xpath": {
+            "pattern": r"\[\d+\]",
+            "warning": "Index-based XPath (e.g. [2]) breaks when new elements are added.",
+            "suggestion": "Use a unique attribute like id, name, or data-testid."
+        },
+        "dynamic_class": {
+            "pattern": r"[a-z0-9]{8,}",  # Random-looking class names
+            "warning": "This class name looks auto-generated and may change on rebuild.",
+            "suggestion": "Ask developers to add stable data-testid attributes."
+        },
+    }
+
+    # Locator strategy priority list (for Coder Agent prompt injection)
+    PRIORITY_GUIDE = """
+SELENIUM LOCATOR STRATEGY — Priority Order:
+
+1. data-testid attribute (BEST)
+   css = "[data-testid='login-button']"
+   → Stable, developer-intended for testing
+
+2. By.ID (EXCELLENT)
+   By.ID, "username"
+   → Fast, unique per page spec
+
+3. By.NAME (GOOD for forms)
+   By.NAME, "email"
+   → Stable for form inputs
+
+4. By.CSS_SELECTOR (GOOD)
+   By.CSS_SELECTOR, "button.login-btn"
+   By.CSS_SELECTOR, "input[placeholder='Email']"
+   By.CSS_SELECTOR, "form > button[type='submit']"
+   → Readable, faster than XPath
+
+5. Relative By.XPATH (ACCEPTABLE)
+   By.XPATH, "//button[contains(text(),'Login')]"
+   By.XPATH, "//input[@placeholder='Email']"
+   → Use only when CSS won't work
+
+6. By.LINK_TEXT (LIMITED)
+   By.LINK_TEXT, "Forgot Password"
+   → Only for anchor tags, breaks on text change
+
+NEVER USE:
+  ❌ Absolute XPath: /html/body/div[1]/form/input[2]
+  ❌ Index-based: (//button)[3]
+  ❌ Auto-generated classes: .sc-bdXHXe.hQDDGZ
+"""
+
+    @classmethod
+    def get_priority_guide(cls) -> str:
+        """Return the full locator priority guide for injection into LLM prompts."""
+        return cls.PRIORITY_GUIDE
+
+    @classmethod
+    def rank_locators(cls, locators: list[dict]) -> list[LocatorSuggestion]:
+        """
+        Rank a list of locator options by reliability.
+
+        Args:
+            locators: List of dicts with 'strategy' and 'value' keys
+
+        Returns:
+            Sorted list of LocatorSuggestion (best first)
+
+        Example:
+            ranked = LocatorAdvisor.rank_locators([
+                {"strategy": "xpath", "value": "/html/body/div/input"},
+                {"strategy": "id", "value": "username"},
+                {"strategy": "css", "value": "input.login-field"},
+            ])
+        """
+        strategy_scores = {
+            "id": LocatorScore.ID,
+            "name": LocatorScore.NAME,
+            "css": LocatorScore.CSS_SELECTOR,
+            "css_selector": LocatorScore.CSS_SELECTOR,
+            "xpath": LocatorScore.XPATH_RELATIVE,
+            "link_text": LocatorScore.LINK_TEXT,
+            "class_name": LocatorScore.CLASS_NAME,
+            "tag_name": LocatorScore.TAG_NAME,
+            "data_testid": LocatorScore.DATA_TESTID,
+            "aria_label": LocatorScore.ARIA_LABEL,
+        }
+
+        suggestions = []
+        for loc in locators:
+            strategy = loc.get("strategy", "").lower().replace(" ", "_")
+            value = loc.get("value", "")
+            score = strategy_scores.get(strategy, 30)
+
+            # Penalize absolute XPath
+            if strategy == "xpath" and value.startswith("/html"):
+                score = LocatorScore.XPATH_ABSOLUTE
+                warning = "⚠️ Absolute XPath — extremely fragile!"
+            elif strategy == "xpath" and "[" in value and value[value.index("[") + 1].isdigit():
+                score = max(score - 30, 10)
+                warning = "⚠️ Index-based XPath — fragile!"
+            elif "[data-testid" in value:
+                score = LocatorScore.DATA_TESTID
+                warning = ""
+            else:
+                warning = ""
+
+            reason = cls._get_reason(strategy, score)
+            suggestions.append(LocatorSuggestion(
+                strategy=strategy,
+                value=value,
+                score=score,
+                reason=reason,
+                warning=warning,
+            ))
+
+        return sorted(suggestions, key=lambda s: s.score, reverse=True)
+
+    @classmethod
+    def best_locator(cls, locators: list[dict]) -> LocatorSuggestion:
+        """Return the single best locator from a list."""
+        ranked = cls.rank_locators(locators)
+        return ranked[0] if ranked else None
+
+    @classmethod
+    def _get_reason(cls, strategy: str, score: int) -> str:
+        reasons = {
+            "id": "Unique per-page, fastest lookup, most stable",
+            "name": "Good for form fields, stable in most frameworks",
+            "css": "Readable, fast, flexible — preferred over XPath",
+            "css_selector": "Readable, fast, flexible — preferred over XPath",
+            "xpath": "Use only when CSS/ID not available",
+            "link_text": "Brittle — breaks on text change or i18n",
+            "class_name": "Often not unique — combine with other strategies",
+            "tag_name": "Almost never unique — avoid",
+            "data_testid": "Best practice — developer-defined test hook",
+            "aria_label": "Good for accessibility-first apps",
+        }
+        return reasons.get(strategy, "No specific guidance available")
+
+    @classmethod
+    def validate(cls, strategy: str, value: str) -> dict:
+        """
+        Validate a single locator and return warnings.
+
+        Returns:
+            dict with 'valid', 'score', 'warnings', 'suggestions'
+        """
+        import re
+        warnings = []
+        suggestions = []
+
+        if strategy.lower() == "xpath":
+            if value.startswith("/html"):
+                warnings.append("Absolute XPath is extremely fragile")
+                suggestions.append("Convert to By.ID or By.CSS_SELECTOR")
+
+            if re.search(r"\[\d+\]", value):
+                warnings.append("Index-based XPath breaks when DOM changes")
+                suggestions.append("Use unique attribute selectors instead")
+
+        if strategy.lower() in ("class_name", "css_selector"):
+            if re.search(r"\b[a-z0-9]{8,}\b", value):
+                warnings.append("Possible auto-generated class name detected")
+                suggestions.append("Request data-testid from developers")
+
+        score_map = {
+            "id": LocatorScore.ID,
+            "name": LocatorScore.NAME,
+            "css_selector": LocatorScore.CSS_SELECTOR,
+            "xpath": LocatorScore.XPATH_RELATIVE if not value.startswith("/html") else LocatorScore.XPATH_ABSOLUTE,
+            "link_text": LocatorScore.LINK_TEXT,
+            "class_name": LocatorScore.CLASS_NAME,
+            "tag_name": LocatorScore.TAG_NAME,
+        }
+
+        score = score_map.get(strategy.lower(), 30)
+
+        return {
+            "valid": len(warnings) == 0,
+            "score": score,
+            "warnings": warnings,
+            "suggestions": suggestions,
+        }