name: api-test-reporter description: This skill should be used when the user wants to perform automated API interface testing based on an interface document (Markdown or other format) and generate a visual HTML test report. It is suitable for any HTTP POST/GET interface that accepts JSON parameters. The skill guides the agent to parse interface documentation, design test cases by parameter groups (required fields, pagination, enums, date ranges, numeric ranges, status flags, combined scenarios, boundary/exception cases), execute all test cases, and generate a structured HTML report containing test case details, request parameters, response data, and validation results. Trigger phrases include: "介面測試", "API測試", "根據介面文件測試", "生成測試報告", "逐個驗證引數", "自動化測試介面". This skill should be used when the user wants to perform automated API interface testing based on an interface document (Markdown or other format) and generate a visual HTML test report. It is suitable for any HTTP POST/GET interface that accepts JSON parameters. The skill guides the agent to parse interface documentation, design test cases by parameter groups (required fields, pagination, enums, date ranges, numeric ranges, status flags, combined scenarios, boundary/exception cases), execute all test cases, and generate a structured HTML report containing test case details, request parameters, response data, and validation results. Trigger phrases include: "介面測試", "API測試", "根據介面文件測試", "生成測試報告", "逐個驗證引數", "自動化測試介面". allowed-tools: disable: true

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 引數） - 業務請求引數（欄位名、型別、是否必填、列舉值）

想要更強大的技能外掛，就來小蔥技能站7w4.net看看吧。

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

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

發票型別欄位規則：

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

第三步：設計測試用例

正向用例（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