dd-apitest 0.2.0__tar.gz

dd_apitest-0.2.0/PKG-INFO

@@ -0,0 +1,197 @@
+Metadata-Version: 2.4
+Name: dd-apitest
+Version: 0.2.0
+Summary: JSON-driven OpenAPI integration test CLI (TUI + suites)
+Author: DBApp Security
+License-Expression: LicenseRef-Proprietary
+Project-URL: Homepage, https://github.com/dbappsecurity/apitest-standalone
+Project-URL: Documentation, https://github.com/dbappsecurity/apitest-standalone/blob/main/docs/2026-05-29-apitest-framework-usage.md
+Project-URL: Issues, https://github.com/dbappsecurity/apitest-standalone/issues
+Keywords: apitest,openapi,api-testing,dd-apitest
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.32.0
+Requires-Dist: python-dotenv>=1.0.1
+Requires-Dist: textual>=0.80.0
+
+# XSIAM Credential / apitest
+
+## 环境准备
+
+### 方式 A：从 PyPI / 内网 PyPI 运行（推荐分发）
+
+PyPI **包名**为 `dd-apitest`（公网 [pypi.org/project/apitest](https://pypi.org/project/apitest/) 已被其他项目占用，命令行仍为 **`apitest`**）。
+
+需已安装 [uv](https://docs.astral.sh/uv/)。**发布前**需维护者先执行 `uv publish`；用户侧：
+
+```powershell
+# 一次性运行（包名 dd-apitest，命令 apitest；Windows 需显式指定命令名）
+uvx --from dd-apitest apitest --user-data init
+uvx --from dd-apitest apitest --user-data
+uvx --from dd-apitest apitest --user-data run --suite demo-ui --group readonly --env httpbin
+
+# 内网 PyPI（示例）
+# uvx --index-url https://pypi.your-company.com/simple/ --from dd-apitest apitest --user-data init
+```
+
+持久安装（装好后直接用 `apitest`）：
+
+```powershell
+uv tool install dd-apitest
+apitest --user-data init
+apitest --user-data
+```
+
+发布流程见 [`docs/publishing-pypi.md`](./docs/publishing-pypi.md)。
+
+### 方式 A′：`uvx --from` 本地或 Git（未上 PyPI 时）
+
+```powershell
+uvx --from "C:/Programs/dbapp-workspace/apitest-standalone" apitest --user-data init
+uvx --from "C:/Programs/dbapp-workspace/apitest-standalone" apitest --user-data
+```
+
+说明：
+
+- `uvx` 会临时安装到 uv 缓存，不污染当前目录；
+- 包内已内置 suite 模板；`init --user-data` 写入 `~/.apitest/`；
+- 已 `init` 且存在 `~/.apitest/suites` 时，可省略每次的 `--user-data`；
+- 在**已 clone 的仓库根目录**内开发时，默认使用仓库下的 `suites/`。
+
+### 方式 B：仓库内开发（仅 uv）
+
+```powershell
+uv venv --python 3.12
+.\.venv\Scripts\Activate.ps1
+uv pip install -e .
+uv pip install "pytest>=8.0.0" "responses>=0.25.0"
+```
+
+`.env` 示例（勿提交仓库）：
+
+```env
+HENGNAO_APPKEY=your_key
+HENGNAO_APPSECRET=your_secret
+```
+
+## apitest（推荐）
+
+JSON 配置驱动的 OpenAPI 联调框架。日常在仓库内用 `uv run apitest`；任意目录用 `uvx --from <源> apitest`（见上文方式 A）。
+
+- **使用文档**：[`docs/2026-05-29-apitest-framework-usage.md`](./docs/2026-05-29-apitest-framework-usage.md)
+- **设计文档**：[`docs/superpowers/specs/2026-05-29-apitest-framework-design.md`](./docs/superpowers/specs/2026-05-29-apitest-framework-design.md)
+
+### 常用命令
+
+```powershell
+# 交互 TUI（Textual）：方向键选组/用例，快捷键见下
+uv run apitest
+
+| 键 | 作用 |
+|----|------|
+| `g` | 跑当前组 |
+| `c` | 跑当前用例 |
+| `a` | 跑全部组 |
+| `e` | **选择环境**（列表点选，Enter 确认） |
+| `n` | 下一环境（顺序轮换） |
+| `s` / `b` | **返回 Suite 选择**（多个 suite 时；Esc 取消并回到当前 suite） |
+| `q` | 退出（也可点底部 Footer 的 Quit） |
+
+日志区使用 RichLog 彩色输出；跑完用例后会输出报告路径与 `file:///.../report.html` 链接。
+
+启动时若存在多个 suite（如 `demo-ui`、`xsiam-credential`），会先弹出 Suite 列表；进入主界面后按 **`s`** 可退回 Suite 选择页重新选择（Esc 取消）。
+
+# 只读冒烟
+uv run apitest run --suite xsiam-credential --group readonly --env dev
+
+# 写组（含 create-then-delete flow）
+uv run apitest run --suite xsiam-credential --group write --env dev
+
+# 全量（所有 group）
+uv run apitest run --suite xsiam-credential --all --env dev
+```
+
+报告目录：`reports/{suite}/{timestamp}/`（已 gitignore）。
+
+报告文件：
+- `report.html`：主报告（可直接浏览器打开）
+- `summary.json`：机器可读摘要
+- `index.json`：索引（含 `reportHtml` 指针）
+- `failures/{caseId}.json`：失败或 `--verbose` 详情（脱敏）
+- `summary.md`：仅兼容模式（`legacy_md=True`）生成
+
+非 TUI/菜单模式会同时打印：
+- `Report: <本地路径>`
+- `Report URL: file:///.../report.html`（多数终端可点击）
+
+可选 data root 切换：
+
+```powershell
+# 使用用户空间 ~/.apitest
+uv run apitest --user-data
+
+# 指定自定义 data root
+uv run apitest --data-dir "D:/apitest-data" run --suite xsiam-credential --all --env dev
+```
+
+默认 data root 为仓库根目录（`suites/`、`plugins/`、`.env` 所在目录）。
+
+### 新增接口（检查清单）
+
+1. 在 `suites/xsiam-credential/payloads/` 增加请求体或 query JSON
+2. 在 `suites/xsiam-credential/cases/` 增加 case（或 flow 步骤）
+3. 在 `groups/readonly/group.json` 或 `groups/write/group.json` 引用该 case
+4. `uv run pytest -q`
+
+Agent 配置用例：`.cursor/skills/apitest-test-data/SKILL.md`（流程）+ `reference.md`（字段/示例）。
+
+表单上传：`bodyType` 为 `form-data` / `form-urlencoded`，见设计文档 §3.4.2。
+
+### 演示 Suite（看 TUI 交互）
+
+无需内网与 `HENGNAO_*` 密钥，走公网 [httpbin.org](https://httpbin.org)：
+
+```powershell
+uv run apitest
+# 启动后若有两个 suite，选 demo-ui
+```
+
+| 组 | 说明 |
+|----|------|
+| `readonly` | GET 连通、Query、2s 延迟 |
+| `write` | POST JSON、form-urlencoded |
+| `flows` | POST → extract → GET 变量传递 |
+
+环境：`demo-ui` 含 `httpbin` / `httpbin-delay` / `playground` / `sandbox`。TUI 内按 **`e`** 弹出列表选择；按 **`n`** 可顺序切换到下一环境。
+
+### 目录
+
+```text
+core/              # 框架内核
+suites/demo-ui/    # TUI 演示（httpbin）
+suites/xsiam-credential/
+  suite.json
+  groups/readonly|write/group.json
+  cases/
+  payloads/
+plugins/           # 项目级自定义 auth_*.py（可选）
+reports/           # 执行产物
+```
+
+## 测试
+
+```powershell
+uv run pytest -q
+```
+
+## 安全说明
+
+- 日志与报告会对 `accessToken`、`refreshToken`、`clientSecret`、`appSecret`、`sign` 脱敏。
+- 勿将 `.env` 提交到仓库。

dd_apitest-0.2.0/README.md

@@ -0,0 +1,174 @@
+# XSIAM Credential / apitest
+
+## 环境准备
+
+### 方式 A：从 PyPI / 内网 PyPI 运行（推荐分发）
+
+PyPI **包名**为 `dd-apitest`（公网 [pypi.org/project/apitest](https://pypi.org/project/apitest/) 已被其他项目占用，命令行仍为 **`apitest`**）。
+
+需已安装 [uv](https://docs.astral.sh/uv/)。**发布前**需维护者先执行 `uv publish`；用户侧：
+
+```powershell
+# 一次性运行（包名 dd-apitest，命令 apitest；Windows 需显式指定命令名）
+uvx --from dd-apitest apitest --user-data init
+uvx --from dd-apitest apitest --user-data
+uvx --from dd-apitest apitest --user-data run --suite demo-ui --group readonly --env httpbin
+
+# 内网 PyPI（示例）
+# uvx --index-url https://pypi.your-company.com/simple/ --from dd-apitest apitest --user-data init
+```
+
+持久安装（装好后直接用 `apitest`）：
+
+```powershell
+uv tool install dd-apitest
+apitest --user-data init
+apitest --user-data
+```
+
+发布流程见 [`docs/publishing-pypi.md`](./docs/publishing-pypi.md)。
+
+### 方式 A′：`uvx --from` 本地或 Git（未上 PyPI 时）
+
+```powershell
+uvx --from "C:/Programs/dbapp-workspace/apitest-standalone" apitest --user-data init
+uvx --from "C:/Programs/dbapp-workspace/apitest-standalone" apitest --user-data
+```
+
+说明：
+
+- `uvx` 会临时安装到 uv 缓存，不污染当前目录；
+- 包内已内置 suite 模板；`init --user-data` 写入 `~/.apitest/`；
+- 已 `init` 且存在 `~/.apitest/suites` 时，可省略每次的 `--user-data`；
+- 在**已 clone 的仓库根目录**内开发时，默认使用仓库下的 `suites/`。
+
+### 方式 B：仓库内开发（仅 uv）
+
+```powershell
+uv venv --python 3.12
+.\.venv\Scripts\Activate.ps1
+uv pip install -e .
+uv pip install "pytest>=8.0.0" "responses>=0.25.0"
+```
+
+`.env` 示例（勿提交仓库）：
+
+```env
+HENGNAO_APPKEY=your_key
+HENGNAO_APPSECRET=your_secret
+```
+
+## apitest（推荐）
+
+JSON 配置驱动的 OpenAPI 联调框架。日常在仓库内用 `uv run apitest`；任意目录用 `uvx --from <源> apitest`（见上文方式 A）。
+
+- **使用文档**：[`docs/2026-05-29-apitest-framework-usage.md`](./docs/2026-05-29-apitest-framework-usage.md)
+- **设计文档**：[`docs/superpowers/specs/2026-05-29-apitest-framework-design.md`](./docs/superpowers/specs/2026-05-29-apitest-framework-design.md)
+
+### 常用命令
+
+```powershell
+# 交互 TUI（Textual）：方向键选组/用例，快捷键见下
+uv run apitest
+
+| 键 | 作用 |
+|----|------|
+| `g` | 跑当前组 |
+| `c` | 跑当前用例 |
+| `a` | 跑全部组 |
+| `e` | **选择环境**（列表点选，Enter 确认） |
+| `n` | 下一环境（顺序轮换） |
+| `s` / `b` | **返回 Suite 选择**（多个 suite 时；Esc 取消并回到当前 suite） |
+| `q` | 退出（也可点底部 Footer 的 Quit） |
+
+日志区使用 RichLog 彩色输出；跑完用例后会输出报告路径与 `file:///.../report.html` 链接。
+
+启动时若存在多个 suite（如 `demo-ui`、`xsiam-credential`），会先弹出 Suite 列表；进入主界面后按 **`s`** 可退回 Suite 选择页重新选择（Esc 取消）。
+
+# 只读冒烟
+uv run apitest run --suite xsiam-credential --group readonly --env dev
+
+# 写组（含 create-then-delete flow）
+uv run apitest run --suite xsiam-credential --group write --env dev
+
+# 全量（所有 group）
+uv run apitest run --suite xsiam-credential --all --env dev
+```
+
+报告目录：`reports/{suite}/{timestamp}/`（已 gitignore）。
+
+报告文件：
+- `report.html`：主报告（可直接浏览器打开）
+- `summary.json`：机器可读摘要
+- `index.json`：索引（含 `reportHtml` 指针）
+- `failures/{caseId}.json`：失败或 `--verbose` 详情（脱敏）
+- `summary.md`：仅兼容模式（`legacy_md=True`）生成
+
+非 TUI/菜单模式会同时打印：
+- `Report: <本地路径>`
+- `Report URL: file:///.../report.html`（多数终端可点击）
+
+可选 data root 切换：
+
+```powershell
+# 使用用户空间 ~/.apitest
+uv run apitest --user-data
+
+# 指定自定义 data root
+uv run apitest --data-dir "D:/apitest-data" run --suite xsiam-credential --all --env dev
+```
+
+默认 data root 为仓库根目录（`suites/`、`plugins/`、`.env` 所在目录）。
+
+### 新增接口（检查清单）
+
+1. 在 `suites/xsiam-credential/payloads/` 增加请求体或 query JSON
+2. 在 `suites/xsiam-credential/cases/` 增加 case（或 flow 步骤）
+3. 在 `groups/readonly/group.json` 或 `groups/write/group.json` 引用该 case
+4. `uv run pytest -q`
+
+Agent 配置用例：`.cursor/skills/apitest-test-data/SKILL.md`（流程）+ `reference.md`（字段/示例）。
+
+表单上传：`bodyType` 为 `form-data` / `form-urlencoded`，见设计文档 §3.4.2。
+
+### 演示 Suite（看 TUI 交互）
+
+无需内网与 `HENGNAO_*` 密钥，走公网 [httpbin.org](https://httpbin.org)：
+
+```powershell
+uv run apitest
+# 启动后若有两个 suite，选 demo-ui
+```
+
+| 组 | 说明 |
+|----|------|
+| `readonly` | GET 连通、Query、2s 延迟 |
+| `write` | POST JSON、form-urlencoded |
+| `flows` | POST → extract → GET 变量传递 |
+
+环境：`demo-ui` 含 `httpbin` / `httpbin-delay` / `playground` / `sandbox`。TUI 内按 **`e`** 弹出列表选择；按 **`n`** 可顺序切换到下一环境。
+
+### 目录
+
+```text
+core/              # 框架内核
+suites/demo-ui/    # TUI 演示（httpbin）
+suites/xsiam-credential/
+  suite.json
+  groups/readonly|write/group.json
+  cases/
+  payloads/
+plugins/           # 项目级自定义 auth_*.py（可选）
+reports/           # 执行产物
+```
+
+## 测试
+
+```powershell
+uv run pytest -q
+```
+
+## 安全说明
+
+- 日志与报告会对 `accessToken`、`refreshToken`、`clientSecret`、`appSecret`、`sign` 脱敏。
+- 勿将 `.env` 提交到仓库。

dd_apitest-0.2.0/core/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.2.0"

dd_apitest-0.2.0/core/__main__.py

@@ -0,0 +1,99 @@
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from dotenv import load_dotenv
+
+from core.errors import ConfigError
+from core.init_cmd import init_user_data
+from core.loader import discover_suites, find_suite_by_name
+from core.menu import run_menu
+from core.paths import resolve_data_root, script_root, set_runtime_data_root, suites_template_source
+from core.report import write_run_report
+from core.runner import run_all_groups, run_group
+
+
+def _file_uri(path: Path) -> str:
+    return path.resolve().as_uri()
+
+
+def _cmd_run(args: argparse.Namespace) -> int:
+    suite = find_suite_by_name(args.suite)
+    session_env = args.env or suite.default_env
+    if args.all:
+        result = run_all_groups(suite, session_env=session_env)
+    else:
+        if not args.group:
+            print("--group or --all is required", file=sys.stderr)
+            return 2
+        result = run_group(suite, args.group, session_env=session_env)
+    out = write_run_report(suite_name=suite.name, session_env=session_env, result=result)
+    report_html = (out / "report.html").resolve()
+    total = result.total
+    rate = (result.passed / total * 100) if total else 0
+    print(f"Summary: passed={result.passed} failed={result.failed} total={total} ({rate:.0f}%)")
+    print(f"Report: {report_html}")
+    print(f"Report URL: {_file_uri(report_html)}")
+    return 0 if result.failed == 0 else 1
+
+
+def _cmd_init(args: argparse.Namespace) -> int:
+    source = suites_template_source()
+    target = resolve_data_root(user_data=args.user_data, data_dir=args.data_dir)
+    initialized = init_user_data(source_data_root=source, target_data_root=target, force=args.force)
+    print(f"Initialized data root: {initialized}")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="apitest")
+    parser.add_argument("--user-data", action="store_true", help="Use ~/.apitest as data root")
+    parser.add_argument("--data-dir", help="Custom data root directory")
+    sub = parser.add_subparsers(dest="command")
+
+    run_parser = sub.add_parser("run", help="Run suite groups non-interactively")
+    run_parser.add_argument("--suite", required=True)
+    run_parser.add_argument("--group")
+    run_parser.add_argument("--all", action="store_true")
+    run_parser.add_argument("--env")
+    run_parser.set_defaults(func=_cmd_run)
+
+    sub.add_parser("menu", help="Interactive menu")
+    init_parser = sub.add_parser("init", help="Initialize data root with suites template")
+    init_parser.add_argument("--force", action="store_true")
+    init_parser.set_defaults(func=_cmd_init)
+
+    args = parser.parse_args(argv)
+    root = resolve_data_root(user_data=args.user_data, data_dir=args.data_dir)
+    set_runtime_data_root(root)
+    # Keep compatibility with current repos; user-space .env should override script/.env.
+    load_dotenv(script_root() / ".env")
+    load_dotenv(root / ".env", override=True)
+
+    if args.command == "run":
+        try:
+            return _cmd_run(args)
+        except ConfigError as exc:
+            print(exc, file=sys.stderr)
+            return 1
+    if args.command == "init":
+        try:
+            return _cmd_init(args)
+        except ConfigError as exc:
+            print(exc, file=sys.stderr)
+            return 1
+
+    if args.command == "menu" or (args.command is None and sys.stdin.isatty()):
+        return run_menu()
+
+    if args.command is None:
+        parser.print_help()
+        return 0
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

dd_apitest-0.2.0/core/assert_engine.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+def _json_subset(expected: Any, actual: Any) -> bool:
+    if isinstance(expected, dict):
+        if not isinstance(actual, dict):
+            return False
+        return all(k in actual and _json_subset(expected[k], actual[k]) for k in expected)
+    return expected == actual
+
+
+def check_success(
+    http_status: int,
+    body: Any,
+    rules: dict[str, Any],
+) -> tuple[bool, list[str]]:
+    reasons: list[str] = []
+    expected_status = rules.get("httpStatus")
+    if expected_status is not None and http_status not in expected_status:
+        reasons.append(f"httpStatus expected {expected_status}, got {http_status}")
+
+    json_rule = rules.get("json")
+    if json_rule is not None:
+        if isinstance(body, dict):
+            if not _json_subset(json_rule, body):
+                reasons.append(f"json subset mismatch: expected {json_rule}, got {body}")
+        elif body is not None and not isinstance(body, dict):
+            pass
+        else:
+            reasons.append("json rule configured but response body is not a JSON object")
+
+    return (len(reasons) == 0, reasons)

dd_apitest-0.2.0/core/bundled/__init__.py

@@ -0,0 +1 @@
+"""Bundled suite templates (populated at wheel build time)."""

dd_apitest-0.2.0/core/bundled/suites/demo-ui/cases/flows/post_then_get.json

@@ -0,0 +1,23 @@
+{
+  "id": "post-then-get",
+  "type": "flow",
+  "name": "POST 写入变量再 GET",
+  "steps": [
+    {
+      "name": "post-seed",
+      "method": "POST",
+      "path": "/post",
+      "bodyFile": "payloads/post_seed.json",
+      "extract": { "echoToken": "$.json.echoToken" }
+    },
+    {
+      "name": "get-echo",
+      "method": "GET",
+      "path": "/get",
+      "query": {
+        "echoToken": "{{echoToken}}",
+        "tag": "{{demoTag}}"
+      }
+    }
+  ]
+}

dd_apitest-0.2.0/core/bundled/suites/demo-ui/cases/get-basic.json

@@ -0,0 +1,6 @@
+{
+  "id": "get-basic",
+  "name": "GET 连通性",
+  "method": "GET",
+  "path": "/get"
+}

dd_apitest-0.2.0/core/bundled/suites/demo-ui/cases/get-delay.json

@@ -0,0 +1,6 @@
+{
+  "id": "get-delay",
+  "name": "GET 延迟 2s（看进度）",
+  "method": "GET",
+  "path": "/delay/2"
+}

dd_apitest-0.2.0/core/bundled/suites/demo-ui/cases/get-query.json

@@ -0,0 +1,7 @@
+{
+  "id": "get-query",
+  "name": "GET 带 Query",
+  "method": "GET",
+  "path": "/get",
+  "queryFile": "payloads/get_query.json"
+}

dd_apitest-0.2.0/core/bundled/suites/demo-ui/cases/post-form.json

@@ -0,0 +1,8 @@
+{
+  "id": "post-form",
+  "name": "POST 表单",
+  "method": "POST",
+  "path": "/post",
+  "bodyType": "form-urlencoded",
+  "formFile": "forms/post_form.json"
+}

dd_apitest-0.2.0/core/bundled/suites/demo-ui/cases/post-json.json

@@ -0,0 +1,7 @@
+{
+  "id": "post-json",
+  "name": "POST JSON",
+  "method": "POST",
+  "path": "/post",
+  "bodyFile": "payloads/post_json.json"
+}

dd_apitest-0.2.0/core/bundled/suites/demo-ui/forms/post_form.json

@@ -0,0 +1,6 @@
+{
+  "fields": {
+    "field1": "hello",
+    "tag": "{{demoTag}}"
+  }
+}

dd_apitest-0.2.0/core/bundled/suites/demo-ui/groups/flows/group.json

@@ -0,0 +1,9 @@
+{
+  "name": "flows",
+  "tags": ["flow", "demo"],
+  "env": "httpbin",
+  "inheritSuccess": true,
+  "cases": [
+    { "id": "post-then-get", "file": "cases/flows/post_then_get.json" }
+  ]
+}

dd_apitest-0.2.0/core/bundled/suites/demo-ui/groups/readonly/group.json

@@ -0,0 +1,11 @@
+{
+  "name": "readonly",
+  "tags": ["read-only", "demo"],
+  "env": "httpbin",
+  "inheritSuccess": true,
+  "cases": [
+    { "id": "get-basic", "file": "cases/get-basic.json" },
+    { "id": "get-query", "file": "cases/get-query.json" },
+    { "id": "get-delay", "file": "cases/get-delay.json" }
+  ]
+}

dd_apitest-0.2.0/core/bundled/suites/demo-ui/groups/write/group.json

@@ -0,0 +1,10 @@
+{
+  "name": "write",
+  "tags": ["write", "demo"],
+  "env": "httpbin",
+  "inheritSuccess": true,
+  "cases": [
+    { "id": "post-json", "file": "cases/post-json.json" },
+    { "id": "post-form", "file": "cases/post-form.json" }
+  ]
+}

dd_apitest-0.2.0/core/bundled/suites/demo-ui/payloads/get_query.json

@@ -0,0 +1,4 @@
+{
+  "foo": "bar",
+  "tag": "{{demoTag}}"
+}

dd_apitest-0.2.0/core/bundled/suites/demo-ui/payloads/post_json.json

@@ -0,0 +1,4 @@
+{
+  "name": "apitest-demo",
+  "tag": "{{demoTag}}"
+}

dd_apitest-0.2.0/core/bundled/suites/demo-ui/payloads/post_seed.json

@@ -0,0 +1,3 @@
+{
+  "echoToken": "token-{{demoTag}}-001"
+}