omni-engine 1.1.2.16__py2.py3-none-any.whl

omni/__init__.py

@@ -0,0 +1,57 @@
+# omni-engine — 多协议自动化测试执行引擎
+
+# ── 核心基类（直接从模块导入，避免循环加载） ──
+from omni.core.base import BaseEngine, StepResult, AIAnalysisMeta
+from omni.core.registry import EngineRegistry
+
+# ── 兼容导出（旧代码使用，保持稳定） ──
+from omni.context import GlobalContext
+from omni.common.emoji_msg import EMsg
+from omni.common.meta_class import CaseMetaClass, StepMetaClass
+from omni.common.case import TestCaseBase
+
+# ── 执行器（lazy 加载，通过 drivers/engine/__init__.py 触发注册） ──
+from omni.drivers.engine import (
+    ApiRunner, WebRunner, CmdRunner, AppRunner,
+)
+
+# ── Fluent API ──
+from omni.drivers.api.step import RunRequest, Config
+
+# ── AI 能力（可选） ──
+try:
+    from omni.core.ai.validators import AIValidator as _AIValidator  # type: ignore[assignment]
+except ImportError:
+    class _AIValidator:  # placeholder if AI not installed
+        """AIValidator"""
+        pass
+AIValidator: type = _AIValidator
+
+# ── Spec 路径 ──
+from omni.spec import SpecCompiler, StepExecutor
+from omni.spec.executor.validator import SpecValidator
+
+# ── 多模态证据 ──
+from omni.core.evidence import EvidenceCollector
+
+# ── 上下文工具 ──
+from omni.context.paths import PathManager
+
+__all__ = [
+    # 执行器
+    "ApiRunner", "WebRunner", "CmdRunner", "AppRunner",
+    # 核心
+    "BaseEngine", "StepResult", "AIAnalysisMeta", "EngineRegistry", "TestCaseBase",
+    # Fluent API
+    "RunRequest", "Config",
+    # AI
+    "AIValidator",
+    # Spec
+    "SpecCompiler", "StepExecutor", "SpecValidator",
+    # 多模态
+    "EvidenceCollector",
+    # 路径
+    "PathManager",
+    # 兼容
+    "GlobalContext", "EMsg", "CaseMetaClass", "StepMetaClass",
+]

omni/agents/__init__.py

@@ -0,0 +1,4 @@
+"""omni.agents — AI 驱动的 Web 测试生成与自愈子系统（路径 C 增强）"""
+from omni.agents.models import TestPlan, TestCase, HealReport
+
+__all__ = ["TestPlan", "TestCase", "HealReport"]

omni/agents/exploration.py

