創建 IDT 測試用例可執行文件 - AWS IoT Greengrass
使用 IDT 客户端軟件開發工具包啟用 IDT CLI 命令寫入事件日誌向 IDT 報告結果指定結束行為

AWS IoT Greengrass Version 1 於 2023 年 6 月 30 日進入延長壽命階段。如需詳細資訊，請參閱 AWS IoT Greengrass V1 維護政策 。在此日期之後， AWS IoT Greengrass V1 不會發佈提供功能、增強功能、錯誤修正或安全修補程式的更新。在 上執行的裝置 AWS IoT Greengrass V1 不會中斷，並會繼續運作和連線至雲端。我們強烈建議您遷移至 AWS IoT Greengrass Version 2，這會新增重要的新功能，並支援其他平台 。

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

創建 IDT 測試用例可執行文件

您可以通過以下方式創建測試用例可執行文件並將其放置在測試套件文件夾中：

  • 對於使用參數或環境變量的測試套件，test.json文件來確定要運行哪些測試，則可以為整個測試套件創建單個測試用例可執行文件，或者為測試套件中的每個測試組創建一個測試可執行文件。

  • 對於要基於指定命令運行特定測試的測試套件，您可以為測試套件中的每個測試用例創建一個測試用例可執行文件。

作為測試編寫者，您可以確定哪種方法適合您的用例，並相應地構建測試用例可執行文件。請確保您在每個test.json文件，並且指定的可執行文件正常運行。

當所有設備都準備好運行測試用例時，IDT 會讀取以下文件：

  • 所以此test.json確定要啟動的進程和要設置的環境變量。

  • 所以此suite.json確定要設置的環境變量。

IDT 啟動所需的測試可發出的過程，基於test.json文件，並將所需的環境變量傳遞給進程。

使用 IDT 客户端軟件開發工具包

IDT 客户端軟件開發工具包可讓您簡化在測試可執行文件中編寫測試邏輯的方式，使用 API 命令可與 IDT 和被測設備進行交互。IDT 目前提供下列開發套件：

  • IDT 客户端開發套件

  • IDT 客户端 SDK for Go

這些軟件開發工具包位於<device-tester-extract-location>/sdksfolder。創建新的測試用例可執行文件時，必須將要使用的 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 選項將無法正常工作。為了提供理想的客户體驗，我們建議您為run-suite命令：

timeout-multiplier

指定一個大於 1.0 的值，該值將應用於運行測試時的所有超時。

測試運行者可以使用此參數來增加他們想要運行的測試用例的超時時間。當測試運行者在其run-suite命令，IDT 使用它來計算 IDT_TEST_TIMEOUT 環境變量的值，並將config.timeoutMultiplier字段在 IDT 上下文中。若要支持此參數，您必須執行下列項目：

  • 而不是直接使用test.json文件中，讀取 IDT_TEST_TIMEOUT 環境變量以獲取正確計算的超時值。

  • 檢索config.timeoutMultiplier值，並將其應用於長時間運行的超時。

如需因超時事件而提前退出的詳細資訊，請參指定結束行為。

stop-on-first-failure

指定 IDT 在遇到故障時應停止運行所有測試。

當測試運行者在其run-suite命令，IDT 將在遇到故障時立即停止運行測試。但是，如果測試用例並行運 parallel，那麼這可能會導致意外的結果。要實現支持，請確保如果 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>/logsfolder。

您可以將每個測試用例配置為將測試運行中的日誌（包括來自被測設備的日誌）寫入到<group-id>_<test-id>檔案位於<device-tester-extract-location>/results/execution-id/logsfolder。為此，請從 IDT 上下文中檢索日誌文件的路徑，並使用testData.logFilePath查詢，在該路徑上創建一個文件，然後將所需的內容寫入到該路徑中。IDT 根據正在運行的測試用例自動更新路徑。如果您選擇不為測試用例創建日誌文件，則不會為該測試用例生成任何文件。

