api-test-toolkit 0.2.0__py3-none-any.whl

api_test_kit/e2e/scenario.py

@@ -0,0 +1,113 @@
+"""Scenario — 编排一组 E2E 步骤。"""
+from __future__ import annotations
+
+import logging
+import time as time_module
+from dataclasses import dataclass, field
+from typing import Literal
+
+from api_test_kit.e2e.context import ScenarioContext
+from api_test_kit.e2e.step import Step, StepResult
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class ScenarioReport:
+    """Report after running a full ``Scenario``."""
+    name: str
+    step_results: list[StepResult] = field(default_factory=list)
+    total: int = 0
+    passed: int = 0
+    failed: int = 0
+    elapsed: float = 0.0
+
+    @property
+    def success(self) -> bool:
+        """True if every step passed."""
+        return self.failed == 0
+
+    def summary(self) -> str:
+        """Multi-line human-readable summary."""
+        status = "✅ PASS" if self.success else "❌ FAIL"
+        lines = [
+            f"[E2E] Scenario: {self.name}",
+            f"  Status: {status}",
+            f"  Steps: {self.passed}/{self.total} passed ({self.elapsed:.2f}s)",
+        ]
+        for r in self.step_results:
+            mark = "✅" if r.passed else "❌"
+            lines.append(f"  {mark} {r.step_name} ({r.status}, {r.elapsed:.3f}s)")
+            if not r.passed and r.error:
+                lines.append(f"     ↳ {r.error}")
+        return "\n".join(lines)
+
+    def assert_all_passed(self) -> None:
+        """Raise ``AssertionError`` listing all failures, if any."""
+        if self.failed > 0:
+            detail = "\n".join(
+                f"  ❌ {r.step_name}: {r.error}"
+                for r in self.step_results
+                if not r.passed
+            )
+            raise AssertionError(
+                f"Scenario '{self.name}' failed: {self.failed}/{self.total} steps failed.\n"
+                f"{detail}"
+            )
+
+
+class Scenario:
+    """A business chain composed of sequential ``Step`` objects.
+
+    Usage::
+
+        scenario = Scenario(
+            "下单流程",
+            steps=[
+                Step(name="登录", execute=...),
+                Step(name="创建订单", execute=...),
+                Step(name="验证订单状态", execute=...),
+            ],
+        )
+        report = scenario.run()
+        report.assert_all_passed()
+    """
+
+    def __init__(
+        self,
+        name: str,
+        steps: list[Step],
+        fail_fast: bool = True,
+    ) -> None:
+        self.name = name
+        self.steps = steps
+        self.fail_fast = fail_fast
+
+    def run(self, ctx: ScenarioContext | None = None) -> ScenarioReport:
+        """Execute all steps in order.
+
+        If ``fail_fast=True`` (default), stops at the first failed step.
+        Returns a ``ScenarioReport`` with per-step results.
+        """
+        context = ctx or ScenarioContext()
+        report = ScenarioReport(name=self.name, total=len(self.steps))
+        start = time_module.perf_counter()
+
+        for step in self.steps:
+            result = step.run(context)
+            report.step_results.append(result)
+            if result.passed:
+                report.passed += 1
+            else:
+                report.failed += 1
+                if self.fail_fast:
+                    logger.info(
+                        "[E2E] Scenario '%s' stopped at failed step '%s'",
+                        self.name,
+                        step.name,
+                    )
+                    break
+
+        report.elapsed = time_module.perf_counter() - start
+        logger.info("\n" + report.summary())
+        return report

api_test_kit/e2e/step.py

