Fluxo de trabalho do Device Advisor

Este tutorial explica como criar um conjunto de testes personalizado e executar testes no dispositivo que você deseja testar no console. Depois que os testes forem concluídos, você poderá visualizar os resultados do teste e os logs detalhados.

Pré-requisitos

Antes de iniciar este tutorial, conclua as etapas descritas em Configuração.

Criar uma definição de conjunto de teste

Primeiro, instale um AWS SDK.

Sintaxe de rootGroup

Um grupo raiz é uma string JSON que especifica quais casos de teste incluir no conjunto de testes. Ele também especifica todas as configurações necessárias para esses casos de teste. Use o grupo raiz para estruturar e ordenar o conjunto de testes com base em suas necessidades. A hierarquia de um conjunto de testes é:

test suite → test group(s) → test case(s)

Um conjunto de testes deve ter pelo menos um grupo de teste, e cada grupo de teste deve ter pelo menos um caso de teste. O Device Advisor executa testes na ordem em que você define os grupos de teste e os casos de teste.

Cada grupo raiz segue essa estrutura básica:

{
    "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": ""
            }
        }]
    }]
}

No grupo raiz, você define o conjunto de testes com um name, um configuration e os tests que o grupo contém. O grupo tests contém as definições de testes individuais. Você define cada teste com um name, um configuration e um bloco test que define os casos de teste desse teste. Finalmente, cada caso de teste é definido com um id e um version.

Para obter informações sobre como usar os campos "id" e "version" para cada caso de teste (bloco test), consulte Casos de teste do Device Advisor. Essa seção também contém informações sobre as configurações configuration disponíveis.

O bloco a seguir é um exemplo de configuração de grupo raiz. Essas configurações especificam os casos de teste MQTT Connect Happy Case e MQTT Connect Exponential Backoff Retries, junto com as descrições dos campos de configuração.

{
    "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
            }
        }]
    }]
}

Você deve fornecer a configuração do grupo raiz ao criar a definição de conjunto de testes. Salve o suiteDefinitionId que é retornado no objeto da resposta. Você pode usar esse ID para recuperar as informações de definição do conjunto de testes e executar o conjunto de testes.

Aqui está um exemplo do 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()
)

Obtenha uma definição de conjunto de teste

Depois de criar a definição de conjunto de testes, você recebe o suiteDefinitionId no objeto de resposta da operação da API CreateSuiteDefinition.

Quando a operação retorna o suiteDefinitionId, você pode ver novos campos id em cada grupo e a definição do caso de teste dentro do grupo raiz. Você pode usar esses IDs para executar um subconjunto da definição do conjunto de testes.

Exemplo de Java SDK:

response = iotDeviceAdvisorClient.GetSuiteDefinition(
    GetSuiteDefinitionRequest.builder()
        .suiteDefinitionId("your-suite-definition-id")
        .build()
)

Obtenha um endpoint de teste

Use a operação da API GetEndpoint para obter o endpoint de teste usado pelo dispositivo. Selecione o endpoint que melhor se adapta ao teste. Para executar vários conjuntos de testes simultaneamente, use o endpoint em nível de dispositivo fornecendo um thing ARN, um certificate ARN ou um device role ARN. Para executar uma única suíte de testes, não forneça argumentos à GetEndpoint operação para escolher o endpoint no nível da conta.

Exemplo do 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())

Inicie a execução de um conjunto de testes

Depois de criar uma definição de conjunto de testes e configurar o dispositivo de teste para se conectar ao endpoint de teste do Device Advisor, execute o conjunto de testes com a API StartSuiteRun.

Para clientes do MQTT, use um certificateArn ou um thingArn para executar o conjunto de testes. Se ambos estiverem configurados, o certificado será usado se pertencer ao objeto.

Para MQTT em vez WebSocket do cliente, use deviceRoleArn para executar a suíte de testes. Se o perfil especificado for diferente do perfil especificado na definição do conjunto de testes, o perfil especificado substituirá o perfil definido.

Para .parallelRun(), use true se você usar um endpoint em nível de dispositivo para executar vários conjuntos de testes em paralelo usando uma Conta da AWS.

Exemplo do 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())

Salve o suiteRunId da resposta. Você usará isso para recuperar os resultados da execução desse conjunto de testes.

Obtenha a execução de um conjunto de testes

Depois de iniciar a execução de um conjunto de testes, você pode verificar o progresso e os resultados com a API GetSuiteRun.

Exemplo do SDK:

// Using the SDK, call the GetSuiteRun API.

response = iotDeviceAdvisorClient.GetSuiteRun(
GetSuiteRunRequest.builder()
    .suiteDefinitionId("your-suite-definition-id")
    .suiteRunId("your-suite-run-id")
.build()) 

Interromper a execução de um conjunto de testes

Para interromper a execução de um conjunto de testes que ainda está em andamento, você pode chamar a operação da API StopSuiteRun. Depois de chamar a operação StopSuiteRun, o serviço inicia o processo de limpeza. Enquanto o serviço executa o processo de limpeza, o conjunto de testes executa atualizações de status para Stopping. O processo pode demorar vários minutos. Quando o processo estiver concluído, o conjunto de testes executará atualizações de status para Stopped. Depois que a execução de um teste for completamente interrompida, você poderá iniciar outra execução do conjunto de testes. Você pode verificar periodicamente o status de execução do conjunto usando a operação da API GetSuiteRun, conforme mostrado na seção anterior.

Exemplo do SDK:

// Using the SDK, call the StopSuiteRun API.

response = iotDeviceAdvisorClient.StopSuiteRun(
StopSuiteRun.builder()
    .suiteDefinitionId("your-suite-definition-id")
    .suiteRunId("your-suite-run-id")
.build())

Obtenha um relatório de qualificação para uma execução bem-sucedida do conjunto de testes de qualificação

Se você executar um conjunto de testes de qualificação concluído com êxito, poderá recuperar um relatório de qualificação com a operação da API GetSuiteRunReport. Você usa esse relatório de qualificação para qualificar o dispositivo com o programa de qualificação AWS IoT Core . Para determinar se o conjunto de testes é um conjunto de testes de qualificação, verifique se o parâmetro intendedForQualification está definido como true. Depois de chamar a operação da API GetSuiteRunReport, você pode baixar o relatório do URL retornado por até 90 segundos. Se passarem mais de 90 segundos desde a última vez em que você chamou a operação GetSuiteRunReport, chame a operação novamente para recuperar um novo URL válido.

Exemplo do SDK:

// Using the SDK, call the getSuiteRunReport API. 

response = iotDeviceAdvisorClient.getSuiteRunReport( 
    GetSuiteRunReportRequest.builder() 
        .suiteDefinitionId("your-suite-definition-id")
        .suiteRunId("your-suite-run-id")
        .build()
)