创建 IDT 测试用例可执行文件 - Amazon IoT Greengrass
使用 IDT 客户端软件开发工具包启用 IDT CLI 命令写入事件日志向 IDT 报告结果指定退出行为
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅中国的 Amazon Web Services 服务入门。

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

创建 IDT 测试用例可执行文件

您可以通过以下方式创建测试用例可执行文件并将其放置在测试套件文件夹中：

  • 对于使用test.json文件来确定要运行哪些测试，您可以为整个测试套件创建单个测试用例可执行文件，或者为测试套件中的每个测试组创建一个测试可执行文件。

  • 对于要根据指定命令运行特定测试的测试套件，您可以为测试套件中的每个测试用例创建一个可执行的测试用例。

作为测试编写者，您可以确定哪种方法适合您的用例，并相应地构建您的测试用例可执行文件。请确保您在每个test.json文件，并且指定的可执行文件正确运行。

当所有设备都准备好运行测试用例时，IDT 将读取以下文件：

  • 这些区域有：test.json确定要启动的进程和要设置的环境变量。

  • 这些区域有：suite.json确定要设置的环境变量。

IDT 启动所需的测试可执行的过程，基于test.json文件，并将所需的环境变量传递给进程。

使用 IDT 客户端软件开发工具包

通过 IDT 客户端 SDK，您可以使用 API 命令来简化在测试可执行文件中编写测试逻辑的方式，这些命令可以与 IDT 和受测设备进行交互。IDT 目前提供以下软件开发工具包：

  • 适用于 Python 的 IDT 客户端开发工具包

  • 适用于 Go 的 IDT 客户端开发工具包

这些软件开发工具包位于<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_OUT 环境变量的值，并将config.timeoutMultiplier字段。要支持此参数，您必须执行以下操作：

  • 而不是直接使用test.json文件中，读取 IDT_TEST_TOUEY 环境变量以获取正确计算的超时值。

  • 检索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>/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.xml文件。IDT 不会对您提供的数据执行任何验证，但以下例外情况除外：

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

  • 至少有一个testsuite标签必须存在于testsuites.

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

指定退出行为

将文本可执行文件配置为始终退出，退出代码为 0，即使测试用例报告失败或错误结果也是如此。仅使用非零退出代码来指示测试用例未运行，或者测试用例可执行文件无法将任何结果传递给 IDT。当 IDT 收到非零退出代码时，它标记测试用例遇到阻止其运行的错误。

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

Timeout

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

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

中断

当测试运行器中断 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. 退出。