創建 IDT 測試用例可執行文件 - AWS IoT Greengrass
使用 IDT 用戶端開發套件啟用 IDT寫入事件記錄向 IDT 報告結果指定退出行為

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

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

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

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

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

作為測試編寫者，您可以確定哪種方法適合您的用例，並相應地構建測試用例可執行文件。請確定您在每個test.json檔案中提供正確的測試案例可執行路徑，並且指定的可執行檔是否正確執行。

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

  • 所選測試案例的決定要啟動的程序以及要設定的環境變數。test.json

  • 測試套件的決定要設定的環境變數。suite.json

IDT 會根據test.json檔案中指定的命令和引數啟動所需的測試可執行程序，並將必要的環境變數傳遞至處理序。

使用 IDT 用戶端開發套件

IDT 客戶端 SDK 使您可以使用 API 命令簡化在測試可執行文件中編寫測試邏輯的方式，這些命令可以與 IDT 和受測設備進行交互。IDT 目前提供下列軟體開發套件：

  • 適用於 Python

  • 適用 SDK for Go

  • SDK for Java T

這些 SDK 位於<device-tester-extract-location>/sdks資料夾中。當您創建新的測試用例可執行文件時，必須將要使用的 SDK 複製到包含測試用例可執行文件的文件夾中，並在代碼中引用 SDK。本節提供了可用於測試用例可執行文件中的可用 API 命令的簡要說明。

裝置互動

以下命令使您可以與被測設備進行通信，而無需實現任何其他設備交互和連接管理功能。

ExecuteOnDevice

允許測試套件在支持 SSH 或 Docker 外殼連接的設備上運行 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

命run-suite令 IDT CLI 提供了幾個選項，讓測試運行器自定義測試執行。為了允許測試運行程序使用這些選項來運行自定義測試套件，請實現對 IDT CLI 的支持。如果您沒有實現支持，測試運行程序仍然可以運行測試，但是某些 CLI 選項將無法正常工作。為了提供理想的客戶體驗，我們建議您在 IDT CLI 中為run-suite命令實作下列引數的支援：

timeout-multiplier

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

測試運行者可以使用此引數來增加他們想要運行的測試用例的超時時間。當測試運行程序在其run-suite命令中指定此引數時，IDT 會使用它來計算 IDT_TEST_TIMEOUT 環境變量的值，並在 IDT 上下文中設置該config.timeoutMultiplier字段。若要支援此引數，您必須執行下列動作：

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

  • 從 IDT 內容擷取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 命令的詳細資訊，請參閱偵錯並執行自訂測試套件。

寫入事件記錄

在測試運行時，您將數據發送stderr到stdout並將事件日誌和錯誤消息寫入控制台。如需有關主控台訊息格式的詳細資訊，請參閱控制台訊息格式。

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

您可以配置每個測試用例以將日誌從其測試運行（包括來自被測設備的日誌）寫入<group-id>_<test-id>文件<device-tester-extract-location>/results/execution-id/logs夾中的文件。若要這麼做，請使用testData.logFilePath查詢從 IDT 內容擷取記錄檔的路徑，在該路徑上建立檔案，然後將您想要的內容寫入。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。

第一次失敗時停止

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

若要偵測此事件，您可以定期輪詢 API，以檢查PollForNotifications API 回應中的CancellationRequested布林值。當 IDT 遇到失敗並配置為在第一次失敗時停止時，它將CancellationRequested布林值設置為true。

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

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

  2. 清理所有臨時資源，例如被測設備上的測試工件。

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

  4. 退出。