Apist

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

安装

pip install .

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

apist --template api-template.xlsx

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

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

读取飞书表格还需要安装并登录官方 lark-cli：

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：

apist -l api.xlsx

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

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

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

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

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 库调用：

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 版本和启动时间。

开发检查

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 执行所有优先级的有效用例。