---
title: "Pipeline YAML Schema 参考"
language: "zh"
url: "https://docs.testany.io/zh/docs/pipeline-yaml-schema-reference/"
markdown_url: "https://docs.testany.io/zh/docs/pipeline-yaml-schema-reference.md"
translation: "https://docs.testany.io/en/docs/pipeline-yaml-schema-reference.md"
last_updated: "2026-03-26T15:39:24+08:00"
---

# Pipeline YAML Schema 参考

本文档提供测试流水线 YAML 结构的完整技术参考。有关使用示例和最佳实践，请参阅 [Pipeline 编写指南和示例](https://docs.testany.io/zh/docs/test-pipeline-writing-guideline-and-samples.md)。

## 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 校验规则


> **警告**
>
> 以下配置会导致校验错误：


1. **缺少字段：** `key` 和 `refKey` 都是必填项。
2. **未定义的源：** 源用例（`refKey` 前缀）必须在前面的规则中定义。
3. **Relay 与 `whenFailed` 一起使用：** 不能从使用 `whenFailed` 引用的用例进行 relay。
4. **并行歧义：** 在 `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 编写指南和示例](https://docs.testany.io/zh/docs/test-pipeline-writing-guideline-and-samples.md) - 使用示例和最佳实践
- [使用输出中继让测试更健壮灵活](https://docs.testany.io/zh/docs/build-your-tests-more-robust-flexible-with-output-.md) - 输出中继详细概念
- [管理测试流水线](https://docs.testany.io/zh/docs/managing-test-pipeline.md) - Pipeline 管理操作

## 本页术语

- [测试流水线 (Test Pipeline)](https://docs.testany.io/zh/docs/glossary.md#test-pipeline)
- [执行 (Execution)](https://docs.testany.io/zh/docs/glossary.md#execution)
- [用户 (User)](https://docs.testany.io/zh/docs/glossary.md#user)
- [工作区 (Workspace)](https://docs.testany.io/zh/docs/glossary.md#workspace)
- [测试用例 (Test Case)](https://docs.testany.io/zh/docs/glossary.md#test-case)
- [测试用例标识 (Test Case Key)](https://docs.testany.io/zh/docs/glossary.md#test-case-key)
- [测试脚本 (Test Script)](https://docs.testany.io/zh/docs/glossary.md#test-script)
- [输出中继 (Output Relay)](https://docs.testany.io/zh/docs/glossary.md#output-relay)
- [环境 (Environment)](https://docs.testany.io/zh/docs/glossary.md#environment)