sap-qa-agent 0.1.0__tar.gz

sap_qa_agent-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,31 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[all]"
+          pip install pytest pytest-asyncio hypothesis
+
+      - name: Validate Skills
+        run: sap-qa-mcp validate-skills
+
+      - name: Run MCP tests
+        run: pytest tests/mcp/ -v --tb=short

sap_qa_agent-0.1.0/.gitignore

@@ -0,0 +1,18 @@
+# OS
+.DS_Store
+Thumbs.db
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+.dist/
+.build/
+.node_modules/
+
+./.venv
+
+pyproject.toml
+.artifacts/

sap_qa_agent-0.1.0/PKG-INFO

@@ -0,0 +1,26 @@
+Metadata-Version: 2.4
+Name: sap-qa-agent
+Version: 0.1.0
+Summary: SAP QA Agent — UI automation engine + MCP Server packaging for SAP Public Cloud
+Requires-Python: >=3.12
+Requires-Dist: fastmcp>=0.2.0
+Requires-Dist: httpx
+Requires-Dist: opencv-python
+Requires-Dist: openpyxl>=3.1
+Requires-Dist: pillow
+Requires-Dist: psutil
+Requires-Dist: pydantic>=2.0
+Requires-Dist: python-frontmatter
+Requires-Dist: pywin32; sys_platform == 'win32'
+Requires-Dist: pyyaml
+Requires-Dist: rapidocr-onnxruntime
+Requires-Dist: ultralytics
+Provides-Extra: all
+Requires-Dist: fastapi>=0.110; extra == 'all'
+Requires-Dist: python-multipart; extra == 'all'
+Requires-Dist: uvicorn>=0.29; extra == 'all'
+Provides-Extra: backend
+Requires-Dist: fastapi>=0.110; extra == 'backend'
+Requires-Dist: python-multipart; extra == 'backend'
+Requires-Dist: uvicorn>=0.29; extra == 'backend'
+Provides-Extra: ui

sap_qa_agent-0.1.0/README.md

@@ -0,0 +1,81 @@
+# SAP QA Agent
+
+基于 AI 驱动的 SAP GUI 自动化测试引擎，支持测试用例解析、智能执行、AI 自愈和操作录制。
+
+## 快速开始
+
+```bash
+# 安装
+pip install -e .
+
+# 启动 FastAPI 后端（配合 Vue 前端使用）
+sap-qa-backend
+
+# 或启动 MCP Server（配合 Claude Desktop / Kiro / Cursor 使用）
+sap-qa-mcp
+```
+
+## 核心功能
+
+- **测试用例解析** — 支持 Excel (.xlsx) 和 Markdown 格式
+- **SAP GUI 自动化** — 基于 COM Scripting API 驱动 SAP 操作
+- **AI 自愈** — 执行失败时自动分析并修复（基于智谱 GLM）
+- **知识库复用** — 积累脚本模板，加速后续执行
+- **操作录制** — 记录手动操作转化为可复用步骤
+
+## 两种使用方式
+
+### 1. Web 界面（FastAPI + Vue）
+
+```bash
+pip install sap-qa-agent[backend]
+sap-qa-backend
+# 访问 http://localhost:8000
+```
+
+### 2. 作为 MCP Server 被使用
+
+SAP QA Agent 可作为 MCP (Model Context Protocol) Server，被 Claude Desktop、Kiro、Cursor 等 AI Agent 直接调用。
+
+```bash
+pip install sap-qa-agent
+sap-qa-mcp
+```
+
+详细接入指南请参阅 **[docs/mcp-integration.md](docs/mcp-integration.md)**，包含：
+
+- Claude Desktop / Kiro / Cursor 三种宿主的配置示例
+- SAP Scripting 启用步骤
+- GLM API Key 配置方式
+- 端到端使用示例
+- 可用工具列表与故障排查
+
+## 项目结构
+
+```
+ui_test_python/
+├── app/                    # 应用代码
+│   ├── main.py             # FastAPI 入口
+│   ├── mcp_server/         # MCP Server 实现
+│   ├── core/               # 核心引擎（解析、执行、自愈）
+│   ├── sap/                # SAP GUI 封装
+│   ├── ai/                 # GLM AI 客户端
+│   └── data/               # 数据模型与知识库
+├── mcp_skills/             # MCP Skills 包
+├── knowledge_base/         # 脚本模板知识库
+├── tests/                  # 测试套件
+├── examples/mcp/           # MCP 配置示例
+├── docs/                   # 文档
+│   └── mcp-integration.md  # MCP 接入指南
+└── pyproject.toml          # 项目配置
+```
+
+## 环境要求
+
+- Python 3.12+
+- Windows 10/11
+- SAP GUI（已启用 Scripting）
+
+## 许可证
+
+Private

