iflow-mcp_galaxyxieyu_api-auto-test 0.1.0__py3-none-any.whl

atf/mcp/tools/unittest_tools.py

@@ -0,0 +1,189 @@
+"""
+Unittest Tools
+单元测试工具
+"""
+
+import time
+
+from mcp.server.fastmcp import FastMCP
+from pydantic import ValidationError
+
+from atf.core.log_manager import log
+from atf.mcp.models import GenerateResponse, UnitTestModel
+from atf.mcp.tools.testcase_tools import format_validation_error
+from atf.unit_case_generator import UnitCaseGenerator
+from atf.mcp.utils import (
+    build_error_payload,
+    build_unittest_yaml,
+    contains_chinese,
+    expected_py_path,
+    log_tool_call,
+    new_request_id,
+    parse_unittest_input,
+    resolve_yaml_path,
+    yaml,
+)
+
+
+def register_unittest_tools(mcp: FastMCP) -> None:
+    """注册单元测试工具"""
+
+    @mcp.tool(
+        name="write_unittest",
+        title="写入单元测试用例并生成 pytest 脚本",
+        description="根据输入的单元测试结构写入 YAML 文件，并生成对应的 pytest 单元测试脚本。\n\n"
+        "**命名规范**:\n"
+        "- `name` 字段**不能使用中文**，必须使用英文命名\n"
+        "- `description` 字段可以使用中文描述\n\n"
+        "**重要**: 必须传递 `workspace` 参数指定项目根目录，否则默认使用 api-auto-test 仓库。\n\n"
+        "**unittest 格式说明**:\n"
+        "```json\n"
+        "{\n"
+        "  \"name\": \"user_service_test\",  // 必须使用英文，不能包含中文\n"
+        "  \"description\": \"用户服务单元测试\",  // 描述可以使用中文\n"
+        "  \"target\": {\n"
+        "    \"module\": \"app.services.user_service\",\n"
+        "    \"class\": \"UserService\",  // 可选，测试类\n"
+        "    \"function\": \"get_user\"   // 可选，测试函数\n"
+        "  },\n"
+        "  \"fixtures\": {\n"
+        "    \"setup\": [{\"type\": \"patch\", \"target\": \"app.services.user_service.UserRepository\", \"return_value\": {\"id\": 1, \"name\": \"test\"}}],\n"
+        "    \"teardown\": []\n"
+        "  },\n"
+        "  \"cases\": [\n"
+        "    {\n"
+        "      \"id\": \"test_get_user_success\",  // 必须使用英文，不能包含中文\n"
+        "      \"description\": \"测试获取用户成功\",  // 描述可以使用中文\n"
+        "      \"inputs\": {\"args\": [1], \"kwargs\": {}},\n"
+        "      \"assert\": [\n"
+        "        {\"type\": \"equals\", \"field\": \"result.id\", \"expected\": 1},\n"
+        "        {\"type\": \"equals\", \"field\": \"result.name\", \"expected\": \"test\"}\n"
+        "      ]\n"
+        "    }\n"
+        "  ]\n"
+        "}\n"
+        "```\n\n"
+        "**assert.type 支持的断言类型**:\n"
+        "- `equals`: 精确匹配\n"
+        "- `not_equals`: 不匹配\n"
+        "- `contains`: 包含\n"
+        "- `raises`: 期望抛出异常，exception 字段指定异常类型\n"
+        "- `is_none`: 结果为 None\n"
+        "- `is_not_none`: 结果不为 None\n"
+        "- `called_once`: mock 被调用一次\n"
+        "- `called_with`: mock 被特定参数调用",
+    )
+    def write_unittest(
+        yaml_path: str,
+        unittest: UnitTestModel | dict | str,
+        overwrite: bool = False,
+        workspace: str | None = None,
+    ) -> GenerateResponse:
+        request_id = new_request_id()
+        start_time = time.perf_counter()
+        try:
+            unittest_model = parse_unittest_input(unittest)
+
+            # 验证 name 字段不能包含中文
+            if contains_chinese(unittest_model.name):
+                raise ValueError(
+                    f"单元测试 name 字段不能包含中文字符: '{unittest_model.name}'\n"
+                    "请使用英文命名，例如: user_service_test, calculate_total_test"
+                )
+
+            yaml_full_path, yaml_relative_path, repo_root = resolve_yaml_path(yaml_path, workspace)
+
+            # 检查路径是否存在
+            if not repo_root.exists() or not repo_root.is_dir():
+                raise ValueError(f"工作目录不存在: {repo_root}")
+
+            py_full_path, py_relative_path = expected_py_path(
+                yaml_full_path=yaml_full_path,
+                testcase_name=unittest_model.name,
+                workspace=workspace,
+            )
+
+            if yaml_full_path.exists() and not overwrite:
+                raise ValueError("YAML 文件已存在，未开启覆盖写入")
+            if py_full_path.exists() and not overwrite:
+                raise ValueError("pytest 文件已存在，未开启覆盖写入")
+
+            yaml_full_path.parent.mkdir(parents=True, exist_ok=True)
+            test_data = build_unittest_yaml(unittest_model)
+            with yaml_full_path.open("w", encoding="utf-8") as file:
+                yaml.safe_dump(test_data, file, allow_unicode=True, sort_keys=False)
+
+            if overwrite and py_full_path.exists():
+                py_full_path.unlink()
+
+            result = UnitCaseGenerator().generate_unit_tests(yaml_relative_path)
+            if not result:
+                raise ValueError("pytest 文件未生成，请检查单元测试数据格式")
+
+            response = GenerateResponse(
+                status="ok",
+                request_id=request_id,
+                written_files=[yaml_relative_path, py_relative_path],
+            )
+        except ValidationError as exc:
+            log.error(f"MCP 写入单元测试参数验证失败: {exc}")
+            error_details = {
+                "error_type": "validation_error",
+                "message": "参数格式错误，请检查以下字段：",
+                "details": format_validation_error(exc),
+                "hints": [
+                    "assert.type 应该是: equals, not_equals, contains, raises, called_once, called_with, not_called, is_none, is_not_none",
+                    "assert.field 应该为 result 或者不传",
+                    "fixtures 格式暂不支持 function 类型，当前仅支持 patch 类型"
+                ]
+            }
+            payload = build_error_payload(
+                code="MCP_VALIDATION_ERROR",
+                message=f"参数验证失败: {exc}",
+                retryable=False,
+                details=error_details,
+            )
+            response = GenerateResponse(
+                status="error",
+                request_id=request_id,
+                written_files=[],
+                **payload,
+            )
+        except ValueError as exc:
+            log.error(f"MCP 写入单元测试业务验证失败: {exc}")
+            payload = build_error_payload(
+                code="MCP_VALUE_ERROR",
+                message=str(exc),
+                retryable=False,
+                details={"error_type": "value_error", "message": str(exc)},
+            )
+            response = GenerateResponse(
+                status="error",
+                request_id=request_id,
+                written_files=[],
+                **payload,
+            )
+        except Exception as exc:
+            log.error(f"MCP 写入单元测试失败: {exc}")
+            payload = build_error_payload(
+                code="MCP_WRITE_UNITTEST_ERROR",
+                message=f"未知错误: {type(exc).__name__}: {str(exc)}",
+                retryable=False,
+                details={"error_type": "unknown_error", "exception_type": type(exc).__name__},
+            )
+            response = GenerateResponse(
+                status="error",
+                request_id=request_id,
+                written_files=[],
+                **payload,
+            )
+        latency_ms = int((time.perf_counter() - start_time) * 1000)
+        log_tool_call(
+            "write_unittest",
+            request_id,
+            response.status,
+            latency_ms,
+            response.error_code,
+            meta={"yaml_path": yaml_path, "overwrite": overwrite},
+        )
+        return response