@@ -0,0 +1,79 @@
+"""探索公共能力（供 Planner / Prober 复用）
+
+从 Planner 抽取: seed 步骤加载与执行、LLM 建议探索步骤转换。
+"""
+import json
+import time
+from pathlib import Path
+from typing import Any, Dict, List, Union
+
+
+def load_seed_actions(seed: Union[str, Path, List[Dict]]) -> List[Dict]:
+    """加载 seed 步骤：内联列表 / .json 步骤列表 / .py 的 SEED_STEPS 变量"""
+    if isinstance(seed, list):
+        return seed
+    seed_path = Path(seed)
+    if not seed_path.exists():
+        raise FileNotFoundError(f"seed 文件不存在: {seed_path}")
+    if seed_path.suffix == ".json":
+        return json.loads(seed_path.read_text(encoding="utf-8"))
+    if seed_path.suffix == ".py":
+        ns: Dict[str, Any] = {}
+        exec(seed_path.read_text(encoding="utf-8"), ns)  # noqa: S102 - seed 约定式
+        steps = ns.get("SEED_STEPS")
+        if not isinstance(steps, list):
+            raise ValueError(f"seed .py 文件 {seed_path} 需定义 SEED_STEPS 步骤列表")
+        return steps
+    raise ValueError(f"不支持的 seed 文件类型: {seed_path.suffix}（支持 .json / .py / 内联列表）")
+
+
+def execute_seed_actions(engine, actions: List[Dict]) -> str:
+    """在浏览器中顺序执行 seed 步骤，返回执行摘要文本"""
+    summary_lines = []
+    for step in actions:
+        _execute_action(engine, step)
+        summary_lines.append(
+            f"- {step.get('action', '?')}: {step.get('locator', step.get('url', step.get('text', '')))}"
+        )
+    return "\n".join(summary_lines)
+
+
+def _execute_action(engine, step: Dict) -> None:
+    action = step.get("action", "")
+    if action == "navigate":
+        engine.navigate(step["url"])
+    elif action == "type":
+        locator = step["locator"]
+        el = engine.find_element(locator)
+        engine.type(el, step.get("text", ""))
+    elif action == "click":
+        locator = step["locator"]
+        el = engine.find_element(locator)
+        engine.click(el)
+    elif action == "sleep":
+        time.sleep(float(step.get("seconds", 1)))
+    else:
+        raise ValueError(f"不支持的 seed 步骤 action: {action}")
+
+
+def ask_exploration_steps(provider, request: str, prd_text: str,
+                          pages: List[Dict], max_steps: int = 5) -> List[Dict]:
+    """让 LLM 基于请求/PRD/当前快照输出建议的探索步骤（JSON 列表）"""
+    snapshot_text = json.dumps(pages, ensure_ascii=False)[:4000]
+    prompt = (
+        f"你是 Web 探索助手。用户请求: {request}\n"
+        f"PRD: {prd_text[:2000]}\n"
+        f"当前页面快照: {snapshot_text}\n\n"
+        f"请返回 JSON 数组，给出最多 {max_steps} 个后续探索步骤（如登录、点击导航、表单填写），"
+        '每步格式: {"action": "type|click|navigate", "locator": {"by": "id", "value": "..."}, '
+        '"text": "...", "url": "..."}。只返回 JSON，不要解释。'
+    )
+    raw = provider.llm_ask(prompt)
+    start, end = raw.find("["), raw.rfind("]")
+    if start == -1 or end == -1:
+        return []
+    try:
+        return json.loads(raw[start:end + 1])
+    except (json.JSONDecodeError, ValueError, TypeError):
+        # LLM 返回截断/非法 JSON → 返回 [] 不裸崩，由调用方明确报错提示改用 --seed（规格 §9.3/§10）
+        return []

omni/agents/generator.py

@@ -0,0 +1,58 @@
+"""🎭 Generator Agent — 手工用例 → PO + testcase 自动化脚本（全 AI）
+
+流程（废除模板渲染）:
+    ① Designer（TestcaseWriter）: plan → testcases/*.md（手工执行用例）
+    ② ScriptWriter: testcases → features/<page>_page.py（PO）+ testcase/<page>/test_<page>.py
+"""
+from pathlib import Path
+from typing import List
+
+from loguru import logger
+
+from omni.core.ai.provider import get_provider
+from omni.agents.script_writer import ScriptWriter
+from omni.agents.models import TestPlan
+from omni.agents import templates
+
+# 默认基类：TestCaseBase 提供框架执行规范（setup/teardown、断言、CaseMetaClass 注册）。
+# 可传业务基类（如 demo.testcase.saucedemo.base.SauceDemo）以组合页面对象。
+_DEFAULT_BASE_CLASS = "TestCaseBase"
+
+
+class Generator:
+    """Generator：将 TestPlan 渲染为 testcases（Designer）再经 ScriptWriter 生成自动化脚本"""
+
+    def __init__(self, provider=None):
+        """__init__"""
+        self.provider = provider or get_provider()
+
+    def generate(self, plan: TestPlan, output_dir: str,
+                 base_class: str = _DEFAULT_BASE_CLASS) -> List[str]:
+        """生成自动化脚本（全 AI：Designer 出用例 → ScriptWriter 出 PO+testcase）
+
+        Args:
+            base_class: 生成的测试类继承的基类（默认 TestCaseBase，可传业务基类）
+        """
+        out = Path(output_dir)
+        out.mkdir(parents=True, exist_ok=True)
+        created = []
+        # 基础文件（conftest 注入 self.driver/om_web）— 执行必需；BasePage 由 PO 从框架 base.base_page 导入，无需生成
+        base_files = [
+            ("conftest.py", templates.CONFTEST_TEMPLATE),
+        ]
+        for rel, content in base_files:
+            target = out / rel
+            target.parent.mkdir(parents=True, exist_ok=True)
+            if not target.exists():
+                target.write_text(content, encoding="utf-8")
+                created.append(str(rel))
+        # ① Designer：plan → 手工用例行数据 + case.csv（不写 md）
+        from omni.agents.testcase_writer import TestcaseWriter
+        cases = TestcaseWriter(provider=self.provider).write(plan, str(out))
+        created.append("case.csv" if (out / "case.csv").exists() else "")
+        # ② ScriptWriter：场景行数据 → PO + testcase
+        if cases:
+            sw = ScriptWriter(provider=self.provider)
+            created += sw.write(cases, str(out), base_class=base_class)
+        logger.info(f"[webai] 生成完成: {len(created)} 个文件")
+        return [c for c in created if c]

