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

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

建立IDT測試案例可執行檔

您可以透過下列方式，在測試套件資料夾中建立和放置可執行的測試案例：

  • 對於使用test.json檔案中的引數或環境變數來決定要執行哪些測試的測試套件，您可以建立整個測試套件可執行的單一測試案例，或測試套件中每個測試群組可執行的測試案例。

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

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

當所有裝置準備好執行測試案例時， 會IDT讀取下列檔案：

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

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

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

使用IDT用戶端 SDK

IDT 用戶端SDKs可讓您使用可與 互動的API命令IDT以及正在測試的裝置，簡化在測試可執行檔中編寫測試邏輯的方式。IDT 目前提供下列 SDKs：

  • IDT Python SDK的用戶端

  • IDT Client SDK for Go

  • IDT Java 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 管理測試案例可執行生命週期。

啟用IDTCLI命令

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

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狀態機器會包含您所需的狀態，而且您不需要採取其他動作。不過，如果您使用的是自訂狀態機器，則使用 狀態機器範例：執行使用者選取的測試群組做為範例，在狀態機器中新增所需的狀態。

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

寫入事件日誌

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

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

您可以設定每個測試案例，將日誌從其測試執行寫入至位於 <device-tester-extract-location>/results/execution-id/logs 資料夾中<group-id>_<test-id>的檔案，包括測試中裝置的日誌。若要執行此操作，請從具有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檔案的內容，您必須在測試執行完成IDT之前使用 SendResult命令將測試結果報告至 。如果 IDT無法找到測試的結果，則會發出測試案例的錯誤。下列 Python 摘錄顯示將測試結果傳送至 的命令IDT：

request-variable = SendResultRequest(TestResult(result))
client.send_result(request-variable)

如果您未透過 報告結果API， 會在測試成品資料夾中IDT尋找測試結果。此資料夾的路徑會儲存在 IDT 內容中的 testData.testArtifactsPath 檔案中。在此資料夾中， IDT會使用第一個依字母順序排序XML的檔案作為測試結果。

如果您的測試邏輯產生JUnitXML結果，您可以將測試結果寫入成品資料夾中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。

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

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

第一次失敗時停止

當與目前測試案例平行執行的測試案例失敗，且測試執行器使用stop-on-first-failure引數指定 IDT應在遇到任何失敗時停止時，便會發生。

若要偵測此事件，您可以定期輪詢 CancellationRequested API，以檢查PollForNotificationsAPI回應中布林值的值。當 IDT遇到故障且 設定為在第一次故障時停止時，它會將CancellationRequested布林值設定為 true。

當發生上述任何事件時， 會IDT等待 5 分鐘，讓任何目前執行的測試案例完成執行。如果所有執行中的測試案例未在 5 分鐘內結束， 會IDT強制其每個程序停止。如果 IDT 未在程序結束前收到測試結果，則會將測試案例標記為已逾時。最佳實務是，您應該確保測試案例在遇到其中一個事件時執行下列動作：

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

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

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

  4. 結束。