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

selenium_agent/agents/planner.py

@@ -0,0 +1,279 @@
+"""
+PLANNER AGENT
+=============
+Works like Playwright's planner agent, for Selenium Python:
+
+1. Opens a real (headless) browser and scans the live DOM of the target
+   URL — optionally exploring same-origin pages — so plans use REAL
+   locators, never guessed ones.
+2. Asks the LLM for a structured JSON plan (scenarios, page objects,
+   locators, wait strategy).
+3. The Orchestrator persists the plan to specs/<slug>.md (human-readable)
+   and specs/<slug>.json (Generator input).
+"""
+
+from selenium_agent.utils.logger import setup_logger
+from selenium_agent.utils.llm import create_llm_client, DEFAULT_PROVIDER, get_default_model
+from selenium_agent.utils.json_utils import extract_json_object, LLMJSONError
+from selenium_agent.selenium.locator_scanner import (
+    scan_site_locators, format_site_for_llm,
+)
+from selenium_agent.bdd.gherkin_advisor import GherkinAdvisor
+
+logger = setup_logger("PlannerAgent")
+
+_SYSTEM_BASE = """
+You are an expert QA Test Planner specializing in Selenium Python automation.
+
+══ PAGE OBJECT ARCHITECTURE — MOST IMPORTANT RULE ══
+
+Every distinct page MUST have its OWN class. NEVER mix pages.
+Class names and locators come from the actual app under test.
+
+EXAMPLE PATTERN (illustrative only — use actual app's pages and locators):
+
+  class LoginPage(BasePage):       ← only login elements
+  class DashboardPage(BasePage):   ← only dashboard elements
+  class ProductPage(BasePage):     ← only product page elements
+  class CartPage(BasePage):        ← only cart elements
+  class CheckoutPage(BasePage):    ← only checkout elements
+
+Each class contains ONLY the locators for that page.
+FORBIDDEN: putting page B locators inside page A's class.
+
+══ MULTI-STEP FLOW RULE ══
+
+For flows that span multiple pages (login → inventory → cart → checkout → logout):
+  - Plan SEPARATE page objects for EACH page
+  - page_objects_needed must list ALL pages: ["LoginPage", "InventoryPage", "CartPage", "CheckoutPage", "MenuPage"]
+  - Each locator entry must specify which page_object it belongs to
+  - wait_for_url() must be called after every navigation click
+
+══ LOCATOR RULES ══
+  1. CSS preferred over XPath
+  2. XPath only when CSS cannot express it
+  3. NEVER absolute XPath, NEVER index-based XPath
+  4. Priority: data-test > data-testid > id > name > css
+  5. Use ONLY locators from DOM scan — never invent
+
+══ WAIT STRATEGY ══
+  - Input fields     → fluent_wait(locator, 'visible')
+  - Buttons/links    → fluent_wait(locator, 'clickable')
+  - After navigation → wait_for_url('partial-url-string')
+  - Loaders          → fluent_wait(locator, 'invisible')
+  No time.sleep(). No hardcoded waits.
+
+══ FORM FILLING ══
+  For React/SPA forms always use safe_type() — not type():
+  safe_type(page, page.FIRST_NAME_INPUT, "John")
+
+══ SCENARIO QUALITY (enterprise test design) ══
+  - Cover the happy path FIRST, then negative/edge cases relevant to the instruction
+  - Every scenario independent — no shared state between scenarios
+  - Each scenario has explicit expected_result that a machine can assert
+  - Use realistic test_data (from the instruction when given)
+  - DOM-scan text shows the page BEFORE any action. expected_result must
+    describe the state AFTER the action (what changes/appears), never the
+    pre-action text you saw in the scan
+  - If the flow CREATES an entity (account, record), mark its test_data
+    values as "GENERATE_UNIQUE_AT_RUNTIME" — hardcoded values collide with
+    previous runs (e.g. "email already taken")
+  - When a scanned page contains a form, plan locators and fill-steps for
+    ALL its inputs/selects — apps silently reject submissions with missing
+    required fields, even if the instruction names only a few
+
+OTHER RULES:
+  - Use EXACT target URL — never example.com
+  - headless comes from config
+  - Respond with valid JSON only — no markdown fences
+"""
+
+_PYTEST_SCHEMA = """
+{
+  "mode": "pytest",
+  "url": "<EXACT URL from instruction>",
+  "browser": "chrome",
+  "headless": false,
+  "test_scenarios": [
+    {
+      "id": "TC001",
+      "name": "descriptive scenario name",
+      "description": "what this test verifies",
+      "steps": [
+        "open <PageName>.URL",
+        "type <field> on <PageName>",
+        "click <button> on <PageName>",
+        "wait_for_url('<url-fragment>')",
+        "interact with <NextPageName>"
+      ],
+      "expected_result": "what success looks like",
+      "test_data": {"key": "value"}
+    }
+  ],
+  "page_objects_needed": ["<Page1Name>", "<Page2Name>"],
+  "locators": [
+    {
+      "page_object": "<PageName>",
+      "element": "descriptive element name",
+      "css": "<css selector>",
+      "xpath": "<xpath>",
+      "preferred": "css",
+      "wait_condition": "visible"
+    }
+  ],
+  "pytest_markers": ["smoke"],
+  "notes": ""
+}
+"""
+
+_BDD_SCHEMA = """
+{
+  "mode": "bdd",
+  "url": "<EXACT URL from instruction>",
+  "feature_name": "<feature name>",
+  "feature_title": "<Feature Title>",
+  "role": "<user role>",
+  "goal": "<goal>",
+  "benefit": "<benefit>",
+  "browser": "chrome",
+  "headless": false,
+  "scenarios": [
+    {
+      "id": "TC001",
+      "name": "descriptive scenario name",
+      "tags": ["smoke"],
+      "steps": [
+        {"type": "Given", "text": "I am on the <page> page"},
+        {"type": "When",  "text": "I perform <action>"},
+        {"type": "Then",  "text": "I should see <result>"}
+      ],
+      "test_data": {}
+    }
+  ],
+  "page_objects_needed": ["<Page1Name>", "<Page2Name>"],
+  "locators": [
+    {
+      "page_object": "<PageName>",
+      "element": "descriptive element name",
+      "css": "<css selector>",
+      "preferred": "css",
+      "wait_condition": "visible"
+    }
+  ],
+  "notes": ""
+}
+"""
+
+_MULTI_PAGE_KEYWORDS = [
+    "checkout", "cart", "logout", "login and", "then", "after",
+    "navigate", "flow", "end to end", "e2e", "journey",
+]
+
+
+class PlannerAgent:
+    def __init__(self, api_key: str, provider: str = DEFAULT_PROVIDER,
+                 model: str | None = None):
+        resolved_model = model or get_default_model(provider)
+        self.client = create_llm_client(
+            provider=provider, api_key=api_key, model=resolved_model
+        )
+
+    def plan(self, user_instruction: str, mode: str = "pytest",
+             project_profile=None, headless: bool = False,
+             target_url: str | None = None,
+             explore_pages: int = 0) -> dict:
+        """
+        Build a test plan.
+
+        explore_pages: how many same-origin pages beyond the target URL to
+        scan for locators (0 = target page only). Multi-page instructions
+        automatically get exploration even when not requested.
+        """
+        logger.info(f"📋 Planning [{mode.upper()}] for: {user_instruction}")
+
+        schema = _BDD_SCHEMA if mode == "bdd" else _PYTEST_SCHEMA
+        system = _SYSTEM_BASE + f"\nRespond using this JSON schema:\n{schema}"
+
+        is_multi_page = (
+            sum(1 for kw in _MULTI_PAGE_KEYWORDS if kw in user_instruction.lower()) >= 2
+        )
+
+        # ── DOM scan BEFORE planning — real locators, never guessed ──
+        dom_context = ""
+        if target_url:
+            extra = explore_pages or (2 if is_multi_page else 0)
+            logger.info(f"🔍 Pre-plan DOM scan: {target_url} (explore={extra} extra pages)")
+            site = scan_site_locators(target_url, headless=True, max_extra_pages=extra,
+                                      instruction=user_instruction)
+            dom_context = format_site_for_llm(site, context="planning")
+            total = sum(len(v) for v in site.values())
+            if total:
+                logger.info(f"✅ {total} real locators from {len(site)} page(s) injected into plan prompt")
+            else:
+                logger.warning("⚠️  DOM scan returned nothing — LLM will infer locators")
+
+        multi_page_hint = ""
+        if is_multi_page:
+            multi_page_hint = (
+                "\n\n🚨 MULTI-PAGE FLOW DETECTED — MANDATORY RULES:\n"
+                "  1. Create a SEPARATE page object class for EACH page visited\n"
+                "  2. page_objects_needed must list ALL pages with meaningful names based on the app\n"
+                "  3. Each locator entry must have 'page_object' field specifying which class it belongs to\n"
+                "  4. NEVER put locators from one page inside another page's class\n"
+                "  5. Add wait_for_url() after every navigation step\n"
+            )
+
+        url_block = ""
+        if target_url:
+            url_block = (
+                f"\n\n🚨 TARGET URL — use EXACTLY:\n"
+                f"  URL = '{target_url}'\n"
+                f"  NEVER use example.com or any other URL.\n"
+            )
+
+        project_context = ""
+        if project_profile:
+            project_context = (
+                f"\n\nFit into this existing project:\n"
+                f"{project_profile.to_llm_context()}\n"
+            )
+
+        user_prompt = (
+            f"Create a Selenium Python {mode} test plan for: {user_instruction}\n"
+            f"headless: {str(headless).lower()}"
+            f"{url_block}"
+            f"{multi_page_hint}"
+            f"\n\n{dom_context}"
+            f"{project_context}"
+        )
+
+        max_tokens = 8000 if is_multi_page else 4000
+        raw = self.client.generate_text(
+            system_prompt=system,
+            user_prompt=user_prompt,
+            max_tokens=max_tokens,
+            json_mode=True,
+        )
+
+        try:
+            plan = extract_json_object(raw)
+        except LLMJSONError:
+            logger.warning("⚠️  Plan JSON unparseable — retrying once with strict reminder")
+            raw = self.client.generate_text(
+                system_prompt=system,
+                user_prompt=user_prompt + "\n\nIMPORTANT: respond with ONLY the JSON object. "
+                                          "No prose, no markdown fences.",
+                max_tokens=max_tokens,
+                json_mode=True,
+            )
+            plan = extract_json_object(raw)
+
+        plan["mode"] = mode
+        plan["headless"] = headless
+        if target_url:
+            plan["url"] = target_url
+
+        count = len(plan.get("test_scenarios") or plan.get("scenarios", []))
+        pages = plan.get("page_objects_needed", [])
+        logger.info(f"✅ Plan ready: {count} scenario(s) | pages={pages} | url={plan.get('url')}")
+        return plan

