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

# 建立 IDT 測試套件組態檔案
<a name="idt-json-config"></a>

本節說明您在撰寫自訂測試套件時所包含之組態檔案的建立格式。

**必要的組態檔案**

**`suite.json`**  
包含測試套件的相關資訊。請參閱 [設定 suite.json](#suite-json)。

**`group.json`**  
包含測試群組的相關資訊。您必須為測試套件中的每個測試群組建立`group.json`檔案。請參閱 [設定 group.json](#group-json)。

**`test.json`**  
包含測試案例的相關資訊。您必須為測試套件中的每個測試案例建立`test.json`檔案。請參閱 [設定 test.json](#test-json)。

**選用組態檔案**

**`test_orchestrator.yaml` 或 `state_machine.json`**  
定義 IDT 執行測試套件時如何執行測試。SSe [設定 test\$1orchestrator.yaml](#test-orchestrator-config)。  
從 IDT v4.5.2 開始，您可以使用 `test_orchestrator.yaml` 檔案來定義測試工作流程。在舊版的 IDT 中，您會使用 `state_machine.json` 檔案。如需狀態機器的資訊，請參閱 [設定 IDT 狀態機器](idt-state-machine.md)。

**`userdata_schema.json`**  
定義測試執行器可以包含在其設定組態中的[`userdata.json`檔案](set-config-custom.md#userdata-config-custom)結構描述。`userdata.json` 檔案會用於執行測試所需的任何其他組態資訊，但不會出現在`device.json`檔案中。請參閱 [設定 userdata\$1schema.json](#userdata-schema-json)。

組態檔案會放置在您的 中`<custom-test-suite-folder>`，如下所示。

```
<custom-test-suite-folder>
└── suite
    ├── suite.json
    ├── test_orchestrator.yaml
    ├── userdata_schema.json
    ├── <test-group-folder>
        ├── group.json
        ├── <test-case-folder>
            └── test.json
```

## 設定 suite.json
<a name="suite-json"></a>

`suite.json` 檔案會設定環境變數，並判斷是否需要使用者資料才能執行測試套件。使用下列範本來設定您的`<custom-test-suite-folder>/suite/suite.json`檔案：

```
{
    "id": "<suite-name>_<suite-version>",
    "title": "<suite-title>",
    "details": "<suite-details>",
    "userDataRequired": true | false,
    "environmentVariables": [
        {
            "key": "<name>",
            "value": "<value>",
        },
        ...
        {
            "key": "<name>",
            "value": "<value>",
        }
    ]
}
```

如下所述，包含值的所有欄位皆為必要：

**`id`**  
測試套件的唯一使用者定義 ID。的值`id`必須符合 `suite.json` 檔案所在的測試套件資料夾名稱。套件名稱和套件版本也必須符合下列要求：  
+ `<suite-name>` 不能包含底線。
+ `<suite-version>` 表示為 `x.x.x`，其中 `x`是數字。
ID 會顯示在 IDT 產生的測試報告中。

**`title`**  
此測試套件正在測試之產品或功能的使用者定義名稱。名稱會顯示在測試執行器的 IDT CLI 中。

**`details`**  
測試套件用途的簡短描述。

**`userDataRequired`**  
定義測試執行器是否需要在`userdata.json`檔案中包含自訂資訊。如果您將此值設定為 `true`，您還必須在測試套件資料夾中包含 [`userdata_schema.json` 檔案](#userdata-schema-json)。

**`environmentVariables`**  
選用。要為此測試套件設定的環境變數陣列。    
**`environmentVariables.key`**  
環境變數的名稱。  
**`environmentVariables.value`**  
環境變數的值。

## 設定 group.json
<a name="group-json"></a>

`group.json` 檔案會定義測試群組為必要或選用。使用下列範本來設定您的`<custom-test-suite-folder>/suite/<test-group>/group.json`檔案：

```
{
    "id": "<group-id>",
    "title": "<group-title>",
    "details": "<group-details>",
    "optional": true | false,
}
```

如下所述，包含值的所有欄位皆為必要：

**`id`**  
測試群組的唯一使用者定義 ID。的值`id`必須符合`group.json`檔案所在的測試群組資料夾名稱，且不應有底線 (`_`)。ID 用於 IDT 產生的測試報告。

**`title`**  
測試群組的描述性名稱。名稱會顯示在測試執行器的 IDT CLI 中。

**`details`**  
測試群組用途的簡短描述。

**`optional`**  
選用。設定為 `true` 以在 IDT 完成執行所需的測試後，將此測試群組顯示為選用群組。預設值為 `false`。

## 設定 test.json
<a name="test-json"></a>

`test.json` 檔案會決定測試案例可執行檔和測試案例所使用的環境變數。如需建立測試案例可執行檔的詳細資訊，請參閱 [建立 IDT 測試案例可執行檔](test-executables.md)。

使用下列範本來設定您的`<custom-test-suite-folder>/suite/<test-group>/<test-case>/test.json`檔案：

```
{
    "id": "<test-id>",
    "title": "<test-title>",
    "details": "<test-details>",
    "requireDUT": true | false,
    "requiredResources": [
        {
            "name": "<resource-name>",
            "features": [
                {
                    "name": "<feature-name>",
                    "version": "<feature-version>",
                    "jobSlots": <job-slots>
                }
            ]
        }
    ],
    "execution": {
        "timeout": <timeout>,
        "mac": {
            "cmd": "/path/to/executable",
            "args": [
                "<argument>"
            ],
        },
        "linux": {
            "cmd": "/path/to/executable",
            "args": [
                "<argument>"
            ],
        },
        "win": {
            "cmd": "/path/to/executable",
            "args": [
                "<argument>"
            ]
        }
    },
    "environmentVariables": [
        {
            "key": "<name>",
            "value": "<value>",
        }
    ]
}
```

如下所述，包含值的所有欄位皆為必要：

**`id`**  
測試案例的唯一使用者定義 ID。的值`id`必須符合`test.json`檔案所在的測試案例資料夾名稱，且不應有底線 (`_`)。ID 用於 IDT 產生的測試報告。

**`title`**  
測試案例的描述性名稱。名稱會顯示在測試執行器的 IDT CLI 中。

**`details`**  
測試案例用途的簡短描述。

**`requireDUT`**  
選用。`true` 如果需要裝置執行此測試，請將 設定為 ，否則將 設定為 `false`。預設值為 `true`。測試執行器會設定將用來在其 `device.json` 檔案中執行測試的裝置。

**`requiredResources`**  
選用。陣列，提供執行此測試所需的資源裝置相關資訊。    
**`requiredResources.name`**  
執行此測試時提供給資源裝置的唯一名稱。  
**`requiredResources.features`**  
使用者定義資源裝置功能的陣列。    
**`requiredResources.features.name`**  
功能的名稱。您要使用此裝置的裝置功能。此名稱會與 `resource.json` 檔案中測試執行器所提供的功能名稱相符。  
**`requiredResources.features.version`**  
選用。功能的版本。此值會與 `resource.json` 檔案中測試執行器所提供的功能版本相符。如果未提供版本，則不會檢查該功能。如果功能不需要版本號碼，請將此欄位保留空白。  
**`requiredResources.features.jobSlots`**  
選用。此功能可支援的同時測試數量。預設值為 `1`。如果您希望 IDT 針對個別功能使用不同的裝置，建議您將此值設定為 `1`。

**`execution.timeout`**  
IDT 等待測試完成執行的時間量 （以毫秒為單位）。如需設定此值的詳細資訊，請參閱 [建立 IDT 測試案例可執行檔](test-executables.md)。

**`execution.os`**  
要根據執行 IDT 之主機電腦的作業系統執行的測試案例可執行檔。支援的值為 `linux`、`mac` 和 `win`。    
**`execution.os.cmd`**  
您想要在指定作業系統上執行的測試案例可執行檔路徑。此位置必須位於系統路徑中。  
**`execution.os.args`**  
選用。要用來執行測試案例可執行檔的引數。

**`environmentVariables`**  
選用。為此測試案例設定的環境變數陣列。    
**`environmentVariables.key`**  
環境變數的名稱。  
**`environmentVariables.value`**  
環境變數的值。
如果您在 `test.json` 檔案和 檔案中指定相同的環境變數`suite.json`，則 `test.json` 檔案中的值優先。

## 設定 test\$1orchestrator.yaml
<a name="test-orchestrator-config"></a>

測試協調器是一種控制測試套件執行流程的建構。它決定測試套件的開始狀態、根據使用者定義的規則管理狀態轉換，並繼續轉換這些狀態，直到達到結束狀態為止。

如果您的測試套件不包含使用者定義的測試協調器，IDT 會為您產生測試協調器。

預設測試協調器會執行下列函數：
+ 讓測試執行器能夠選取和執行特定測試群組，而不是整個測試套件。
+ 如果未選取特定測試群組， 會以隨機順序執行測試套件中的每個測試群組。
+ 產生報告並列印主控台摘要，顯示每個測試群組和測試案例的測試結果。

如需 IDT 測試協調器如何運作的詳細資訊，請參閱 [設定 IDT 測試協調器](idt-test-orchestrator.md)。

## 設定 userdata\$1schema.json
<a name="userdata-schema-json"></a>

`userdata_schema.json` 檔案會決定測試執行器提供使用者資料的結構描述。如果您的測試套件需要`device.json`檔案中不存在的資訊，則需要使用者資料。例如，您的測試可能需要使用者必須提供的 Wi-Fi 網路登入資料、特定開放連接埠或憑證。此資訊可以做為名為 的輸入參數提供給 IDT，這是使用者在其`<device-tester-extract-location>/config`資料夾中建立`userdata.json`的檔案`userdata`值。檔案的格式`userdata.json`取決於您在測試套件中包含的 `userdata_schema.json` 檔案。

若要指出測試執行器必須提供 `userdata.json` 檔案：

1. 在 `suite.json`檔案中，將 `userDataRequired` 設定為 `true`。

1. 在您的 中`<custom-test-suite-folder>`，建立 `userdata_schema.json` 檔案。

1. 編輯 `userdata_schema.json` 檔案以建立有效的 [IETF 草稿 v4 JSON 結構描述](https://json-schema.org/specification-links#draft-4)。

當 IDT 執行您的測試套件時，它會自動讀取結構描述，並使用它來驗證測試執行器所提供的`userdata.json`檔案。如果有效，`userdata.json`檔案的內容可在 [IDT 內容](idt-context.md)和[測試協調器內容](idt-test-orchestrator.md#idt-test-orchestrator-context)中使用。