@@ -0,0 +1,99 @@
+"""Step — 业务链路场景中的可组合单元。"""
+from __future__ import annotations
+
+import logging
+import time
+from dataclasses import dataclass, field
+from typing import Any, Callable
+
+from api_test_kit.client import ApiResponse
+from api_test_kit.e2e.context import ScenarioContext
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class StepResult:
+    """Result of executing a single Step."""
+    step_name: str
+    passed: bool
+    status: int
+    elapsed: float
+    data: Any = None
+    error: str | None = None
+
+
+class Step:
+    """One step in an E2E scenario.
+
+    Usage::
+
+        Step(
+            name="创建订单",
+            execute=lambda ctx: OrdersEndpoint(client).create(
+                product_id=ctx.get("product_id"), quantity=2
+            ),
+            extract={"order_id": "$.data.id"},
+            verify=lambda resp: assert_status(resp, 201),
+        )
+    """
+
+    def __init__(
+        self,
+        name: str,
+        execute: Callable[[ScenarioContext], ApiResponse],
+        extract: dict[str, str] | None = None,
+        verify: Callable[[ApiResponse], None] | None = None,
+    ) -> None:
+        self.name = name
+        self.execute = execute
+        self.extract = extract or {}
+        self.verify = verify
+
+    def run(self, ctx: ScenarioContext) -> StepResult:
+        """Execute this step, run verification, extract data.
+
+        Returns a ``StepResult`` — does NOT raise on assertion failure.
+        """
+        start = time.perf_counter()
+        try:
+            logger.info("[E2E] Step: %s", self.name)
+            resp = self.execute(ctx)
+            elapsed = time.perf_counter() - start
+
+            # Run verification (if provided)
+            if self.verify:
+                self.verify(resp)
+
+            # Extract data for subsequent steps
+            ctx.extract_from(resp, self.extract)
+
+            logger.info("[E2E] Step '%s' → %d (%.3fs)", self.name, resp.status, elapsed)
+            return StepResult(
+                step_name=self.name,
+                passed=True,
+                status=resp.status,
+                elapsed=elapsed,
+                data=resp.data,
+            )
+
+        except AssertionError as e:
+            elapsed = time.perf_counter() - start
+            logger.warning("[E2E] Step '%s' FAILED: %s", self.name, e)
+            return StepResult(
+                step_name=self.name,
+                passed=False,
+                status=resp.status if "resp" in dir() else 0,
+                elapsed=elapsed,
+                error=str(e),
+            )
+        except Exception as e:
+            elapsed = time.perf_counter() - start
+            logger.error("[E2E] Step '%s' ERROR: %s", self.name, e)
+            return StepResult(
+                step_name=self.name,
+                passed=False,
+                status=0,
+                elapsed=elapsed,
+                error=f"{type(e).__name__}: {e}",
+            )

api_test_kit/endpoints/__init__.py

@@ -0,0 +1,44 @@
+"""基础端点类 — API 资源的 CRUD 模板。
+
+每个 API 资源对应一个子类。"""
+from __future__ import annotations
+
+from typing import Any
+
+from api_test_kit.client import BaseClient, ApiResponse
+
+
+class BaseEndpoint:
+    """Extend this class for each API resource.
+
+    Usage::
+
+        class UserEndpoint(BaseEndpoint):
+            path = "/users"
+
+            def activate(self, user_id: int) -> ApiResponse:
+                return self.client.post(f"{self.path}/{user_id}/activate")
+
+    If your API does not follow standard CRUD, override
+    ``list``, ``get``, ``create``, ``update``, ``delete`` as needed.
+    """
+
+    path: str = ""
+
+    def __init__(self, client: BaseClient) -> None:
+        self.client = client
+
+    def list(self, **params: Any) -> ApiResponse:
+        return self.client.get(self.path, params=params)
+
+    def get(self, id_: str | int, **params: Any) -> ApiResponse:
+        return self.client.get(f"{self.path}/{id_}", params=params)
+
+    def create(self, **payload: Any) -> ApiResponse:
+        return self.client.post(self.path, json=payload)
+
+    def update(self, id_: str | int, **payload: Any) -> ApiResponse:
+        return self.client.put(f"{self.path}/{id_}", json=payload)
+
+    def delete(self, id_: str | int) -> ApiResponse:
+        return self.client.delete(f"{self.path}/{id_}")

api_test_kit/endpoints/_base.py

