Pipeline YAML Schema 参考

本文档提供测试流水线 YAML 结构的完整技术参考。有关使用示例和最佳实践，请参阅 Pipeline 编写指南和示例。

Schema 版本

Testany 当前兼容 rule/v1.2 与 rule/v1.3。

ℹ️

对于所有新建 Pipeline，Testany 明确推荐使用 rule/v1.3。rule/v1.2 仅用于兼容历史 Pipeline，不具备 case 级并行执行能力。

版本选择建议

版本	状态	说明
`rule/v1.3`	推荐	适用于所有新建 Pipeline；支持 case 级并行执行，并保持 `whenPassed` / `whenFailed` / `expect` / `relay` 语义
`rule/v1.2`	兼容保留	历史 Pipeline 可继续运行；不支持 case 级并行执行
`rule/v1.1`	兼容保留	仅供更早期旧 Pipeline 向后兼容

`rule/v1.3` 的默认并发度

当 Pipeline 使用 rule/v1.3 时，平台会根据当前实例类型决定默认实际并发度：

社区版默认 2
社区版付费用户默认 4
企业版默认 8

如果同一时刻语义上可并行的 case 数多于当前工作区可用并发度，平台会排队调度，而不是一次性全部启动；当槽位不足时，同一 ready 波次内按 YAML 顺序补位启动。

顶层结构

YAML
kind: rule/v1.3
spec:
  rules:
    - run: <TEST-CASE-KEY>
      # ... 规则字段

字段	类型	必填	说明
`kind`	string	是	Schema 版本标识符。新建 Pipeline 推荐使用 `rule/v1.3`；`rule/v1.2` 仅用于兼容历史 Pipeline。
`spec`	object	是	Pipeline 规格容器。
`spec.rules`	array	是	定义 Pipeline 执行流程的规则对象列表。必须至少包含一条规则。

Rule 对象

rules 数组中的每条规则定义要执行的测试用例及其触发条件。

YAML
- run: AC2F5A50
  whenPassed: 9686C618
  expect: fail
  relay:
    - key: ACCESS_TOKEN
      refKey: 9686C618/ACCESS_TOKEN
      nonSecret: true

Rule 字段

字段	类型	必填	默认值	说明
`run`	string	是	-	要执行的测试用例 Key。在同一 Pipeline 中必须唯一。
`whenPassed`	string	否	-	条件：仅当指定用例通过时执行此规则。
`whenFailed`	string	否	-	条件：仅当指定用例失败时执行此规则。
`expect`	string	否	`pass`	预期结果。当测试用例预期失败时（如负向测试）使用 `fail`。
`relay`	array	否	`[]`	用于在用例之间传递变量的中继配置列表。可用于 `rule/v1.2` 和 `rule/v1.3`。

条件字段：`whenPassed` 与 `whenFailed`

⚠️

whenPassed 和 whenFailed 互斥。同一规则不能同时使用两者。

字段	触发条件
`whenPassed`	被引用的用例向 Pipeline 报告 `Passed`。注意：设置了 `expect: fail` 的用例无论实际结果如何，都会报告 `Passed`。
`whenFailed`	被引用的用例向 Pipeline 报告 `Failed`、`Aborted` 或 `Timeout`。注意：设置了 `expect: fail` 的用例永远不会触发此条件。

校验规则：

被引用的测试用例 Key必须在前面的规则中定义。
如果既没有 whenPassed 也没有 whenFailed，规则将无条件执行（或在提供 relay 的测试脚本完成后执行，如果定义了 relay）。

`expect` 字段

expect 字段改变测试结果向 Pipeline 的报告方式。

值	行为
`pass`（默认）	用例向 Pipeline 报告其实际执行结果。
`fail`	用例始终向 Pipeline 报告 `Passed`，无论实际执行结果如何。适用于预期测试会失败但不希望它导致 Pipeline 失败的场景。

关键点： 设置了 expect: fail 的用例始终向 Pipeline 报告 Passed。因此，后续用例应使用 whenPassed（而非 whenFailed）来跟随它。

YAML
- run: A1B2C3D4             # 测试用例：验证设置
- run: E5F6A7B8             # 测试用例：测试无效输入
  whenPassed: A1B2C3D4
  expect: fail              # 始终向 Pipeline 报告 "Passed"
- run: C9D0E1F2             # 测试用例：下一步
  whenPassed: E5F6A7B8      # 使用 whenPassed，而非 whenFailed

Relay 对象

relay 字段启用输出中继 - 将环境变量从一个用例传递到另一个用例。

YAML
relay:
  - key: ACCESS_TOKEN
    refKey: 5DC1106D/ACCESS_TOKEN
    nonSecret: true

Relay 字段

字段	类型	必填	默认值	说明
`key`	string	是	-	为当前用例定义的环境变量名。
`refKey`	string	是	-	源变量引用。格式：`<源用例KEY>/<变量名>`。
`nonSecret`	boolean	否	`false`	如果为 `true`，值可以在日志中打印。如果为 `false`（默认），值被视为敏感数据，在日志中会被遮蔽。

