创建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：

  • IDTPyt SDK hon 客户端

  • IDTGo SDK 客户端

  • IDTJava 客户端 SDK

SDKs它们位于<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管理测试用例可执行文件的生命周期。

启用IDTCLI命令

该run-suite命令IDTCLI提供了多个选项，允许测试运行器自定义测试执行。要允许测试运行者使用这些选项来运行您的自定义测试套件，您需要实现对的支持IDTCLI。如果您不实现支持，测试运行器仍然可以运行测试，但是某些CLI选项将无法正常运行。为了提供理想的客户体验，我们建议您在中实现对run-suite命令的以下参数的支持 IDTCLI：

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将在遇到故障后立即停止运行测试。但是，如果测试用例是并行运行的，可能会导致意外的结果。要实现支持，请确保在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文件内容，必须使用SendResult命令在测试执行完成IDT之前向其报告测试结果。如果找IDT不到测试结果，则会为测试用例发出错误。以下 Python 摘录显示了将测试结果发送到IDT的命令：

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

如果您没有通过报告结果API，则会在测试工件文件夹中IDT查找测试结果。此文件夹的路径存储在IDT上下testData.testArtifactsPath文中的文件中。在此文件夹中，IDT使用它找到的第一个按字母顺序排序XML的文件作为测试结果。

如果您的测试逻辑生成JUnitXML结果，则可以将测试结果写入 artifacts 文件夹中的一个XML文件中，以便直接向其提供结果，IDT而不必解析结果然后使用将其提交API给。IDT

如果使用此方法，请确保您的测试逻辑准确汇总了测试结果，并将结果文件格式化为与 suite-name_report.xml 文件相同的格式。IDT不对您提供的数据进行任何验证，但以下情况除外：

  • IDT忽略testsuites标签的所有属性。相反，它会从其他报告的测试组结果计算标签属性。

  • testsuites 中必须至少存在一个 testsuite 标签。

由于所有测试用例都IDT使用相同的构件文件夹，并且不会在两次测试运行之间删除结果文件，因此如果IDT读取了错误的文件，则此方法还可能导致错误的报告。我们建议您在所有测试用例中对生成的XML结果文件使用相同的名称，以覆盖每个测试用例的结果，并确保有正确的结果IDT可供使用。尽管您可以在测试套件中使用混合方法进行报告，也就是说，对某些测试用例使用XML结果文件，而API对于其他测试用例，则通过提交结果，但我们不建议使用这种方法。

指定退出行为

将您的文本可执行文件配置为始终以退出代码 0 退出，即使测试用例报告失败或错误结果时也不例外。仅使用非零退出代码表示测试用例未运行，或者测试用例可执行文件无法将任何结果传达给IDT该测试用例。当IDT收到非零退出代码时，它标志着测试用例遇到了导致其无法运行的错误。

IDT在以下事件中，可能会请求或期望测试用例在完成之前停止运行。您可以使用此信息来配置测试用例可执行文件，以检测测试用例中的每个事件：

超时

当测试用例的运行时间超过 test.json 文件中指定的超时值时发生。如果测试运行器使用timeout-multiplier参数来指定超时乘数，则使用乘数IDT计算超时值。

要检测此事件，请使用 IDT TEST _ TIMEOUT 环境变量。当测试运行器启动测试时，IDT将 IDT TEST _ TIMEOUT 环境变量的值设置为计算出的超时值（以秒为单位），并将该变量传递给测试用例可执行文件。您可以读取变量值来设置相应的计时器。

中断

在测试运行器中断IDT时发生。例如，按下 Ctrl+C。

终端会将信号传播到所有子进程，因此您只需在测试用例中配置信号处理程序来检测中断信号即可。

或者，您可以定期轮询API以检查PollForNotificationsAPI响应中CancellationRequested布尔值的值。当IDT收到中断信号时，它会将CancellationRequested布尔值设置为true。

首次失败时停止

当与当前测试用例并行运行的测试用例失败并且测试运行器使用stop-on-first-failure参数来指定遇到任何失败时IDT应停止的测试用例时发生。

要检测此事件，您可以定期轮询API以检查PollForNotificationsAPI响应中CancellationRequested布尔值的值。当IDT遇到故障并配置为在第一次失败时停止时，它会将CancellationRequested布尔值设置为true。

当其中任何一个事件发生时，请IDT等待 5 分钟，让任何当前正在运行的测试用例完成运行。如果所有正在运行的测试用例都未在 5 分钟内退出，则会IDT强制其每个进程停止。如果在流程结束之前IDT没有收到测试结果，它会将测试用例标记为已超时。作为一种最佳实践，您应确保测试用例在遇到其中一个事件时执行以下操作：

  1. 停止运行正常的测试逻辑。

  2. 清理所有的临时资源，例如被测设备上的测试构件。

  3. 向报告测试结果IDT，例如测试失败或错误。

  4. 退出。