本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# Device Advisor 工作流
本教程说明如何创建自定义测试套件，以及如何在控制台中对要测试的设备运行测试。测试完成后，您可以查看测试结果和详细日志。
## 先决条件
在开始此教程之前，请完成 [设置](device-advisor-setting-up.md) 中概述的步骤。
## 创建测试套件定义
首先，[安装一个 AWS SDK](https://docs.aws.amazon.com/iot/latest/developerguide/iot-connect-service.html#iot-service-sdks)。
### `rootGroup` 语法
根组是一个 JSON 字符串，用于指定要在测试套件中包含哪些测试使用案例。它还为这些测试使用案例指定了任何必要的配置。使用根组根据您的需要构建和排列测试套件。测试套件的层次结构如下：
```
test suite → test group(s) → test case(s)
```
测试套件必须至少有一个测试组，并且每个测试组必须至少有一个测试使用案例。Device Advisor 将按照定义的测试组和测试用例顺序运行测试。
每个根组都遵循此基本结构：
```
{
"configuration": { // for all tests in the test suite
"": ""
}
"tests": [{
"name": ""
"configuration": { // for all sub-groups in this test group
"": ""
},
"tests": [{
"name": ""
"configuration": { // for all test cases in this test group
"": ""
},
"test": {
"id": ""
"version": ""
}
}]
}]
}
```
在根组中，您使用组包含的 `name`、`configuration` 和 `tests` 定义测试套件。`tests` 组包含各个测试的定义。您使用 `name`、`configuration` 和一个 `test` 数据块来定义每个测试，该数据块定义了该测试的测试使用案例。最后，每个测试使用案例都使用 `id` 和 `version` 来定义。
有关如何使用每个测试使用案例（`test` 数据块）中 `"id"` 和 `"version"` 字段的信息，请参阅 [Device Advisor 测试使用案例](device-advisor-tests.md)。该部分还包含有关可用 `configuration` 设置的信息。
以下数据块是根组配置的示例。此配置指定 *MQTT Connect Happy Case* 和 *MQTT Connect Exponential Backoff Retries* 测试使用案例，以及配置字段的描述。
```
{
"configuration": {}, // Suite-level configuration
"tests": [ // Group definitions should be provided here
{
"name": "My_MQTT_Connect_Group", // Group definition name
"configuration": {} // Group definition-level configuration,
"tests": [ // Test case definitions should be provided here
{
"name": "My_MQTT_Connect_Happy_Case", // Test case definition name
"configuration": {
"EXECUTION_TIMEOUT": 300 // Test case definition-level configuration, in seconds
},
"test": {
"id": "MQTT_Connect", // test case id
"version": "0.0.0" // test case version
}
},
{
"name": "My_MQTT_Connect_Jitter_Backoff_Retries", // Test case definition name
"configuration": {
"EXECUTION_TIMEOUT": 600 // Test case definition-level configuration, in seconds
},
"test": {
"id": "MQTT_Connect_Jitter_Backoff_Retries", // test case id
"version": "0.0.0" // test case version
}
}]
}]
}
```
创建测试套件定义时，您必须提供根组配置。保存在响应对象中返回的 `suiteDefinitionId`。您可以使用此 ID 检索测试套件定义信息和运行测试套件。
以下是一个 Java SDK 示例：
```
response = iotDeviceAdvisorClient.createSuiteDefinition(
CreateSuiteDefinitionRequest.builder()
.suiteDefinitionConfiguration(SuiteDefinitionConfiguration.builder()
.suiteDefinitionName("your-suite-definition-name")
.devices(
DeviceUnderTest.builder()
.thingArn("your-test-device-thing-arn")
.certificateArn("your-test-device-certificate-arn")
.deviceRoleArn("your-device-role-arn") //if using SigV4 for MQTT over WebSocket
.build()
)
.rootGroup("your-root-group-configuration")
.devicePermissionRoleArn("your-device-permission-role-arn")
.protocol("MqttV3_1_1 || MqttV5 || MqttV3_1_1_OverWebSocket || MqttV5_OverWebSocket")
.build()
)
.build()
)
```
## 获取测试套件定义
创建测试套件定义后，您会在 `CreateSuiteDefinition` API 操作的响应对象中收到 `suiteDefinitionId`。
当操作返回 `suiteDefinitionId` 时，您可能会在每个组中看到新的 `id` 字段，并在根组中看到测试使用案例定义。您可以使用它们 IDs 来运行测试套件定义的子集。
Java SDK 示例：
```
response = iotDeviceAdvisorClient.GetSuiteDefinition(
GetSuiteDefinitionRequest.builder()
.suiteDefinitionId("your-suite-definition-id")
.build()
)
```
## 获取测试端点
使用 `GetEndpoint` API 操作获取设备使用的测试端点。选择最适合您的测试的端点。要同时运行多个测试套件，请通过提供 `thing ARN`、`certificate ARN` 或 `device role ARN` 使用设备级端点。要运行单个测试套件，请不要为 GetEndpoint 操作提供任何参数来选择账户级端点。
SDK 示例：
```
response = iotDeviceAdvisorClient.getEndpoint(GetEndpointRequest.builder()
.certificateArn("your-test-device-certificate-arn")
.thingArn("your-test-device-thing-arn")
.deviceRoleArn("your-device-role-arn") //if using SigV4 for MQTT over WebSocket
.build())
```
## 启动测试套件运行
在创建测试套件定义并配置测试设备以连接到 Device Advisor 测试端点之后，请使用 `StartSuiteRun` API 运行您的测试套件。
对于 MQTT 客户，使用 `certificateArn` 或 `thingArn` 运行测试套件。如果两者都完成了配置，当证书属于该事物时，则使用该证书。
对于 MQTT 而不是 WebSocket 客户，请使用`deviceRoleArn`来运行测试套件。如果指定的角色与在测试套件定义中指定的角色不同，则指定的角色将覆盖定义的角色。
对于 `.parallelRun()`，如果通过一个 AWS 账户使用设备级端点并行运行多个测试套件，则使用 `true`。
SDK 示例：
```
response = iotDeviceAdvisorClient.startSuiteRun(StartSuiteRunRequest.builder()
.suiteDefinitionId("your-suite-definition-id")
.suiteRunConfiguration(SuiteRunConfiguration.builder()
.primaryDevice(DeviceUnderTest.builder()
.certificateArn("your-test-device-certificate-arn")
.thingArn("your-test-device-thing-arn")
.deviceRoleArn("your-device-role-arn") //if using SigV4 for MQTT over WebSocket
.build())
.parallelRun(true | false)
.build())
.build())
```
保存响应中的 `suiteRunId`。您会用此来检索此测试套件运行的结果。
## 运行一个测试套件
启动测试套件运行后，您可以使用 `GetSuiteRun` API 检查其进度及结果。
SDK 示例：
```
// Using the SDK, call the GetSuiteRun API.
response = iotDeviceAdvisorClient.GetSuiteRun(
GetSuiteRunRequest.builder()
.suiteDefinitionId("your-suite-definition-id")
.suiteRunId("your-suite-run-id")
.build())
```
## 停止测试套件运行
要停止仍在运行的测试套件，可以调用 `StopSuiteRun` API 操作。在您调用 `StopSuiteRun` API 操作后，此服务启动清理过程。当服务运行清理过程时，测试套件运行状态更新为 `Stopping`。清理过程可能需要几分钟时间。此过程完成后，测试套件运行状态更新为 `Stopped`。测试运行完全停止后，您可以启动另一个测试套件运行。您可以使用 `GetSuiteRun` API 操作定期检查套件运行状态，如上一节所示。
SDK 示例：
```
// Using the SDK, call the StopSuiteRun API.
response = iotDeviceAdvisorClient.StopSuiteRun(
StopSuiteRun.builder()
.suiteDefinitionId("your-suite-definition-id")
.suiteRunId("your-suite-run-id")
.build())
```
## 获取成功的资格测试套件运行的资格报告
如果您运行的资格测试套件成功完成，则可以使用 `GetSuiteRunReport` API 操作检索资格报告。您使用此资格报告来通过 AWS IoT Core 资格计划为您的设备获取资格。要确定测试套件是否为合资格测试套件，请检查 `intendedForQualification` 参数是否设置为 `true`。调用 `GetSuiteRunReport` API 操作后，您最多可以从返回的 URL 下载报告，持续时间最长 90 秒。如果从上次调用 `GetSuiteRunReport` API 操作之后超过 90 秒，请再次调用该 API 操作以检索新的有效 URL。
SDK 示例：
```
// Using the SDK, call the getSuiteRunReport API.
response = iotDeviceAdvisorClient.getSuiteRunReport(
GetSuiteRunReportRequest.builder()
.suiteDefinitionId("your-suite-definition-id")
.suiteRunId("your-suite-run-id")
.build()
)
```