Relay 校验规则

⚠️

以下配置会导致校验错误：

缺少字段： key 和 refKey 都是必填项。
未定义的源： 源用例（refKey 前缀）必须在前面的规则中定义。
Relay 与 whenFailed 一起使用： 不能从使用 whenFailed 引用的用例进行 relay。
并行歧义： 在 rule/v1.3 中，提供 relay 的测试脚本必须能够在消费 relay 的测试脚本启动前确定完成；如果两者可能处于同一并发波次，配置会被拒绝。

无效示例：

YAML
# 错误：不能从失败的用例进行 relay
- run: 5385B189
- run: A3D9405F
  whenFailed: 5385B189      # 这个用例失败了
  relay:
    - key: NEW_URL
      refKey: 5385B189/NEW_URL  # 不能从失败的用例 relay

隐式 `whenPassed` 行为

如果规则定义了 relay 但没有显式的 whenPassed 或 whenFailed，系统会自动添加 whenPassed 引用第一个提供 relay 的测试脚本。

YAML
# 这两种配置是等效的：

# 显式
- run: 5DC1106D
- run: DE96D6A0
  whenPassed: 5DC1106D
  relay:
    - key: TOKEN
      refKey: 5DC1106D/TOKEN

# 隐式（系统自动添加 whenPassed）
- run: 5DC1106D
- run: DE96D6A0
  relay:
    - key: TOKEN
      refKey: 5DC1106D/TOKEN

完整校验规则

平台根据以下规则校验 Pipeline YAML：

规则	错误信息
`rules` 数组为空	`definition error: no rules defined`
同一规则同时有 `whenPassed` 和 `whenFailed`	`rule N error: multiple precondition`
条件引用了未定义的用例	`rule N error: precondition undefined`
重复的 `run` 值	`rule N error: duplicate run`
Relay 缺少 `key` 或 `refKey`	`rule N error: relay must contain both a key and a refKey`
Relay 引用了未定义的用例	`rule N error: relay undefined for <refKey>`
从 `whenFailed` 用例进行 Relay	`rule N error: The identifier <case> was used in the relay reference. The precondition for the current rule should be set to whenPassed instead of whenFailed.`
同一规则中重复的 relay key	`rule N error: duplicate relay`

快速参考

最简 Pipeline

YAML
kind: rule/v1.3
spec:
  rules:
    - run: A1B2C3D4           # 你的测试用例 Key

顺序执行（通过链）

YAML
kind: rule/v1.3
spec:
  rules:
    - run: A1B2C3D4           # 步骤 1
    - run: E5F6A7B8           # 步骤 2
      whenPassed: A1B2C3D4
    - run: C9D0E1F2           # 步骤 3
      whenPassed: E5F6A7B8

并行执行（无条件，推荐使用 `rule/v1.3`）

YAML
kind: rule/v1.3
spec:
  rules:
    - run: A1B2C3D4           # 测试 A
    - run: E5F6A7B8           # 测试 B
    - run: C9D0E1F2           # 测试 C

📝

在 rule/v1.3 中，上面三个 root case 在语义上可以并行执行；如果当前工作区可用并发槽位不足，平台会按 YAML 顺序分批补位启动。相同形状的 rule/v1.2 Pipeline 仍按 legacy 串行语义执行。

使用输出中继

YAML
kind: rule/v1.3
spec:
  rules:
    - run: A1B2C3D4           # 登录测试用例
    - run: E5F6A7B8           # 创建订单测试用例
      whenPassed: A1B2C3D4
      relay:
        - key: ORDER_ID
          refKey: A1B2C3D4/ORDER_ID
        - key: ITEM_COUNT
          refKey: A1B2C3D4/ITEM_COUNT
          nonSecret: true

负向测试

YAML
kind: rule/v1.3
spec:
  rules:
    - run: A1B2C3D4           # 测试用例：测试无效输入
      expect: fail            # 无论实际结果如何，始终报告 "Passed"
    - run: E5F6A7B8           # 测试用例：下一个测试
      whenPassed: A1B2C3D4    # 使用 whenPassed，因为 expect:fail 始终报告 Passed

另请参阅

Pipeline 编写指南和示例 - 使用示例和最佳实践
使用输出中继让测试更健壮灵活 - 输出中继详细概念
管理测试流水线 - Pipeline 管理操作

Pipeline YAML Schema 参考

Schema 版本

版本选择建议

rule/v1.3 的默认并发度

顶层结构

Rule 对象

Rule 字段

条件字段：whenPassed 与 whenFailed

expect 字段

Relay 对象

Relay 字段

Relay 校验规则

隐式 whenPassed 行为

完整校验规则

快速参考

最简 Pipeline

顺序执行（通过链）

并行执行（无条件，推荐使用 rule/v1.3）

使用输出中继

负向测试

另请参阅

还有疑问？

`rule/v1.3` 的默认并发度

条件字段：`whenPassed` 与 `whenFailed`

`expect` 字段

隐式 `whenPassed` 行为

并行执行（无条件，推荐使用 `rule/v1.3`）