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

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

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

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

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

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

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

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

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

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

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

使用 IDT 客户端开发工具包

借助 IDT 客户端 SDKs，您可以使用 API 命令简化在测试可执行文件中编写测试逻辑的方式，这些命令可用于与 IDT 和所测试设备交互。IDT 当前提供以下SDKs：

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

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

这些 SDKs 位于 <device-tester-extract-location>/sdks 文件夹中。在创建新的测试用例可执行文件时，您必须将要使用的开发工具包复制到包含测试用例可执行文件的文件夹中，并在代码中引用开发工具包。本节简要介绍了您可以在测试案例可执行文件中使用的可用 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 命令

命令 IDT CLI 提供了多个选项，让测试运行程序自定义测试执行。run-suite要允许测试运行程序使用这些选项来运行自定义测试套件，您需要实施对 IDT CLI 的支持。如果您没有实施支持，测试运行程序仍然能够运行测试，但某些 CLI 选项无法正常运行。为了提供理想的客户体验，我们建议您在 IDT CLI 中对 run-suite 命令的以下参数实施支持：

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 状态机会包含所需的状态，您无需执行其他操作。但是，如果您使用的是自定义状态机，则使用 状态机示例：运行用户选择的测试组 作为示例在状态机中添加所需状态。

有关 IDT CLI 命令的更多信息，请参阅调试和运行自定义测试套件。

写入事件日志

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

当 IDT 完成运行测试套件时，此信息也会在位于 test_manager.log 文件夹的 <devicetester-extract-location>/results/<execution-id>/logs 文件中提供。

您可以将每个测试用例配置为将来自其测试运行的日志（包括来自所测试设备的日志）写入到位于 <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 以检查 CancellationRequested API 响应中的 PollForNotifications 布尔值。当 IDT 收到中断信号时，它会将 CancellationRequested 布尔值设置为 true。

在第一次失败时停止

在与当前测试用例并行运行的测试用例失败并且测试运行程序使用 stop-on-first-failure 参数指定 IDT 在遇到任何故障时应停止时，发生此错误。

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

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

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

  2. 清除任何临时资源，例如所测试设备上的测试项目。

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

  4. 退出。