@@ -0,0 +1,44 @@
+"""基础端点类 —— API 资源的 CRUD 模板。
+
+每个 API 资源对应一个子类。"""
+from __future__ import annotations
+
+from typing import Any
+
+from api_test_kit.client import BaseClient, ApiResponse
+
+
+class BaseEndpoint:
+    """为每个 API 资源扩展此类。
+
+    使用方法::
+
+        class UserEndpoint(BaseEndpoint):
+            path = "/users"
+
+            def activate(self, user_id: int) -> ApiResponse:
+                return self.client.post(f"{self.path}/{user_id}/activate")
+
+    如果你的 API 不遵循标准 CRUD，按需覆盖
+    ``list``、``get``、``create``、``update``、``delete`` 方法。
+    """
+
+    path: str = ""
+
+    def __init__(self, client: BaseClient) -> None:
+        self.client = client
+
+    def list(self, **params: Any) -> ApiResponse:
+        return self.client.get(self.path, params=params)
+
+    def get(self, id_: str | int, **params: Any) -> ApiResponse:
+        return self.client.get(f"{self.path}/{id_}", params=params)
+
+    def create(self, **payload: Any) -> ApiResponse:
+        return self.client.post(self.path, json=payload)
+
+    def update(self, id_: str | int, **payload: Any) -> ApiResponse:
+        return self.client.put(f"{self.path}/{id_}", json=payload)
+
+    def delete(self, id_: str | int) -> ApiResponse:
+        return self.client.delete(f"{self.path}/{id_}")

api_test_kit/logger.py

@@ -0,0 +1,25 @@
+"""测试框架的日志设置。"""
+from __future__ import annotations
+
+import logging
+import sys
+
+
+def setup_logging(level: str = "INFO") -> None:
+    """配置测试框架的根日志。
+
+    在测试会话开始时调用一次（通常在 ``conftest.py`` 中）。
+    """
+    logger = logging.getLogger("api_test_kit")
+    logger.setLevel(getattr(logging, level.upper(), logging.INFO))
+
+    if not logger.handlers:
+        handler = logging.StreamHandler(sys.stdout)
+        handler.setLevel(logging.DEBUG)
+        fmt = logging.Formatter(
+            "%(asctime)s | %(levelname)-8s | %(name)s | %(message)s",
+            datefmt="%H:%M:%S",
+        )
+        handler.setFormatter(fmt)
+        logger.addHandler(handler)
+        logger.propagate = False

api_test_kit/scaffold.py

