Metadata-Version: 2.4
Name: fapitest
Version: 1.0.19
Summary: JSON-driven OpenAPI integration test CLI (TUI + suites)
Author: DBApp Security
License-Expression: LicenseRef-Proprietary
Project-URL: Homepage, https://gitlab.info.dbappsecurity.com.cn/base/fapitest
Project-URL: Documentation, https://gitlab.info.dbappsecurity.com.cn/base/fapitest/-/blob/main/docs/2026-05-29-apitest-framework-usage.md
Project-URL: Issues, https://gitlab.info.dbappsecurity.com.cn/base/fapitest/-/issues
Keywords: fapitest,apitest,openapi,api-testing
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 **包名与命令**均为 **`fapitest`**（`uvx fapitest` 即可；公网 [apitest](https://pypi.org/project/apitest/) 为其他项目，勿混用）。

需已安装 [uv](https://docs.astral.sh/uv/)：

```powershell
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`](./docs/publishing-pypi.md)「数据目录」与 FAQ。

持久安装：

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

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

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

```powershell
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）

```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 fapitest`；任意目录用 `uvx fapitest`（见上文方式 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）：三列（组 / 用例 / 详情），完整快捷键与过滤见使用文档 §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 切换（全局参数写在子命令前）：

```powershell
# 使用用户空间 ~/.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](https://httpbin.org)：

```powershell
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`** 可顺序切换到下一环境。

### 目录

```text
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/           # 执行产物
```

## 测试

```powershell
uv run pytest -q
```

## Suite 数据布局

```text
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 可配置）示例：

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

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

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

## 安全说明

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