Metadata-Version: 2.4
Name: apist
Version: 26.8
Summary: Apist, spreadsheet-driven API automation testing
Home-page: https://gitee.com/teark/apist.git
Author: Teark
Author-email: 913355434@qq.com
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests
Requires-Dist: openpyxl
Requires-Dist: bottle
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# Apist

Apist 是一个由表格驱动的接口自动化测试工具。测试人员只需维护 Excel 或飞书电子表格，程序会执行 HTTP 请求、判断结果、回写状态码/响应/测试结果，并生成 HTML 报告。

## 安装

```bash
pip install .
```

安装后可直接复制内置表格模板：

```bash
apist --template api-template.xlsx
```

模板包含 `API` 和 `配置` 两个工作表，以及全部必需列和可选列。也可以指定输出路径：

```bash
apist --template ./examples/api-template.xlsx
```

读取飞书表格还需要安装并登录官方 [lark-cli](https://github.com/larksuite/cli)：

```bash
lark-cli doctor
lark-cli whoami
```

程序没有检测到 `lark-cli`、登录失效、没有表格权限或表格格式不正确时，会输出对应的中文提示。

## 表格规范

第一个工作表是测试用例表，必须包含以下 12 个表头：

`优先级`、`接口说明`、`请求方式`、`url`、`请求参数`、`状态码`、`响应内容`、`后置-响应提取`、`期望值`、`测试结果`、`断言类型`、`耗时`。

表头必须放在第一行且名称唯一，列顺序可以自由调整。程序会按表头动态定位读取列以及“状态码”、“响应内容”、“测试结果”回写列。

`耗时` 由程序自动回填，单位为秒并保留三位小数，例如 `0.238`。

接口 Sheet 可选增加 `一键cURL` 列。存在该列时，程序会将本次实际请求生成可直接复制到终端的 cURL 命令并回填；没有该列时不生成、不回填。GET/HEAD 会生成 Query 参数，其他请求会生成请求体和请求头。

浏览器 Network 面板的 “Copy as cURL” 内容可放入 API Sheet 的 `解析cURL` 列，再通过 `--parse` 导入。程序只把请求方式、URL 和实际请求参数写入用例；浏览器 Header、Cookie、Authorization 及内部请求类型标记均不会写入，鉴权由登录接口返回的 `access_token` 在运行时注入。JSON、表单和 multipart 的 Content-Type 由 requests 自动生成。

可选的 `配置` 工作表同时存放请求头和邮件配置：第一行是配置名称，第二行是配置值。

`配置所属人` 仅用于记录。程序从上到下查找 `是否为默认配置` 等于 `是` 的第一行，将该行的 `用户名`、`密码` 注册为全局变量，可在请求参数中通过 `${用户名}`、`${密码}` 引用；没有默认配置时不注入这两个变量。报告生成后会追加到 `测试报告存档` 列的最后一行；飞书表格写入附件，本地表格写入报告绝对路径。配置列均按第一行名称动态识别，可以自由调整顺序。

配置 Sheet 使用一个 `自定义变量` 列定义全局变量。单个变量可写成 `name=lily`；多个变量使用列表形式，例如 `[var1=1, var2='hello']`。数字、布尔值、列表和字典会保留实际类型，未加引号的普通文本按字符串处理。接口用例通过 `${name}`、`${var1}` 调用；变量使用安全字面量解析，不执行代码。旧的 `我的变量1`、`我的变量2` 等列不再生效。

邮件配置名称为 `发送邮件`、`邮箱账号`、`邮箱授权码`、`收件人`、`邮件标题`、`邮件正文`、`SMTP服务器`、`SMTP端口`、`SMTP加密方式`。`密码` 是接口全局变量，`邮箱授权码` 专用于邮件，两者互不冲突。其他配置列仅作为记录，不会自动转换为 HTTP 请求头。`发送邮件` 为 `true`（也兼容 `y`）时自动发送邮件，并附带本次生成的 HTML 测试报告。SMTP 默认使用 `smtp.qq.com:465` 和 SSL，`SMTP加密方式` 可设为 `ssl`、`starttls` 或 `none`。

当接口 URL 包含 `login` 且成功响应中存在 `access_token` 时，程序会自动生成 `Authorization: Bearer <access_token>` 并用于后续请求，不要求额外配置后置提取。非登录接口即使返回同名字段也不会覆盖鉴权。若请求参数中还需要引用 Token，可另外配置 `token=$..access_token`。Token 仅保存在本次运行内存中，不会回写配置 Sheet。

请求参数列只填写实际参数，不使用任何内部前缀。标准 JSON 自动按 JSON 发送；`a=1&b=2` 形式自动按表单或查询参数处理；普通文本自动按 raw 发送；JSON 对象中包含 `@文件路径` 时自动按 multipart 处理。GET/HEAD 查询字符串会自动拼接到 URL。后置提取支持 JSONPath 和正则表达式，一格可写多行，例如 `student_id=$.data.id` 和 `student_name=$.data.name`。使用 `student_ids[]=$.data.lists[*].id` 可保存全部匹配结果为数组。变量可在请求参数和 URL 中通过 `${变量名}` 引用。

例如 `{"token":"${token}","id":"${user_id}"}` 会自动依赖 `token` 和 `user_id`。缺失、重复、循环依赖以及生产者提取失败都会被明确标记为失败，不会继续发送依赖请求。

未运行的生产者只有在历史“测试结果”为 `PASS`、响应内容非空且提取成功时才可提供变量，程序会在日志中明确提示变量来自历史响应。正式执行前会一次性检查请求方式、URL、参数格式、断言、后置提取和依赖关系；存在配置问题时不会发送任何请求。

状态码固定要求属于 2xx。`断言类型` 与 `期望值` 配合使用，空白时默认为 `包含`，可选值仅为 `包含`、`等于`、`不包含`；期望值为空时仅校验状态码。

多个期望值使用 JSON 数组，例如 `["success", {"err_code": 0}, {"data": {"id": 1}}]`。`包含`要求全部满足，`不包含`要求全部不存在，`等于`匹配其中任意一个。字符串按文本判断，字典、列表、数字、布尔值和 `null` 按 JSON 结构递归判断。

连接超时固定为 10 秒，读取超时固定为 30 秒，默认不重试。报告会隐藏密码、Cookie、Authorization、Token 等敏感字段。

## 运行

本地 `.xlsx`：

```bash
apist -l api.xlsx
```

飞书电子表格或知识库中的电子表格：

```bash
apist -l 'https://example.feishu.cn/wiki/xxx'
```

`-l/--link` 接受本地表格文件路径或飞书电子表格链接。使用链接时，默认执行优先级为 `1` 的用例并将结果回写飞书表格。未指定工作表时，程序会自动选择包含完整接口表头的 Sheet；链接包含 `?sheet=<sheet_id>` 时则直接选择对应工作表。报告始终在本地生成；仅当指定 `-r=true` 时，HTML 报告才会作为电子表格素材上传，并以附件形式追加到配置 Sheet 的 `测试报告存档` 列。素材不会显示在个人云盘。链接包含 `?` 或 `&` 时请使用引号。

指定工作表名称、运行其它优先级、发送邮件以及不自动打开报告：

```bash
apist -l api.xlsx -s Sheet1 -p 2 --no-open
apist -l api.xlsx -p 0 --check
apist -l api.xlsx --failed
apist -l api.xlsx --json=true
apist -l api.xlsx --parse
apist -l 'https://example.feishu.cn/wiki/xxx' --parse
apist -l 'https://example.feishu.cn/wiki/xxx' -r=true
```

优先级只接受数字表达式：`-p 2` 执行单个优先级，`-p 2,3` 执行多个优先级，`-p 2-5` 执行连续范围，`-p 1,3-5` 支持混合写法，`-p 0` 执行全部用例。文本 `all` 不再支持。`--check` 只执行表头、请求、断言、提取和依赖预检，不发送请求、不回写结果，也不生成报告。

`--failed` 只重新执行表格中上次结果为 `FAIL` 的用例。执行过程中按 Ctrl+C 时，已完成用例和当前取消用例会正常回写并生成报告，命令最终返回 `130`。

API Sheet 可增加可选列 `解析cURL`，用于暂存浏览器 Copy as cURL 的内容。`--parse` 会读取该列中的全部非空内容，将请求方式、URL 和请求参数解析回写到 cURL 所在行，不会新增行或立即执行。只有所有内容均解析成功后才开始更新；更新成功后仅清空原来的 `解析cURL` 单元格，不影响同一行其他内容。解析行默认写入优先级 `1`、接口说明 `cURL导入`、断言类型 `包含`，执行时可正常使用 `-p` 筛选。

也可作为 Python 库调用：

```python
from apist import Api

Api("api.xlsx", priority=1, is_email=False)
Api("https://example.feishu.cn/wiki/xxx", sheet="Sheet1", priority=1, save=True)
```

旧版的 `from apist.apist import Api` 导入方式仍然可用。

报告保存在数据源所在目录的 `reports/` 中；在线表格的报告保存在当前工作目录。固定路径 `report.html` 始终指向最近一次报告。

失败用例的报告详情会展示状态码、断言、依赖或提取失败的具体原因。遇到 `401/403` 时还会说明请求是否携带 Authorization 及其来源。网络异常会区分 DNS、连接/读取超时、SSL、代理、连接拒绝和重定向错误。详情同时记录脱敏后的响应头与重定向链。本地 `.xlsx` 的执行结果会在全部用例处理完成后一次性原子写入；飞书连续结果会合并为批量范围回写。

本地 `.xlsx` 会创建隐藏的 `_apist变量缓存` Sheet，保存变量 JSON 值、来源行、提取时间和来源结果，避免响应因 Excel 单元格长度限制被截断后无法再次提取。变量覆盖顺序为：本次响应 > 配置变量 > 历史缓存/历史 PASS 响应；覆盖发生时会输出来源提示。

命令退出码适用于 CI：全部通过或 `--check` 通过返回 `0`，存在失败用例返回 `1`，配置/表格/程序输入错误返回 `2`，用户取消返回 `130`。

每次执行始终生成 HTML 报告和同名 Markdown 摘要。仅当指定 `--json=true` 时额外生成同名 JSON 报告，包含运行参数、汇总、脱敏变量和结构化用例结果。HTML 报告支持搜索、成功/失败筛选、复制 URL、复制 cURL，并展示本次数据源、优先级、Python 版本和启动时间。

## 开发检查

```bash
pip install -r requirements-dev.txt
ruff check apist tests
python -m unittest discover -s tests -q
```

请求解析、断言、响应提取和结果模型已拆分为独立模块，执行结果统一使用 `CaseResult`，本地与飞书数据源通过相同的读取/回写契约测试。

## 注意事项

- 当前本地格式仅支持 `.xlsx`，不再支持 `.xls`。
- 飞书数据源仅支持普通电子表格（Sheet），不支持飞书多维表格（Base）。
- 在线执行会根据表头名称动态定位状态码、响应内容和测试结果列，列顺序可以随时调整。
- 默认仅执行优先级为 `1` 的用例。支持 `-p 2`、`-p 2,3`、`-p 2-5`、`-p 1,3-5`；`-p 0` 执行所有优先级的有效用例。