omni/agents/healer.py

@@ -0,0 +1,142 @@
+"""🎭 Healer Agent — 执行失败 → 分类 → 修复 → 重跑"""
+import subprocess
+import sys
+from pathlib import Path
+from typing import List, Optional
+
+from loguru import logger
+
+from omni.core.ai.provider import get_provider
+from omni.agents.models import HealReport
+
+_PROMPT = Path(__file__).resolve().parent / "prompts" / "healer.md"
+
+
+class Healer:
+    """Healer：执行测试、收集失败信号、AI 分类修复、重跑验证"""
+
+    def __init__(self, provider=None, max_attempts: int = 3):
+        """__init__"""
+        self.provider = provider or get_provider()
+        assert self.provider is not None, "AI Provider 不可用"
+        self.max_attempts = max_attempts
+
+    # ── 生成产物校验 + AI 自修复（对齐官方 healer guardrails） ──
+
+    def validate_generated(self, code: str, kind: str) -> bool:
+        """校验 AI 生成产物：po 继承 BasePage；testcase 方法 test_ 且含 self.om_web"""
+        from omni.agents.script_writer import _validate_po, _validate_testcase
+        if kind == "po":
+            return _validate_po(code)
+        if kind == "testcase":
+            return _validate_testcase(code)
+        return False
+
+    def self_heal(self, code: str, kind: str, error: str = "") -> Optional[str]:
+        """AI 自修复：校验不合格时让 LLM 修正，重试 ≤3 次"""
+        provider = self.provider
+        if provider is None:
+            return None
+        for attempt in range(1, self.max_attempts + 1):
+            if self.validate_generated(code, kind):
+                return code
+            try:
+                code = provider.llm_ask(
+                    f"修复以下 {kind} 代码，使其通过校验"
+                    f"（PO 继承 BasePage；testcase 方法 test_ 且含 self.om_web 调用）。\n"
+                    f"错误: {error}\n代码:\n{code}\n只返回修正后的代码。"
+                )
+            except Exception as e:
+                logger.warning(f"[webai] healer 自修复 LLM 失败（{e}）")
+                return None
+        return code if self.validate_generated(code, kind) else None
+
+    def heal(self, test_path: str, cwd: str = "") -> HealReport:
+        """执行单个测试文件并尝试修复
+
+        首版：测试通过 → status=healed；测试失败 → 交由 LLM 分类给出修复建议，
+        无法自动落地修复时标记 skipped（不静默通过）。
+        """
+        test_file = Path(test_path)
+        name = test_file.name
+        logger.info(f"[webai] heal 开始执行: {name}")
+        run = self._run_pytest(test_file, cwd)
+        if run.returncode == 0:
+            logger.info(f"[webai] heal: {name} 测试通过（无需修复）")
+            return HealReport(test_name=name, category="none", original="",
+                              fixed="", attempts=1, status="healed")
+
+        # 失败：收集信号
+        failure_text = run.stdout[-2000:] + run.stderr[-2000:]
+        logger.warning(f"[webai] heal: {name} 测试失败（rc={run.returncode}），收集失败信号")
+        provider = self.provider
+        if provider is None:
+            return HealReport(test_name=name, category="unknown", original="",
+                              fixed="", attempts=1, status="skipped")
+        try:
+            system = _PROMPT.read_text(encoding="utf-8")
+            raw = provider.llm_ask(
+                f"{system}\n\n测试 {name} 失败，输出：\n{failure_text}\n\n"
+                "请回复 JSON: {\"category\": \"locator|timing|assertion|bug\", "
+                "\"suggestion\": \"...\"}"
+            )
+            category = self._classify(raw)
+            suggestion = self._extract_suggestion(raw)
+            logger.info(f"[webai] heal: {name} 分类={category} 建议={suggestion[:80]}")
+        except Exception as err:  # noqa: BLE001 — LLM/提示词异常不可使 heal() 崩溃
+            logger.warning(f"[webai] heal: {name} LLM 不可用（{err}），标记 skipped")
+            return HealReport(
+                test_name=name, category="unknown",
+                original=failure_text[:500], fixed=f"LLM unavailable: {err}",
+                attempts=1, status="skipped",
+            )
+        status = "skipped" if category != "bug" else "failed"
+        logger.info(f"[webai] heal: {name} 完成（status={status}）")
+        return HealReport(
+            test_name=name, category=category,
+            original=failure_text[:500], fixed=suggestion,
+            attempts=1, status=status,
+        )
+
+    def heal_all(self, tests_dir: str, cwd: str = "") -> List[HealReport]:
+        """修复目录下所有失败测试"""
+        reports = []
+        for test_file in sorted(Path(tests_dir).glob("test_*.py")):
+            if test_file.name.startswith("test_") and test_file.name != "conftest.py":
+                reports.append(self.heal(str(test_file), cwd=cwd))
+        return reports
+
+    def _run_pytest(self, test_file: Path, cwd: str) -> subprocess.CompletedProcess:
+        python = sys.executable
+        # 绝对路径作为 pytest 目标：cwd 已设为 test_file.parent，
+        # 若再传相对路径会拼接成 cwd/相对路径 重复（Test file not found）
+        target = str(test_file.resolve())
+        try:
+            return subprocess.run(
+                [python, "-m", "pytest", target, "-q", "--no-header", "-x"],
+                capture_output=True, text=True, cwd=cwd or str(test_file.parent),
+                timeout=120,
+            )
+        except subprocess.TimeoutExpired as err:
+            # 超时视为失败（非零返回码），流向 LLM 分支
+            out = err.stdout or ""
+            if isinstance(out, bytes):
+                out = out.decode("utf-8", errors="replace")
+            err_out = err.stderr or ""
+            if isinstance(err_out, bytes):
+                err_out = err_out.decode("utf-8", errors="replace")
+            out += "\n[pytest timed out after 120s]"
+            return subprocess.CompletedProcess(
+                args=[python, "-m", "pytest", target],
+                returncode=-9, stdout=out, stderr=err_out,
+            )
+
+    def _classify(self, raw: str) -> str:
+        import json, re
+        m = re.search(r'"category"\s*:\s*"(\w+)"', raw)
+        return m.group(1) if m else "unknown"
+
+    def _extract_suggestion(self, raw: str) -> str:
+        import json, re
+        m = re.search(r'"suggestion"\s*:\s*"([^"]*)"', raw)
+        return m.group(1) if m else raw[:200]

