api-test-toolkit 0.2.0__tar.gz

api_test_toolkit-0.2.0/PKG-INFO

@@ -0,0 +1,21 @@
+Metadata-Version: 2.4
+Name: api-test-toolkit
+Version: 0.2.0
+Summary: AI 友好的 API 自动化测试工具包
+Requires-Python: >=3.11
+Requires-Dist: requests>=2.31
+Requires-Dist: pydantic<3,>=2.5
+Requires-Dist: pydantic-settings>=2.1
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: jsonpath-ng>=1.6
+Requires-Dist: deepdiff>=7.0
+Requires-Dist: typer<1,>=0.12
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-xdist>=3.5; extra == "dev"
+Requires-Dist: pytest-html>=4.1; extra == "dev"
+Requires-Dist: allure-pytest>=2.13; extra == "dev"
+Requires-Dist: responses>=0.25; extra == "dev"
+Requires-Dist: faker>=22.0; extra == "dev"
+Requires-Dist: ruff>=0.3; extra == "dev"
+Requires-Dist: mypy>=1.8; extra == "dev"

api_test_toolkit-0.2.0/README.md

@@ -0,0 +1,113 @@
+# API Test Kit
+
+基于 Python + pytest + requests 的 AI 友好型 API 自动化测试工具包。
+
+专为 AI 助手（Copilot、Hermes、Claude）设计，让它们**秒懂工程约定**，快速生成一致、类型化、可维护的测试脚本。
+
+## 快速开始
+
+```bash
+make install      # 一次性安装
+make test         # 并行运行所有测试
+make test-report  # 生成 HTML 测试报告
+```
+
+## 项目结构
+
+```
+src/api_test_kit/          # 测试框架核心
+  config.py           # 多环境配置（Pydantic）
+  client.py           # HTTP 客户端（重试、日志、鉴权）
+  assertions.py       # 可读性断言工具
+  logger.py           # 日志配置
+  endpoints/          # API 端点模型（AI 生成）
+    _base.py          # CRUD 基类
+
+tests/                # 测试脚本
+  conftest.py         # 全局 fixtures
+  helpers/            # 测试数据工厂
+  endpoints/          # 按端点的测试文件（AI 生成）
+  e2e/                # 业务链路 E2E 测试
+
+data/fixtures/        # JSON/YAML 测试数据
+scripts/
+  new-endpoint.sh     # 一键生成新端点的脚手架脚本
+```
+
+## 新增 API 测试
+
+```bash
+./scripts/new-endpoint.sh products
+```
+
+然后在 `src/api_test_kit/endpoints/products.py` 实现端点模型，运行：
+
+```bash
+pytest tests/endpoints/test_products.py -v
+```
+
+**AI 协助的测试生成流程：**
+
+```
+① 提供 curl / API 文档
+② AI 试调接口，设计测试用例 → 展示给你 review
+③ 你确认/补充业务场景
+④ AI 写 endpoint 模型 + 测试
+⑤ pytest -v 跑通
+```
+
+详细规范见 [AGENTS.md](./AGENTS.md)。
+
+## 常用命令
+
+| 命令 | 说明 |
+|------|------|
+| `make install` | 安装依赖 |
+| `make test` | 并行运行所有测试 |
+| `make test-report` | 生成 HTML 报告 |
+| `make lint` | ruff 代码检查 |
+| `make format` | 自动格式化代码 |
+| `pytest -m smoke` | 只跑 smoke 测试 |
+| `pytest -m e2e` | 只跑 E2E 链路测试 |
+| `pytest tests/endpoints/test_xxx.py -v` | 单文件测试 |
+
+## 核心概念
+
+- **`HarnessConfig`** — 基于 Pydantic 的多环境配置（`.env` 文件）
+- **`BaseClient`** — `requests.Session` 封装，支持重试、日志、自动鉴权
+- **`ApiResponse(status, data, elapsed)`** — 类型化响应，不暴露原始 `requests.Response`
+- **`BaseEndpoint`** — CRUD 模板：`list / get / create / update / delete`
+- **`assert_*`** — `assert_status`、`assert_json_has`、`assert_json_match`、`assert_error`
+- **`Scenario` / `Step`** — E2E 业务链路测试（详见 [AGENTS.md §10](./AGENTS.md#10-e2e-business-chain-tests)）
+
+## E2E 业务链路测试
+
+除了单接口测试，工具包还支持**多步骤 E2E 场景**，数据在步骤间流转：
+
+```python
+from api_test_kit.e2e import Scenario, Step, run_chain
+
+scenario = Scenario("业务链路", steps=[
+    Step(name="步骤1", execute=..., extract={"key": "$.data.id"}, verify=...),
+    Step(name="步骤2", execute=lambda ctx: api.call(ctx.get("key")), verify=...),
+])
+report = run_chain(scenario)
+report.assert_all_passed()
+```
+
+- `Step(name, execute, extract, verify)` — 业务链中的一个环节
+- `ScenarioContext` — 跨步骤共享状态
+- `ScenarioReport` — 每步的通过/失败汇总
+- 测试类标记 `@pytest.mark.e2e`；用 `pytest -m e2e` 执行
+
+## 配合 AI 使用
+
+给 AI 助手一个 API 的 curl 或接口文档，即可自动生成完整测试：
+
+```
+① 你提供 curl / API 文档
+② AI 试调接口 → 设计测试用例 → 展示给你 review
+③ 你确认 / 补充业务场景
+④ AI 写 endpoint 模型 + 测试脚本
+⑤ pytest -v 跑通
+```

api_test_toolkit-0.2.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta:__legacy__"
+
+[project]
+name = "api-test-toolkit"
+version = "0.2.0"
+description = "AI 友好的 API 自动化测试工具包"
+requires-python = ">=3.11"
+dependencies = [
+    "requests>=2.31",
+    "pydantic>=2.5,<3",
+    "pydantic-settings>=2.1",
+    "python-dotenv>=1.0",
+    "jsonpath-ng>=1.6",
+    "deepdiff>=7.0",
+    "typer>=0.12,<1",
+]
+
+[project.scripts]
+api-test-toolkit = "api_test_kit.cli:app"
+
+[tool.setuptools.package-data]
+api_test_kit = ["templates/**/*"]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-xdist>=3.5",
+    "pytest-html>=4.1",
+    "allure-pytest>=2.13",
+    "responses>=0.25",
+    "faker>=22.0",
+    "ruff>=0.3",
+    "mypy>=1.8",
+]

