apidog-test-case

API 测试用例

前置条件：先阅读 ../apidog-cli/SKILL.md。如果稳定入口技能与此领域技能冲突，请以当前 CLI 帮助和此技能为准。对于 API 定义，请根据当前 CLI 帮助使用 endpoint、schema、folder 和相关命令。对于多步骤流程，请阅读 ../apidog-test-scenario/SKILL.md。

始终使用当前 CLI 帮助确认准确参数。创建或更新 API 测试用例时，请特别注意 categoryId 的显示风险、测试用例与测试场景的界限、requestBody/processor/assertion/extractor 结构，以及运行时验证。Agent 必须先使用 cli-schema validate 验证 payload，再写入，然后使用 get 确认保存的结构。

适用场景

• 在单个 endpoint 下创建自动化测试用例。
• 更新测试步骤、断言、变量提取器以及前置/后置处理器。
• 列出 endpoint 下的测试用例。
• 通过 caseId、endpointId 或 categoryId 运行 API 测试用例。
• 创建或维护测试数据集。
• 诊断客户端中缺少测试步骤、断言无效或提取的变量为空等问题。

不适用场景

• 多 endpoint 工作流编排或场景建模：使用 apidog-test-scenario。
• 仅运行现有场景、套件或 CI 命令：使用 apidog-test-automation。
• 仅编辑 API 定义、请求参数或响应模型：使用当前 CLI 帮助中的 endpoint/schema 命令。
• 仅查看测试报告：使用当前 CLI 帮助中的 test-report；执行和报告边界请使用 apidog-test-automation。

核心概念

概念	CLI 资源	说明
API 测试用例	test-case	绑定到 endpoint 的测试数据和步骤
测试分类	test-case category	测试用例分类；创建用例前使用它获取有效的 categoryId
测试数据集	test-data	用于迭代运行的数据源
API 定义	endpoint	用例的依赖项；不等同于用例本身
测试场景	test-scenario	边界不同的多步骤工作流编排

命令入口

使用当前 CLI 帮助了解 test-case、test-data 和 apidog run --test-case。使用 test-case category 获取 categoryId；当前的 test-case category 不支持 --endpoint。要查看 endpoint 下的用例，请使用 test-case list --endpoint <endpointId>。apidog run --test-case 仅接受 caseId。

将单 endpoint 用例导入测试场景时，不要在此技能中手写场景步骤。请切换到 apidog-test-scenario 并使用：

apidog test-scenario import-steps <scenarioId> --project <projectId> --source test-case --endpoint <endpointId> --ids <testCaseIds> --sync manual

标准创建流程

1. 确认项目和分支。
2. 使用 apidog endpoint list/get 定位 endpoint。
3. 运行 apidog test-case category --project <projectId> 获取有效的 categoryId；要检查 endpoint 下的现有用例，请运行 apidog test-case list --project <projectId> --endpoint <endpointId>。
4. 如果存在类似用例，请使用 list，然后用 get 获取一个作为模板。
5. 获取并验证 test-case-create schema。
6. 构建完整的 JSON payload；不要只创建一个仅包含 name/endpointId 的空壳。
7. 创建后立即运行 test-case get <caseId>，确认保存的后端结构。
8. 使用本地 JSON 报告运行一次，确认 requestBody、处理器、断言和脚本能在运行器中正常工作。
9. 如果要上传报告，请根据当前 CLI 帮助使用 test-report；如果缺少报告详情，请使用 apidog-test-automation 了解本地/云端报告的边界。

categoryId 是影响客户端显示的关键必填字段，并非普通的可选分类。无效的 categoryId 可能导致 CLI 的 get/list 能看到用例，但客户端分类列表中不可见或无法使用。创建用例前，务必通过 test-case category 获取有效 ID。

标准更新流程

更新前，始终先 get 原始结构，并在该完整结构上进行修改。然后根据 test-case-update 架构进行验证，以避免丢失现有步骤、断言、变量提取器或处理器。update 不是 JSON Patch，也不会按 id 合并数组元素。

test-case-create 和 test-case-update 架构包含处理器、断言、提取器和枚举的说明。首次编写处理器时，请先阅读架构；不要猜测字段名称、枚举值或旧版格式。目前，test-case-update 会根据 type 验证处理器 data；例如，extractor 会验证 variableType/subject/shareScope，assertion 会验证 subject/comparison，而 delay 要求 data 为数值。

test-case get 可能会返回空字符串作为 method。这并不表示客户端显示的 HTTP 方法有误；客户端通常会从绑定的端点显示该方法。目前的 test-case-update 架构接受这种回读结构。除非用户明确要求更改绑定的端点或请求方法，否则不要猜测并重写该方法。

测试步骤显示规则

如果用户关心客户端显示效果，请验证以下所有内容：

1. 创建或更新后运行 test-case get。
2. 确认后端已保存步骤、断言、提取器和处理器。
3. 确认字段不是空数组、空对象，也没有写入错误的层级。
4. 如果 CLI 返回成功，但客户端未显示数据，请切换到 apidog-cli-checkup，并先确认项目、分支、端点、categoryId 和回读结构。

内容和处理器结构

• requestBody.data 必须是字符串；不要将 JSON Body 写成对象。
• 多行 JSON 正文、预脚本和后脚本应使用 \n 格式化；这样可以提高客户端的可读性，且不会改变执行语义。
• preProcessors 和 postProcessors 使用扁平结构 { id, type, data, defaultEnable, enable }；不要使用旧版嵌套结构 { type, config }。
• 处理器应使用稳定的 id 值，尤其是 assertion、extractor 和 customScript；缺少 ID 可能仍能通过验证，但会使运行器或客户端解析器产生混淆。
• 提取全局变量时，使用 data.variableType: "globals"；如果需要指定作用域，优先使用 data.shareScope: "PROJECT"。TEAM 是团队级作用域，可能依赖付费功能；除非明确要求，否则不要默认使用。
• 写入前始终运行 cli-schema validate，写入后运行 test-case get。

示例：

{
  "requestBody": {
    "type": "application/json",
    "data": "{\n  \"name\": \"Demo\",\n  \"description\": \"Readable in client\"\n}"
  },
  "postProcessors": [
    {
      "id": "postProcessors.0.customScript",
      "type": "customScript",
      "data": "pm.test('returns id', function () {\n  var body = pm.response.json();\n  pm.expect(body.data.id).to.exist;\n});",
      "defaultEnable": true,
      "enable": true
    },
    {
      "id": "postProcessors.1.extractor",
      "type": "extractor",
      "data": {
        "variableName": "project_pet_name",
        "variableType": "globals",
        "shareScope": "PROJECT",
        "subject": "responseJson",
        "expression": "$.name"
      },
      "defaultEnable": true,
      "enable": true
    }
  ]
}

运行和验证

• 如果执行行为很重要，请在写入后运行用例。
• 使用显式的 --environment 以确保结果可复现。
• 诊断运行器行为时，生成本地 JSON 报告。
• 不要将客户端显示成功视为执行成功；需要时应同时验证已保存的结构和运行结果。

常见恢复方法

症状	操作
用例已创建，但客户端中未显示	检查项目、分支、端点和有效的 categoryId
更新后步骤丢失	根据完整的 get 输出重建；update 不会修补数组
断言未运行	检查处理器的 type、data、enable 和生成的报告
提取出的变量为空	检查 subject、JSONPath、响应结构、variableType 和 shareScope
找不到新的 CLI 参数	使用 apidog-cli-checkup 验证版本和帮助信息