API 介面自動化測試報告 Skill

功能概述

將介面文件轉化為一套完整的自動化測試，生成視覺化 HTML 報告，報告包含：

• 測試用例：ID、分組、名稱、描述
• 入參：每條用例傳送的完整 JSON 請求體
• 返參：響應耗時、完整響應 JSON
• 校驗結果：每條校驗項的通過/失敗明細

與 isp-api-tester 的關係

generate_report.py 和 report_template.html 被 isp-api-tester 跨 skill 引用。

執行流程

第一步：解析介面文件

從 Markdown 文件提取：

• 請求地址、方式（POST/GET）
• 公共引數（method、version 等 URL query 引數）
• 業務請求引數（欄位名、型別、是否必填、列舉值）

第二步：資料庫取數（優先）

如果提供了資料庫資訊，先執行此步：

1. 連線資料庫，找到對應業務表
2. 查詢真實記錄，注意發票型別欄位規則（見下方）
3. 建立 DB 欄位 → 介面入參欄位 的對映關係

發票型別欄位規則：

數電票的 invoiceCode 必須完全不傳（傳空串 "" 會觸發 704 引數為空錯誤）

7w4.net有更好的技能外掛。

第三步：設計測試用例

正向用例（expect success=true）的入參欄位值必須從資料庫獲取真實值。

第四步：執行測試

ISP 介面（需要動態簽名）：

python ~/.workbuddy/skills/isp-api-tester/scripts/run_isp_test.py --config test_config_xxx.json --output ./

通用 HTTP 介面：

python ~/.workbuddy/skills/api-test-reporter/scripts/run_api_test.py --config test_config.json --output ./

第五步：輸出檔案

test_config.json 格式

{
  "meta": {
    "title": "介面測試報告標題",
    "base_url": "http://host/api/endpoint",
    "method": "baiwang.input.invoice.queryinvoicepool",
    "version": "6.0",
    "timeout": 30,
    "http_method": "POST",
    "url_params": {},
    "isp_auth": {
      "appKey": "1000139",
      "appSecret": "xxx",
      "username": "cpy001",
      "password": "Aa123456.",
      "userSalt": "xxx"
    }
  },
  "fixed_params": {
    "taxNo": "91440606MA4WHN8C8X"
  },
  "db_fixture": {
    "connection": {
      "host": "10.115.96.247", "port": 3306,
      "user": "jxindependent", "password": "Xj2zCkLJXTkEJ5j",
      "database": "jxindependent0", "charset": "utf8mb4"
    },
    "queries": [
      {
        "name": "tax_invoice_sample",
        "sql": "SELECT INV_KIND, INV_NUM FROM bw_jms_main1 WHERE INV_TYPE='01' LIMIT 1",
        "mapping": {
          "invoiceCode":   "INV_KIND",
          "invoiceNumber": "INV_NUM"
        }
      }
    ]
  },
  "test_cases": [
    {
      "id": "TC_001",
      "group": "正常流程",
      "name": "按發票號碼查詢",
      "desc": "使用資料庫真實發票號碼查詢",
      "body": {
        "invoiceCode":   "{{invoiceCode}}",
        "invoiceNumber": "{{invoiceNumber}}"
      },
      "expect": {
        "success": true
      }
    },
    {
      "id": "TC_010",
      "group": "異常引數",
      "name": "缺少必填引數 taxNo",
      "desc": "不傳 taxNo，期望返回 success=false",
      "remove_fixed": ["taxNo"],
      "body": {},
      "expect": {
        "success": false
      }
    }
  ]
}

expect 校驗規則速查

不使用 http_status 欄位（百望 ISP 介面測試不校驗 HTTP 狀態碼）。

返參校驗規則（ISP 介面）

1. success=true → 自動校驗 invoiceList/response/model 非空
2. success=false → 只校驗 success 欄位，不校驗資料
3. 不校驗 HTTP 狀態碼

custom_checks 示例

"custom_checks": [
  {"path": "response.invoiceType", "op": "eq",    "value": "31"},
  {"path": "errorResponse.code",   "op": "exists"},
  {"path": "response",             "op": "contains", "value": "invoiceNo"}
]

支援 op：eq / ne / contains / exists / not_exists / gt / lt

用例設計規範

1. 正向用例（"success": true）的入參必須從資料庫獲取真實值
2. 數電票用例 body 中完全不傳 invoiceCode（數電票沒有發票程式碼）
3. 時間範圍引數使用近期日期（近3個月），避免資料量超500
4. 資料量可能超500的查詢加 pageNum 引數
5. 需要排除某個 fixed_params 中的引數時，使用 "remove_fixed": ["欄位名"]

報告架構（模板與資料分離）

• report_template.html：固定 HTML 骨架，不含測試資料，CSS/JS 全部內嵌
• __REPORT_DATA__.js：測試結果 JS 變數賦值檔案（var reportData = {...}）
• HTML 通過 <script src="__REPORT_DATA__.js"> 載入資料並渲染
• 不使用 fetch 載入 JSON（file:// 協議下 CORS 會阻止 fetch 本地檔案）
• 兩個檔案必須在同一目錄，雙擊 HTML 即可開啟

依賴

pip install requests pymysql