您還可以設置文本可執行文件，以根據需要在<device-tester-extract-location>/logsfolder。我們建議您為日誌文件名指定唯一的前綴，以便您的文件不會被覆蓋。

向 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 將在測試對象文件夾中查找測試結果。此文件夾的路徑存放在testData.testArtifactsPath在 IDT 上下文中提交。在此文件夾中，IDT 使用它定位的第一個按字母順序排序的 XML 文件作為測試結果。

如果測試邏輯生成 JUnit XML 結果，則可以將測試結果寫入工件文件夾中的 XML 文件，以便將結果直接提供給 IDT，而不是解析結果，然後使用 API 將結果提交給 IDT。

如果使用此方法，請確保測試邏輯準確地彙總了測試結果，並將結果文件格式與suite-name_report.xmlfile. IDT 不會對您提供的數據執行任何驗證，但以下例外情況除外：

  • IDT 忽略testsuites標籤。相反，它會根據其他報告的測試組結果計算標籤屬性。

  • 至少有一個testsuite標籤必須存在於testsuites。

由於 IDT 對所有測試用例使用相同的工件文件夾，並且不會在測試運行之間刪除結果文件，因此如果 IDT 讀取不正確的文件，此方法還可能導致錯誤報告。我們建議您在所有測試用例中對生成的 XML 結果文件使用相同的名稱，以覆蓋每個測試用例的結果，並確保 IDT 可以使用正確的結果。儘管您可以在測試套件中使用混合方法進行報告，也就是説，對某些測試用例使用 XML 結果文件，並通過 API 為其他測試用例提交結果，但我們不建議使用此方法。

指定結束行為

將文本可執行文件配置為始終以 0 退出代碼退出，即使測試用例報告失敗或錯誤結果也是如此。僅使用非零退出代碼指示測試用例未運行或測試用例可執行文件無法將任何結果傳遞給 IDT。當 IDT 收到非零退出代碼時，它會標記測試用例遇到阻止其運行的錯誤。

IDT 可能會請求或期望測試用例在以下事件中完成之前停止運行。使用此信息配置測試用例可執行文件，以便從測試用例中檢測以下每個事件：

Timeout (逾時)

當測試用例運行時間超過test.jsonfile. 如果測試運行者使用timeout-multiplier參數指定超時乘數，則 IDT 使用乘數計算超時值。

要檢測此事件，請使用 IDT_TEST_TIMEOUT 環境變量。當測試運行者啟動測試時，IDT 會將 IDT_TEST_TIMEOUT 環境變量的值設置為計算的超時值（以秒為單位），並將該變量傳遞給測試用例可執行文件。您可以讀取變量值來設置適當的計時器。

中斷

當測試運行程序中斷 IDT 時發生。例如，通過按Ctrl+C。

由於終端將信號傳播到所有子進程，因此您可以簡單地在測試用例中配置信號處理程序來檢測中斷信號。

或者，您可以定期輪詢 API 以檢查CancellationRequested布林值PollForNotificationsAPI 回應。當 IDT 收到中斷信號時，它會設置CancellationRequested布林值轉換為true。

第一次失敗時停止

當與當前測試用例並行運行的測試用例失敗並且測試運行者使用stop-on-first-failure參數來指定 IDT 在遇到任何故障時應停止。

要檢測此事件，您可以定期輪詢 API 以檢查CancellationRequested布林值PollForNotificationsAPI 回應。當 IDT 遇到故障並配置為在第一次故障時停止時，它會設置CancellationRequested布林值轉換為true。

發生上述任何事件時，IDT 將等待 5 分鐘，以便當前正在運行的所有測試用例完成運行。如果所有正在運行的測試用例未在 5 分鐘內退出，IDT 會強制其每個進程停止。如果 IDT 在進程結束之前尚未收到測試結果，它會將測試用例標記為超時。作為最佳做法，您應確保測試用例遇到其中一個事件時執行以下操作：

  1. 停止運行正常測試邏輯。

  2. 清理所有臨時資源，如測試裝置上的測試件。

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

  4. 結束。