omni/agents/mcp_bridge.py

@@ -0,0 +1,37 @@
+"""双通道桥接 — 将 agent 能力经 @playwright/mcp 暴露给外部 agent（VS Code/Claude 等）
+
+外部接入方式：
+    python -m omni.agents.mcp_bridge start        # 启动 playwright MCP 服务
+    python -m omni.agents.mcp_bridge config       # 打印 .mcp.json 配置
+"""
+import subprocess
+import sys
+from typing import Dict
+
+
+def build_mcp_config() -> Dict:
+    """返回 .mcp.json 兼容的 playwright MCP 配置"""
+    return {
+        "mcpServers": {
+            "playwright": {
+                "command": "npx",
+                "args": ["-y", "@playwright/mcp@latest"],
+            }
+        }
+    }
+
+
+def start_mcp_server(port: int = 8931) -> subprocess.Popen:
+    """启动 playwright MCP 服务子进程（独立进程，不影响内闭环）"""
+    return subprocess.Popen(
+        ["npx", "-y", "@playwright/mcp@latest", f"--port={port}"],
+        stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
+    )
+
+
+if __name__ == "__main__":
+    if len(sys.argv) > 1 and sys.argv[1] == "start":
+        start_mcp_server()
+    else:
+        import json
+        print(json.dumps(build_mcp_config(), indent=2))

