本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 配置 IDT 测试编排工具
<a name="idt-test-orchestrator"></a>

从 IDT v4.5.2 开始，IDT 包括一个新的*测试编排工具*组件。测试编排工具是一个 IDT 组件，用于控制测试套件的执行流程，并在 IDT 完成运行所有测试后生成测试报告。测试编排工具根据用户定义的规则确定测试选择和测试的运行顺序。

如果您的测试套件不包含用户定义的测试编排工具，IDT 将为您生成一个测试编排工具。

默认测试编排工具执行以下功能：
+ 使测试运行器能够选择和运行特定的测试组，而不是整个测试套件。
+ 如果未选择特定的测试组，则按随机顺序运行测试套件中的每个测试组。
+ 生成报告并打印控制台摘要，其中显示每个测试组和测试用例的测试结果。

测试编排工具用于取代 IDT 状态机。我们强烈建议您使用测试编排工具来开发测试套件，而不是使用 IDT 状态机。测试编排工具提供了以下改进功能：
+ IDT 状态机使用命令式格式，而该工具使用声明式格式。这允许您指定要运行哪些测试以及何时运行它们。
+ 管理特定的组处理、报告生成、错误处理和结果跟踪，让您无需手动管理这些操作。
+ 使用 YAML 格式，该格式默认支持注释。
+ 定义相同的工作流程所需的磁盘空间比测试编排工具少 80%。
+ 添加测试前验证，以验证您的工作流程定义不包含不正确的测试 IDs 或循环依赖关系。

## 测试编排工具格式
<a name="idt-test-orchestrator-format"></a>

您可以使用以下模板来配置自己的`custom-test-suite-folder/suite/test_orchestrator.yaml`文件：

```
Aliases:
  string: context-expression

ConditionalTests:
  - Condition: context-expression
    Tests:
      - test-descriptor

Order:
  - - group-descriptor
    - group-descriptor

Features:
  - Name: feature-name
    Value: support-description
    Condition: context-expression
    Tests:
        - test-descriptor
    OneOfTests:
        - test-descriptor
    IsRequired: boolean
```

包含值的所有字段都为必填字段，如下所述：

