本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 設定 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 `not-supported` 為基礎的功能值會根據測試結果設為 `supported`或 。如果您使用不同的條件測試相同的功能，您可以為`Features`清單中該功能的每個執行個體使用自訂值，IDT 會串連支援條件的功能值。如需詳細資訊，請參閱   
`Condition`  
評估為布林值的內容表達式。如果評估的值為 true，IDT 會在測試報告完成執行測試套件之後，將此功能新增至測試報告。如果評估的值為 false，則測試不會包含在報告中。  
`Tests`  
選用。測試描述項的清單。此清單中指定的所有測試都必須通過，才能支援此功能。  
此清單中的每個測試描述項都使用測試群組 ID 和一或多個測試案例 IDs，來識別要從特定測試群組執行的個別測試。測試描述項使用下列格式：  

```
GroupId: group-id
CaseIds: [test-id, test-id] # optional
```
您必須`OneOfTests`為`Features`清單中的每個功能指定 `Tests`或 。  
`OneOfTests`  
選用。測試描述項的清單。此清單中指定的至少一個測試必須通過，才能支援此功能。  
此清單中的每個測試描述項都使用測試群組 ID 和一或多個測試案例 IDs，來識別要從特定測試群組執行的個別測試。測試描述項使用下列格式：  

```
GroupId: group-id
CaseIds: [test-id, test-id] # optional
```
您必須`OneOfTests`為`Features`清單中的每個功能指定 `Tests`或 。  
`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)。