omni/agents/models.py

@@ -0,0 +1,109 @@
+"""agent 数据模型 — 测试计划 / 用例 / 修复报告"""
+import re
+from dataclasses import dataclass, field
+from typing import Dict, List
+
+
+@dataclass
+class TestCase:
+    """单个测试场景（steps[i] 与 expected[i] 一一对应）"""
+    id: int
+    title: str
+    steps: List[str] = field(default_factory=list)
+    expected: List[str] = field(default_factory=list)
+    data: Dict = field(default_factory=dict)
+
+
+@dataclass
+class TestPlan:
+    """Markdown 测试计划"""
+    name: str
+    scenarios: List[TestCase] = field(default_factory=list)
+
+    def to_markdown(self) -> str:
+        """to_markdown"""
+        lines = [f"# {self.name}", ""]
+        for sc in self.scenarios:
+            lines.append(f"## Scenario {sc.id}: {sc.title}")
+            lines.append("")
+            # 步骤与期望一一对应：表格形式（每行 步骤 | 期望结果）
+            if sc.steps:
+                lines.append("| 步骤 | 期望结果 |")
+                lines.append("|------|----------|")
+                for i, step in enumerate(sc.steps, 1):
+                    exp = sc.expected[i - 1] if i - 1 < len(sc.expected) else ""
+                    lines.append(f"| {i}. {step} | {exp} |")
+                lines.append("")
+        return "\n".join(lines)
+
+    @classmethod
+    def from_markdown(cls, text: str) -> "TestPlan":
+        """from_markdown"""
+        lines = text.splitlines()
+        name = ""
+        for ln in lines:
+            if ln.startswith("# ") and not ln.startswith("## "):
+                name = ln[2:].strip()
+                break
+        scenarios = []
+        current = None
+        in_table = False
+        in_expected_block = False
+        for ln in lines:
+            stripped = ln.strip()
+            # 标准格式：## Scenario 1: 标题（提示词要求的唯一格式）
+            m = re.match(r"^## Scenario (\d+): (.+)$", stripped)
+            # 防御兼容：### 1. 标题（三级标题，旧提示词/LLM 可能输出）
+            m3 = re.match(r"^### (\d+)\.\s+(.+)$", stripped) if not m else None
+            matched = m or m3
+            if matched is not None:
+                current = TestCase(id=int(matched.group(1)),
+                                   title=matched.group(2).strip())
+                scenarios.append(current)
+                in_table = False
+                in_expected_block = False
+                continue
+            if current is None:
+                continue
+            # 表格行：| 1. 步骤 | 期望结果 |
+            if stripped.startswith("|") and stripped.endswith("|") and not stripped.startswith("|---"):
+                cols = [c.strip() for c in stripped.strip("|").split("|")]
+                if len(cols) >= 2 and not cols[0].startswith("步骤"):
+                    step_text = re.sub(r"^\d+\.\s*", "", cols[0]).strip()
+                    current.steps.append(step_text)
+                    current.expected.append(cols[1].strip())
+                    in_table = True
+                    in_expected_block = False
+                    continue
+            # 兼容旧格式：**Expected:** 区块
+            if stripped == "**Expected:**":
+                in_expected_block = True
+                continue
+            step_m = re.match(r"^(\d+)\.\s+(.+)$", stripped)
+            if step_m and not in_table and not in_expected_block:
+                current.steps.append(step_m.group(2).strip())
+            elif stripped.startswith("- ") and in_expected_block:
+                current.expected.append(stripped[2:].strip())
+        return cls(name=name, scenarios=scenarios)
+
+
+@dataclass
+class HealReport:
+    """healer 修复报告（可审计）"""
+    test_name: str
+    category: str          # locator / timing / assertion / bug
+    original: str
+    fixed: str
+    attempts: int
+    status: str            # healed / skipped / failed
+
+    def to_markdown(self) -> str:
+        """to_markdown"""
+        return (
+            f"## {self.test_name}\n\n"
+            f"- category: {self.category}\n"
+            f"- attempts: {self.attempts}\n"
+            f"- status: {self.status}\n"
+            f"- original: `{self.original}`\n"
+            f"- fixed: `{self.fixed}`\n"
+        )

