scriptgini 0.1.2__py3-none-any.whl

app/agents/prompts.py

@@ -0,0 +1,147 @@
+"""
+Prompt templates used by the ScriptGini LangGraph agent.
+"""
+
+SYSTEM_PROMPT = """You are SCRIPT GINI, an enterprise-grade Test Script Generation Engine.
+
+Your primary responsibility is to convert FUNCTIONAL TEST CASES into
+HIGH-QUALITY, REVIEW-READY AUTOMATION TEST SCRIPTS using the supplied
+APPLICATION UNDER TEST (AUT) URL as execution context.
+
+CORE PRINCIPLES:
+1. Understand WHAT is being tested before writing HOW.
+2. Reason using generic actions (navigate, click, fill, select, assert, wait),
+   then convert to the requested framework syntax in the final output.
+3. Generate executable test scripts ONLY — no project scaffolding, no CI config.
+4. Place TODO comments where selectors or data are ambiguous.
+5. DO NOT hallucinate APIs, DB calls, or backend validations. UI only.
+
+SELECTOR PRIORITY (follow strictly):
+1. Role-based / accessible selectors
+2. Label-based selectors
+3. data-testid / data-qa attributes
+4. Stable CSS selectors
+5. XPath — LAST RESORT only
+
+ASSERTIONS must validate visible UI state: text, visibility, URL, page title.
+"""
+
+INTENT_ANALYSIS_PROMPT = """\
+Analyze the following functional test case and extract:
+1. Business intent — what user flow / feature is being tested
+2. Preconditions — what must be true before the test starts
+3. Key actions — list of user interactions (navigate, click, fill, select, etc.)
+4. Assertions — what outcomes need to be verified
+
+AUT Base URL: {aut_base_url}
+
+Test Case:
+{test_case_content}
+
+Preconditions provided: {preconditions}
+Test data hints: {test_data_hints}
+
+Respond in structured JSON with keys: business_intent, preconditions, actions, assertions.
+"""
+
+SCRIPT_GENERATION_PROMPT = """\
+Generate a complete, executable automation test script for the following test case.
+
+Framework: {framework}
+AUT Base URL: {aut_base_url}
+Authentication hints: {auth_hints}
+
+Test Case Title: {test_case_title}
+Business Intent: {business_intent}
+Preconditions: {preconditions}
+Key Actions: {actions}
+Expected Assertions: {assertions}
+
+RULES (NON-NEGOTIABLE):
+1. STEP FIDELITY: Implement EVERY action as an explicit framework call, in exact order.
+   Add a comment before each step: # Step N: <original action text>
+2. LOCATOR PRIORITY (follow strictly):
+   role-based > label-based > placeholder > visible text > data-testid/data-qa > CSS > XPath (last resort)
+3. LOCATOR PROVENANCE: Infer locator names ONLY from the provided actions and assertions.
+   Never invent UI labels, placeholders, or test-ids not present in the input.
+   If you must assume, add an # ASSUMPTION: comment explaining why.
+4. ASSERTION TRACEABILITY: Every expected assertion must map to ≥1 framework assertion call.
+   Add a comment above each assertion: # Assert: <expected outcome text>
+5. NO PSEUDO-CODE: Output runnable code only. No placeholders, no stub functions.
+6. ARRANGE / ACT / ASSERT: Structure the script with a comment separating each phase.
+7. TEST DATA: If test data hints are provided use them; if not, add # No test data required.
+8. The script must be directly runnable — complete imports, no missing setup.
+9. Follow {framework} best practices and idiomatic style.
+
+Output ONLY the script code. No explanations, no markdown fences.
+"""
+
+PLAYWRIGHT_SCRIPT_GENERATION_PROMPT = """\
+Generate a complete, runnable Python Playwright (sync API) + Pytest script for the following test case.
+
+AUT Base URL: {aut_base_url}
+Authentication hints: {auth_hints}
+
+Test Case Title: {test_case_title}
+Business Intent: {business_intent}
+Preconditions: {preconditions}
+Key Actions: {actions}
+Expected Assertions: {assertions}
+
+MANDATORY FRAMEWORK RULES:
+- Use pytest-playwright built-in fixtures: page, context, browser (sync API only).
+- Use Playwright sync API exclusively (playwright.sync_api). Never use async/await.
+- All assertions MUST use Playwright expect() — never bare Python assert for UI state.
+- Name the test function: test_<slugified_title>() (lowercase, underscores, max 60 chars).
+- Add a docstring containing: Title, Business Intent, Preconditions.
+
+LOCATOR PRIORITY (follow strictly):
+1. page.get_by_role(role, name="...")
+2. page.get_by_label("...")
+3. page.get_by_placeholder("...")
+4. page.get_by_text("...")
+5. page.get_by_test_id("...") — only if explicitly justified by the input
+6. page.locator("css=...") — last resort only
+Never invent labels, roles, or test-ids not present in the input.
+If you must assume a locator name, add: # ASSUMPTION: <reason>
+
+STEP FIDELITY (NON-NEGOTIABLE):
+- Implement EVERY action in exact order.
+- Add a comment before each action: # Step N: <original action text>
+- For navigation: use page.goto(base_url + path). Define base_url as a local variable.
+- Never skip or summarise steps.
+
+ASSERTION TRACEABILITY (NON-NEGOTIABLE):
+- Every expected assertion must produce ≥1 expect() call.
+- Add a comment above each assertion: # Assert: <expected outcome text>
+- Validate visible UI state: text content, element visibility, URL, page title.
+- If the assertion says "no error shown": assert the error locator is hidden or not present.
+
+ARRANGE / ACT / ASSERT structure:
+- Separate the three phases with # --- Arrange ---, # --- Act ---, # --- Assert --- comments.
+
+TEST DATA:
+- If test data hints are provided, define them as named constants at the top of the function.
+- If no test data: add # No test data required.
+- Never hardcode credentials inline without a named constant.
+
+The script must be directly runnable with: pytest <filename>.py
+Output ONLY the script code. No explanations, no markdown fences.
+"""
+
+REVIEW_PROMPT = """\
+Review the following {framework} test script for quality issues:
+
+1. Are all assertions present and meaningful?
+2. Are there any hardcoded credentials or sensitive data? (flag them)
+3. Are TODO comments placed wherever assumptions were made?
+4. Is the script readable and logically structured?
+
+If there are issues, rewrite the improved script.
+If the script is acceptable, return it unchanged.
+
+Script:
+{script}
+
+Output ONLY the final script code. No explanations, no markdown fences.
+"""

