\r \r

API 接口自动化测试报告 Skill\r

\r

功能概述\r

\r 将接口文档转化为一套完整的自动化测试，生成可视化 HTML 报告，报告包含：\r

• 测试用例：ID、分组、名称、描述\r
• 入参：每条用例发送的完整 JSON 请求体\r
• 返参：响应耗时、完整响应 JSON\r
• 校验结果：每条校验项的通过/失败明细\r \r

与 isp-api-tester 的关系\r

\r | 场景 | 使用的执行器 |\r |------|------------|\r | 百望 ISP 开放平台接口 | isp-api-tester 的 run_isp_test.py（内置动态签名） |\r | 通用 HTTP 接口 | 本 skill 的 run_api_test.py |\r \r generate_report.py 和 report_template.html 被 isp-api-tester 跨 skill 引用。\r \r ---\r \r

执行流程\r

\r

第一步：解析接口文档\r

\r 从 Markdown 文档提取：\r

• 请求地址、方式（POST/GET）\r
• 公共参数（method、version 等 URL query 参数）\r
• 业务请求参数（字段名、类型、是否必填、枚举值）\r \r

第二步：数据库取数（优先）\r

\r 如果提供了数据库信息，先执行此步：\r

1. 连接数据库，找到对应业务表\r
2. 查询真实记录，注意发票类型字段规则（见下方）\r
3. 建立 DB 字段 → 接口入参字段 的映射关系\r \r 发票类型字段规则：\r \r | 票种大类 | invoiceCode | invoiceNumber |\r |---------|:-----------:|:-------------:|\r | 数电票（31/32/51/59/61/83/84） | ❌ 不传 | E_INV_NUM（20位数电号码） |\r | 税控票（01/03/04/08/10/11/14/15） | INV_KIND | INV_NUM |\r | 数电纸票（85/86/87/88） | INV_KIND | INV_NUM |\r \r

数电票的 invoiceCode 必须完全不传（传空串 "" 会触发 704 参数为空错误）\r \r

第三步：设计测试用例\r

\r | 分组 | 策略 |\r |------|------|\r | 必填参数验证 | 每个必填字段：缺失1条 + 空字符串1条 |\r | 分页参数验证 | 正常值 + 边界值 + 负数 |\r | 枚举字段验证 | 每个合法枚举值1条 + 非法值1条 |\r | 日期范围筛选 | 正常范围 + 起止倒置 + 格式错误 |\r | 状态/标记字段 | 每个合法值各1条 |\r | 综合多条件组合 | 2~3字段组合 + 全量字段组合 |\r | 边界与异常参数 | 超长字段 + 空body + 类型错误 |\r \r 正向用例（expect success=true）的入参字段值必须从数据库获取真实值。\r \r

第四步：执行测试\r

\r ISP 接口（需要动态签名）：\r