@@ -0,0 +1,186 @@
+"""项目脚手架 — 生成新项目的目录结构和文件。"""
+from __future__ import annotations
+
+import os
+import shutil
+from pathlib import Path
+from typing import Any
+
+import typer
+
+from api_test_kit import __version__
+
+# ── 交互式问题 ──────────────────────────────────────────────
+
+QUESTIONS: list[dict[str, Any]] = [
+    {
+        "key": "base_url",
+        "prompt": "API 基础地址",
+        "default": "http://localhost:8000",
+    },
+    {
+        "key": "api_prefix",
+        "prompt": "API 前缀",
+        "default": "/api/v1",
+    },
+    {
+        "key": "auth_type",
+        "prompt": "鉴权方式",
+        "default": "bearer",
+        "choices": ["bearer", "api_key", "none"],
+    },
+    {
+        "key": "env_name",
+        "prompt": "环境名",
+        "default": "staging",
+    },
+]
+
+# ── 模板文件清单 ────────────────────────────────────────────
+
+TEMPLATE_FILES: list[str] = [
+    "pyproject.toml",
+    "README.md",
+    "AGENTS.md",
+    "pytest.ini",
+    "tests/__init__.py",
+    "tests/conftest.py",
+    "scripts/new-endpoint.sh",
+]
+
+EMPTY_DIRS: list[str] = [
+    "tests/endpoints",
+    "reports",
+]
+
+# ── 变量替换 ────────────────────────────────────────────────
+
+def _resolve_template_dir() -> Path:
+    """返回模板文件目录（与 scaffold.py 同级的 templates/）。"""
+    return Path(__file__).resolve().parent / "templates"
+
+
+def _ask_questions(interactive: bool) -> dict[str, Any]:
+    """收集用户配置（交互式或默认值）。"""
+    config: dict[str, Any] = {}
+    for q in QUESTIONS:
+        if interactive:
+            if "choices" in q:
+                val = typer.prompt(
+                    q["prompt"],
+                    default=q["default"],
+                )
+                # 验证选择
+                if val not in q["choices"]:
+                    typer.echo(f"  有效选项: {', '.join(q['choices'])}")
+                    val = q["default"]
+            else:
+                val = typer.prompt(q["prompt"], default=q["default"])
+            config[q["key"]] = val
+        else:
+            config[q["key"]] = q["default"]
+    return config
+
+
+def _render_template(src: Path, dst: Path, vars: dict[str, str]) -> None:
+    """读取模板文件，替换变量，写入目标路径。"""
+    content = src.read_text(encoding="utf-8")
+    for key, val in vars.items():
+        content = content.replace("{{ " + key + " }}", str(val))
+    dst.write_text(content, encoding="utf-8")
+
+
+# ── 主入口 ──────────────────────────────────────────────────
+
+def create_project(
+    project_dir: str,
+    base_url: str | None = None,
+    api_prefix: str | None = None,
+    auth_type: str | None = None,
+    env_name: str | None = None,
+    interactive: bool = True,
+) -> None:
+    """创建新 API 自动化测试项目。
+
+    Args:
+        project_dir: 目标目录名（相对 CWD 或绝对路径）。
+        base_url: API 基础地址。
+        api_prefix: API 前缀。
+        auth_type: 鉴权方式（bearer / api_key / none）。
+        env_name: 环境名。
+        interactive: 是否交互式提问。
+    """
+    target = Path.cwd() / project_dir
+
+    # 检查目标目录
+    if target.exists():
+        typer.confirm(f"目录 {target} 已存在，覆盖？", abort=True)
+        shutil.rmtree(target)
+
+    # 收集配置
+    config = _ask_questions(interactive)
+    if base_url is not None:
+        config["base_url"] = base_url
+    if api_prefix is not None:
+        config["api_prefix"] = api_prefix
+    if auth_type is not None:
+        config["auth_type"] = auth_type
+    if env_name is not None:
+        config["env_name"] = env_name
+
+    # 派生变量
+    package_name = project_dir.replace("-", "_").replace(" ", "_").lower()
+    config["project_name"] = project_dir
+    config["package_name"] = package_name
+    config["api_test_kit_version"] = __version__
+
+    # 创建目录
+    template_dir = _resolve_template_dir()
+
+    # 复制模板文件
+    for rel in TEMPLATE_FILES:
+        src = template_dir / rel
+        dst = target / rel
+        dst.parent.mkdir(parents=True, exist_ok=True)
+        _render_template(src, dst, config)
+        # 如果是 shell 脚本，保留可执行权限
+        if src.suffix == ".sh":
+            dst.chmod(dst.stat().st_mode | 0o111)
+
+    # 创建空目录
+    for rel in EMPTY_DIRS:
+        (target / rel).mkdir(parents=True, exist_ok=True)
+
+    # 写入 .gitignore
+    (target / ".gitignore").write_text(
+        "__pycache__/\n*.py[cod]\n*.egg-info/\ndist/\nbuild/\n.env\n"
+        "config.*.env\n.pytest_cache/\nreports/\n.mypy_cache/\n.idea/\n.vscode/\n"
+    )
+
+    # 写入环境配置
+    env_content = (
+        f"# {project_dir} — {config['env_name']} 环境\n"
+        f"ENV_NAME={config['env_name']}\n"
+        f"BASE_URL={config['base_url']}\n"
+        f"API_PREFIX={config['api_prefix']}\n"
+        f"AUTH_HEADER_NAME=authorization\n"
+        f"LANG=zh-CN\n"
+    )
+    env_file = target / f"config.{config['env_name']}.env"
+    env_file.write_text(env_content)
+
+    # 写入空的 tests/endpoints/__init__.py
+    init_file = target / "tests/endpoints/__init__.py"
+    init_file.write_text("")
+
+    # 完成提示
+    typer.echo(f"""
+✅ 项目已创建: {target}/
+──────────────────────────────
+  cd {project_dir}
+  pip install -e ".[dev]"
+  pytest -v
+
+  然后告诉 AI 你的接口信息，开始写测试。
+──────────────────────────────
+""")