app/agents/script_gini_agent.py

@@ -0,0 +1,342 @@
+"""
+ScriptGini LangGraph Agent.
+
+Graph nodes:
+  1. parse_intent  — Analyse test case; extract business intent, actions, assertions
+  2. generate_script — Produce framework-specific test script
+  3. review_script   — Quality-check and optionally rewrite the script
+  4. finalize        — Return the final script
+
+State flows linearly: parse_intent → generate_script → review_script → finalize
+"""
+from __future__ import annotations
+
+import json
+import logging
+import re
+from typing import TypedDict, Annotated
+
+from langchain_core.messages import HumanMessage, SystemMessage
+from langgraph.graph import StateGraph, END
+
+from app.agents.prompts import (
+    SYSTEM_PROMPT,
+    INTENT_ANALYSIS_PROMPT,
+    SCRIPT_GENERATION_PROMPT,
+    PLAYWRIGHT_SCRIPT_GENERATION_PROMPT,
+    REVIEW_PROMPT,
+)
+from app.config import settings
+from app.llm.provider import get_llm, LLMProvider
+
+logger = logging.getLogger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# Agent State
+# ---------------------------------------------------------------------------
+
+class AgentState(TypedDict):
+    # Inputs
+    test_case_title: str
+    test_case_content: str
+    preconditions: str
+    test_data_hints: str
+    aut_base_url: str
+    framework: str
+    auth_hints: str
+    llm_provider: str
+    llm_model: str | None
+
+    # Intermediate
+    business_intent: str
+    actions: str
+    assertions: str
+    parsed_preconditions: str
+
+    # Output
+    script: str
+    error: str | None
+    token_usage: int
+
+
+# ---------------------------------------------------------------------------
+# Node implementations
+# ---------------------------------------------------------------------------
+
+def _llm_invoke(state: AgentState, system: str, human: str) -> tuple[str, int]:
+    """Helper: call the configured LLM and return (content, token_count)."""
+    llm = get_llm(
+        provider=state["llm_provider"],  # type: ignore[arg-type]
+        model=state.get("llm_model"),
+    )
+    messages = [SystemMessage(content=system), HumanMessage(content=human)]
+
+    max_attempts = 1
+    if state.get("llm_provider") == "ollama":
+        max_attempts += settings.OLLAMA_TIMEOUT_RETRIES
+
+    last_error: Exception | None = None
+    for attempt in range(1, max_attempts + 1):
+        try:
+            response = llm.invoke(messages)
+            break
+        except Exception as exc:  # pragma: no cover - depends on provider/network behavior
+            if state.get("llm_provider") == "gemini" and "not_found" in str(exc).lower():
+                raise ValueError(
+                    "Gemini model was not found for this API version/method. "
+                    "Update GEMINI_MODEL in .env (for example: gemini-2.0-flash) "
+                    "or set llm_model in the request payload to a currently available model."
+                ) from exc
+            is_timeout = "timeout" in str(exc).lower() or exc.__class__.__name__.endswith("Timeout")
+            if state.get("llm_provider") != "ollama" or not is_timeout or attempt >= max_attempts:
+                raise
+            last_error = exc
+            logger.warning("Ollama timeout during LLM invoke (attempt %s/%s). Retrying once.", attempt, max_attempts)
+    else:
+        # Defensive guard: loop exhausted without a response or raised exception.
+        raise RuntimeError("LLM invocation failed unexpectedly")
+
+    usage = 0
+    if hasattr(response, "usage_metadata") and response.usage_metadata:
+        usage = response.usage_metadata.get("total_tokens", 0)
+    return response.content, usage
+
+
+def _normalize_case_line(value: str) -> str:
+    return re.sub(r"^[-*\d\.)\s]+", "", value.strip())
+
+
+def _extract_local_intent(state: AgentState) -> dict:
+    """Fast path: derive intent/actions/assertions heuristically without an LLM round-trip."""
+    raw_content = state.get("test_case_content", "") or ""
+    lines = [_normalize_case_line(line) for line in raw_content.splitlines() if line.strip()]
+
+    actions: list[str] = []
+    assertions: list[str] = []
+    extracted_preconditions: list[str] = []
+
+    for line in lines:
+        lowered = line.lower()
+
+        if lowered.startswith("precondition"):
+            extracted_preconditions.append(line)
+            continue
+        if lowered.startswith("given"):
+            extracted_preconditions.append(line)
+            continue
+        if lowered.startswith("step") or lowered.startswith("when") or lowered.startswith("and"):
+            actions.append(line)
+            continue
+        if lowered.startswith("expected") or lowered.startswith("then") or lowered.startswith("assert"):
+            assertions.append(line)
+            continue
+
+    # Fall back to sentence chunks so downstream generation still gets structured hints.
+    if not actions:
+        actions = [segment.strip() for segment in re.split(r"[\r\n]+", raw_content) if segment.strip()][:8]
+    if not assertions:
+        assertions = [line for line in lines if "expect" in line.lower() or "should" in line.lower()][:6]
+
+    business_intent = state.get("test_case_title", "").strip() or (lines[0] if lines else "")
+    preconditions = state.get("preconditions", "").strip()
+    if extracted_preconditions:
+        merged = [item for item in [preconditions, *extracted_preconditions] if item]
+        preconditions = "\n".join(dict.fromkeys(merged))
+
+    return {
+        "business_intent": business_intent,
+        "parsed_preconditions": preconditions,
+        "actions": json.dumps(actions, indent=2),
+        "assertions": json.dumps(assertions, indent=2),
+        "error": None,
+    }
+
+
+def _extract_llm_intent(state: AgentState) -> dict:
+    prompt = INTENT_ANALYSIS_PROMPT.format(
+        aut_base_url=state["aut_base_url"],
+        test_case_content=state["test_case_content"],
+        preconditions=state.get("preconditions") or "None provided",
+        test_data_hints=state.get("test_data_hints") or "None provided",
+    )
+    content, tokens = _llm_invoke(state, SYSTEM_PROMPT, prompt)
+
+    # Try to parse JSON; fall back to using the raw text
+    try:
+        parsed = json.loads(content)
+    except json.JSONDecodeError:
+        # LLM may wrap JSON in markdown fences — strip them
+        clean = content.strip().removeprefix("```json").removeprefix("```").removesuffix("```").strip()
+        try:
+            parsed = json.loads(clean)
+        except json.JSONDecodeError:
+            parsed = {
+                "business_intent": content,
+                "preconditions": state.get("preconditions", ""),
+                "actions": [],
+                "assertions": [],
+            }
+
+    return {
+        "business_intent": parsed.get("business_intent", ""),
+        "parsed_preconditions": str(parsed.get("preconditions", state.get("preconditions", ""))),
+        "actions": json.dumps(parsed.get("actions", []), indent=2) if isinstance(parsed.get("actions"), list) else str(parsed.get("actions", "")),
+        "assertions": json.dumps(parsed.get("assertions", []), indent=2) if isinstance(parsed.get("assertions"), list) else str(parsed.get("assertions", "")),
+        "token_usage": state.get("token_usage", 0) + tokens,
+        "error": None,
+    }
+
+
+def node_parse_intent(state: AgentState) -> dict:
+    """Node 1 — Parse the test case and extract structured intent."""
+    try:
+        if settings.USE_LLM_INTENT_ANALYSIS:
+            return _extract_llm_intent(state)
+        return _extract_local_intent(state)
+    except Exception as exc:
+        logger.exception("parse_intent node failed")
+        return {"error": str(exc)}
+
+
+def node_generate_script(state: AgentState) -> dict:
+    """Node 2 — Generate the test script from parsed intent."""
+    if state.get("error"):
+        return {}
+
+    if state["framework"] == "playwright_python":
+        prompt = PLAYWRIGHT_SCRIPT_GENERATION_PROMPT.format(
+            aut_base_url=state["aut_base_url"],
+            auth_hints=state.get("auth_hints") or "None provided",
+            test_case_title=state["test_case_title"],
+            business_intent=state.get("business_intent", ""),
+            preconditions=state.get("parsed_preconditions", ""),
+            actions=state.get("actions", ""),
+            assertions=state.get("assertions", ""),
+        )
+    else:
+        prompt = SCRIPT_GENERATION_PROMPT.format(
+            framework=state["framework"],
+            aut_base_url=state["aut_base_url"],
+            auth_hints=state.get("auth_hints") or "None provided",
+            test_case_title=state["test_case_title"],
+            business_intent=state.get("business_intent", ""),
+            preconditions=state.get("parsed_preconditions", ""),
+            actions=state.get("actions", ""),
+            assertions=state.get("assertions", ""),
+        )
+    try:
+        content, tokens = _llm_invoke(state, SYSTEM_PROMPT, prompt)
+        return {
+            "script": content,
+            "token_usage": state.get("token_usage", 0) + tokens,
+        }
+    except Exception as exc:
+        logger.exception("generate_script node failed")
+        error_message = str(exc)
+        if state.get("llm_provider") == "ollama" and "timeout" in error_message.lower():
+            error_message = (
+                f"{error_message}. Ollama timed out while generating script. "
+                "Try a smaller model, reduce OLLAMA_NUM_PREDICT, or increase OLLAMA_REQUEST_TIMEOUT_SECONDS in .env."
+            )
+        return {"error": error_message}
+
+
+def node_review_script(state: AgentState) -> dict:
+    """Node 3 — Quality review; rewrite if issues found."""
+    if state.get("error") or not state.get("script"):
+        return {}
+
+    if settings.SKIP_REVIEW_FOR_OLLAMA and state.get("llm_provider") == "ollama":
+        return {}
+
+    prompt = REVIEW_PROMPT.format(
+        framework=state["framework"],
+        script=state["script"],
+    )
+    try:
+        content, tokens = _llm_invoke(state, SYSTEM_PROMPT, prompt)
+        return {
+            "script": content,
+            "token_usage": state.get("token_usage", 0) + tokens,
+        }
+    except Exception as exc:
+        logger.exception("review_script node failed")
+        return {"error": str(exc)}
+
+
+# ---------------------------------------------------------------------------
+# Graph definition
+# ---------------------------------------------------------------------------
+
+def build_graph() -> StateGraph:
+    graph = StateGraph(AgentState)
+
+    graph.add_node("parse_intent", node_parse_intent)
+    graph.add_node("generate_script", node_generate_script)
+    graph.add_node("review_script", node_review_script)
+
+    graph.set_entry_point("parse_intent")
+    graph.add_edge("parse_intent", "generate_script")
+    graph.add_edge("generate_script", "review_script")
+    graph.add_edge("review_script", END)
+
+    return graph.compile()
+
+
+# Singleton compiled graph
+_app = None
+
+
+def get_agent():
+    global _app
+    if _app is None:
+        _app = build_graph()
+    return _app
+
+
+# ---------------------------------------------------------------------------
+# Public entry point
+# ---------------------------------------------------------------------------
+
+def run_agent(
+    *,
+    test_case_title: str,
+    test_case_content: str,
+    preconditions: str = "",
+    test_data_hints: str = "",
+    aut_base_url: str,
+    framework: str = "playwright_python",
+    auth_hints: str = "",
+    llm_provider: LLMProvider = "openai",
+    llm_model: str | None = None,
+) -> dict:
+    """
+    Execute the ScriptGini agent and return a result dict with keys:
+        script, error, token_usage
+    """
+    initial_state: AgentState = {
+        "test_case_title": test_case_title,
+        "test_case_content": test_case_content,
+        "preconditions": preconditions,
+        "test_data_hints": test_data_hints,
+        "aut_base_url": aut_base_url,
+        "framework": framework,
+        "auth_hints": auth_hints,
+        "llm_provider": llm_provider,
+        "llm_model": llm_model,
+        # intermediate / output — initialise to empty
+        "business_intent": "",
+        "actions": "",
+        "assertions": "",
+        "parsed_preconditions": "",
+        "script": "",
+        "error": None,
+        "token_usage": 0,
+    }
+    result = get_agent().invoke(initial_state)
+    return {
+        "script": result.get("script", ""),
+        "error": result.get("error"),
+        "token_usage": result.get("token_usage", 0),
+    }