selenium_agent/bdd/__init__.py

@@ -0,0 +1,15 @@
+from selenium_agent.bdd.gherkin_advisor import GherkinAdvisor
+from selenium_agent.bdd.templates import (
+    FEATURE_FILE_TEMPLATE,
+    SCENARIO_TEMPLATE,
+    STEP_DEFINITION_TEMPLATE,
+    CONFTEST_TEMPLATE,
+)
+
+__all__ = [
+    "GherkinAdvisor",
+    "FEATURE_FILE_TEMPLATE",
+    "SCENARIO_TEMPLATE",
+    "STEP_DEFINITION_TEMPLATE",
+    "CONFTEST_TEMPLATE",
+]

selenium_agent/bdd/gherkin_advisor.py

@@ -0,0 +1,189 @@
+"""
+GHERKIN ADVISOR
+===============
+pytest-bdd specific intelligence for writing good BDD tests.
+
+Provides:
+- Gherkin best practices guide (injected into LLM prompts)
+- Step naming conventions
+- Anti-pattern detection
+- Feature file structure rules
+"""
+
+from __future__ import annotations
+from dataclasses import dataclass
+
+
+@dataclass
+class StepValidation:
+    """Result of validating a Gherkin step."""
+    valid: bool
+    warnings: list[str]
+    suggestions: list[str]
+
+
+class GherkinAdvisor:
+    """
+    Advises on writing good Gherkin feature files and step definitions.
+    Used by Planner and Coder agents when BDD mode is enabled.
+    """
+
+    BEST_PRACTICES_GUIDE = """
+PYTEST-BDD / GHERKIN BEST PRACTICES:
+
+FEATURE FILE RULES:
+1. One Feature per file — named <feature>.feature
+2. Feature title describes the business capability, not the UI
+3. Scenarios should be independent — no shared state
+4. Use Scenario Outline for data-driven tests
+5. Tags (@smoke, @regression) go above Scenario
+
+STEP WRITING RULES:
+1. Given  → System state / precondition
+   ✅ Given I am on the login page
+   ✅ Given the user "admin" exists in the system
+   ❌ Given I click the login button  (that's a When)
+
+2. When   → User action
+   ✅ When I enter username "standard_user"
+   ✅ When I click the submit button
+   ❌ When the page shows an error  (that's a Then)
+
+3. Then   → Expected outcome / assertion
+   ✅ Then I should see the dashboard
+   ✅ Then the error message "Invalid credentials" should be displayed
+   ❌ Then I click OK  (that's a When)
+
+4. And/But → Continuation of previous step type
+   ✅ When I enter username "user"
+      And I enter password "pass"
+      And I click Login
+
+STEP DEFINITION RULES:
+1. Use parsers.parse() for parameterized steps:
+   @when(parsers.parse('I enter username "{username}"'))
+   def enter_username(login_page, username):
+       login_page.type(LoginPage.USERNAME_INPUT, username)
+
+2. Never put assertions in Given/When steps
+3. Always use page object methods — never raw driver calls
+4. Fixtures inject page objects, not driver directly
+
+ANTI-PATTERNS TO AVOID:
+❌ UI-centric steps: "When I click the blue button at position 3"
+❌ Steps with implementation details: "When I send POST to /api/login"
+❌ Chained UI actions in one step: "When I login and navigate to profile"
+❌ Assertions in Given: "Given the error message is shown"
+❌ Vague Then: "Then it works"
+
+GOOD SCENARIO EXAMPLE:
+  @smoke @login
+  Scenario: Successful login with valid credentials
+    Given I am on the login page
+    When I enter username "standard_user"
+    And I enter password "secret_sauce"
+    And I click the login button
+    Then I should be redirected to the products page
+    And the page title should be "Products"
+
+SCENARIO OUTLINE EXAMPLE (data-driven):
+  Scenario Outline: Login with multiple users
+    Given I am on the login page
+    When I enter username "<username>"
+    And I enter password "<password>"
+    Then I should see "<expected_result>"
+
+    Examples:
+      | username        | password     | expected_result     |
+      | standard_user   | secret_sauce | Products            |
+      | locked_out_user | secret_sauce | Epic sadface logo   |
+"""
+
+    @classmethod
+    def get_guide(cls) -> str:
+        """Return full Gherkin best practices guide for LLM prompt injection."""
+        return cls.BEST_PRACTICES_GUIDE
+
+    @classmethod
+    def validate_step(cls, step: str) -> StepValidation:
+        """
+        Validate a single Gherkin step for common anti-patterns.
+
+        Args:
+            step: Full step string e.g. "When I click the blue button at index 3"
+
+        Returns:
+            StepValidation with warnings and suggestions
+        """
+        warnings = []
+        suggestions = []
+        step_lower = step.lower()
+
+        # UI-centric anti-patterns
+        ui_terms = ["click", "button", "input", "field", "textbox", "dropdown"]
+        if any(t in step_lower for t in ui_terms) and step_lower.startswith("given"):
+            warnings.append("Given steps should describe state, not UI actions")
+            suggestions.append("Rewrite as: Given the user is authenticated")
+
+        # Index-based references
+        if any(w in step_lower for w in ["index", "position", "number", "nth"]):
+            warnings.append("Index-based steps are brittle")
+            suggestions.append("Reference elements by label or role instead")
+
+        # Assertion in Given/When
+        if step_lower.startswith(("given", "when")) and any(
+            w in step_lower for w in ["should", "must", "verify", "assert", "check"]
+        ):
+            warnings.append("Assertions belong in Then steps, not Given/When")
+            suggestions.append("Move verification to a Then step")
+
+        # Vague Then
+        if step_lower.startswith("then") and any(
+            w in step_lower for w in ["it works", "success", "ok", "done"]
+        ):
+            warnings.append("Vague Then step — be specific about what is verified")
+            suggestions.append("Specify exact element, message, or URL expected")
+
+        # Too many actions in one step
+        action_words = ["and", "then", "also", "afterwards"]
+        if sum(1 for w in action_words if f" {w} " in step_lower) >= 2:
+            warnings.append("Step contains multiple actions — split into separate steps")
+            suggestions.append("Use And/But to chain related steps")
+
+        return StepValidation(
+            valid=len(warnings) == 0,
+            warnings=warnings,
+            suggestions=suggestions,
+        )
+
+    @classmethod
+    def validate_feature(cls, feature_content: str) -> list[StepValidation]:
+        """Validate all steps in a feature file."""
+        results = []
+        for line in feature_content.splitlines():
+            line = line.strip()
+            if any(line.startswith(kw) for kw in ("Given", "When", "Then", "And", "But")):
+                results.append(cls.validate_step(line))
+        return results
+
+    @classmethod
+    def get_folder_structure(cls) -> str:
+        """Return recommended BDD folder structure for generated tests."""
+        return """
+RECOMMENDED pytest-bdd FOLDER STRUCTURE:
+
+generated_tests/
+├── features/                    ← .feature files (Gherkin)
+│   └── login.feature
+├── step_definitions/            ← pytest-bdd step implementations
+│   └── test_login_steps.py     ← must start with test_ for pytest discovery
+├── pages/                       ← Page Objects (BasePage subclasses)
+│   └── login_page.py
+└── conftest.py                  ← shared fixtures (driver, etc.)
+
+IMPORTANT:
+- step_definitions files MUST start with test_ for pytest to discover them
+- Feature files go in features/ folder
+- conftest.py must be at root of generated_tests/
+- scenarios() call in step file links to feature file
+"""

