fapitest 1.0.31

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）：三列（组 / 用例 / 详情），完整快捷键与过滤见使用文档 §8.1
uv run fapitest

| 键 | 作用 |
|----|------|
| `g` | 跑当前组 |
| `c` | 跑当前用例 |
| `a` | 跑全部组 |
| `e` | **选择环境**（列表点选，Enter 确认） |
| `r` | **选择角色**（多选；默认全选当前环境全部角色） |
| `ctrl+r` | **重载 `.env`** 并刷新当前 suite（改 token 后无需退出 TUI） |
| `n` | 下一环境（顺序轮换） |
| `l` / `ctrl+l` | 折叠/展开运行日志 / 清空日志 |
| `s` / `b` | **返回 Suite 选择**（多个 suite 时；Esc 取消并回到当前 suite） |
| `q` | 退出（也可点底部 Footer 的 Quit） |

详情区会检测本地 `case.json` / `payload.json` 等变更并自动刷新（约 1s）；其余能力（`/ 过滤`、双击启用用例等）见 [`docs/2026-05-29-apitest-framework-usage.md`](./docs/2026-05-29-apitest-framework-usage.md) §8.1。

日志区使用 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）生成

HTML 报告固定为 core/templates/report.html（通过率、断言摘要、维度统计、用例明细与 HTTP 展开）。

非 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/groups/<组>/<case-id>/ 新建目录
2. 编写 payload.json 与 case.json（含 assertions；flow 的 step 文件相对 case 目录）
3. 确认 group.json 存在（用例由子目录自动发现，无需 cases[] 列表）
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
      <case-id>/
        case.json
        payload.json
plugins/           # 项目级自定义 auth_*.py（可选）
reports/           # 执行产物

测试

uv run pytest -q

Suite 数据布局

suites/<suite>/
  suite.json              # 勿含 suiteMode（v1.0+ 报错）
  groups/
    <group>/
      group.json          # 必填
      <case-id>/
        case.json         # 用例元信息、assertions、flow steps
        payload.json      # single 必填；flow 可选（缺省 {}）

payload.json 规则：

• bodyType=json：payload.json 作为请求 body
• bodyType=form-data / form-urlencoded：payload.json 作为 form 对象
• 若写成显式结构 { "body": ..., "query": ..., "form": ... }，按字段映射

断言 DSL（case 或 flow step 可配置）示例：

{
  "assertions": {
    "type": "all",
    "items": [
      { "type": "http_status_in", "expected": [200] },
      { "type": "json_eq", "path": "$.code", "expected": 0 }
    ]
  }
}

鉴权异常注入（在 auth plugin 之后执行）：

{
  "authOverride": {
    "setHeaders": { "sign": "invalid" },
    "dropQuery": ["appKey"]
  }
}

安全说明

• 报告和失败快照会保留真实请求/响应内容，便于测试定位问题。
• 勿将 .env、真实密钥和敏感报告产物提交到仓库。