app/config.py

@@ -0,0 +1,59 @@
+from pydantic_settings import BaseSettings, SettingsConfigDict
+from typing import Literal
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(env_file=".env", env_file_encoding="utf-8", extra="ignore")
+
+    # App
+    APP_NAME: str = "ScriptGini"
+    DEBUG: bool = False
+
+    # Database
+    DATABASE_URL: str = "sqlite:///./scriptgini.db"
+
+    # Default LLM provider
+    DEFAULT_LLM_PROVIDER: Literal["openai", "ollama", "openrouter", "gemini", "bedrock"] = "openai"
+    LLM_REQUEST_TIMEOUT_SECONDS: float = 45.0
+    SCRIPT_GENERATION_TIMEOUT_SECONDS: int = 180
+    PLAYWRIGHT_RUN_HEADED: bool = True
+    SCRIPT_EXECUTION_TIMEOUT_SECONDS: int = 300
+    SKIP_REVIEW_FOR_OLLAMA: bool = True
+    USE_LLM_INTENT_ANALYSIS: bool = True
+
+    # Automatic Git export
+    AUTO_EXPORT_GIT_ENABLED: bool = False
+    AUTO_EXPORT_GIT_REPO_URL: str = ""
+    AUTO_EXPORT_GIT_BRANCH: str = "main"
+    AUTO_EXPORT_GIT_LOCAL_PATH: str = "~/.scriptgini/scriptgini-sandbox"
+    AUTO_EXPORT_GIT_USER_NAME: str = "ScriptGini"
+    AUTO_EXPORT_GIT_USER_EMAIL: str = "scriptgini@local"
+
+    # OpenAI
+    OPENAI_API_KEY: str = ""
+    OPENAI_MODEL: str = "gpt-4o"
+
+    # Ollama
+    OLLAMA_BASE_URL: str = "http://localhost:11434"
+    OLLAMA_MODEL: str = "llama3"
+    OLLAMA_NUM_PREDICT: int = 700
+    OLLAMA_REQUEST_TIMEOUT_SECONDS: float = 180.0
+    OLLAMA_TIMEOUT_RETRIES: int = 1
+
+    # OpenRouter
+    OPENROUTER_API_KEY: str = ""
+    OPENROUTER_MODEL: str = "openai/gpt-4o"
+    OPENROUTER_BASE_URL: str = "https://openrouter.ai/api/v1"
+
+    # Google Gemini
+    GOOGLE_API_KEY: str = ""
+    GEMINI_MODEL: str = "gemini-2.5-flash"
+
+    # AWS Bedrock
+    AWS_ACCESS_KEY_ID: str = ""
+    AWS_SECRET_ACCESS_KEY: str = ""
+    AWS_REGION_NAME: str = "us-east-1"
+    BEDROCK_MODEL_ID: str = "anthropic.claude-3-5-sonnet-20241022-v2:0"
+
+
+settings = Settings()

app/database.py

@@ -0,0 +1,23 @@
+from sqlalchemy import create_engine
+from sqlalchemy.orm import sessionmaker, DeclarativeBase
+
+from app.config import settings
+
+engine = create_engine(
+    settings.DATABASE_URL,
+    connect_args={"check_same_thread": False},  # required for SQLite
+)
+
+SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)
+
+
+class Base(DeclarativeBase):
+    pass
+
+
+def get_db():
+    db = SessionLocal()
+    try:
+        yield db
+    finally:
+        db.close()