selenium_agent/bdd/templates.py

@@ -0,0 +1,98 @@
+"""
+BDD TEMPLATES
+=============
+Pre-built templates for pytest-bdd feature files and step definitions.
+Coder Agent uses these as base when generating BDD test code.
+"""
+
+FEATURE_FILE_TEMPLATE = '''\
+# {feature_name}.feature
+# Generated by selenium-python-ai-agent
+
+Feature: {feature_title}
+  As a {role}
+  I want to {goal}
+  So that {benefit}
+
+{scenarios}
+'''
+
+SCENARIO_TEMPLATE = '''\
+  Scenario: {scenario_name}
+{steps}
+'''
+
+STEP_DEFINITION_TEMPLATE = '''\
+"""
+Step Definitions for: {feature_name}
+Generated by selenium-python-ai-agent
+"""
+
+import pytest
+from pytest_bdd import given, when, then, parsers, scenarios
+from selenium_agent.selenium.driver_factory import DriverFactory
+from pages.{page_module} import {page_class}
+
+# Link to feature file
+scenarios("../features/{feature_name}.feature")
+
+
+# ── Fixtures ──────────────────────────────────────────────────
+
+@pytest.fixture
+def driver():
+    d = DriverFactory.create(browser="chrome", headless=True)
+    yield d
+    d.quit()
+
+
+@pytest.fixture
+def {page_fixture}(driver):
+    page = {page_class}(driver)
+    page.open({page_class}.URL)
+    return page
+
+
+# ── Step Definitions ─────────────────────────────────────────
+
+{steps}
+'''
+
+GIVEN_STEP_TEMPLATE = '''\
+@given("{step_text}")
+def {func_name}({params}):
+    """{step_text}"""
+    {body}
+'''
+
+WHEN_STEP_TEMPLATE = '''\
+@when("{step_text}")
+def {func_name}({params}):
+    """{step_text}"""
+    {body}
+'''
+
+THEN_STEP_TEMPLATE = '''\
+@then("{step_text}")
+def {func_name}({params}):
+    """{step_text}"""
+    {body}
+'''
+
+CONFTEST_TEMPLATE = '''\
+"""
+conftest.py — pytest-bdd shared fixtures
+Generated by selenium-python-ai-agent
+"""
+
+import pytest
+from selenium_agent.selenium.driver_factory import DriverFactory
+
+
+@pytest.fixture(scope="function")
+def driver():
+    """Create WebDriver instance for each test."""
+    d = DriverFactory.create(browser="chrome", headless=True)
+    yield d
+    d.quit()
+'''