omni/agents/orchestrator.py

@@ -0,0 +1,83 @@
+"""AgentOrchestrator — 三 agent 编排（single / sequential / loop）"""
+import subprocess
+import sys
+from pathlib import Path
+from typing import Dict, List
+
+from loguru import logger
+
+from omni.agents.planner import Planner
+from omni.agents.generator import Generator
+from omni.agents.healer import Healer
+from omni.core.ai.provider import get_provider
+
+
+class AgentOrchestrator:
+    """编排 Planner → Generator → (pytest) → Healer"""
+
+    def __init__(self, planner=None, generator=None, healer=None, provider=None):
+        """__init__"""
+        self.provider = provider or get_provider()
+        self.planner = planner or Planner(engine=None, provider=self.provider)
+        self.generator = generator or Generator(provider=self.provider)
+        self.healer = healer or Healer(provider=self.provider)
+
+    def run_sequential(self, url: str, plan_path: str, tests_dir: str,
+                       request: str = "", seed=None, prd: str = "") -> Dict:
+        """planner → generator → pytest → healer 顺序执行
+
+        Args:
+            url: 被测应用 URL
+            plan_path: 测试计划保存路径（Markdown）
+            tests_dir: 生成测试输出目录
+            request: 明确请求（如"为访客结账生成一个计划"），透传给 planner
+            seed: 种子测试（内联步骤列表 / .json / .py 文件），预置环境
+            prd: 产品需求文档（文本或文件路径），作为 LLM 上下文
+        """
+        # P6：探索引擎生命周期经 ResourceManager 托管（退出统一释放，防浏览器泄漏）
+        from omni.context.resource_manager import ResourceManager
+
+        with ResourceManager() as rm:
+            # 1. Planner 产出计划：engine 非空且计划不存在时先探索（含 seed/request/PRD）再保存；
+            #    engine 为 None 时保持原行为——不探索，直接走 save_plan/LLM 兜底
+            plan_file = Path(plan_path)
+            if not plan_file.exists():
+                if self.planner.engine is not None:
+                    if seed:
+                        self.planner.run_seed(seed)
+                    self.planner.explore(url, request=request, prd=prd)
+                self.planner.save_plan(plan_path)
+            logger.info(f"计划: {plan_path}")
+
+            # 2. Generator 生成测试
+            from omni.agents.models import TestPlan
+            plan = TestPlan.from_markdown(plan_file.read_text(encoding="utf-8"))
+            created = self.generator.generate(plan, tests_dir)
+            logger.info(f"生成测试: {created}")
+
+            # 禁止静默成功：计划无场景或零生成文件必须报错
+            if not plan.scenarios or not created:
+                logger.error(
+                    f"计划未产出可执行场景: scenarios={len(plan.scenarios)}, "
+                    f"created={len(created)}"
+                )
+                raise ValueError(
+                    "计划未产出任何可执行测试场景"
+                    f"（scenarios={len(plan.scenarios)}, created={len(created)}）"
+                )
+
+            # 3. 执行 pytest
+            python = sys.executable
+            run = subprocess.run(
+                [python, "-m", "pytest", tests_dir, "-q", "--no-header"],
+                capture_output=True, text=True,
+            )
+            logger.info(f"pytest exit={run.returncode}")
+
+            # 4. 失败 → Healer
+            heal_reports = []
+            if run.returncode != 0:
+                heal_reports = self.healer.heal_all(tests_dir)
+                logger.info(f"healer 报告: {len(heal_reports)} 条")
+
+            return {"plan": plan_path, "tests": created, "heal_reports": heal_reports}