api_test_kit/templates/AGENTS.md

@@ -0,0 +1,45 @@
+# {{ project_name }} — AI 开发者指南
+
+> 这个文件告诉 AI 助手本项目的确切约定。每次生成代码前先读这个文件。
+
+## 首次使用
+
+你可以用自然语言告诉我接口信息，我来生成测试。
+
+## AI 能做什么
+
+| 能力 | 说明 |
+|------|------|
+| **新增单接口测试** | 给我 curl 或接口文档，生成 endpoint 模型 + 测试脚本 |
+| **新增 E2E 业务链路测试** | 你用自然语言描述业务流程，AI 生成多步骤场景 |
+| **测试设计 review** | AI 先出测试用例表格，你确认后再写代码 |
+
+## 你需要提供什么
+
+**单接口：** curl 命令（最推荐）/ OpenAPI / Postman / 文档链接 / URL+参数 / HAR 文件
+
+**E2E 链路：** 自然语言描述，包含 4 个信息：
+1. 链路做什么（如"先查销售状态，再拿第一个状态去筛库存"）
+2. 每一步调什么接口
+3. 步骤间数据怎么传
+4. 验证什么
+
+## 文件结构
+
+```
+tests/
+  conftest.py      # 全局 fixtures（client, env_config, e2e_context）
+  endpoints/       # AI 生成的测试放这里
+  e2e/             # AI 生成的 E2E 测试放这里
+config.*.env       # 环境配置（按需编辑）
+```
+
+## 工作流程
+
+```
+① 你提供 curl 或描述业务场景
+② AI 试调接口 → 设计测试用例 → 展示给你 review
+③ 你确认 / 补充业务场景
+④ AI 写代码
+⑤ pytest -v 跑通
+```

api_test_kit/templates/README.md

@@ -0,0 +1,31 @@
+# {{ project_name }}
+
+API 自动化测试项目。基于 `api-test-toolkit` 框架。
+
+## 快速开始
+
+```bash
+pip install -e ".[dev]"
+pytest -v
+```
+
+## 添加新 API 测试
+
+提供 curl 或接口文档给 AI，AI 会按以下流程工作：
+
+```
+① 你提供 curl / 描述业务场景
+② AI 试调接口 → 设计测试用例 → 展示给你 review
+③ 你确认 / 补充业务场景
+④ AI 写 endpoint 模型 + 测试
+⑤ pytest -v 跑通
+```
+
+## 常用命令
+
+| 命令 | 说明 |
+|------|------|
+| `pip install -e ".[dev]"` | 安装依赖 |
+| `pytest -v` | 运行测试 |
+| `pytest -m smoke` | 只跑冒烟测试 |
+| `pytest -m e2e` | 只跑 E2E 链路测试 |

api_test_kit/templates/pyproject.toml

@@ -0,0 +1,21 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta:__legacy__"
+
+[project]
+name = "{{ project_name }}"
+version = "0.1.0"
+description = "API 自动化测试项目"
+requires-python = ">=3.11"
+dependencies = [
+    "api-test-toolkit>={{ api_test_kit_version }}",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-xdist>=3.5",
+    "pytest-html>=4.1",
+    "responses>=0.25",
+    "ruff>=0.3",
+]

api_test_kit/templates/pytest.ini

@@ -0,0 +1,11 @@
+[pytest]
+testpaths = tests
+python_files = test_*.py
+python_classes = Test*
+python_functions = test_*
+markers =
+    smoke: 快速冒烟测试
+    e2e: 端到端业务链路测试
+log_cli = true
+log_cli_level = INFO
+addopts = --tb=short -v