atf/mcp/utils.py

@@ -0,0 +1,376 @@
+"""
+MCP Server Utilities
+工具函数集合
+"""
+
+import json
+import os
+import re
+from datetime import datetime
+import uuid
+from pathlib import Path
+from typing import Any, Literal
+
+import yaml as _yaml
+from pydantic import ValidationError
+
+from atf.core.log_manager import log
+from atf.case_generator import sanitize_name
+from atf.mcp.models import (
+    TestcaseModel,
+    UnitTestModel,
+)
+
+# 统一导出 yaml 模块，供其他模块使用
+yaml = _yaml
+
+# ==================== 常量定义 ====================
+REPO_ROOT = Path(os.getenv("ATF_REPO_ROOT", Path(__file__).resolve().parent.parent.parent))
+TESTS_ROOT = REPO_ROOT / "tests"
+CASES_ROOT = TESTS_ROOT / "cases"      # YAML 测试用例目录
+SCRIPTS_ROOT = TESTS_ROOT / "scripts"  # 生成的 py 脚本目录
+# 兼容旧版本
+TEST_CASES_ROOT = SCRIPTS_ROOT
+
+# pytest 执行常量
+PYTEST_TIMEOUT = int(os.getenv("PYTEST_TIMEOUT", "300"))  # 5分钟超时
+MAX_ERROR_LENGTH = int(os.getenv("MAX_ERROR_LENGTH", "500"))  # 错误信息最大长度
+MAX_HISTORY_SIZE = int(os.getenv("MAX_HISTORY_SIZE", "1000"))  # 历史记录最大条数
+MCP_LOGS_ROOT = Path(os.getenv(
+    "MCP_LOGS_ROOT",
+    str(Path(__file__).resolve().parent.parent / "logs"),
+)).expanduser()
+MCP_CALLS_LOG = Path(os.getenv("MCP_CALLS_LOG", str(MCP_LOGS_ROOT / "mcp_calls.jsonl"))).expanduser()
+MCP_LOG_CALLS_ENABLED = os.getenv("MCP_LOG_CALLS_ENABLED", "1").lower() in {"1", "true", "yes"}
+
+
+def new_request_id() -> str:
+    """生成请求标识，用于关联日志与响应"""
+    return uuid.uuid4().hex[:12]
+
+
+def build_error_payload(
+    code: str,
+    message: str,
+    retryable: bool = False,
+    details: dict | None = None,
+) -> dict[str, Any]:
+    """构建统一错误结构"""
+    return {
+        "error_code": code,
+        "retryable": retryable,
+        "error_message": message,
+        "error_details": details or {},
+    }
+
+
+def log_tool_call(
+    tool_name: str,
+    request_id: str,
+    status: str,
+    latency_ms: int,
+    error_code: str | None = None,
+    meta: dict[str, Any] | None = None,
+) -> None:
+    """记录工具调用日志（JSONL）"""
+    if not MCP_LOG_CALLS_ENABLED:
+        return
+    record = {
+        "timestamp": datetime.now().astimezone().isoformat(),
+        "tool": tool_name,
+        "request_id": request_id,
+        "status": status,
+        "latency_ms": latency_ms,
+    }
+    if error_code:
+        record["error_code"] = error_code
+    if meta:
+        record["meta"] = meta
+
+    try:
+        MCP_LOGS_ROOT.mkdir(parents=True, exist_ok=True)
+        with MCP_CALLS_LOG.open("a", encoding="utf-8") as file:
+            file.write(json.dumps(record, ensure_ascii=False) + "\n")
+    except Exception as exc:
+        log.warning(f"MCP 调用日志写入失败: {exc}")
+
+
+def get_roots(workspace: str | None = None) -> tuple[Path, Path, Path, Path]:
+    """根据 workspace 参数返回 (repo_root, tests_root, cases_root, scripts_root)
+    
+    目录结构：
+    - tests/cases/   - YAML 测试用例
+    - tests/scripts/ - 生成的 py 脚本
+    """
+    if workspace:
+        repo = Path(workspace).resolve(strict=False)
+    else:
+        repo = REPO_ROOT
+    tests = repo / "tests"
+    return repo, tests, tests / "cases", tests / "scripts"
+
+
+def resolve_yaml_path(
+    yaml_path: str, workspace: str | None = None
+) -> tuple[Path, str, Path]:
+    """返回 (yaml_full_path, yaml_relative_path, repo_root)
+    
+    YAML 文件应放在 tests/cases/ 目录下
+    """
+    repo_root, _, cases_root, _ = get_roots(workspace)
+    raw_path = Path(yaml_path)
+    if raw_path.is_absolute():
+        normalized = raw_path.resolve(strict=False)
+    else:
+        # 如果是相对路径，优先在 cases_root 下查找
+        if (cases_root / raw_path).exists():
+            normalized = (cases_root / raw_path).resolve(strict=False)
+        else:
+            normalized = (repo_root / raw_path).resolve(strict=False)
+    if not normalized.name.endswith(".yaml"):
+        raise ValueError("yaml_path 必须以 .yaml 结尾")
+    if not normalized.is_relative_to(repo_root):
+        raise ValueError(f"yaml_path 必须在项目目录 {repo_root} 下")
+    relative_path = normalized.relative_to(repo_root).as_posix()
+    return normalized, relative_path, repo_root
+
+
+def resolve_tests_root(
+    root_path: str | None = None, workspace: str | None = None
+) -> tuple[Path, Path]:
+    """返回 (resolved_cases_root, repo_root)
+
+    默认返回 tests/cases/ 目录，如果目录不存在会自动创建
+    """
+    repo_root, _, cases_root, _ = get_roots(workspace)
+    cases_root_resolved = cases_root.resolve(strict=False)
+    if not root_path:
+        # 直接创建，默认目录不存在则自动创建
+        try:
+            cases_root_resolved.mkdir(parents=True, exist_ok=True)
+        except OSError as exc:
+            raise ValueError(f"无法创建目录 {cases_root_resolved}: {exc}") from exc
+        return cases_root_resolved, repo_root
+
+    raw_path = Path(root_path)
+    if raw_path.is_absolute():
+        normalized = raw_path.resolve(strict=False)
+    else:
+        normalized = (repo_root / raw_path).resolve(strict=False)
+
+    if not normalized.is_relative_to(repo_root):
+        raise ValueError(f"root_path 必须在项目目录 {repo_root} 下")
+
+    # 直接创建，exist_ok=True 避免并发竞态
+    try:
+        normalized.mkdir(parents=True, exist_ok=True)
+    except OSError as exc:
+        raise ValueError(f"无法创建目录 {normalized}: {exc}") from exc
+
+    if not normalized.is_dir():
+        raise ValueError("root_path 必须是目录")
+    return normalized, repo_root
+
+
+def expected_py_path(
+    yaml_full_path: Path, testcase_name: str, workspace: str | None = None
+) -> tuple[Path, str]:
+    """返回 (py_full_path, py_relative_path)
+    
+    目录映射规则：
+    - tests/cases/xxx.yaml → tests/scripts/test_xxx.py
+    - tests/cases/subdir/xxx.yaml → tests/scripts/subdir/test_xxx.py
+    """
+    repo_root, _, cases_root, scripts_root = get_roots(workspace)
+
+    # 计算 YAML 相对于 cases_root 的子目录结构
+    if yaml_full_path.is_relative_to(cases_root):
+        # YAML 在 tests/cases/ 下
+        relative_to_cases = yaml_full_path.relative_to(cases_root)
+        directory_path = relative_to_cases.parent
+        if str(directory_path) == '.':
+            directory_path = Path()
+    else:
+        # 兼容旧路径：YAML 不在 cases_root 下，尝试保持相对结构
+        try:
+            tests_root = cases_root.parent
+            if yaml_full_path.is_relative_to(tests_root):
+                relative_to_tests = yaml_full_path.relative_to(tests_root)
+                directory_path = relative_to_tests.parent
+                if str(directory_path) == '.':
+                    directory_path = Path()
+            else:
+                directory_path = Path()
+        except ValueError:
+            directory_path = Path()
+
+    # 使用 sanitize_name 确保文件名与 case_generator 生成的一致
+    safe_name = sanitize_name(testcase_name)
+    py_filename = f"test_{safe_name}.py"
+    py_full_path = (scripts_root / directory_path / py_filename).resolve(strict=False)
+    py_relative_path = py_full_path.relative_to(repo_root).as_posix()
+    return py_full_path, py_relative_path
+
+
+def load_yaml_file(path: Path) -> dict[str, Any]:
+    """加载 YAML 文件"""
+    if not path.exists():
+        raise ValueError("YAML 文件不存在")
+    with path.open("r", encoding="utf-8") as file:
+        data = yaml.safe_load(file)
+    if data is None:
+        raise ValueError("YAML 文件内容为空")
+    if not isinstance(data, dict):
+        raise ValueError("YAML 顶层必须是对象")
+    return data
+
+
+def build_testcase_yaml(testcase: TestcaseModel) -> dict[str, Any]:
+    """构建测试用例 YAML 数据"""
+    payload = testcase.model_dump(by_alias=True, exclude_none=True)
+    return {"testcase": payload}
+
+
+def build_unittest_yaml(unittest: UnitTestModel) -> dict[str, Any]:
+    """构建单元测试 YAML 数据"""
+    payload = unittest.model_dump(by_alias=True, exclude_none=True)
+    return {"unittest": payload}
+
+
+def parse_testcase_input(raw_testcase: Any) -> TestcaseModel:
+    """解析测试用例输入"""
+    if isinstance(raw_testcase, TestcaseModel):
+        return raw_testcase
+
+    data = raw_testcase
+    if isinstance(raw_testcase, str):
+        stripped = raw_testcase.strip()
+        if not stripped:
+            raise ValueError("testcase 不能为空")
+        try:
+            data = json.loads(stripped)
+        except json.JSONDecodeError as json_err:
+            log.debug(f"JSON 解析失败: {json_err}, 原始字符串: {stripped[:200]}")
+            try:
+                data = yaml.safe_load(stripped)
+            except yaml.YAMLError as exc:
+                raise ValueError(f"testcase 字符串解析失败, 原始内容: {stripped[:200]}") from exc
+
+    if not isinstance(data, dict):
+        raise ValueError("testcase 必须是对象")
+
+    if "testcase" in data and isinstance(data["testcase"], dict):
+        data = data["testcase"]
+
+    return TestcaseModel.model_validate(data)
+
+
+def parse_unittest_input(raw_unittest: Any) -> UnitTestModel:
+    """解析单元测试输入"""
+    if isinstance(raw_unittest, UnitTestModel):
+        return raw_unittest
+
+    data = raw_unittest
+    if isinstance(raw_unittest, str):
+        stripped = raw_unittest.strip()
+        if not stripped:
+            raise ValueError("unittest 不能为空")
+        try:
+            data = json.loads(stripped)
+        except json.JSONDecodeError:
+            try:
+                data = yaml.safe_load(stripped)
+            except yaml.YAMLError as exc:
+                raise ValueError(f"unittest 字符串解析失败") from exc
+
+    if not isinstance(data, dict):
+        raise ValueError("unittest 必须是对象")
+
+    if "unittest" in data and isinstance(data["unittest"], dict):
+        data = data["unittest"]
+
+    return UnitTestModel.model_validate(data)
+
+
+def build_testcase_summary(testcase: TestcaseModel) -> dict[str, Any]:
+    """构建测试用例摘要"""
+    summary: dict[str, Any] = {
+        "name": testcase.name,
+        "steps": [
+            {"id": step.id, "path": step.path, "method": step.method}
+            for step in testcase.steps
+        ],
+    }
+    if testcase.description:
+        summary["description"] = testcase.description
+    if testcase.allure:
+        summary["allure"] = testcase.allure.model_dump(exclude_none=True)
+    if testcase.teardowns:
+        summary["teardowns"] = [
+            {"id": td.id, "operation_type": td.operation_type}
+            for td in testcase.teardowns
+        ]
+    return summary
+
+
+def format_validation_error(exc: ValidationError) -> list[str]:
+    """格式化 Pydantic 验证错误"""
+    return [
+        f"{'.'.join(str(l) for l in err['loc'])}: {err['msg']} (类型: {err.get('type', 'unknown')})"
+        for err in exc.errors()
+    ]
+
+
+def detect_testcase_type(data: dict) -> Literal["unittest", "testcase"]:
+    """检测测试用例类型"""
+    if "unittest" in data:
+        return "unittest"
+    elif "testcase" in data:
+        return "testcase"
+    raise ValueError("未知的测试用例格式: YAML 文件既不是 unittest 也不是 testcase 格式")
+
+
+def truncate_text(text: str, max_length: int = MAX_ERROR_LENGTH) -> str:
+    """截断文本到指定长度"""
+    if not text:
+        return ""
+    return text[-max_length:] if len(text) > max_length else text
+
+
+def contains_chinese(text: str) -> bool:
+    """检测字符串是否包含中文字符"""
+    if not text:
+        return False
+    return bool(re.search(r'[\u4e00-\u9fff]', str(text)))
+
+
+__all__ = [
+    "REPO_ROOT",
+    "TESTS_ROOT",
+    "CASES_ROOT",
+    "SCRIPTS_ROOT",
+    "TEST_CASES_ROOT",  # 兼容旧版本
+    "PYTEST_TIMEOUT",
+    "MAX_ERROR_LENGTH",
+    "MAX_HISTORY_SIZE",
+    "MCP_LOGS_ROOT",
+    "MCP_CALLS_LOG",
+    "yaml",
+    "new_request_id",
+    "build_error_payload",
+    "log_tool_call",
+    "get_roots",
+    "resolve_yaml_path",
+    "resolve_tests_root",
+    "expected_py_path",
+    "load_yaml_file",
+    "build_testcase_yaml",
+    "build_unittest_yaml",
+    "parse_testcase_input",
+    "parse_unittest_input",
+    "build_testcase_summary",
+    "format_validation_error",
+    "detect_testcase_type",
+    "truncate_text",
+    "contains_chinese",
+]