建立 IDT 測試案例可執行檔 - AWS IoT Greengrass
使用 IDT 用戶端 SDK啟用 IDT CLI 命令寫入事件日誌向 IDT 報告結果指定結束行為

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

建立 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位於 <device-tester-extract-location>/sdks 資料夾中。建立新的測試案例可執行檔時，您必須將要使用的 SDK 複製到包含測試案例可執行檔的資料夾，並在程式碼中參考 SDK。本節提供可在測試案例可執行檔中使用的可用 API 命令的簡短描述。

裝置互動

下列命令可讓您與受測裝置通訊，而不必實作任何其他裝置互動和連線管理功能。

ExecuteOnDevice

允許測試套件在支援 SSH 或 Docker shell 連線的裝置上執行 Shell 命令。

CopyToDevice

允許測試套件將本機檔案從執行 IDT 的主機機器複製到支援 SSH 或 Docker shell 連線之裝置上的指定位置。

ReadFromDevice

允許測試套件從支援 UART 連線的裝置序列連接埠讀取。

注意

由於 IDT 不會管理使用內容中的裝置存取資訊所建立之裝置的直接連線，我們建議您在測試案例可執行檔中使用這些裝置互動 API 命令。不過，如果這些命令不符合您的測試案例要求，則您可以從 IDT 內容擷取裝置存取資訊，並使用它從測試套件直接連線至裝置。

若要進行直接連線，請分別擷取 中的資訊，device.connectivity以及受測裝置和資源裝置resource.devices.connectivity的欄位。如需使用 IDT 內容的詳細資訊，請參閱 使用 IDT 內容。

IDT 互動

下列命令可讓您的測試套件與 IDT 通訊。

PollForNotifications

允許測試套件檢查來自 IDT 的通知。

GetContextValue 和 GetContextString

允許測試套件從 IDT 內容擷取值。如需詳細資訊，請參閱使用 IDT 內容。

SendResult

允許測試套件向 IDT 報告測試案例結果。此命令必須在測試套件中每個測試案例的結尾呼叫。

主機互動

下列命令可讓您的測試套件與主機機器通訊。

PollForNotifications

允許測試套件檢查來自 IDT 的通知。

GetContextValue 和 GetContextString

允許測試套件從 IDT 內容擷取值。如需詳細資訊，請參閱使用 IDT 內容。

ExecuteOnHost

允許測試套件在本機機器上執行命令，並讓 IDT 管理測試案例可執行生命週期。

啟用 IDT CLI 命令

run-suite 命令 IDT CLI 提供多種選項，可讓測試執行器自訂測試執行。若要允許測試執行器使用這些選項來執行自訂測試套件，請實作對 IDT CLI 的支援。如果您未實作支援，測試執行器仍然可以執行測試，但某些 CLI 選項將無法正常運作。為了提供理想的客戶體驗，建議您在 IDT CLI 中為 run-suite命令實作下列引數的支援：

timeout-multiplier

指定大於 1.0 的值，該值將在執行測試時套用至所有逾時。

測試執行器可以使用此引數來增加他們想要執行的測試案例的逾時。當測試執行器在其run-suite命令中指定此引數時，IDT 會使用它來計算 IDT_TEST_TIMEOUT 環境變數的值，並在 IDT 內容中設定 config.timeoutMultiplier 欄位。若要支援此引數，您必須執行下列動作：

  • 讀取 IDT_TEST_TIMEOUT 環境變數以取得正確計算的逾時值，而不是直接使用 test.json 檔案的逾時值。

  • 從 IDT 內容擷取config.timeoutMultiplier值，並將其套用至長時間執行的逾時。

如需因逾時事件而提早結束的詳細資訊，請參閱指定結束行為。

stop-on-first-failure

指定如果 IDT 遇到失敗，應停止執行所有測試。

當測試執行器在其run-suite命令中指定此引數時，IDT 會在遇到失敗時立即停止執行測試。不過，如果測試案例平行執行，則這可能會導致非預期的結果。若要實作支援，請確定如果 IDT 遇到此事件，您的測試邏輯會指示所有執行中的測試案例停止、清除臨時資源，並向 IDT 報告測試結果。如需在故障時提早結束的詳細資訊，請參閱 指定結束行為。

group-id 和 test-id

指定 IDT 應僅執行選取的測試群組或測試案例。

測試執行器可以將這些引數與其run-suite命令搭配使用，以指定下列測試執行行為：

  • 在指定的測試群組內執行所有測試。

  • 在指定的測試群組內執行一系列的測試。

若要支援這些引數，測試套件的測試協調器必須在測試協調器中包含一組特定的 RunTask和 Choice 狀態。如果您不使用自訂狀態機器，則預設的 IDT 測試協調器會包含您所需的狀態，而且您不需要採取其他動作。不過，如果您使用的是自訂測試協調器，則使用 狀態機器範例：執行使用者選取的測試群組做為範例，在您的測試協調器中新增所需的狀態。

如需 IDT CLI 命令的詳細資訊，請參閱 偵錯並執行自訂測試套件。

寫入事件日誌

測試執行時，您可以將資料傳送至 stdout和 stderr，以將事件日誌和錯誤訊息寫入主控台。如需主控台訊息格式的相關資訊，請參閱主控台訊息格式。

當 IDT 完成執行測試套件時，此資訊也可在 資料夾的 test_manager.log 檔案中取得<devicetester-extract-location>/results/<execution-id>/logs。

您可以設定每個測試案例，將日誌從其測試執行寫入至位於 <device-tester-extract-location>/results/execution-id/logs 資料夾中<group-id>_<test-id>的檔案，包括測試中裝置的日誌。若要執行此操作，請從 IDT 內容中擷取日誌檔案的路徑testData.logFilePath，在該路徑建立檔案，然後寫入您想要的內容。IDT 會根據正在執行的測試案例自動更新路徑。如果您選擇不建立測試案例的日誌檔案，則不會產生該測試案例的檔案。

您也可以設定文字可執行檔，視需要在 <device-tester-extract-location>/logs 資料夾中建立其他日誌檔案。建議您為日誌檔案名稱指定唯一的字首，以免您的檔案遭到覆寫。

向 IDT 報告結果

IDT 會將測試結果寫入 awsiotdevicetester_report.xml和 suite-name_report.xml 檔案。這些報告檔案位於 。 <device-tester-extract-location>/results/<execution-id>/兩個報告都會擷取測試套件執行的結果。如需 IDT 用於這些報告之結構描述的詳細資訊，請參閱 檢閱 IDT 測試結果和日誌

若要填入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_TEST_TIMEOUT 環境變數。當測試執行器啟動測試時，IDT 會將 IDT_TEST_TIMEOUT 環境變數的值設定為計算的逾時值 （以秒為單位），並將變數傳遞至測試案例可執行檔。您可以讀取變數值來設定適當的計時器。

中斷

當測試執行器中斷 IDT 時發生。例如，按 Ctrl+C。

由於終端機會將訊號傳播到所有子程序，因此您只需在測試案例中設定訊號處理常式，即可偵測中斷訊號。

或者，您可以定期輪詢 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. 停止執行正常測試邏輯。

  2. 清除任何臨時資源，例如受測裝置上的測試成品。

  3. 向 IDT 報告測試結果，例如測試失敗或錯誤。

  4. 結束。