本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 建立 IDT 測試案例可執行檔
您可以透過下列方式，在測試套件資料夾中建立和放置測試案例可執行檔：
+ 對於使用 `test.json` 檔案中的引數或環境變數來判斷要執行哪些測試的測試套件，您可以建立整個測試套件的單一測試案例可執行檔，或測試套件中每個測試群組的測試可執行檔。
+ 對於您想要根據指定命令執行特定測試的測試套件，您可以在測試套件中為每個測試案例建立一個可執行的測試案例。
身為測試寫入器，您可以判斷哪種方法適合您的使用案例，並據以建構您的測試案例可執行檔。請確定您在每個`test.json`檔案中提供正確的測試案例可執行路徑，且指定的可執行檔正確執行。
當所有裝置準備好執行測試案例時，IDT 會讀取下列檔案：
+ 所選測試案例`test.json`的 會決定要啟動的程序，以及要設定的環境變數。
+ 測試套件`suite.json`的 決定要設定的環境變數。
IDT 會根據 `test.json` 檔案中指定的命令和引數啟動必要的測試可執行程序，並將所需的環境變數傳遞給程序。
## 使用 IDT 用戶端 SDK
IDT 用戶端SDKs可讓您使用 API 命令，簡化在測試可執行檔中編寫測試邏輯的方式，您可以使用該命令與 IDT 和受測裝置互動。IDT 目前提供下列 SDKs：
+ 適用於 Python 的 IDT 用戶端 SDK
+ IDT Client SDK for Go
+ 適用於 Java 的 IDT 用戶端 SDK
這些 SDKs位於 `/sdks` 資料夾中。建立新的測試案例可執行檔時，您必須將要使用的 SDK 複製到包含測試案例可執行檔的資料夾，並在程式碼中參考 SDK。本節提供可在測試案例可執行檔中使用的可用 API 命令的簡短描述。
**Topics**
+ [裝置互動](#api-device-interaction)
+ [IDT 互動](#api-idt-interaction)
+ [主機互動](#api-host-interaction)
### 裝置互動
下列命令可讓您與受測裝置通訊，而不必實作任何其他裝置互動和連線管理功能。
`ExecuteOnDevice`
允許測試套件在支援 SSH 或 Docker shell 連線的裝置上執行 Shell 命令。
`CopyToDevice`
允許測試套件將本機檔案從執行 IDT 的主機機器複製到支援 SSH 或 Docker shell 連線之裝置上的指定位置。
`ReadFromDevice`
允許測試套件從支援 UART 連線的裝置序列連接埠讀取。
**注意**
由於 IDT 不會管理使用內容中的裝置存取資訊所建立之裝置的直接連線，我們建議您在測試案例可執行檔中使用這些裝置互動 API 命令。不過，如果這些命令不符合您的測試案例要求，則您可以從 IDT 內容擷取裝置存取資訊，並使用它從測試套件直接連線至裝置。
若要進行直接連線，請分別擷取 中的資訊，`device.connectivity`以及受測裝置和資源裝置`resource.devices.connectivity`的欄位。如需使用 IDT 內容的詳細資訊，請參閱 [使用 IDT 內容](idt-context.md)。
### IDT 互動
下列命令可讓您的測試套件與 IDT 通訊。
`PollForNotifications`
允許測試套件檢查來自 IDT 的通知。
`GetContextValue ` 和 `GetContextString`
允許測試套件從 IDT 內容擷取值。如需詳細資訊，請參閱[使用 IDT 內容](idt-context.md)。
`SendResult`
允許測試套件向 IDT 報告測試案例結果。此命令必須在測試套件中每個測試案例的結尾呼叫。
### 主機互動
下列命令可讓您的測試套件與主機機器通訊。
`PollForNotifications`
允許測試套件檢查來自 IDT 的通知。
`GetContextValue ` 和 `GetContextString`
允許測試套件從 IDT 內容擷取值。如需詳細資訊，請參閱[使用 IDT 內容](idt-context.md)。
`ExecuteOnHost`
允許測試套件在本機機器上執行命令，並讓 IDT 管理測試案例可執行生命週期。
## 啟用 IDT CLI 命令
`run-suite` 命令 IDT CLI 提供多種選項，可讓測試執行器自訂測試執行。若要允許測試執行器使用這些選項來執行自訂測試套件，請實作對 IDT CLI 的支援。如果您未實作支援，測試執行器仍然可以執行測試，但某些 CLI 選項將無法正常運作。為了提供理想的客戶體驗，建議您在 IDT CLI 中為 `run-suite`命令實作下列引數的支援：
`timeout-multiplier`
指定大於 1.0 的值，該值將在執行測試時套用至所有逾時。
測試執行器可以使用此引數來增加他們想要執行的測試案例的逾時。當測試執行器在其`run-suite`命令中指定此引數時，IDT 會使用它來計算 IDT\$1TEST\$1TIMEOUT 環境變數的值，並在 IDT 內容中設定 `config.timeoutMultiplier` 欄位。若要支援此引數，您必須執行下列動作：
+ 讀取 IDT\$1TEST\$1TIMEOUT 環境變數以取得正確計算的逾時值，而不是直接使用 `test.json` 檔案的逾時值。
+ 從 IDT 內容擷取`config.timeoutMultiplier`值，並將其套用至長時間執行的逾時。
如需因逾時事件而提早結束的詳細資訊，請參閱[指定結束行為](#test-exec-exiting)。
`stop-on-first-failure`
指定如果 IDT 遇到失敗，應停止執行所有測試。
當測試執行器在其`run-suite`命令中指定此引數時，IDT 會在遇到失敗時立即停止執行測試。不過，如果測試案例平行執行，則這可能會導致非預期的結果。若要實作支援，請確定如果 IDT 遇到此事件，您的測試邏輯會指示所有執行中的測試案例停止、清除臨時資源，並向 IDT 報告測試結果。如需在故障時提早結束的詳細資訊，請參閱 [指定結束行為](#test-exec-exiting)。
`group-id` 和 `test-id`
指定 IDT 應僅執行選取的測試群組或測試案例。
測試執行器可以將這些引數與其`run-suite`命令搭配使用，以指定下列測試執行行為：
+ 在指定的測試群組內執行所有測試。
+ 在指定的測試群組內執行一系列的測試。
若要支援這些引數，測試套件的測試協調器必須在測試協調器中包含一組特定的 `RunTask`和 `Choice` 狀態。如果您不使用自訂狀態機器，則預設的 IDT 測試協調器會包含您所需的狀態，而且您不需要採取其他動作。不過，如果您使用的是自訂測試協調器，則使用 [狀態機器範例：執行使用者選取的測試群組](idt-state-machine.md#allow-specific-groups)做為範例，在您的測試協調器中新增所需的狀態。
如需 IDT CLI 命令的詳細資訊，請參閱 [偵錯並執行自訂測試套件](run-debug-custom-tests.md)。
## 寫入事件日誌
測試執行時，您可以將資料傳送至 `stdout`和 `stderr`，以將事件日誌和錯誤訊息寫入主控台。如需主控台訊息格式的相關資訊，請參閱[主控台訊息格式](idt-review-results-logs.md#idt-console-format)。
當 IDT 完成執行測試套件時，此資訊也可在 資料夾的 `test_manager.log` 檔案中取得`/results//logs`。
您可以設定每個測試案例，將日誌從其測試執行寫入至位於 `/results/execution-id/logs` 資料夾中`_`的檔案，包括測試中裝置的日誌。若要執行此操作，請從 IDT 內容中擷取日誌檔案的路徑`testData.logFilePath`，在該路徑建立檔案，然後寫入您想要的內容。IDT 會根據正在執行的測試案例自動更新路徑。如果您選擇不建立測試案例的日誌檔案，則不會產生該測試案例的檔案。
您也可以設定文字可執行檔，視需要在 `/logs` 資料夾中建立其他日誌檔案。建議您為日誌檔案名稱指定唯一的字首，以免您的檔案遭到覆寫。
## 向 IDT 報告結果
IDT 會將測試結果寫入 `awsiotdevicetester_report.xml`和 `suite-name_report.xml` 檔案。這些報告檔案位於 。 `/results//`兩個報告都會擷取測試套件執行的結果。如需 IDT 用於這些報告之結構描述的詳細資訊，請參閱 [檢閱 IDT 測試結果和日誌](idt-review-results-logs.md)
若要填入`suite-name_report.xml`檔案的內容，您必須在測試執行完成之前使用 `SendResult`命令向 IDT 報告測試結果。如果 IDT 找不到測試的結果，則會發出測試案例的錯誤。下列 Python 摘錄顯示將測試結果傳送至 IDT 的命令：
```
request-variable = SendResultRequest(TestResult(result))
client.send_result(request-variable)
```
如果您未透過 API 報告結果，IDT 會在測試成品資料夾中尋找測試結果。此資料夾的路徑會存放在 IDT 內容中`testData.testArtifactsPath`存檔的 中。在此資料夾中，IDT 會使用第一個依字母順序排序的 XML 檔案做為測試結果。
如果您的測試邏輯產生 JUnit XML 結果，您可以將測試結果寫入成品資料夾中的 XML 檔案，以直接將結果提供給 IDT，而不是剖析結果，然後使用 API 將結果提交給 IDT。
如果您使用此方法，請確定您的測試邏輯準確摘要測試結果，並以與檔案相同的格式格式化結果`suite-name_report.xml`檔案。IDT 不會對您提供的資料執行任何驗證，但以下情況除外：
+ IDT 會忽略`testsuites`標籤的所有屬性。反之，它會從其他報告的測試群組結果計算標籤屬性。
+ 必須至少有一個`testsuite`標籤存在於 中`testsuites`。
由於 IDT 在所有測試案例使用相同的成品資料夾，且不會在測試執行之間刪除結果檔案，因此如果 IDT 讀取不正確的檔案，此方法也可能會導致錯誤報告。建議您在所有測試案例使用與產生 XML 結果檔案相同的名稱，以覆寫每個測試案例的結果，並確保 IDT 可以使用正確的結果。雖然您可以使用混合方法在測試套件中報告，也就是說，對於某些測試案例使用 XML 結果檔案，並透過 API 為其他人提交結果，但不建議使用此方法。
## 指定結束行為
將您的文字可執行檔設定為一律以結束碼 0 結束，即使測試案例報告失敗或錯誤結果亦然。僅使用非零結束碼來表示測試案例未執行，或測試案例可執行檔無法將任何結果傳達給 IDT。當 IDT 收到非零結束碼時，它會標記測試案例發生錯誤，導致無法執行。
IDT 可能會請求或預期測試案例在下列事件完成之前停止執行。使用此資訊來設定您的測試案例可執行檔，以偵測測試案例中的每個事件：
**Timeout (逾時)**
當測試案例執行的時間超過`test.json`檔案中指定的逾時值時，便會發生。如果測試執行器使用`timeout-multiplier`引數指定逾時乘數，則 IDT 會使用乘數計算逾時值。
若要偵測此事件，請使用 IDT\$1TEST\$1TIMEOUT 環境變數。當測試執行器啟動測試時，IDT 會將 IDT\$1TEST\$1TIMEOUT 環境變數的值設定為計算的逾時值 （以秒為單位），並將變數傳遞至測試案例可執行檔。您可以讀取變數值來設定適當的計時器。
**中斷**
當測試執行器中斷 IDT 時發生。例如，按 Ctrl\$1C。
由於終端機會將訊號傳播到所有子程序，因此您只需在測試案例中設定訊號處理常式，即可偵測中斷訊號。
或者，您可以定期輪詢 API，以檢查 `PollForNotifications` API `CancellationRequested` 回應中的布林值。當 IDT `CancellationRequested` 收到中斷訊號時，它會將布林值設定為 `true`。
**第一次失敗時停止**
當與目前測試案例平行執行的測試案例失敗，且測試執行器使用`stop-on-first-failure`引數指定 IDT 應在遇到任何失敗時停止時，便會發生。
若要偵測此事件，您可以定期輪詢 API，以檢查 `PollForNotifications` API `CancellationRequested` 回應中的布林值。當 IDT 遇到故障，且設定為在第一次故障時停止時，它會將`CancellationRequested`布林值設定為 `true`。
當這些事件發生時，IDT 會等待 5 分鐘，讓任何目前正在執行的測試案例完成執行。如果所有執行中的測試案例未在 5 分鐘內結束，IDT 會強制其每個程序停止。如果 IDT 未在程序結束前收到測試結果，則會將測試案例標記為已逾時。最佳實務是，您應該確保測試案例在遇到其中一個事件時執行下列動作：
1. 停止執行正常測試邏輯。
1. 清除任何臨時資源，例如受測裝置上的測試成品。
1. 向 IDT 報告測試結果，例如測試失敗或錯誤。
1. 結束。