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

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_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_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_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_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_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",
+]

api_test_kit/e2e/context.py

@@ -0,0 +1,63 @@
+"""ScenarioContext — E2E 步骤间共享的可变状态。
+
+每个步骤可以从自己的响应中提取值存入上下文，
+后续步骤再读取使用。
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from jsonpath_ng import parse as parse_jsonpath
+
+from api_test_kit.client import ApiResponse
+
+
+class ScenarioContext:
+    """Dict-like context that passes data between E2E steps.
+
+    Usage::
+
+        ctx = ScenarioContext()
+        ctx.set("order_id", "ORD-123")
+        ctx.get("order_id")  # -> "ORD-123"
+
+        # Extract from API response using JSONPath:
+        ctx.extract_from(resp, {"created_id": "$.data.id"})
+        ctx.get("created_id")  # -> 42
+    """
+
+    def __init__(self) -> None:
+        self._store: dict[str, Any] = {}
+
+    def set(self, key: str, value: Any) -> None:
+        """Store a value in context."""
+        self._store[key] = value
+
+    def get(self, key: str, default: Any = None) -> Any:
+        """Retrieve a value from context (or *default* if missing)."""
+        return self._store.get(key, default)
+
+    def extract_from(self, resp: ApiResponse, mappings: dict[str, str]) -> None:
+        """Extract values from an API response into context.
+
+        ``mappings`` maps context key → JSONPath expression::
+
+            ctx.extract_from(resp, {"order_id": "$.data.id", "status": "$.data.status"})
+
+        Raises ``KeyError`` if any JSONPath produces no match.
+        """
+        for context_key, jsonpath in mappings.items():
+            matches = parse_jsonpath(jsonpath).find(resp.data)
+            if matches:
+                self._store[context_key] = matches[0].value
+            else:
+                raise KeyError(
+                    f"JSONPath '{jsonpath}' found no match in response "
+                    f"for context key '{context_key}'"
+                )
+
+    def __contains__(self, key: str) -> bool:
+        return key in self._store
+
+    def __repr__(self) -> str:
+        return f"ScenarioContext({self._store})"

api_test_kit/e2e/helpers.py

@@ -0,0 +1,26 @@
+"""E2E 场景测试的便捷辅助函数。"""
+from __future__ import annotations
+
+from api_test_kit.e2e.context import ScenarioContext
+from api_test_kit.e2e.scenario import Scenario, ScenarioReport
+
+
+def run_chain(scenario: Scenario, ctx: ScenarioContext | None = None) -> ScenarioReport:
+    """Run a scenario — sugar for one-liner tests.
+
+    Usage::
+
+        def test_business_flow(client):
+            report = run_chain(Scenario(
+                "下单流程",
+                steps=[Step(name="创建", execute=...)],
+            ))
+            report.assert_all_passed()
+    """
+    return scenario.run(ctx)
+
+
+def chain_summary(report: ScenarioReport) -> str:
+    """Return an inline one-line summary for pytest verbose output."""
+    status = "✅" if report.success else "❌"
+    return f"[E2E] {report.name}: {status} {report.passed}/{report.total} ({report.elapsed:.2f}s)"