sap_qa_agent-0.1.0/app/__init__.py

@@ -0,0 +1 @@
+# backend app package

sap_qa_agent-0.1.0/app/ai/__init__.py

@@ -0,0 +1 @@
+"""AI layer modules for GLM integration."""

sap_qa_agent-0.1.0/app/ai/glm_client.py

@@ -0,0 +1,398 @@
+"""智谱 AI GLM 模型客户端 — 封装所有 AI 调用。"""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any
+
+from zhipuai import ZhipuAI
+
+from app.config import (
+    GLM_API_KEY,
+    GLM_BASE_URL,
+    GLM_EXCEPTION_TIMEOUT,
+    GLM_MODEL,
+    GLM_TIMEOUT,
+)
+from app.data.models import ElementInfo, StepActionType, StepResult, TestStep
+from app.ai.prompt_manager import PromptManager
+
+logger = logging.getLogger(__name__)
+
+
+class GlmClient:
+    """智谱 AI GLM 模型客户端。
+
+    所有公开方法均为 async（保持接口兼容），内部直接同步调用 SDK。
+    由于执行线程是独立的 worker thread，阻塞调用不会影响 FastAPI 主 loop。
+    """
+
+    def __init__(
+        self,
+        api_key: str = GLM_API_KEY,
+        base_url: str = GLM_BASE_URL,
+        model: str = GLM_MODEL,
+    ) -> None:
+        self._client = ZhipuAI(api_key=api_key, base_url=base_url)
+        self._base_url = base_url
+        self._model = model
+        self._prompt_manager = PromptManager()
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _chat_sync(self, prompt: str, timeout: int = GLM_TIMEOUT) -> str:
+        """Synchronous GLM chat call."""
+        logger.info("GLM request (model=%s, timeout=%ds):\n%s", self._model, timeout, prompt[:500])
+        response = self._client.chat.completions.create(
+            model=self._model,
+            messages=[{"role": "user", "content": prompt}],
+            timeout=timeout,
+        )
+        content = response.choices[0].message.content
+        logger.info("GLM response:\n%s", content[:500])
+        return content
+
+    @staticmethod
+    def _parse_json(text: str) -> Any:
+        """Extract and parse JSON from GLM response text."""
+        cleaned = text.strip()
+        if cleaned.startswith("```"):
+            lines = cleaned.splitlines()
+            inner_lines = []
+            started = False
+            for line in lines:
+                if not started:
+                    if line.strip().startswith("```"):
+                        started = True
+                        continue
+                elif line.strip() == "```":
+                    break
+                else:
+                    inner_lines.append(line)
+            cleaned = "\n".join(inner_lines)
+        try:
+            return json.loads(cleaned)
+        except json.JSONDecodeError as exc:
+            logger.error("Failed to parse GLM JSON response: %s\nRaw: %s", exc, text[:300])
+            raise
+
+    # ------------------------------------------------------------------
+    # Public async API (sync internally, async interface for compatibility)
+    # ------------------------------------------------------------------
+
+    async def split_steps(self, test_case_text: str, test_data: dict[str, str] | None = None) -> list[TestStep]:
+        """调用 GLM 拆分测试步骤，返回 TestStep 列表。"""
+        import json as _json
+        test_data_str = _json.dumps(test_data, ensure_ascii=False) if test_data else ""
+        prompt = self._prompt_manager.render_step_split(
+            transaction_code="",
+            steps_text=test_case_text,
+            test_data=test_data_str,
+        )
+        raw = self._chat_sync(prompt, GLM_TIMEOUT)
+        items = self._parse_json(raw)
+        steps: list[TestStep] = []
+        for item in items:
+            # GLM 可能返回不同的字段名，做容错处理
+            target = (
+                item.get("target_description")
+                or item.get("target")
+                or item.get("description")
+                or item.get("field")
+                or ""
+            )
+            action = item.get("action_type") or item.get("action") or "input"
+            value = item.get("value") or item.get("input_value")
+            # 解析表格行号和列名（结构化表格输入）
+            row = None
+            raw_row = item.get("row")
+            if raw_row is not None:
+                try:
+                    row = int(raw_row)
+                except (ValueError, TypeError):
+                    pass
+            column = item.get("column")  # str or None
+            steps.append(
+                TestStep(
+                    index=item.get("index", len(steps) + 1),
+                    action_type=StepActionType(action),
+                    target_description=target,
+                    value=value,
+                    flow_variable_ref=item.get("flow_variable_ref"),
+                    row=row,
+                    column=column,
+                )
+            )
+        logger.info("split_steps produced %d steps", len(steps))
+        return steps
+
+    async def generate_script(self, test_steps: list[TestStep], screen_elements: str = "") -> str:
+        """调用 GLM 生成 SAP GUI Scripting API 脚本。"""
+        steps_dicts = [
+            {
+                "index": s.index,
+                "action_type": s.action_type.value,
+                "target_description": s.target_description,
+                "value": s.value,
+                "flow_variable_ref": s.flow_variable_ref,
+                "row": s.row,
+                "column": s.column,
+            }
+            for s in test_steps
+        ]
+        prompt = self._prompt_manager.render_script_generate(
+            test_steps_json=json.dumps(steps_dicts, ensure_ascii=False, indent=2),
+            screen_elements=screen_elements,
+        )
+        raw = self._chat_sync(prompt, GLM_TIMEOUT)
+        script = raw.strip()
+        if script.startswith("```"):
+            lines = script.splitlines()
+            inner: list[str] = []
+            started = False
+            for line in lines:
+                if not started:
+                    if line.strip().startswith("```"):
+                        started = True
+                        continue
+                elif line.strip() == "```":
+                    break
+                else:
+                    inner.append(line)
+            script = "\n".join(inner)
+        logger.info("generate_script produced %d chars", len(script))
+        return script
+
+    async def analyze_exception(
+        self,
+        error_info: str,
+        element_tree_snapshot: str,
+    ) -> dict:
+        """调用 GLM 分析异常并生成恢复方案。"""
+        prompt = self._prompt_manager.render_exception_handle(
+            error_info=error_info,
+            current_step="",
+            ui_state=element_tree_snapshot,
+            status_bar_message="",
+            dialog_content="",
+        )
+        raw = self._chat_sync(prompt, GLM_EXCEPTION_TIMEOUT)
+        plan = self._parse_json(raw)
+        logger.info("analyze_exception decision: %s", plan.get("action"))
+        return plan
+
+    async def select_element(
+        self,
+        candidates: list[ElementInfo],
+        step_context: str,
+    ) -> int:
+        """调用 GLM 从候选元素中选择最佳匹配，返回索引。"""
+        candidates_dicts = [
+            {
+                "id_path": c.id_path,
+                "element_type": c.element_type,
+                "tooltip": c.tooltip,
+                "label_text": c.label_text,
+                "current_value": c.current_value,
+            }
+            for c in candidates
+        ]
+        prompt = self._prompt_manager.render_element_match(
+            target_description=step_context,
+            step_context=step_context,
+            window_context="",
+            candidates_json=json.dumps(candidates_dicts, ensure_ascii=False, indent=2),
+        )
+        raw = self._chat_sync(prompt, GLM_TIMEOUT)
+        result = self._parse_json(raw)
+        selected = int(result["selected_index"])
+        logger.info("select_element chose index %d: %s", selected, result.get("reason", ""))
+        return selected
+
+    async def analyze_exception_v2(
+        self,
+        error_info: str,
+        step_description: str,
+        screen_snapshot: str,
+        retry_history: list[dict],
+    ) -> dict:
+        """调用 GLM 分析异常并生成 RecoveryPlan（v2）。"""
+        history_str = "\n".join(
+            f"第{h.get('attempt', '?')}次: 错误={h.get('error', '')}, 快照={h.get('snapshot', '')}"
+            for h in retry_history
+        ) if retry_history else "无"
+
+        prompt = self._prompt_manager.render_recovery_plan(
+            step_description=step_description,
+            error_info=error_info,
+            screen_snapshot=screen_snapshot,
+            retry_history=history_str,
+        )
+        raw = self._chat_sync(prompt, GLM_EXCEPTION_TIMEOUT)
+        plan = self._parse_json(raw)
+        logger.info("analyze_exception_v2 decision: %s (confidence=%.2f)",
+                     plan.get("action"), plan.get("confidence", 0))
+        return plan
+
+    async def analyze_dialog(
+        self,
+        dialog_title: str,
+        dialog_text: str,
+        timeout: int = GLM_EXCEPTION_TIMEOUT,
+    ) -> dict:
+        """调用 GLM 分析未知 SAP 弹窗并返回处理建议。"""
+        prompt = self._prompt_manager.render_dialog_analyze(
+            dialog_title=dialog_title,
+            dialog_text=dialog_text,
+        )
+        raw = self._chat_sync(prompt, timeout)
+        suggestion = self._parse_json(raw)
+        logger.info("analyze_dialog action: %s, reason: %s",
+                     suggestion.get("action"), suggestion.get("reason", ""))
+        return suggestion
+
+    async def analyze_failure(self, step_result: StepResult) -> str:
+        """调用 GLM 生成失败根因分析。"""
+        prompt = self._prompt_manager.render_failure_analysis(
+            step_description=f"Step {step_result.step_index}",
+            error_message=step_result.error_message or "",
+            status_bar_message=step_result.status_bar_message or "",
+            screenshot_description="",
+        )
+        raw = self._chat_sync(prompt, GLM_TIMEOUT)
+        analysis = raw.strip()
+        logger.info("analyze_failure result: %s", analysis[:200])
+        return analysis
+
+    async def verify_result(
+        self,
+        expected: str,
+        window_title: str,
+        status_bar: str,
+        screen_elements: str,
+    ) -> dict:
+        """调用 GLM 判断当前屏幕状态是否满足测试预期。"""
+        prompt = self._prompt_manager.render_verify_result(
+            expected=expected,
+            window_title=window_title,
+            status_bar=status_bar,
+            screen_elements=screen_elements,
+        )
+        raw = self._chat_sync(prompt, timeout=10)
+        result = self._parse_json(raw)
+        logger.info("verify_result: pass=%s, reason=%s",
+                     result.get("pass"), result.get("reason", ""))
+        return result
+
+    async def adjust_steps(
+        self,
+        test_case_context: str,
+        window_title: str,
+        status_bar: str,
+        screen_elements: str,
+        original_steps: list[dict],
+    ) -> list[dict]:
+        """根据当前屏幕状态调整步骤列表。
+
+        Returns:
+            调整后的步骤 dict 列表。
+        """
+        original_steps_json = json.dumps(original_steps, ensure_ascii=False, indent=2)
+        prompt = self._prompt_manager.render_step_adjust(
+            test_case_context=test_case_context,
+            window_title=window_title,
+            status_bar=status_bar,
+            screen_elements=screen_elements,
+            original_steps=original_steps_json,
+        )
+        raw = self._chat_sync(prompt, GLM_TIMEOUT)
+        adjusted = self._parse_json(raw)
+        logger.info("adjust_steps: %d → %d steps", len(original_steps), len(adjusted))
+        return adjusted
+
+    async def generate_recovery_script(
+        self,
+        test_case_context: str,
+        step_index: int,
+        action_type: str,
+        target_description: str,
+        value: str,
+        error_message: str,
+        completed_steps: str,
+        window_title: str,
+        status_bar: str,
+        screen_elements: str,
+        fingerprint_info: str = "",
+    ) -> str:
+        """调用 GLM 生成修复脚本 — 步骤失败时根据当前屏幕状态生成可执行代码。"""
+        prompt = self._prompt_manager.render_recovery_script(
+            test_case_context=test_case_context,
+            step_index=step_index,
+            action_type=action_type,
+            target_description=target_description,
+            value=value,
+            error_message=error_message,
+            completed_steps=completed_steps,
+            window_title=window_title,
+            status_bar=status_bar,
+            screen_elements=screen_elements,
+            fingerprint_info=fingerprint_info,
+        )
+        raw = self._chat_sync(prompt, GLM_TIMEOUT)
+        script = raw.strip()
+        if script.startswith("```"):
+            lines = script.splitlines()
+            inner: list[str] = []
+            started = False
+            for line in lines:
+                if not started:
+                    if line.strip().startswith("```"):
+                        started = True
+                        continue
+                elif line.strip() == "```":
+                    break
+                else:
+                    inner.append(line)
+            script = "\n".join(inner)
+        logger.info("generate_recovery_script produced %d chars", len(script))
+        return script
+
+    async def generate_batch_recovery_script(
+        self,
+        test_case_context: str,
+        batch_steps: str,
+        completed_steps: str,
+        window_title: str,
+        status_bar: str,
+        screen_elements: str,
+    ) -> str:
+        """调用 GLM 生成批量修复脚本 — 多个连续输入步骤一次性处理。"""
+        prompt = self._prompt_manager.render_batch_recovery(
+            test_case_context=test_case_context,
+            batch_steps=batch_steps,
+            completed_steps=completed_steps,
+            window_title=window_title,
+            status_bar=status_bar,
+            screen_elements=screen_elements,
+        )
+        raw = self._chat_sync(prompt, GLM_TIMEOUT)
+        script = raw.strip()
+        if script.startswith("```"):
+            lines = script.splitlines()
+            inner: list[str] = []
+            started = False
+            for line in lines:
+                if not started:
+                    if line.strip().startswith("```"):
+                        started = True
+                        continue
+                elif line.strip() == "```":
+                    break
+                else:
+                    inner.append(line)
+            script = "\n".join(inner)
+        logger.info("generate_batch_recovery_script produced %d chars", len(script))
+        return script