创建 IDT 测试用例可执行文件 - FreeRTOS
使用 IDT 客户端 SDK启用 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 客户端 SDK

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

  • 适用于 Python 的 IDT 客户端 SDK

  • 适用于 Go 的 IDT 客户端 SDK

这些 SDK 位于<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-suiteIDT CLI 中的命令：

timeout-multiplier

指定一个大于 1.0 的值，该值将在运行测试时应用于所有超时。

测试运行者可以使用此参数来增加他们想要运行的测试用例的超时时间。当测试运行者在他们的中指定这个参数时run-suite命令中，IDT 使用它来计算 IDT_TEST_TIMEOUT 环境变量的值并设置config.timeoutMultiplier字段在 IDT 上下文中。要支持这一论点，您必须执行以下操作：

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

  • 检索config.timeoutMultiplier值来自 IDT 上下文并将其应用于长时间运行的超时。

有关由于超时事件而提前退出的更多信息，请参阅。指定退出行为.

stop-on-first-failure

指定如果 IDT 遇到失败，应停止运行所有测试。

当测试运行者在他们的中指定这个参数时run-suite命令，IDT 将在遇到失败后立即停止运行测试。但是，如果测试用例并行运 parallel，那么这可能会导致意想不到的结果。要实施支持，请确保如果 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。要执行此操作，请使用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 可能会请求或期望在以下事件中结束测试用例之前停止运行。使用以下信息配置测试用例可执行文件以检测测试用例中的每个事件：

超时

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

要检测此事件，请使用 IDT_TEST_TEMOUT 环境变量。当测试运行器启动测试时，IDT 会将 IDT_TEST_TEMOUT 环境变量的值设置为计算的超时值（以秒为单位），然后将变量传递给测试用例可执行文件。你可以读取变量值来设置适当的计时器。

中断

当测试运行者中断 IDT 时发生。例如，通过按Ctrl+C.

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

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

第一次失败时停止

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

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

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

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

  2. 清理所有临时资源，例如在测试设备上进行测试的工件。

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

  4. 退出。