api_test_toolkit-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

api_test_toolkit-0.2.0/src/api_test_kit/__init__.py

@@ -0,0 +1,18 @@
+"""API Test Kit — AI 友好的 API 自动化测试工具包。"""
+from api_test_kit.e2e.context import ScenarioContext
+from api_test_kit.e2e.step import Step, StepResult
+from api_test_kit.e2e.scenario import Scenario, ScenarioReport
+from api_test_kit.e2e.helpers import run_chain, chain_summary
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "ScenarioContext",
+    "Step",
+    "StepResult",
+    "Scenario",
+    "ScenarioReport",
+    "run_chain",
+    "chain_summary",
+    "__version__",
+]

api_test_toolkit-0.2.0/src/api_test_kit/assertions.py

@@ -0,0 +1,128 @@
+"""API 测试的断言辅助函数。
+
+使用方法::
+
+    from api_test_kit.assertions import assert_status, assert_json_has, assert_json_match
+
+    resp = client.get("/users")
+    assert_status(resp, 200)
+    assert_json_has(resp, "$.data.items[*].id")
+    assert_json_match(resp, {"page": 1})
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from deepdiff import DeepDiff
+from jsonpath_ng import parse as parse_jsonpath
+
+from api_test_kit.client import ApiResponse
+
+
+def assert_status(resp: ApiResponse, expected: int = 200) -> None:
+    """断言 HTTP 状态码完全匹配。"""
+    assert resp.status == expected, (
+        f"Expected status {expected}, got {resp.status}. Body: {resp.data}"
+    )
+
+
+def assert_ok(resp: ApiResponse) -> None:
+    """断言 ``resp.ok`` 为 True（状态码在 2xx 范围内）。"""
+    assert resp.ok, f"Expected 2xx, got {resp.status}. Body: {resp.data}"
+
+
+def assert_json_has(resp: ApiResponse, jsonpath: str) -> list[Any]:
+    """断言 *jsonpath* 在响应体中至少匹配一次。
+
+    返回匹配的值以支持进一步的断言链式调用。
+
+    示例::
+
+        ids = assert_json_has(resp, "$.data.items[*].id")
+        assert len(ids) > 0
+    """
+    matches = parse_jsonpath(jsonpath).find(resp.data)
+    assert len(matches) > 0, (
+        f"JSONPath ``{jsonpath}`` found no matches in response.\n"
+        f"Response body: {resp.data}"
+    )
+    return [m.value for m in matches]
+
+
+def assert_json_not_has(resp: ApiResponse, jsonpath: str) -> None:
+    """断言 *jsonpath* 在响应体中无匹配项。"""
+    matches = parse_jsonpath(jsonpath).find(resp.data)
+    assert len(matches) == 0, (
+        f"JSONPath ``{jsonpath}`` unexpectedly found: {[m.value for m in matches]}"
+    )
+
+
+def assert_json_match(
+    resp: ApiResponse,
+    expected: dict,
+    exclude_paths: list[str] | None = None,
+) -> None:
+    """断言响应体包含 *expected* 中的所有键/值（子集匹配）。
+
+    *exclude_paths*: 要忽略的根相对路径列表，例如 ``["created_at"]``。
+
+    示例::
+
+        assert_json_match(resp, {"total": 10, "page": 1})
+    """
+    body = resp.data if isinstance(resp.data, dict) else {"body": resp.data}
+    diff = DeepDiff(
+        expected,
+        body,
+        verbose_level=2,
+        exclude_paths=[f"root['{p}']" for p in (exclude_paths or [])],
+    )
+    # Subset check: body can have extra keys — only fail on mismatches/absences
+    diff.pop("dictionary_item_added", None)
+    assert not diff, (
+        f"Response body does not match expected subset.\n"
+        f"Differences: {diff}\n"
+        f"Expected subset: {expected}\n"
+        f"Actual: {resp.data}"
+    )
+
+
+def assert_paginated(resp: ApiResponse) -> dict:
+    """断言响应具有标准分页结构并返回分页元数据。
+
+    检查 ``page``、``size``、``total``、``items`` 键是否存在。
+    """
+    data = resp.data if isinstance(resp.data, dict) else {}
+    for key in ("page", "size", "total", "items"):
+        assert key in data, f"Missing pagination key ``{key}`` in response: {data}"
+    assert isinstance(data["items"], list), (
+        f"``items`` must be a list, got {type(data['items'])}"
+    )
+    return data
+
+
+def assert_error(
+    resp: ApiResponse,
+    expected_code: int = 400,
+    message_hint: str | None = None,
+) -> None:
+    """断言错误响应，可选的消息提示检查。
+
+    处理常见的错误结构::
+
+        {"code": "VALIDATION_ERROR", "message": "...", "details": [...]}
+        {"error": {"code": "NOT_FOUND", "message": "..."}}
+    """
+    assert resp.status == expected_code, (
+        f"Expected error status {expected_code}, got {resp.status}"
+    )
+    body = resp.data if isinstance(resp.data, dict) else {}
+    if message_hint:
+        msg = (
+            body.get("message", "")
+            or (body.get("error", {}) or {}).get("message", "")
+            or str(body)
+        )
+        assert message_hint.lower() in msg.lower(), (
+            f"Expected error message containing ``{message_hint}``, got: {msg}"
+        )

api_test_toolkit-0.2.0/src/api_test_kit/cli.py

@@ -0,0 +1,45 @@
+"""CLI 入口 — project scaffolding commands."""
+from __future__ import annotations
+
+import typer
+
+from api_test_kit import __version__
+
+app = typer.Typer(
+    name="api-test-toolkit",
+    help="AI 友好的 API 自动化测试工具包",
+)
+
+
+@app.command()
+def init(
+    project_dir: str = typer.Argument(..., help="新项目目录名"),
+    base_url: str | None = typer.Option(None, "--base-url", "-b", help="API 基础地址"),
+    api_prefix: str | None = typer.Option(None, "--api-prefix", "-p", help="API 前缀"),
+    auth_type: str | None = typer.Option(None, "--auth-type", "-a", help="鉴权方式"),
+    env_name: str | None = typer.Option(None, "--env", "-e", help="环境名"),
+    yes: bool = typer.Option(
+        False, "--yes", "-y", help="非交互模式（使用默认值，不提问）"
+    ),
+) -> None:
+    """创建一个新的 API 自动化测试项目。"""
+    from api_test_kit.scaffold import create_project
+
+    create_project(
+        project_dir=project_dir,
+        base_url=base_url,
+        api_prefix=api_prefix,
+        auth_type=auth_type,
+        env_name=env_name,
+        interactive=not yes,
+    )
+
+
+@app.command()
+def version() -> None:
+    """显示版本号。"""
+    typer.echo(f"api-test-kit v{__version__}")
+
+
+if __name__ == "__main__":
+    app()

api_test_toolkit-0.2.0/src/api_test_kit/client.py

@@ -0,0 +1,208 @@
+"""支持重试、日志、认证和类型化响应的基础 HTTP 客户端。"""
+from __future__ import annotations
+
+import logging
+import time
+from dataclasses import dataclass, field
+from typing import Any
+
+import requests
+from requests.adapters import HTTPAdapter, Retry
+
+from api_test_kit.config import HarnessConfig
+
+logger = logging.getLogger(__name__)
+
+
+# ── 类型化响应 ──────────────────────────────────────────────
+
+
+@dataclass
+class ApiResponse:
+    """标准 API 响应——绝不向测试暴露原始的 ``requests.Response``。"""
+
+    status: int
+    data: Any  # 解析后的 JSON 正文，或原始文本回退
+    elapsed: float  # 实际运行秒数
+    headers: dict[str, str] = field(default_factory=dict)
+    ok: bool = True
+
+    @classmethod
+    def from_requests(cls, resp: requests.Response) -> ApiResponse:
+        """从 ``requests.Response`` 构建——尽可能解析 JSON。"""
+        try:
+            data = resp.json()
+        except ValueError:
+            data = resp.text
+        return cls(
+            status=resp.status_code,
+            data=data,
+            elapsed=resp.elapsed.total_seconds(),
+            headers=dict(resp.headers),
+            ok=200 <= resp.status_code < 300,
+        )
+
+    def __bool__(self) -> bool:
+        return self.ok
+
+
+# ── Token 提供者 ──────────────────────────────────────────────
+
+
+class TokenProvider:
+    """抽象 Token 提供者——为每种认证方式重写。"""
+
+    def get_token(self) -> str:
+        """返回当前 token。"""
+        raise NotImplementedError
+
+    def refresh(self) -> str:
+        """收到 401 时调用。返回一个新的 token。"""
+        return self.get_token()
+
+
+class BearerTokenProvider(TokenProvider):
+    """基于固定值（如环境变量或配置）的简单 bearer token。"""
+
+    def __init__(self, token: str) -> None:
+        self._token = token
+
+    def get_token(self) -> str:
+        return self._token
+
+
+# ── 基础客户端 ─────────────────────────────────────────────────
+
+
+class BaseClient:
+    """封装 ``requests.Session``，支持重试、日志和认证。
+
+    使用方法::
+
+        config = HarnessConfig.from_env("staging")
+        client = BaseClient(config)
+        client.authenticate(BearerTokenProvider("xxx"))
+        resp: ApiResponse = client.get("/api/v1/users")
+    """
+
+    def __init__(self, config: HarnessConfig) -> None:
+        self.config = config
+        self.session = requests.Session()
+        self._setup_retry()
+        self._token_provider: TokenProvider | None = None
+        self._token: str | None = None
+
+    # ── 认证 ────────────────────────────────────────────────────
+
+    def authenticate(self, provider: TokenProvider) -> None:
+        """设置认证提供者。Token 在首次请求时惰性获取。"""
+        self._token_provider = provider
+        self._token = None
+
+    def _ensure_token(self) -> None:
+        if self._token is None and self._token_provider:
+            self._token = self._token_provider.get_token()
+
+    def _refresh_token(self) -> None:
+        if self._token_provider:
+            self._token = self._token_provider.refresh()
+        else:
+            self._token = None
+
+    def _inject_auth(self, headers: dict[str, str]) -> dict[str, str]:
+        auth_type = self.config.auth_type
+        header_name = self.config.auth_header_name
+        if auth_type == "bearer" and self._token:
+            headers[header_name] = f"Bearer {self._token}"
+        elif auth_type == "api_key" and self._token:
+            headers[header_name] = self._token
+        return headers
+
+    # ── HTTP 方法 ────────────────────────────────────────────
+
+    def get(self, path: str, **kwargs: Any) -> ApiResponse:
+        return self._request("GET", path, **kwargs)
+
+    def post(self, path: str, **kwargs: Any) -> ApiResponse:
+        return self._request("POST", path, **kwargs)
+
+    def put(self, path: str, **kwargs: Any) -> ApiResponse:
+        return self._request("PUT", path, **kwargs)
+
+    def patch(self, path: str, **kwargs: Any) -> ApiResponse:
+        return self._request("PATCH", path, **kwargs)
+
+    def delete(self, path: str, **kwargs: Any) -> ApiResponse:
+        return self._request("DELETE", path, **kwargs)
+
+    # ── 内部方法 ────────────────────────────────────────────────
+
+    def _request(self, method: str, path: str, **kwargs: Any) -> ApiResponse:
+        url = self._resolve_url(path)
+        self._ensure_token()
+        headers = kwargs.pop("headers", {})
+        headers = self._inject_auth(headers)
+
+        for attempt in range(self.config.max_retries + 1):
+            start = time.perf_counter()
+            try:
+                if self.config.log_requests:
+                    logger.debug(
+                        "[REQ] %s %s | body=%s",
+                        method,
+                        url,
+                        kwargs.get("json", kwargs.get("data", "")),
+                    )
+                resp = self.session.request(
+                    method, url, headers=headers, timeout=self.config.timeout, **kwargs
+                )
+                elapsed = time.perf_counter() - start
+                api_resp = ApiResponse.from_requests(resp)
+
+                if self.config.log_responses:
+                    logger.debug(
+                        "[RES] %s %s → %d (%.3fs)", method, url, resp.status_code, elapsed
+                    )
+
+                # Auto-refresh token on 401 and retry
+                if resp.status_code == 401 and self._token_provider and attempt < self.config.max_retries:
+                    logger.info("[AUTH] 401 received — refreshing token (attempt %d)", attempt + 1)
+                    self._refresh_token()
+                    headers = self._inject_auth(headers)
+                    continue
+
+                return api_resp
+
+            except requests.RequestException as e:
+                elapsed = time.perf_counter() - start
+                logger.warning("[ERR] %s %s failed after %.3fs: %s", method, url, elapsed, e)
+                if attempt < self.config.max_retries:
+                    backoff = self.config.retry_backoff * (2**attempt)
+                    logger.info(
+                        "[RETRY] waiting %.1fs before retry %d/%d",
+                        backoff,
+                        attempt + 1,
+                        self.config.max_retries,
+                    )
+                    time.sleep(backoff)
+                    continue
+                return ApiResponse(status=0, data=str(e), elapsed=elapsed, ok=False)
+
+        raise RuntimeError("Unreachable — all retries exhausted")
+
+    def _resolve_url(self, path: str) -> str:
+        if path.startswith("http://") or path.startswith("https://"):
+            return path
+        return f"{self.config.api_url}{path}"
+
+    def _setup_retry(self) -> None:
+        """挂载适配器，为 DNS / 连接错误提供连接级重试。"""
+        retry_strategy = Retry(
+            total=self.config.max_retries,
+            backoff_factor=self.config.retry_backoff * 0.5,
+            status_forcelist=[429, 500, 502, 503, 504],
+            allowed_methods=["GET", "HEAD", "OPTIONS"],
+        )
+        adapter = HTTPAdapter(max_retries=retry_strategy)
+        self.session.mount("http://", adapter)
+        self.session.mount("https://", adapter)

api_test_toolkit-0.2.0/src/api_test_kit/config.py

@@ -0,0 +1,82 @@
+"""通过 Pydantic Settings 实现的多环境配置。
+
+使用方法::
+
+    config = HarnessConfig.from_env("staging")
+    config.base_url  # -> "https://staging-api.example.com"
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Literal
+
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class HarnessConfig(BaseSettings):
+    """从环境文件或环境变量加载的应用配置。
+
+    优先级：环境变量 > 环境文件 > 默认值。
+    """
+
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        extra="ignore",
+        frozen=True,
+    )
+
+    # --- 核心 ---
+    env_name: str = Field(default="dev", description="Environment name (dev/staging/prod)")
+    base_url: str = Field(default="http://localhost:8000", description="API base URL")
+    api_prefix: str = Field(default="/api/v1", description="API version prefix")
+
+    # --- 认证 ---
+    auth_type: Literal["none", "bearer", "api_key", "basic", "oauth2"] = Field(
+        default="bearer",
+    )
+    auth_header_name: str = Field(
+        default="authorization",
+        description="HTTP header name for the auth token "
+                    "(default: 'authorization' for bearer, 'x-api-key' for api_key)",
+    )
+    auth_token_url: str | None = Field(default=None, description="Token endpoint for OAuth2")
+    client_id: str | None = Field(default=None)
+    client_secret: str | None = Field(default=None, description="Also used as bearer token value")
+
+    # --- HTTP 客户端 ---
+    timeout: int = Field(default=30, ge=1, le=300)
+    max_retries: int = Field(default=3, ge=0, le=10)
+    retry_backoff: float = Field(default=1.0, ge=0.1)
+
+    # --- 日志 ---
+    log_level: str = Field(default="INFO", pattern=r"^(DEBUG|INFO|WARNING|ERROR)$")
+    log_requests: bool = Field(default=True)
+    log_responses: bool = Field(default=True)
+
+    # --- 派生 ---
+    @property
+    def api_url(self) -> str:
+        """完整的 API 基础 URL（base_url + api_prefix）。"""
+        return f"{self.base_url}{self.api_prefix}"
+
+    @classmethod
+    def from_env(cls, env_name: str = "dev") -> HarnessConfig:
+        """加载指定环境的配置。
+
+        查找项目根目录下的 ``config.{env_name}.env``，
+        如果不存在则回退到 ``.env``。
+        """
+        project_root = cls._find_project_root()
+        env_file = project_root / f"config.{env_name}.env"
+        return cls(_env_file=str(env_file) if env_file.exists() else None)
+
+    @staticmethod
+    def _find_project_root() -> Path:
+        """从当前工作目录向上查找项目根目录（包含 pyproject.toml 的目录）。"""
+        start = Path.cwd()
+        for parent in [start] + list(start.parents):
+            if (parent / "pyproject.toml").exists():
+                return parent
+        return start

api_test_toolkit-0.2.0/src/api_test_kit/e2e/__init__.py

@@ -0,0 +1,15 @@
+"""E2E 业务链路测试 — Scenario、Step、Context。"""
+from api_test_kit.e2e.context import ScenarioContext
+from api_test_kit.e2e.step import Step, StepResult
+from api_test_kit.e2e.scenario import Scenario, ScenarioReport
+from api_test_kit.e2e.helpers import run_chain, chain_summary
+
+__all__ = [
+    "ScenarioContext",
+    "Step",
+    "StepResult",
+    "Scenario",
+    "ScenarioReport",
+    "run_chain",
+    "chain_summary",
+]