`Aliases`  
可选。映射到上下文表达式的用户定义字符串。别名允许您生成友好的名称，以便识别测试编排工具配置中的上下文表达式。如果您要创建复杂的上下文表达式或在多个位置使用的表达式，则此功能特别有用。  
您可以使用上下文表达式来存储上下文查询，从而允许您访问其他 IDT 配置中的数据。有关更多信息，请参阅 [在上下文中访问数据](idt-context.md#accessing-context-data)。  

**Example**  
**示例**  

```
Aliases:
    FizzChosen: "'{{$pool.features[?(@.name == 'Fizz')].value[0]}}' == 'yes'"    
    BuzzChosen: "'{{$pool.features[?(@.name == 'Buzz')].value[0]}}' == 'yes'"    
    FizzBuzzChosen: "'{{$aliases.FizzChosen}}' && '{{$aliases.BuzzChosen}}'"
```

`ConditionalTests`  
可选。条件列表以及满足每个条件时运行的相应测试用例。每个条件可以有多个测试用例；但是，您只能将给定测试用例分配给一个条件。  
默认情况下，IDT 会运行任何未分配给此列表中的条件的测试用例。如果您未指定此部分，IDT 将运行测试套件中的所有测试组。  
`ConditionalTests` 列表中的每个项目都包含以下参数：    
`Condition`  
计算结果为布尔值的上下文字符串。如果计算值为 true，IDT 将运行 `Tests` 参数中指定的测试用例。  
`Tests`  
测试描述符列表。  
每个测试描述符使用测试组 ID 和一个或多个测试用例 IDs 来标识要从特定测试组运行的单个测试。测试描述符使用以下格式：  

```
GroupId: group-id
CaseIds: [test-id, test-id] # optional
```

**Example**  
**示例**  
以下示例使用可定义为 `Aliases` 的通用上下文表达式。  

```
ConditionalTests:
    - Condition: "{{$aliases.Condition1}}"
      Tests:
          - GroupId: A
          - GroupId: B
    - Condition: "{{$aliases.Condition2}}"
      Tests:
          - GroupId: D
    - Condition: "{{$aliases.Condition1}} || {{$aliases.Condition2}}"
      Tests:
          - GroupId: C
```

IDT 根据定义的条件选择测试组，如下所示：
+ 如果 `Condition1` 为 true，IDT 将在测试组 A、B 和 C 中运行测试。
+ 如果 `Condition2` 为 true，IDT 将在测试组 C 和 D 中运行测试。

`Order`  
可选。运行测试的顺序。您可以在测试组级别指定测试顺序。如果未指定此部分，IDT 将按随机顺序运行所有适用的测试组。`Order` 的值是组描述符列表的列表。未在 `Order` 中列出的任何测试组都可以与列出的任何其他测试组并行运行。  

每个组描述符列表都包含一个或多个组描述符，并标识每个描述符中指定的组的运行顺序。您可以使用以下格式定义单个组描述符：
+ `group-id` – 现有测试组的组 ID。
+ `[group-id, group-id]` – 可按相对于彼此的任意顺序运行的测试组列表。
+ `"*"` – 通配符。这等同于所有尚未在当前组描述符列表中指定的测试组的列表。

`Order` 的值必须满足以下要求：
+ 您在组 IDs 描述符中指定的测试组必须存在于您的测试套件中。
+ 每个组描述符列表必须包含至少一个测试组。
+ 每个组描述符列表必须包含唯一的组 IDs。不能在单个组描述符中使用重复的测试组 ID。
+ 一个组描述符列表最多可以有一个通配符组描述符。通配符组描述符必须是列表中的第一项或最后一项。

**Example**  
**示例**  
对于包含测试组 A、B、C、D 和 E 的测试套件，以下示例列表显示了指定 IDT 应先运行测试组 A，然后运行测试组 B，然后按任意顺序运行测试组 C、D 和 E 的不同方法。  
+ 

  ```
  Order:
      - - A
        - B
        - [C, D, E]
  ```
+ 

  ```
  Order:
      - - A
        - B
        - "*"
  ```
+ 

  ```
  Order:
      - - A
        - B
      
      - - B
        - C
      
      - - B
        - D
      
      - - B
        - E
  ```

`Features`  
可选。您希望将 IDT 添加到 `awsiotdevicetester_report.xml` 文件中的产品功能列表。如果未指定此部分，则 IDT 不会将任何产品功能添加到报告中。  
产品功能是关于设备可能符合的特定标准的用户定义信息。例如，MQTT 产品功能可以指定设备正确发布 MQTT 消息。在 `awsiotdevicetester_report.xml` 中，根据指定的测试是否通过，将产品功能设置为 `supported`、`not-supported` 或自定义的用户定义值。  
`Features` 列表中的每个项目都包含以下参数：    
`Name`  
特征的名称。  
`Value`  
可选。要在报告中使用的自定义值，而不是 `supported`。如果未指定此值，则根据测试结果，IDT 将特征值设置为 `supported` 或 `not-supported`。如果您使用不同的条件测试相同的功能，则可以在 `Features` 列表中为该特征的各个实例使用自定义值，而 IDT 会将支持条件的特征值串联起来。有关更多信息，请参阅   
`Condition`  
计算结果为布尔值的上下文字符串。如果计算值为 true，IDT 将在运行完测试套件后将该功能添加到测试报告中。如果计算值为 false，则不会将测试包含在报告中。  
`Tests`  
可选。测试描述符列表。必须通过在此列表中指定的所有测试才能支持该功能。  
此列表中的每个测试描述符都使用测试组 ID 和一个或多个测试用例 IDs 来标识要从特定测试组运行的单个测试。测试描述符使用以下格式：  

```
GroupId: group-id
CaseIds: [test-id, test-id] # optional
```
必须为 `Features` 列表中的每个特征指定 `Tests` 或 `OneOfTests`。  
`OneOfTests`  
可选。测试描述符列表。必须通过在此列表中指定的至少一个测试才能支持该功能。  
此列表中的每个测试描述符都使用测试组 ID 和一个或多个测试用例 IDs 来标识要从特定测试组运行的单个测试。测试描述符使用以下格式：  

```
GroupId: group-id
CaseIds: [test-id, test-id] # optional
```
必须为 `Features` 列表中的每个特征指定 `Tests` 或 `OneOfTests`。  
`IsRequired`  
用于定义测试报告中是否需要该功能的布尔值。默认值为 `false`。

## 测试编排工具上下文
<a name="idt-test-orchestrator-context"></a>

测试编排工具上下文是一个只读 JSON 文档，其中包含在执行期间可供测试编排工具使用的数据。测试编排工具上下文只能从测试编排工具访问，其中包含决定测试流程的信息。例如，您可以使用 `userdata.json` 文件中测试运行器配置的信息来确定是否需要运行特定的测试。

测试编排工具上下文使用以下格式：

```
{
    "pool": {
        <device-json-pool-element>
    },
    "userData": {
        <userdata-json-content>
    },
    "config": {
        <config-json-content>
    }
}
```

`pool`  
有关为测试运行选择的设备池的信息。对于选定的设备池，此信息将从 `device.json` 文件中定义的相应顶级设备池阵列元素中检索。

`userData`  
`userdata.json` 文件中的信息

`config`  
`config.json` 文件中的信息

您可以使用 JSONPath 符号查询上下文。状态定义中 JSONPath查询的语法是`{{query}}`。从测试编排工具上下文访问数据时，请确保每个值的计算结果都为字符串、数字或布尔值。

有关使用 JSONPath 符号从上下文访问数据的更多信息，请参阅[使用 IDT 上下文](idt-context.md)。