配置 IDT 状态机 - Amazon IoT Greengrass
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 Amazon Web Services 服务入门

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

配置 IDT 状态机

状态机是控制测试套件执行流程的结构。它确定测试套件的起始状态,根据用户定义的规则管理状态转换,并继续通过这些状态转换,直到达到结束状态。

如果您的测试套件不包括用户定义的状态机,IDT 将为您生成状态机。默认状态机执行以下功能:

  • 为测试运行者提供选择和运行特定测试组的能力,而不是整个测试套件。

  • 如果未选择特定的测试组,则按随机顺序运行测试套件中的每个测试组。

  • 生成报告并打印显示每个测试组和测试用例的测试结果的控制台摘要。

IDT 测试套件的状态机必须满足以下条件:

  • 每个状态对应于 IDT 要执行的操作,例如运行测试组或产品报告文件。

  • 转换到状态将执行与状态关联的操作。

  • 每个状态都定义了下一个状态的转换规则。

  • 终止状态必须是Succeed或者Fail

状态机格式

您可以使用以下模板配置您自己的<custom-test-suite-folder>/suite/state_machine.jsonfile:

{ "Comment": "<description>", "StartAt": "<state-name>", "States": { "<state-name>": { "Type": "<state-type>", // Additional state configuration } // Required states "Succeed": { "Type": "Succeed" }, "Fail": { "Type": "Fail" } } }

包含值的所有字段都为必填字段,如下所述:

Comment

状态机的描述。

StartAt

IDT 开始运行测试套件的状态的名称。的值StartAt必须设置为States对象。

States

将用户定义的状态名称映射到有效 IDT 状态的对象。每个国家。状态机名称对象包含映射到状态机名称

这些区域有:States对象必须包含SucceedFail状态。有关有效状态的信息,请参阅有效的状态和状态定义

有效的状态和状态定义

本节介绍可在 IDT 状态机中使用的所有有效状态的状态定义。以下某些状态支持测试用例级别的配置。但是,我们建议您在测试组级别而不是测试用例级别配置状态转换规则,除非绝对必要。

RunTask

这些区域有:RunTask状态从测试套件中定义的测试组运行测试用例。

{ "Type": "RunTask", "Next": "<state-name>", "TestGroup": "<group-id>", "TestCases": [ "<test-id>" ], "ResultVar": "<result-name>" }

包含值的所有字段都为必填字段,如下所述:

Next

在当前状态下执行操作后,要转换为的状态的名称。

TestGroup

可选。要运行的测试组的 ID。如果未指定此值,则 IDT 将运行测试运行程序选择的测试组。

TestCases

可选。中指定的组中的测试用例 ID 数组TestGroup。基于TestGroupTestCases,IDT 确定测试执行行为,如下所示:

  • 当这两者TestGroupTestCases时,IDT 会从测试组运行指定的测试用例。

  • 何时TestCases指定,TestGroup,则 IDT 将运行指定的测试用例。

  • 何时TestGroup指定,但TestCases,IDT 将运行指定测试组内的所有测试案例。

  • 当两者都没有TestGroup或者TestCases时,IDT 会从测试运行程序从 IDT CLI 中选择的测试组运行所有测试用例。要为测试运行者启用组选择,必须同时包含RunTaskChoice状态statemachine.json文件。有关其工作方式的示例,请参阅示例状态机:运行用户选择的测试组

    有关为测试运行者启用 IDT CLI 命令的更多信息,请参阅启用 IDT CLI 命令

ResultVar

要与测试运行结果一起设置的上下文变量的名称。如果您未指定TestGroup。IDT 设置您在ResultVartrue或者false根据以下内容:

  • 如果变量名称的形式为text_text_passed,则将该值设置为第一个测试组中的所有测试是通过还是跳过。

  • 在所有其他情况下,将该值设置为所有测试组中的所有测试是通过还是跳过。

通常情况下,您可以使用RunTask状态指定测试组 ID 而不指定单个测试用例 ID,以便 IDT 运行指定测试组中的所有测试用例。由此状态运行的所有测试用例都以随机顺序并行运行。但是,如果所有测试用例都需要一台设备运行,并且只有一台设备可用,则测试用例将按顺序运行。

错误处理

如果任何指定的测试组或测试用例 ID 无效,则此状态会发出RunTaskError执行错误。如果状态遇到执行错误,则它还设置hasExecutionError变量设置为true

Choice

这些区域有:Choice状态允许您根据用户定义的条件动态设置要过渡到的下一个状态。

{ "Type": "Choice", "Default": "<state-name>", "FallthroughOnError": true | false, "Choices": [ { "Expression": "<expression>", "Next": "<state-name>" } ] }

包含值的所有字段都为必填字段,如下所述:

Default

在中没有定义任何表达式时,要转换为的默认状态Choices可以被评估为true

FallthroughOnError

可选。指定状态在计算表达式时遇到错误时的行为。将设置为true如果计算结果出现错误,则要跳过表达式。如果没有表达式匹配,则状态机会转换为Default状态。如果FallthroughOnError值,则默认为false

Choices

表达式和状态数组,用于确定在当前状态下执行操作后转换到哪个状态。

Choices.Expression

计算结果为布尔值的表达式字符串。如果表达式的计算结果为true,则状态机会转换为Choices.Next。表达式字符串从状态机上下文中检索值,然后对它们执行操作以获得布尔值。有关访问状态机上下文的信息,请参阅状态机上下文

Choices.Next

在中定义的表达式名称,要转换为的状态的名称Choices.Expression评估为true

错误处理

这些区域有:Choice状态可能需要在以下情况下进行错误处理:

  • 选择表达式中的某些变量不存在于状态机上下文中。

  • 表达式的结果不是布尔值。

  • JSON 查找的结果不是字符串、数字或布尔值。

您无法使用Catch块处理此状态下的错误。如果要在状态机遇到错误时停止执行状态机,则必须将FallthroughOnErrorfalse。但是,建议您将FallthroughOnErrortrue,并根据您的用例,执行以下操作之一:

  • 如果您正在访问的变量在某些情况下不存在,则使用Default和其他Choices块指定下一个状态。

  • 如果您正在访问的变量应该始终存在,则将Default状态Fail

Parallel

这些区域有:Parallel状态允许您相互并行定义和运行新的状态机。

{ "Type": "Parallel", "Next": "<state-name>", "Branches": [ <state-machine-definition> ] }

包含值的所有字段都为必填字段,如下所述:

Next

在当前状态下执行操作后,要转换为的状态的名称。

Branches

要运行的状态机定义数组。每个状态机定义都必须包含其自己的StartAtSucceed, 和Fail状态。此数组中的状态机定义不能引用其自身定义之外的状态。

注意

由于每个分支状态机共享相同的状态机上下文,因此在一个分支中设置变量,然后从另一个分支读取这些变量可能会导致意外行为。

这些区域有:Parallel状态仅在运行所有分支状态计算机后才会移动到下一个状态。需要设备的每个状态都会等待运行,直到设备可用。如果有多个设备可用,则此状态会从多个组并行运行测试用例。如果没有足够的设备可用,则测试用例将按顺序运行。由于测试用例并行运行时以随机顺序运行,因此可能会使用不同的设备来运行同一测试组中的测试。

错误处理

确保分支状态机和父状态机都转换到Fail状态来处理执行错误。

由于分支状态机不会将执行错误传输到父状态机,因此您不能使用Catch块来处理分支状态机中的执行错误。请改用hasExecutionErrors值在共享状态机上下文中。有关其工作方式的示例,请参阅示例状态机:并行运行两个测试组

AddProductFeatures

这些区域有:AddProductFeatures状态允许您将产品功能添加到awsiotdevicetester_report.xml由 IDT 生成的文件。

产品功能是用户定义的有关设备可能满足的特定条件的信息。例如,MQTT产品功能可以指定设备正确发布 MQTT 消息。在报告中,产品功能设置为supportednot-supported或自定义值,具体取决于指定的测试是否通过。

注意

这些区域有:AddProductFeatures状态本身不会生成报告。此状态必须转换到Reportstate生成报告。

{ "Type": "Parallel", "Next": "<state-name>", "Features": [ { "Feature": "<feature-name>", "Groups": [ "<group-id>" ], "OneOfGroups": [ "<group-id>" ], "TestCases": [ "<test-id>" ], "IsRequired": true | false, "ExecutionMethods": [ "<execution-method>" ] } ] }

包含值的所有字段都为必填字段,如下所述:

Next

在当前状态下执行操作后,要转换为的状态的名称。

Features

要显示在awsiotdevicetester_report.xml文件。

Feature

功能名称

FeatureValue

可选。要在报告中使用的自定义值,而不是supported。如果未指定此值,则根据测试结果,要素值将设置为supported或者not-supported

如果您将自定义值用于FeatureValue,您可以在不同条件下测试同一要素,IDT 将支持条件的要素值连接起来。例如,以下摘录显示了MyFeature功能,具有两个单独的要素值:

... { "Feature": "MyFeature", "FeatureValue": "first-feature-supported", "Groups": ["first-feature-group"] }, { "Feature": "MyFeature", "FeatureValue": "second-feature-supported", "Groups": ["second-feature-group"] }, ...

如果两个测试组都通过,则要素值设置为first-feature-supported, second-feature-supported

Groups

可选。测试组 ID 的数组。每个指定测试组中的所有测试都必须通过,才能支持该功能。

OneOfGroups

可选。测试组 ID 的数组。至少一个指定测试组中的所有测试都必须通过,才能支持该功能。

TestCases

可选。测试用例 ID 的数组。如果指定此值,则应用以下内容:

  • 必须通过所有指定的测试用例才能支持该功能。

  • Groups只能包含一个测试组 ID。

  • OneOfGroups必须不指定。

IsRequired

可选。将设置为false将此功能标记为报表中的可选功能。默认值为 true

ExecutionMethods

可选。一个与protocol指定的值device.json文件。如果指定了此值,则测试运行者必须指定protocol值,该值与此数组中的某个值匹配,以便将要素包括在报表中。如果未指定此值,则要素将始终包含在报告中。

使用AddProductFeatures状态,则必须设置ResultVar中的RunTask状态设置为以下值之一:

  • 如果您指定了单个测试用例 ID,则将ResultVargroup-id_test-id_passed

  • 如果您没有指定单个测试用例 ID,则将ResultVargroup-id_passed

这些区域有:AddProductFeatures状态检查测试结果的方式如下:

  • 如果未指定任何测试用例 ID,则每个测试组的结果将根据group-id_passed变量在状态机上下文中。

  • 如果您确实指定了测试用例 ID,则每个测试的结果将根据group-id_test-id_passed变量在状态机上下文中。

错误处理

如果在此状态下提供的组 ID 不是有效的组 ID,则此状态会导致AddProductFeaturesError执行错误。如果状态遇到执行错误,则它还设置hasExecutionErrors变量设置为true

Report

这些区域有:Report状态下将生成suite-name_Report.xmlawsiotdevicetester_report.xml文件。此状态还会将报告流式传输到控制台。

{ "Type": "Report", "Next": "<state-name>" }

包含值的所有字段都为必填字段,如下所述:

Next

在当前状态下执行操作后,要转换为的状态的名称。

您应该始终转换到Report状态,以便测试运行者可以查看测试结果。通常,此状态之后的下一个状态是Succeed

错误处理

如果此状态在生成报告时遇到问题,则会发出ReportError执行错误。

LogMessage

这些区域有:LogMessage状态下将生成test_manager.log文件,并将日志消息流传送到控制台。

{ "Type": "LogMessage", "Next": "<state-name>" "Level": "info | warn | error" "Message": "<message>" }

包含值的所有字段都为必填字段,如下所述:

Next

在当前状态下执行操作后,要转换为的状态的名称。

Level

创建日志消息的错误级别。如果指定的级别无效,则此状态将生成错误消息并丢弃它。

Message

要记录的消息。

SelectGroup

这些区域有:SelectGroup状态会更新状态机上下文,以指示选择了哪些组。由此状态设置的值由任何后续Choice状态。

{ "Type": "SelectGroup", "Next": "<state-name>" "TestGroups": [ <group-id>" ] }

包含值的所有字段都为必填字段,如下所述:

Next

在当前状态下执行操作后,要转换为的状态的名称。

TestGroups

将标记为选定的测试组数组。对于此数组中的每个测试组 ID,group-id_selected变量设置为true在上下文中。请确保您提供了有效的测试组 ID,因为 IDT 不会验证指定的组是否存在。

Fail

这些区域有:Fail状态表示状态机未正确执行。这是状态机的结束状态,并且每个状态机定义都必须包含此状态。

{ "Type": "Fail" }

Succeed

这些区域有:Succeed状态表示状态机正确执行。这是状态机的结束状态,并且每个状态机定义都必须包含此状态。

{ "Type": "Succeed" }

状态机上下文

状态机上下文是只读 JSON 文档,其中包含状态机在执行期间可用的数据。状态机上下文只能从状态机访问,并且包含确定测试流程的信息。例如,您可以使用测试运行者在userdata.json文件来确定是否需要运行特定测试。

状态机上下文使用以下格式:

{ "pool": { <device-json-pool-element> }, "userData": { <userdata-json-content> }, "config": { <config-json-content> }, "suiteFailed": true | false, "specificTestGroups": [ "<group-id>" ], "specificTestCases": [ "<test-id>" ], "hasExecutionErrors": true }
pool

有关为测试运行选定的设备池的信息。对于选定的设备池,此信息将从device.json文件。

userData

中的信息userdata.json文件。

config

信息引脚config.json文件。

suiteFailed

该值设置为false状态机启动时。如果测试组在RunTask状态,则此值设置为true状态机执行的剩余持续时间。

specificTestGroups

如果测试运行程序选择要运行的特定测试组,而不是整个测试套件,则会创建此项,并包含特定测试组 ID 的列表。

specificTestCases

如果测试运行程序选择要运行的特定测试用例,而不是整个测试套件,则会创建此项,并包含特定测试用例 ID 的列表。

hasExecutionErrors

状态机启动时不退出。如果任何状态遇到执行错误,则会创建此变量并将其设置为true状态机执行的剩余持续时间。

您可以使用 JSONPath 表示法查询上下文。状态定义中的 JSONPath 查询的语法是{{$.query}}。您可以在某些状态中使用 JSONPath 查询作为占位符字符串。IDT 将占位符字符串替换为来自上下文的已评估 JSONPath 查询的值。您可以对以下值使用占位符:

  • 这些区域有:TestCases中的值RunTask状态。

  • 这些区域有:ExpressionChoice状态。

当您从状态机上下文访问数据时,请务必满足以下条件:

  • 您的 JSON 路径必须以开头$.

  • 每个值必须求值为字符串、数字或布尔值。

有关使用 JSONPath 符号从上下文访问数据的更多信息,请参阅使用 IDT 上下文

执行错误

执行错误是状态机定义中的错误,状态机在执行状态时遇到这些错误。IDT 将有关每个错误的信息记录在test_manager.log文件,并将日志消息流传送到控制台。

您可以使用以下方法处理执行错误:

Catch

使用Catch中,将以下内容添加到状态定义中:

"Catch": [ { "ErrorEquals": [ "<error-type>" ] "Next": "<state-name>" } ]

包含值的所有字段都为必填字段,如下所述:

Catch.ErrorEquals

要捕获的错误类型的数组。如果执行错误与指定值之一匹配,则状态机转换为Catch.Next。有关其产生的错误类型的信息,请参阅每个状态定义。

Catch.Next

如果当前状态遇到与Catch.ErrorEquals

捕获块按顺序处理,直到一个匹配。如果没有错误与 Catch 块中列出的错误匹配,则状态计算机将继续执行。由于执行错误是由不正确的状态定义导致的,因此我们建议您在状态遇到执行错误时转换到 “失败” 状态。

hasExecutionError

当某些状态遇到执行错误时,除了发出错误之外,它们还将hasExecutionError值为true在状态机上下文中。您可以使用此值来检测何时发生错误,然后使用Choice状态以将状态机转换为Fail状态。

此方法具有以下特征。

  • 状态机不以分配给hasExecutionError,并且在特定状态设置之前,此值才可用。这意味着您必须明确设置FallthroughOnErrorfalse(对于 )Choice表示访问此值以防止状态机在没有发生执行错误时停止。

  • 一旦它被设置为truehasExecutionError永远不会设置为 false 或从上下文中删除。这意味着此值仅在第一次将其设置为true,并且对于所有后续状态,它不提供有意义的值。

  • 这些区域有:hasExecutionError值与Parallel状态,这可能会导致意外结果,具体取决于访问顺序。

由于这些特性,如果您可以使用 Catch 块,我们不建议您使用此方法。

示例状态机

本章节提供状态机配置的一些示例。

示例状态机:运行单个测试组

状态机:

  • 使用 id 运行测试组GroupA,它必须位于套件中group.json文件。

  • 检查执行错误和转换为Fail(如果找到任何)。

  • 生成报告并过渡到Succeed如果没有错误,Fail否则为。

{ "Comment": "Runs a single group and then generates a report.", "StartAt": "RunGroupA", "States": { "RunGroupA": { "Type": "RunTask", "Next": "Report", "TestGroup": "GroupA", "Catch": [ { "ErrorEquals": [ "RunTaskError" ], "Next": "Fail" } ] }, "Report": { "Type": "Report", "Next": "Succeed", "Catch": [ { "ErrorEquals": [ "ReportError" ], "Next": "Fail" } ] }, "Succeed": { "Type": "Succeed" }, "Fail": { "Type": "Fail" } } }

示例状态机:运行用户选择的测试组

状态机:

  • 检查测试运行者是否选择了特定的测试组。状态机不检查特定的测试用例,因为测试运行者不能在不选择测试组的情况下选择测试用例。

  • 如果选择测试组:

    • 在所选测试组中运行测试用例。为此,状态机不会在RunTask状态。

    • 在运行所有测试并退出后生成报告。

  • 如果未选择测试组:

    • 在测试组中运行测试GroupA

    • 生成报告并退出。

{ "Comment": "Runs specific groups if the test runner chose to do that, otherwise runs GroupA.", "StartAt": "SpecificGroupsCheck", "States": { "SpecificGroupsCheck": { "Type": "Choice", "Default": "RunGroupA", "FallthroughOnError": true, "Choices": [ { "Expression": "{{$.specificTestGroups[0]}} != ''", "Next": "RunSpecificGroups" } ] }, "RunSpecificGroups": { "Type": "RunTask", "Next": "Report", "Catch": [ { "ErrorEquals": [ "RunTaskError" ], "Next": "Fail" } ] }, "RunGroupA": { "Type": "RunTask", "Next": "Report", "TestGroup": "GroupA", "Catch": [ { "ErrorEquals": [ "RunTaskError" ], "Next": "Fail" } ] }, "Report": { "Type": "Report", "Next": "Succeed", "Catch": [ { "ErrorEquals": [ "ReportError" ], "Next": "Fail" } ] }, "Succeed": { "Type": "Succeed" }, "Fail": { "Type": "Fail" } } }

示例状态机:运行具有产品功能的单个测试组

状态机:

  • 运行测试组GroupA

  • 检查执行错误和转换为Fail(如果找到任何)。

  • 添加FeatureThatDependsOnGroupA功能添加到awsiotdevicetester_report.xmlfile:

    • 如果GroupA过程,则将要素设置为supported

    • 报告中不会将此功能标记为可选功能。

  • 生成报告并过渡到Succeed如果没有错误,Fail否则

{ "Comment": "Runs GroupA and adds product features based on GroupA", "StartAt": "RunGroupA", "States": { "RunGroupA": { "Type": "RunTask", "Next": "AddProductFeatures", "TestGroup": "GroupA", "ResultVar": "GroupA_passed", "Catch": [ { "ErrorEquals": [ "RunTaskError" ], "Next": "Fail" } ] }, "AddProductFeatures": { "Type": "AddProductFeatures", "Next": "Report", "Features": [ { "Feature": "FeatureThatDependsOnGroupA", "Groups": [ "GroupA" ], "IsRequired": true } ] }, "Report": { "Type": "Report", "Next": "Succeed", "Catch": [ { "ErrorEquals": [ "ReportError" ], "Next": "Fail" } ] }, "Succeed": { "Type": "Succeed" }, "Fail": { "Type": "Fail" } } }

示例状态机:并行运行两个测试组

状态机:

  • 运行GroupAGroupB并行测试组。这些区域有:ResultVar变量存储在上下文中RunTask状态中的状态可用于AddProductFeatures状态。

  • 检查执行错误和转换为Fail(如果找到任何)。此状态机不使用Catch块,因为该方法不检测分支状态机中的执行错误。

  • 将要素添加到awsiotdevicetester_report.xml文件基于传递

    • 如果GroupA过程,则将要素设置为supported

    • 报告中不会将此功能标记为可选功能。

  • 生成报告并过渡到Succeed如果没有错误,Fail否则

如果在设备池中配置了两个设备,则GroupAGroupB可以同时运行。但是,如果GroupA或者GroupB有多个测试,那么这两个设备可以分配给这些测试。如果只配置了一个设备,则测试组将按顺序运行。

{ "Comment": "Runs GroupA and GroupB in parallel", "StartAt": "RunGroupAAndB", "States": { "RunGroupAAndB": { "Type": "Parallel", "Next": "CheckForErrors", "Branches": [ { "Comment": "Run GroupA state machine", "StartAt": "RunGroupA", "States": { "RunGroupA": { "Type": "RunTask", "Next": "Succeed", "TestGroup": "GroupA", "ResultVar": "GroupA_passed", "Catch": [ { "ErrorEquals": [ "RunTaskError" ], "Next": "Fail" } ] }, "Succeed": { "Type": "Succeed" }, "Fail": { "Type": "Fail" } } }, { "Comment": "Run GroupB state machine", "StartAt": "RunGroupB", "States": { "RunGroupA": { "Type": "RunTask", "Next": "Succeed", "TestGroup": "GroupB", "ResultVar": "GroupB_passed", "Catch": [ { "ErrorEquals": [ "RunTaskError" ], "Next": "Fail" } ] }, "Succeed": { "Type": "Succeed" }, "Fail": { "Type": "Fail" } } } ] }, "CheckForErrors": { "Type": "Choice", "Default": "AddProductFeatures", "FallthroughOnError": true, "Choices": [ { "Expression": "{{$.hasExecutionErrors}} == true", "Next": "Fail" } ] }, "AddProductFeatures": { "Type": "AddProductFeatures", "Next": "Report", "Features": [ { "Feature": "FeatureThatDependsOnGroupA", "Groups": [ "GroupA" ], "IsRequired": true }, { "Feature": "FeatureThatDependsOnGroupB", "Groups": [ "GroupB" ], "IsRequired": true } ] }, "Report": { "Type": "Report", "Next": "Succeed", "Catch": [ { "ErrorEquals": [ "ReportError" ], "Next": "Fail" } ] }, "Succeed": { "Type": "Succeed" }, "Fail": { "Type": "Fail" } } }