fapitest 0.2.6

JSON-driven OpenAPI integration test CLI (TUI + suites)

XSIAM Credential / apitest

环境准备

方式 A：从 PyPI / 内网 PyPI 运行（推荐分发）

PyPI 包名与命令均为 fapitest（uvx fapitest 即可；公网 apitest 为其他项目，勿混用）。

需已安装 uv：

uvx fapitest --user-data init
uvx fapitest --user-data
uvx fapitest --user-data run --suite demo-ui --group readonly --env httpbin

# 项目目录作为数据根（全局参数写在子命令前）
uvx fapitest --data-dir . init
uvx fapitest --data-dir . run --suite demo-ui --group readonly --env httpbin

# 内网 PyPI（示例）
# uvx --index-url https://pypi.your-company.com/simple/ fapitest --user-data init

选项	数据根	场景
--user-data	~/.apitest	本机共用 suites / .env（推荐）
--data-dir <路径>	指定目录	项目内 suites/、CI、多环境隔离
（无）	已有 ~/.apitest/suites 时用 ~/.apitest	曾 init 过可省略 --user-data

init 目标目录已有 suites/ 时需 --force；详见 docs/publishing-pypi.md「数据目录」与 FAQ。

持久安装：

uv tool install fapitest
fapitest --user-data init
fapitest --user-data

发布流程见 docs/publishing-pypi.md；版本历史见 CHANGELOG.md。维护者发版可用 .cursor/skills/fapitest-release/。

方式 A′：uvx --from 本地或 Git（未上 PyPI 时）

uvx --from "C:/Programs/dbapp-workspace/apitest-standalone" fapitest --user-data init
uvx --from "C:/Programs/dbapp-workspace/apitest-standalone" fapitest --user-data

说明：

• uvx 会临时安装到 uv 缓存，不污染当前目录；
• 包内已内置 suite 模板；init --user-data 写入 ~/.apitest/；
• 已 init 且存在 ~/.apitest/suites 时，可省略每次的 --user-data；
• 在已 clone 的仓库根目录内开发时，默认使用仓库下的 suites/。

方式 B：仓库内开发（仅 uv）

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 示例（勿提交仓库）：

HENGNAO_APPKEY=your_key
HENGNAO_APPSECRET=your_secret

apitest（推荐）

JSON 配置驱动的 OpenAPI 联调框架。日常在仓库内用 uv run fapitest；任意目录用 uvx fapitest（见上文方式 A）。

• 使用文档：docs/2026-05-29-apitest-framework-usage.md
• 设计文档：docs/superpowers/specs/2026-05-29-apitest-framework-design.md

常用命令

# 交互 TUI（Textual）：方向键选组/用例，快捷键见下
uv run fapitest

| 键 | 作用 |
|----|------|
| `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 fapitest run --suite xsiam-credential --group readonly --env dev

# 写组（含 create-then-delete flow）
uv run fapitest run --suite xsiam-credential --group write --env dev

# 全量（所有 group）
uv run fapitest 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 切换（全局参数写在子命令前）：

# 使用用户空间 ~/.apitest
uv run fapitest --user-data
uv run fapitest --user-data init

# 指定自定义 data root（PyPI 安装同理：uvx fapitest --data-dir ...）
uv run fapitest --data-dir "D:/apitest-data" run --suite xsiam-credential --all --env dev
uv run fapitest --data-dir . init

默认 data root：仓库开发时为仓库根目录；uvx 安装且已存在 ~/.apitest/suites 时自动用 ~/.apitest。环境变量 APITEST_DATA_DIR 等价于 --data-dir。

新增接口（检查清单）

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/fapitester/SKILL.md（流程）+ reference.md（字段/示例）。

表单上传：bodyType 为 form-data / form-urlencoded，见设计文档 §3.4.2。

演示 Suite（看 TUI 交互）

无需内网与 HENGNAO_* 密钥，走公网 httpbin.org：

uv run fapitest
# 启动后若有两个 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 可顺序切换到下一环境。

目录

core/              # 框架内核
suites/demo-ui/    # TUI 演示（httpbin）
suites/xsiam-credential/
  suite.json
  groups/readonly|write/group.json
  cases/
  payloads/
plugins/           # 项目级自定义 auth_*.py（可选）
reports/           # 执行产物

测试

uv run pytest -q

安全说明

• 日志与报告会对 accessToken、refreshToken、clientSecret、appSecret、sign 脱敏。
• 勿将 .env 提交到仓库。