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

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

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

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

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

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

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

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

  • 所选测试test.json用例的决定了要启动的进程和要设置的环境变量。

  • 测试套件suite.json的决定了要设置的环境变量。

IDT 根据test.json文件中指定的命令和参数启动所需的测试可执行进程，并将所需的环境变量传递给该进程。

使用 IDT 客户端 SDK

IDT Client SDK 允许您使用 API 命令来简化在测试可执行文件中编写测试逻辑的方式，您可以使用这些命令与 IDT 和被测设备进行交互。IDT 目前提供以下 SDK：

  • 适用于 Python 的 IDT 客户端 S

  • DT DT SDK for Go

  • DT DK for Java

这些 SDK 位于该<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 管理测试用例可执行生命周期。

启用 IDT CLI 命令

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 CI 命令的更多信息，请参阅调试和运行自定义测试套件。

写入事件日志

在测试运行时，您可以向控制台发送数据stderr，stdout并将事件日志和错误消息写入控制台。有关控制台消息格式的信息，请参阅控制台消息格式。

当 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 会在测试工件文件夹中查找测试结果。此文件夹的路径存储在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 可能会请求或期望测试用例在完成之前停止运行。使用此信息配置您的测试用例可执行文件，以检测测试用例中的每个事件：

超时

当测试用例的运行时间超过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. 退出。