python ~/.workbuddy/skills/isp-api-tester/scripts/run_isp_test.py --config test_config_xxx.json --output ./\r
```\r
\r
**通用 HTTP 接口：**\r
```bash\r
python ~/.workbuddy/skills/api-test-reporter/scripts/run_api_test.py --config test_config.json --output ./\r
```\r
\r
### 第五步：输出文件\r
\r
| 文件 | 说明 |\r
|------|------|\r
| `test_report_\x3Cmethod>_\x3Ctimestamp>.html` | 可视化报告（双击打开） |\r
| `__REPORT_DATA__.js` | 报告数据文件（与 HTML 同目录，不可删） |\r
| `test_results_\x3Cmethod>_\x3Ctimestamp>.json` | 原始结果 JSON |\r
\r
---\r
\r
## test_config.json 格式\r
\r
```json\r
{\r
  "meta": {\r
    "title": "接口测试报告标题",\r
    "base_url": "http://host/api/endpoint",\r
    "method": "baiwang.input.invoice.queryinvoicepool",\r
    "version": "6.0",\r
    "timeout": 30,\r
    "http_method": "POST",\r
    "url_params": {},\r
    "isp_auth": {\r
      "appKey": "1000139",\r
      "appSecret": "xxx",\r
      "username": "cpy001",\r
      "password": "Aa123456.",\r
      "userSalt": "xxx"\r
    }\r
  },\r
  "fixed_params": {\r
    "taxNo": "91440606MA4WHN8C8X"\r
  },\r
  "db_fixture": {\r
    "connection": {\r
      "host": "10.115.96.247", "port": 3306,\r
      "user": "jxindependent", "password": "Xj2zCkLJXTkEJ5j",\r
      "database": "jxindependent0", "charset": "utf8mb4"\r
    },\r
    "queries": [\r
      {\r
        "name": "tax_invoice_sample",\r
        "sql": "SELECT INV_KIND, INV_NUM FROM bw_jms_main1 WHERE INV_TYPE='01' LIMIT 1",\r
        "mapping": {\r
          "invoiceCode":   "INV_KIND",\r
          "invoiceNumber": "INV_NUM"\r
        }\r
      }\r
    ]\r
  },\r
  "test_cases": [\r
    {\r
      "id": "TC_001",\r
      "group": "正常流程",\r
      "name": "按发票号码查询",\r
      "desc": "使用数据库真实发票号码查询",\r
      "body": {\r
        "invoiceCode":   "{{invoiceCode}}",\r
        "invoiceNumber": "{{invoiceNumber}}"\r
      },\r
      "expect": {\r
        "success": true\r
      }\r
    },\r
    {\r
      "id": "TC_010",\r
      "group": "异常参数",\r
      "name": "缺少必填参数 taxNo",\r
      "desc": "不传 taxNo，期望返回 success=false",\r
      "remove_fixed": ["taxNo"],\r
      "body": {},\r
      "expect": {\r
        "success": false\r
      }\r
    }\r
  ]\r
}\r
```\r
\r
---\r
\r
## `expect` 校验规则速查\r
\r
| 字段 | 类型 | 说明 |\r
|------|------|------|\r
| `success` | bool | 校验响应体 success 字段值 |\r
| `response.{field}` | any | 校验 response 节点下的字段，如 `"response.invoiceType": "31"` |\r
| `model.{field}` | any | 校验 model 节点下的字段 |\r
| `has_response` | bool | 期望 response/model 字段存在且非 null |\r
| `check_page_data` | bool | 期望返回列表/分页数据 |\r
| `error_field_exists` | bool | 期望 errorResponse 字段存在 |\r
| `custom_checks` | list | 自定义路径校验（见下方） |\r
\r
**不使用 `http_status` 字段**（百望 ISP 接口测试不校验 HTTP 状态码）。\r
\r
### 返参校验规则（ISP 接口）\r
\r
1. **`success=true`** → 自动校验 invoiceList/response/model 非空\r
2. **`success=false`** → 只校验 success 字段，不校验数据\r
3. **不校验 HTTP 状态码**\r
\r
### custom_checks 示例\r
\r
```json\r
"custom_checks": [\r
  {"path": "response.invoiceType", "op": "eq",    "value": "31"},\r
  {"path": "errorResponse.code",   "op": "exists"},\r
  {"path": "response",             "op": "contains", "value": "invoiceNo"}\r
]\r
```\r
\r
支持 `op`：`eq` / `ne` / `contains` / `exists` / `not_exists` / `gt` / `lt`\r
\r
---\r
\r
## 用例设计规范\r
\r
1. 正向用例（`"success": true`）的入参**必须从数据库获取真实值**\r
2. 数电票用例 body 中**完全不传 invoiceCode**（数电票没有发票代码）\r
3. 时间范围参数使用近期日期（近3个月），避免数据量超500\r
4. 数据量可能超500的查询加 `pageNum` 参数\r
5. 需要排除某个 fixed_params 中的参数时，使用 `"remove_fixed": ["字段名"]`\r
\r
---\r
\r
## 报告架构（模板与数据分离）\r
\r
- `report_template.html`：固定 HTML 骨架，不含测试数据，CSS/JS 全部内嵌\r
- `__REPORT_DATA__.js`：测试结果 JS 变量赋值文件（`var reportData = {...}`）\r
- HTML 通过 `\x3Cscript src="__REPORT_DATA__.js">` 加载数据并渲染\r
- **不使用 fetch 加载 JSON**（`file://` 协议下 CORS 会阻止 fetch 本地文件）\r
- 两个文件必须在同一目录，双击 HTML 即可打开\r
\r
---\r
\r
## 依赖\r
\r
```bash\r
pip install requests pymysql\r
```\r