As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.
# Usar o IDT para desenvolver e executar os próprios pacotes de testes
A partir do IDT v4.0.1, o IDT for AWS IoT Greengrass V2 combina uma configuração padronizada e um formato de resultado com um ambiente de suíte de testes que permite desenvolver suítes de testes personalizadas para seus dispositivos e software de dispositivos. É possível adicionar testes personalizados para sua própria validação interna ou fornecê-los aos seus clientes para verificação de dispositivo.
Use o IDT para desenvolver e executar pacotes de testes personalizados da seguinte forma:
**Para desenvolver conjuntos de testes personalizados**
+ Crie conjuntos de testes com lógica de teste personalizada para o dispositivo Greengrass que você deseja testar.
+ Forneça ao IDT seus conjuntos de testes personalizados para os executores de testes. Inclua informações sobre configurações específicas para seus pacotes de teste.
**Para executar pacotes de testes personalizados**
+ Configure o dispositivo que deseja testar.
+ Implemente as configurações conforme exigido pelos pacotes de testes que deseja usar.
+ Use o IDT para executar seus pacotes de teste personalizados.
+ Veja os resultados do teste e os logs de execução dos testes executados pelo IDT.
## Baixe a versão mais recente do AWS IoT Device Tester for AWS IoT Greengrass
Baixe a [versão mais recente](idt-programmatic-download.md) do IDT e extraia o software em um local (**) em seu sistema de arquivos em que você tenha permissões de leitura/gravação.
**nota**
O IDT não oferece suporte a execução por vários usuários em um local compartilhado, como um diretório NFS ou uma pasta compartilhada de rede do Windows. Recomendamos extrair o pacote do IDT para uma unidade local e executar o binário do IDT na estação de trabalho local.
O Windows tem uma limitação de comprimento de caminho de 260 caracteres. Se você estiver usando o Windows, extraia o IDT para um diretório raiz como `C:\ ` ou `D:\` para manter os caminhos abaixo do limite de 260 caracteres.
## Fluxo de trabalho de criação de pacotes de teste
Os pacotes de teste são compostos por três tipos de arquivos:
+ Arquivos de configuração que fornecem ao IDT informações sobre como executar o conjunto de testes.
+ Os arquivos executáveis de teste que o IDT usa para executar casos de teste.
+ Arquivos adicionais necessários para executar testes.
Conclua as etapas básicas a seguir para criar testes de IDT personalizados:
1. [Crie arquivos de configuração](idt-json-config.md) para seu pacote de teste.
1. [Crie executáveis de casos de teste](create-test-executables.md) que contenham a lógica de teste para seu pacote de teste.
1. Verifique e documente as [informações de configuração necessárias para que os executores de teste](set-custom-idt-config.md) executem o pacote de teste.
1. Verifique se o IDT pode executar seu pacote de teste e produzir [resultados de teste](run-debug-custom-tests.md) conforme o esperado.
Para criar rapidamente uma amostra de pacote personalizado e executá-la, siga as instruções em [Tutorial: compile e execute o pacote de amostra de teste de IDT](build-sample-suite.md).
Para começar a criar um pacote de testes personalizado em Python, consulte [Tutorial: desenvolva um pacote de testes de IDT simples](create-custom-tests.md).
# Tutorial: compile e execute o pacote de amostra de teste de IDT
O AWS IoT Device Tester download inclui o código-fonte de uma amostra de suíte de testes. Você pode concluir este tutorial para criar e executar a suíte de testes de amostra para entender como você pode usar o IDT AWS IoT Greengrass para executar suítes de testes personalizadas.
Neste tutorial, você concluirá as seguintes etapas:
1. [Compile o pacote de teste de amostra](#build-sample)
1. [Usar o IDT para executar o pacote de teste de amostra](#run-sample)
## Pré-requisitos
Para concluir este tutorial, você precisará do seguinte:
+
**Requisitos do computador host**
+ Versão mais recente do AWS IoT Device Tester
+ [Python](https://www.python.org/downloads/) 3.7 ou posterior
Para verificar a versão do Python instalada em seu computador, execute o seguinte comando:
```
python3 --version
```
No Windows, se o uso deste comando retornar um erro, use `python --version`. Se o número da versão retornada for 3.7 ou superior, execute o seguinte comando em um terminal do Powershell para definir `python3` como um alias para seu comando `python`.
```
Set-Alias -Name "python3" -Value "python"
```
Se nenhuma informação sobre versão for retornada ou se o número da versão for menor do que 3.7, siga as instruções em [Fazer download do Python](https://wiki.python.org/moin/BeginnersGuide/Download) para instalar o Python 3.7\$1. Para obter mais informações, consulte a [Documentação do Python](https://docs.python.org).
+ [urllib3](https://urllib3.readthedocs.io/en/latest/)
Para verificar se `urllib3` está instalado corretamente, execute o seguinte comando:
```
python3 -c 'import urllib3'
```
Se o `urllib3` não estiver instalado, execute o comando a seguir para instalá-lo:
```
python3 -m pip install urllib3
```
+
**Requisitos do dispositivo**
+ Um dispositivo com sistema operacional Linux e uma conexão de rede com a mesma rede do seu computador host.
É recomendado o uso de um [Raspberry Pi](https://www.raspberrypi.org/) com o sistema operacional Raspberry Pi. Certifique-se de configurar o [SSH](https://www.raspberrypi.org/documentation/remote-access/ssh/) no seu Raspberry Pi para se conectar remotamente a ele.
## Configurar as informações do dispositivo para o IDT
Configure as informações do seu dispositivo para o IDT executar o teste. É preciso atualizar o modelo `device.json` localizado na pasta `/configs` com as informações a seguir.
```
[
{
"id": "pool",
"sku": "N/A",
"devices": [
{
"id": "",
"connectivity": {
"protocol": "ssh",
"ip": "",
"port": "",
"auth": {
"method": "pki | password",
"credentials": {
"user": "",
"privKeyPath": "/path/to/private/key",
"password": ""
}
}
}
}
]
}
]
```
No objeto `devices`, forneça as seguintes informações:
`id`
Um identificador exclusivo, definido pelo usuário, para o seu dispositivo.
`connectivity.ip`
O endereço IP do seu dispositivo.
`connectivity.port`
Opcional. O número da porta que deve ser usado nas conexões SSH ao seu dispositivo.
`connectivity.auth`
Informações de autenticação da conexão.
Essa propriedade será aplicada somente se `connectivity.protocol` estiver definido como `ssh`.
`connectivity.auth.method`
O método de autenticação usado para acessar um dispositivo pelo protocolo de conectividade indicado.
Os valores compatíveis são:
+ `pki`
+ `password`
`connectivity.auth.credentials`
As credenciais usadas para autenticação.
`connectivity.auth.credentials.user`
O nome de usuário usado para fazer login no seu dispositivo.
`connectivity.auth.credentials.privKeyPath`
O caminho completo para a chave privada usada para fazer login no dispositivo.
Esse valor se aplica somente se `connectivity.auth.method` estiver definido como `pki`.
`devices.connectivity.auth.credentials.password`
A senha usada para fazer login no dispositivo.
Esse valor se aplica somente se `connectivity.auth.method` estiver definido como `password`.
**nota**
Especifique `privKeyPath` somente se `method` estiver definido como `pki`.
Especifique `password` somente se `method` estiver definido como `password`.
## Compile o pacote de teste de amostra
A pasta `/samples/python` contém exemplos de arquivos de configuração, código-fonte e o SDK do cliente IDT que você pode combinar em um pacote de teste usando os scripts de compilação fornecidos. A seguinte árvore de diretórios mostra a localização desses arquivos de amostra:
```
├── ...
├── tests
├── samples
│ ├── ...
│ └── python
│ ├── configuration
│ ├── src
│ └── build-scripts
│ ├── build.sh
│ └── build.ps1
└── sdks
├── ...
└── python
└── idt_client
```
Para compilar o pacote de teste, execute os seguintes comandos em seu computador host:
------
#### [ Windows ]
```
cd /samples/python/build-scripts
./build.ps1
```
------
#### [ Linux, macOS, or UNIX ]
```
cd /samples/python/build-scripts
./build.sh
```
------
Isso compila o conjunto de testes de amostra na pasta `IDTSampleSuitePython_1.0.0` dentro da pasta `/tests`. Examine os arquivos na pasta `IDTSampleSuitePython_1.0.0` para entender como o pacote de testes de amostra está estruturado e confira vários exemplos de executáveis de casos de teste e arquivos JSON de configuração de teste.
**nota**
O pacote de teste de amostra inclui um código-fonte em Python. Não inclua informações confidenciais no código do seu pacote de teste.
Próxima etapa: use o IDT para [executar o pacote de teste de amostra](#run-sample) criada.
## Usar o IDT para executar o pacote de teste de amostra
Para executar o pacote de teste de amostra, execute os seguintes comandos em seu computador host:
```
cd /bin
./devicetester_[linux | mac | win_x86-64] run-suite --suite-id IDTSampleSuitePython
```
O IDT executa o pacote de teste de amostra e transmite os resultados para o console. Quando a execução do teste é concluída, são vistas as seguintes informações:
```
========== Test Summary ==========
Execution Time: 5s
Tests Completed: 4
Tests Passed: 4
Tests Failed: 0
Tests Skipped: 0
----------------------------------
Test Groups:
sample_group: PASSED
----------------------------------
Path to IoT Device Tester Report: /path/to/devicetester/results/87e673c6-1226-11eb-9269-8c8590419f30/awsiotdevicetester_report.xml
Path to Test Execution Logs: /path/to/devicetester/results/87e673c6-1226-11eb-9269-8c8590419f30/logs
Path to Aggregated JUnit Report: /path/to/devicetester/results/87e673c6-1226-11eb-9269-8c8590419f30/IDTSampleSuitePython_Report.xml
```
## Solução de problemas
Use as informações a seguir para ajudar a resolver os problemas ao concluir o tutorial.
**Caso de teste não é executado**
Se o teste não for executado, o IDT transmitirá os logs de erro para o console e isso pode ajudar a solucionar o problema de execução do teste. Verifique se todos os [pré-requisitos deste tutorial](#prereqs-tutorial-sample) são atendidos.
**Não é possível se conectar ao dispositivo em teste**
Verifique o seguinte:
+ Seu arquivo `device.json` contém o endereço IP, a porta e as informações de autenticação corretos.
+ Você pode se conectar ao seu dispositivo via SSH a partir do seu computador host.
# Tutorial: desenvolva um pacote de testes de IDT simples
Um conjunto de testes combina o seguinte:
+ Executáveis de teste que contêm a lógica de teste
+ Arquivos de configuração que descrevem o pacote de teste
Este tutorial mostra como usar o IDT AWS IoT Greengrass para desenvolver uma suíte de testes em Python que contém um único caso de teste. Neste tutorial, você concluirá as seguintes etapas:
1. [Crie um diretório de pacotes de teste](#test-suite-dir)
1. [Crie arquivos de configuração](#test-suite-json)
1. [Crie o executável do caso de teste](#test-suite-exe)
1. [Execute o pacote de teste](#run-test-suite)
## Pré-requisitos
Para concluir este tutorial, você precisará do seguinte:
+
**Requisitos do computador host**
+ Versão mais recente do AWS IoT Device Tester
+ [Python](https://www.python.org/downloads/) 3.7 ou posterior
Para verificar a versão do Python instalada em seu computador, execute o seguinte comando:
```
python3 --version
```
No Windows, se o uso deste comando retornar um erro, use `python --version`. Se o número da versão retornada for 3.7 ou superior, execute o seguinte comando em um terminal do Powershell para definir `python3` como um alias para seu comando `python`.
```
Set-Alias -Name "python3" -Value "python"
```
Se nenhuma informação sobre versão for retornada ou se o número da versão for menor do que 3.7, siga as instruções em [Fazer download do Python](https://wiki.python.org/moin/BeginnersGuide/Download) para instalar o Python 3.7\$1. Para obter mais informações, consulte a [Documentação do Python](https://docs.python.org).
+ [urllib3](https://urllib3.readthedocs.io/en/latest/)
Para verificar se `urllib3` está instalado corretamente, execute o seguinte comando:
```
python3 -c 'import urllib3'
```
Se o `urllib3` não estiver instalado, execute o comando a seguir para instalá-lo:
```
python3 -m pip install urllib3
```
+
**Requisitos do dispositivo**
+ Um dispositivo com sistema operacional Linux e uma conexão de rede com a mesma rede do seu computador host.
É recomendado o uso de um [Raspberry Pi](https://www.raspberrypi.org/) com o sistema operacional Raspberry Pi. Certifique-se de configurar o [SSH](https://www.raspberrypi.org/documentation/remote-access/ssh/) no seu Raspberry Pi para se conectar remotamente a ele.
## Crie um diretório de pacotes de teste
O IDT separa logicamente os casos de teste em grupos de teste dentro de cada pacote de teste. Cada caso de teste deve estar dentro de um grupo de teste. Para este tutorial, crie uma pasta chamada `MyTestSuite_1.0.0` e crie a seguinte árvore de diretórios nesta pasta:
```
MyTestSuite_1.0.0
└── suite
└── myTestGroup
└── myTestCase
```
## Crie arquivos de configuração
Seu pacote de teste deve conter os seguintes [arquivos de configuração](idt-json-config.md) necessários:Arquivos de configuração necessária
`suite.json`
Contém informações sobre o pacote de teste. Consulte [Configurar suite.json](idt-json-config.md#suite-json).
`group.json`
Contém informações sobre um grupo de teste. É preciso criar um arquivo `group.json` para cada grupo de teste em seu pacote de teste. Consulte [Configurar group.json](idt-json-config.md#group-json).
`test.json`
Contém informações sobre um caso de teste. É preciso criar um arquivo `test.json` para cada caso de teste em seu pacote de teste. Consulte [Configurar test.json](idt-json-config.md#test-json).
1. Na pasta `MyTestSuite_1.0.0/suite`, crie um arquivo `suite.json` com a seguinte estrutura:
```
{
"id": "MyTestSuite_1.0.0",
"title": "My Test Suite",
"details": "This is my test suite.",
"userDataRequired": false
}
```
1. Na pasta `MyTestSuite_1.0.0/myTestGroup`, crie um arquivo `group.json` com a seguinte estrutura:
```
{
"id": "MyTestGroup",
"title": "My Test Group",
"details": "This is my test group.",
"optional": false
}
```
1. Na pasta `MyTestSuite_1.0.0/myTestGroup/myTestCase`, crie um arquivo `test.json` com a seguinte estrutura:
```
{
"id": "MyTestCase",
"title": "My Test Case",
"details": "This is my test case.",
"execution": {
"timeout": 300000,
"linux": {
"cmd": "python3",
"args": [
"myTestCase.py"
]
},
"mac": {
"cmd": "python3",
"args": [
"myTestCase.py"
]
},
"win": {
"cmd": "python3",
"args": [
"myTestCase.py"
]
}
}
}
```
Agora, a árvore de diretórios da pasta `MyTestSuite_1.0.0` deve ser semelhante à seguinte:
```
MyTestSuite_1.0.0
└── suite
├── suite.json
└── myTestGroup
├── group.json
└── myTestCase
└── test.json
```
## Obtenha o SDK do cliente do IDT
Use o [SDK de cliente do IDT](create-test-executables.md#idt-client-sdk) para permitir que o IDT interaja com o dispositivo testado e relate os resultados do teste. Neste tutorial, use a versão em Python do SDK.
Na pasta `/sdks/python/`, copie a pasta `idt_client` para sua pasta `MyTestSuite_1.0.0/suite/myTestGroup/myTestCase`.
Para verificar se o SDK foi copiado com êxito, execute o comando a seguir.
```
cd MyTestSuite_1.0.0/suite/myTestGroup/myTestCase
python3 -c 'import idt_client'
```
## Crie o executável do caso de teste
Os executáveis do caso de teste contêm a lógica de teste que você deseja executar. Um pacote de teste pode conter vários executáveis de casos de teste. Para este tutorial, crie somente um executável de caso de teste.
1. Crie o arquivo do pacote de teste.
Na pasta `MyTestSuite_1.0.0/suite/myTestGroup/myTestCase`, crie um arquivo `myTestCase.py` com o seguinte conteúdo:
```
from idt_client import *
def main():
# Use the client SDK to communicate with IDT
client = Client()
if __name__ == "__main__":
main()
```
1. Use as funções do SDK de cliente para adicionar a seguinte lógica de teste ao seu arquivo `myTestCase.py`:
1. Execute um comando SSH no dispositivo em teste.
```
from idt_client import *
def main():
# Use the client SDK to communicate with IDT
client = Client()
# Create an execute on device request
exec_req = ExecuteOnDeviceRequest(ExecuteOnDeviceCommand("echo 'hello world'"))
# Run the command
exec_resp = client.execute_on_device(exec_req)
# Print the standard output
print(exec_resp.stdout)
if __name__ == "__main__":
main()
```
1. Envie o resultado do teste para o IDT.
```
from idt_client import *
def main():
# Use the client SDK to communicate with IDT
client = Client()
# Create an execute on device request
exec_req = ExecuteOnDeviceRequest(ExecuteOnDeviceCommand("echo 'hello world'"))
# Run the command
exec_resp = client.execute_on_device(exec_req)
# Print the standard output
print(exec_resp.stdout)
# Create a send result request
sr_req = SendResultRequest(TestResult(passed=True))
# Send the result
client.send_result(sr_req)
if __name__ == "__main__":
main()
```
## Configurar as informações do dispositivo para o IDT
Configure as informações do seu dispositivo para o IDT executar o teste. É preciso atualizar o modelo `device.json` localizado na pasta `/configs` com as informações a seguir.
```
[
{
"id": "pool",
"sku": "N/A",
"devices": [
{
"id": "",
"connectivity": {
"protocol": "ssh",
"ip": "",
"port": "",
"auth": {
"method": "pki | password",
"credentials": {
"user": "",
"privKeyPath": "/path/to/private/key",
"password": ""
}
}
}
}
]
}
]
```
No objeto `devices`, forneça as seguintes informações:
`id`
Um identificador exclusivo, definido pelo usuário, para o seu dispositivo.
`connectivity.ip`
O endereço IP do seu dispositivo.
`connectivity.port`
Opcional. O número da porta que deve ser usado nas conexões SSH ao seu dispositivo.
`connectivity.auth`
Informações de autenticação da conexão.
Essa propriedade será aplicada somente se `connectivity.protocol` estiver definido como `ssh`.
`connectivity.auth.method`
O método de autenticação usado para acessar um dispositivo pelo protocolo de conectividade indicado.
Os valores compatíveis são:
+ `pki`
+ `password`
`connectivity.auth.credentials`
As credenciais usadas para autenticação.
`connectivity.auth.credentials.user`
O nome de usuário usado para fazer login no seu dispositivo.
`connectivity.auth.credentials.privKeyPath`
O caminho completo para a chave privada usada para fazer login no dispositivo.
Esse valor se aplica somente se `connectivity.auth.method` estiver definido como `pki`.
`devices.connectivity.auth.credentials.password`
A senha usada para fazer login no dispositivo.
Esse valor se aplica somente se `connectivity.auth.method` estiver definido como `password`.
**nota**
Especifique `privKeyPath` somente se `method` estiver definido como `pki`.
Especifique `password` somente se `method` estiver definido como `password`.
## Execute o pacote de teste
Depois de criar o pacote de teste, verifique se ele funciona conforme o esperado. Conclua as etapas a seguir para executar o pacote de teste em seu grupo de dispositivos existente.
1. Copie sua pasta `MyTestSuite_1.0.0` em `/tests`.
1. Execute os seguintes comandos :
```
cd /bin
./devicetester_[linux | mac | win_x86-64] run-suite --suite-id MyTestSuite
```
O IDT executa seu pacote de teste e transmite os resultados para o console. Quando a execução do teste é concluída, são vistas as seguintes informações:
```
time="2020-10-19T09:24:47-07:00" level=info msg=Using pool: pool
time="2020-10-19T09:24:47-07:00" level=info msg=Using test suite "MyTestSuite_1.0.0" for execution
time="2020-10-19T09:24:47-07:00" level=info msg=b'hello world\n' suiteId=MyTestSuite groupId=myTestGroup testCaseId=myTestCase deviceId=my-device executionId=9a52f362-1227-11eb-86c9-8c8590419f30
time="2020-10-19T09:24:47-07:00" level=info msg=All tests finished. executionId=9a52f362-1227-11eb-86c9-8c8590419f30
time="2020-10-19T09:24:48-07:00" level=info msg=
========== Test Summary ==========
Execution Time: 1s
Tests Completed: 1
Tests Passed: 1
Tests Failed: 0
Tests Skipped: 0
----------------------------------
Test Groups:
myTestGroup: PASSED
----------------------------------
Path to IoT Device Tester Report: /path/to/devicetester/results/9a52f362-1227-11eb-86c9-8c8590419f30/awsiotdevicetester_report.xml
Path to Test Execution Logs: /path/to/devicetester/results/9a52f362-1227-11eb-86c9-8c8590419f30/logs
Path to Aggregated JUnit Report: /path/to/devicetester/results/9a52f362-1227-11eb-86c9-8c8590419f30/MyTestSuite_Report.xml
```
## Solução de problemas
Use as informações a seguir para ajudar a resolver os problemas ao concluir o tutorial.
**Caso de teste não é executado**
Se o teste não for executado, o IDT transmitirá os logs de erro para o console e isso pode ajudar a solucionar o problema de execução do teste. Antes de verificar os logs de erro, verifique o seguinte:
+ O SDK de cliente do IDT está na pasta correta, conforme descrito [nesta etapa](#add-idt-sdk).
+ Você atende a todos os [pré-requisitos](#prereqs-tutorial-custom) deste tutorial.
**Não é possível se conectar ao dispositivo em teste**
Verifique o seguinte:
+ Seu arquivo `device.json` contém o endereço IP, a porta e as informações de autenticação corretos.
+ Você pode se conectar ao seu dispositivo via SSH a partir do seu computador host.
# Crie arquivos de configuração do pacote de testes do IDT
Esta seção descreve os formatos nos quais você cria arquivos de configuração incluídos ao escrever um pacote de teste personalizado.Arquivos de configuração necessária
`suite.json`
Contém informações sobre o pacote de teste. Consulte [Configurar suite.json](#suite-json).
`group.json`
Contém informações sobre um grupo de teste. É preciso criar um arquivo `group.json` para cada grupo de teste em seu pacote de teste. Consulte [Configurar group.json](#group-json).
`test.json`
Contém informações sobre um caso de teste. É preciso criar um arquivo `test.json` para cada caso de teste em seu pacote de teste. Consulte [Configurar test.json](#test-json).Arquivos de configuração opcional
`test_orchestrator.yaml` ou `state_machine.json`
Define como os testes são executados quando o IDT executa o pacote de teste. Consulte [Configurar test\$1orchestrator.yaml](#test-orchestrator-config).
Desde o IDT v4.5.1, você usa o arquivo `test_orchestrator.yaml` para definir o fluxo de trabalho de testes. Nas versões anteriores do IDT, você usa o arquivo `state_machine.json`. Para obter informações sobre a máquina de estado, consulte [Configure a máquina de estados do IDT](idt-state-machine.md).
`userdata_schema.json`
Define o esquema do [arquivo `userdata.json`](set-custom-idt-config.md#userdata-config-custom) que os executores de teste podem incluir na definição de configuração. O arquivo `userdata.json` é usado em qualquer informação de configuração adicional necessária para executar o teste, mas que não esteja presente no arquivo `device.json`. Consulte [Configurar userdata\$1schema.json](#userdata-schema-json).
Os arquivos de configuração JSON são colocados no seu ``, conforme mostrado aqui.
```
└── suite
├── suite.json
├── test_orchestrator.yaml
├── userdata_schema.json
├──
├── group.json
├──
└── test.json
```
## Configurar suite.json
O arquivo `suite.json` define as variáveis de ambiente e determina se os dados do usuário são necessários para executar o pacote de teste. Use o modelo a seguir para configurar seu arquivo `/suite/suite.json`:
```
{
"id": "_",
"title": "",
"details": "",
"userDataRequired": true | false,
"environmentVariables": [
{
"key": "",
"value": "",
},
...
{
"key": "",
"value": "",
}
]
}
```
Todos os campos que contêm valores são necessários, conforme descrito aqui:
`id`
Um ID exclusivo, definido pelo usuário, para o pacote de teste. O valor de `id` deve corresponder ao nome da pasta do pacote de teste na qual o arquivo `suite.json` está localizado. O nome e a versão do pacote devem atender aos seguintes requisitos:
+ `` não pode conter sublinhados.
+ `` é indicado como `x.x.x`, em que `x` é um número.
O ID é mostrado nos relatórios de teste gerados pelo IDT.
`title`
Um nome definido pelo usuário para o produto ou recurso que está sendo testado por esse pacote de teste. O nome é exibido na CLI do IDT para os executores de teste.
`details`
Uma descrição breve da finalidade do pacote de teste.
`userDataRequired`
Define se os executores de teste precisam incluir informações personalizadas em um arquivo `userdata.json`. Se definir esse valor como `true`, também deverá incluir o [arquivo `userdata_schema.json`](#userdata-schema-json) na pasta do pacote de teste.
`environmentVariables`
Opcional. Uma matriz de variáveis de ambiente para configurar para esse pacote de teste.
`environmentVariables.key`
O nome da variável de ambiente.
`environmentVariables.value`
O valor da variável de ambiente.
## Configurar group.json
O arquivo `group.json` define se o grupo de teste é necessário ou opcional. Use o modelo a seguir para configurar seu arquivo `/suite//group.json`:
```
{
"id": "",
"title": "",
"details": "",
"optional": true | false,
}
```
Todos os campos que contêm valores são necessários, conforme descrito aqui:
`id`
Um ID exclusivo, definido pelo usuário, para o grupo de teste. O valor de `id` deve corresponder ao nome da pasta do grupo de testes, na qual o arquivo `group.json` está localizado, e não pode conter sublinhados (`_`). O ID é usado nos relatórios de teste gerados pelo IDT.
`title`
Um nome descritivo para o grupo de teste. O nome é exibido na CLI do IDT para os executores de teste.
`details`
Uma descrição breve da finalidade do grupo de teste.
`optional`
Opcional. Defina como `true` para exibir este grupo de teste como um grupo opcional depois que o IDT terminar de executar os testes necessários. O valor padrão é . `false`.
## Configurar test.json
O arquivo `test.json` determina os executáveis do caso de teste e as variáveis de ambiente que são usadas por um caso de teste. Para obter mais informações sobre como criar executáveis de casos de teste, consulte [Criar executáveis de casos de teste do IDT](create-test-executables.md).
Use o modelo a seguir para configurar seu arquivo `/suite///test.json`:
```
{
"id": "",
"title": "",
"details": "",
"requireDUT": true | false,
"requiredResources": [
{
"name": "",
"features": [
{
"name": "",
"version": "",
"jobSlots":
}
]
}
],
"execution": {
"timeout": ,
"mac": {
"cmd": "/path/to/executable",
"args": [
""
],
},
"linux": {
"cmd": "/path/to/executable",
"args": [
""
],
},
"win": {
"cmd": "/path/to/executable",
"args": [
""
]
}
},
"environmentVariables": [
{
"key": "",
"value": "",
}
]
}
```
Todos os campos que contêm valores são necessários, conforme descrito aqui:
`id`
Um ID exclusivo, definido pelo usuário, para o caso de teste. O valor de `id` deve corresponder ao nome da pasta do caso de teste na qual o arquivo `test.json` está localizado e não pode conter sublinhados (`_`). O ID é usado nos relatórios de teste gerados pelo IDT.
`title`
Um nome descritivo para o caso de teste. O nome é exibido na CLI do IDT para os executores de teste.
`details`
Uma descrição breve da finalidade do caso de teste.
`requireDUT`
Opcional. Defina como `true` se um dispositivo for necessário para executar este teste. Caso contrário, defina como `false`. O valor padrão é . `true`. Os executores de teste configurarão os dispositivos que usarão para executar o teste nos arquivos `device.json`.
`requiredResources`
Opcional. Uma matriz que fornece informações sobre os dispositivos de recursos necessários para executar esse teste.
`requiredResources.name`
O nome exclusivo a ser dado ao dispositivo de recurso quando este teste está sendo executado.
`requiredResources.features`
Uma matriz de recursos de dispositivos de recursos definidos pelo usuário.
`requiredResources.features.name`
O nome do recurso. O recurso do dispositivo para o qual você deseja usar este dispositivo. Este nome é comparado ao nome do recurso fornecido pelo executor de teste no arquivo `resource.json`.
`requiredResources.features.version`
Opcional. A versão do recurso. Este valor é comparado à versão do recurso fornecida pelo executor de teste no arquivo `resource.json`. Se uma versão não for fornecida, o recurso não será verificado. Se um número de versão não for obrigatório para o recurso, deixe este campo em branco.
`requiredResources.features.jobSlots`
Opcional. O número de testes simultâneos que podem ser compatíveis com este recurso. O valor padrão é `1`. Se você quiser que o IDT use dispositivos distintos para recursos individuais, recomendamos que você defina esse valor como `1`.
`execution.timeout`
A quantidade de tempo (em milissegundos) que o IDT aguardará a conclusão da execução do teste. Para obter mais informações sobre este valor, consulte [Criar executáveis de casos de teste do IDT](create-test-executables.md).
`execution.os`
Os executáveis do caso de teste a serem executados com base no sistema operacional do computador host que executa o IDT. Os valores compatíveis são `linux`, `mac` e `win`.
`execution.os.cmd`
O caminho para o executável do caso de teste que deseja executar para o sistema operacional especificado. Este local deve estar no caminho do sistema.
`execution.os.args`
Opcional. Os argumentos a serem fornecidos para executar o executável do caso de teste.
`environmentVariables`
Opcional. Uma matriz de variáveis de ambiente definidas para este caso de teste.
`environmentVariables.key`
O nome da variável de ambiente.
`environmentVariables.value`
O valor da variável de ambiente.
Se especificar a mesma variável de ambiente no arquivo `test.json` e no arquivo `suite.json`, o valor no arquivo `test.json` terá precedência.
## Configurar test\$1orchestrator.yaml
Um orquestrador de teste é uma estrutura que controla o fluxo de execução do pacote de teste. Ele determina o estado inicial de um pacote de teste, gerencia as transições de estado com base nas regras definidas pelo usuário e continua a transição por esses estados até atingir o estado final.
Se seu pacote de teste não incluir um orquestrador de testes definido pelo usuário, o IDT gerará um orquestrador de testes para você.
O orquestrador de teste padrão executa as seguintes funções:
+ Fornece aos executores de teste a capacidade de selecionar e executar grupos de testes específicos, em vez de todo o pacote de teste.
+ Se grupos de teste específicos não forem selecionados, executará cada grupo de teste no pacote de teste em uma ordem aleatória.
+ Gera relatórios e imprime um resumo do console que mostra os resultados do teste para cada grupo de teste e caso de teste.
Para obter mais informações sobre como o orquestrador de testes do IDT funciona, consulte [Configure o orquestrador de testes do IDT](idt-test-orchestrator.md).
## Configurar userdata\$1schema.json
O arquivo `userdata_schema.json` determina o esquema no qual os executores de teste fornecem dados do usuário. Os dados do usuário são necessários se seu pacote de teste exigir informações que não estejam presentes no arquivo `device.json`. Por exemplo, seus testes podem precisar de credenciais de rede Wi-Fi, portas abertas específicas ou certificados que um usuário deve fornecer. Estas informações podem ser fornecidas ao IDT como um parâmetro de entrada chamado `userdata`, cujo valor é um arquivo `userdata.json`, que os usuários criam em suas pastas `/config`. O formato do arquivo `userdata.json` é baseado no arquivo `userdata_schema.json` incluído no pacote de teste.
Para indicar que os executores de teste devem fornecer um arquivo `userdata.json`:
1. No arquivo `suite.json`, defina `userDataRequired` como `true`.
1. No seu ``, crie um arquivo `userdata_schema.json`.
1. Edite o arquivo `userdata_schema.json` para criar um [esquema JSON válido do IETF Draft v4](https://json-schema.org/specification-links.html#draft-4).
Quando o IDT executa seu pacote de teste, ele lê automaticamente o esquema e o usa para validar o arquivo `userdata.json` fornecido pelo executor do teste. Se válido, o conteúdo do arquivo `userdata.json` estará disponível no [contexto do IDT](idt-context.md) e no [contexto do orquestrador de testes](idt-state-machine.md#state-machine-context).
# Configure o orquestrador de testes do IDT
Desde o IDT v4.5.1, o IDT inclui um novo componente *orquestrador de testes*. O orquestrador de testes é um componente do IDT que controla o fluxo de execução do pacote de teste e gera o relatório de teste depois que o IDT termina de executar todos os testes. O orquestrador de testes determina a seleção do teste e a ordem na qual os testes são executados com base nas regras definidas pelo usuário.
Se seu pacote de teste não incluir um orquestrador de testes definido pelo usuário, o IDT gerará um orquestrador de testes para você.
O orquestrador de teste padrão executa as seguintes funções:
+ Fornece aos executores de teste a capacidade de selecionar e executar grupos de testes específicos, em vez de todo o pacote de teste.
+ Se grupos de teste específicos não forem selecionados, executará cada grupo de teste no pacote de teste em uma ordem aleatória.
+ Gera relatórios e imprime um resumo do console que mostra os resultados do teste para cada grupo de teste e caso de teste.
O orquestrador de testes substitui o orquestrador de testes do IDT. É recomendado utilizar a versão mais recente do orquestrador de testes para desenvolver seus pacotes de teste em vez do orquestrador de testes do IDT. O orquestrador de testes fornece os seguintes recursos aprimorados:
+ Usa um formato declarativo em comparação com o formato imperativo que a máquina de estado do IDT usa. Isto permite que especificar quais testes deseja executar e quando deseja executá-los.
+ Gerencia o tratamento de grupos específicos, a geração de relatórios, o tratamento de erros e o rastreamento de resultados para que você não precise gerenciar manualmente essas ações.
+ Usa o formato YAML, que é compatível com comentários por padrão.
+ Requer 80% menos espaço em disco do que o orquestrador de teste para definir o mesmo fluxo de trabalho.
+ Adiciona validação de pré-teste para verificar se a definição do fluxo de trabalho não contém IDs de teste incorretos ou dependências circulares.
## Formato do orquestrador de testes
É possível usar o modelo a seguir para configurar seu próprio arquivo `/suite/test_orchestrator.yaml`:
```
Aliases:
string: context-expression
ConditionalTests:
- Condition: context-expression
Tests:
- test-descriptor
Order:
- - group-descriptor
- group-descriptor
Features:
- Name: feature-name
Value: support-description
Condition: context-expression
Tests:
- test-descriptor
OneOfTests:
- test-descriptor
IsRequired: boolean
```
Todos os campos que contêm valores são necessários, conforme descrito aqui:
`Aliases`
Opcional. Strings definidas pelo usuário que são mapeadas para expressões de contexto. Os aliases permitem que você gere nomes amigáveis para identificar expressões de contexto na configuração do orquestrador de teste. Isto é muito útil se estiver criando expressões de contexto complexas ou expressões usadas em vários lugares.
É possível usar expressões de contexto para armazenar consultas de contexto que permitem acessar dados de outras configurações do IDT. Para obter mais informações, consulte [Acessar dados no contexto](idt-context.md#accessing-context-data).
**Example Exemplo**
```
Aliases:
FizzChosen: "'{{$pool.features[?(@.name == 'Fizz')].value[0]}}' == 'yes'"
BuzzChosen: "'{{$pool.features[?(@.name == 'Buzz')].value[0]}}' == 'yes'"
FizzBuzzChosen: "'{{$aliases.FizzChosen}}' && '{{$aliases.BuzzChosen}}'"
```
`ConditionalTests`
Opcional. Uma lista de condições e os casos de teste correspondentes que são executados quando cada condição é atendida. Cada condição pode ter vários casos de teste. No entanto, só é possível atribuir um determinado caso de teste a uma condição.
Por padrão, o IDT executa qualquer caso de teste que não esteja atribuído a uma condição nessa lista. Se não especificar essa seção, o IDT executará todos os grupos de teste no pacote de teste.
Cada item da lista `ConditionalTests` inclui os seguintes parâmetros:
`Condition`
Uma expressão de contexto que deve ser avaliada para um valor booleano. Se o valor avaliado for verdadeiro, o IDT executará os casos de teste especificados no parâmetro `Tests`.
`Tests`
A lista dos descritores de teste.
Cada descritor de testes usa o ID do grupo de teste e um ou mais IDs do caso de teste para identificar os testes individuais a serem executados a partir de um grupo de teste específico. O descritor de teste usa o seguinte formato:
```
GroupId: group-id
CaseIds: [test-id, test-id] # optional
```
**Example Exemplo**
O exemplo a seguir usa expressões de contexto genéricas que podem ser definidas como `Aliases`.
```
ConditionalTests:
- Condition: "{{$aliases.Condition1}}"
Tests:
- GroupId: A
- GroupId: B
- Condition: "{{$aliases.Condition2}}"
Tests:
- GroupId: D
- Condition: "{{$aliases.Condition1}} || {{$aliases.Condition2}}"
Tests:
- GroupId: C
```
Com base nas condições definidas, o IDT seleciona os grupos de teste da seguinte forma:
+ Se `Condition1` for verdade, o IDT executa os testes nos grupos de teste A, B e C.
+ Se `Condition2` for verdade, o IDT executa os testes nos grupos de teste C e D.
`Order`
Opcional. A ordem em que os testes serão executados. Especifique a ordem do teste no nível do grupo de teste. Se não especificar essa seção, o IDT executará todos os grupos de teste aplicáveis em uma ordem aleatória. O valor de `Order` é uma lista de listas de descritores de grupos. Qualquer grupo de teste que não esteja listado em `Order` pode ser executado em paralelo com qualquer outro grupo de teste listado.
Cada lista de descritores de grupo contém um ou mais descritores de grupo e identifica a ordem na qual executar os grupos especificados em cada descritor. É possível usar os seguintes formatos para definir descritores de grupo individuais:
+ `group-id`: o ID do grupo de um grupo de teste existente.
+ `[group-id, group-id]`: lista de grupos de teste que podem ser executados em qualquer ordem em relação um ao outro.
+ `"*"`: curinga. Isto é equivalente à lista de todos os grupos de teste que ainda não estão especificados na lista atual de descritores de grupo.
O valor de `Order` também devem atender aos seguintes requisitos:
+ Os IDs de grupo de teste que você especifica em um descritor de grupo devem existir em seu pacote de teste.
+ Cada lista de descritores de grupo deve incluir pelo menos um grupo de teste.
+ Cada lista de descritores de grupo deve conter IDs de grupo exclusivos. Não é possível repetir um ID de grupo de teste em descritores de grupos individuais.
+ Uma lista de descritores de grupo pode ter no máximo um descritor de grupo curinga. O descritor do grupo curinga deve ser o primeiro ou o último item na lista.
**Example Exemplos**
Para um pacote de teste que contém os grupos de teste A, B, C, D e E, a lista de exemplos a seguir mostra maneiras diferentes de especificar que o IDT deve primeiro executar o grupo de teste A, depois executar o grupo de teste B e, em seguida, executar os grupos de teste C, D e E em qualquer ordem.
+
```
Order:
- - A
- B
- [C, D, E]
```
+
```
Order:
- - A
- B
- "*"
```
+
```
Order:
- - A
- B
- - B
- C
- - B
- D
- - B
- E
```
`Features`
Opcional. A lista de recursos do produto que você deseja que o IDT adicione ao arquivo `awsiotdevicetester_report.xml`. Se você não especificar essa seção, o IDT não adicionará nenhum recurso do produto ao relatório.
Um recurso do produto é uma informação definida pelo usuário sobre critérios específicos que um dispositivo pode atender. Por exemplo, o recurso do produto MQTT pode indicar que o dispositivo publica mensagens MQTT corretamente. Em `awsiotdevicetester_report.xml`, os recursos do produto são definidos como `supported`, `not-supported` ou um valor personalizado e definido pelo usuário, com base na aprovação dos testes especificados.
Cada item da lista `Features` consiste dos seguintes parâmetros:
`Name`
O nome do recurso.
`Value`
Opcional. O valor personalizado que deseja usar no relatório em vez de `supported`. Se esse valor não for especificado, com base nos conjuntos do IDT, o valor do recurso será definido como `supported` ou `not-supported`. Se você testar o mesmo recurso com condições diferentes, poderá usar um valor personalizado para cada instância desse recurso na lista `Features`, e o IDT concatena os valores do recurso para as condições compatíveis. Para obter mais informações, consulte
`Condition`
Uma expressão de contexto que deve ser avaliada para um valor booleano. Se o valor avaliado for verdadeiro, o IDT adiciona o recurso ao relatório de teste após concluir a execução do pacote de teste. Se o valor avaliado for falso, o teste não será incluído no relatório.
`Tests`
Opcional. A lista dos descritores de teste. Todos os testes que são especificados nesta lista devem ser aprovados para que o recurso seja compatível.
Cada descritor de testes nesta lista usa o ID do grupo de teste e um ou mais IDs do caso de teste para identificar os testes individuais a serem executados em um grupo de teste específico. O descritor de teste usa o seguinte formato:
```
GroupId: group-id
CaseIds: [test-id, test-id] # optional
```
Você deve especificar um `Tests` ou `OneOfTests` para cada recurso na lista `Features`.
`OneOfTests`
Opcional. A lista dos descritores de teste. Pelo menos um dos testes especificados nesta lista deve ser aprovado para que o recurso seja compatível.
Cada descritor de testes nesta lista usa o ID do grupo de teste e um ou mais IDs do caso de teste para identificar os testes individuais a serem executados em um grupo de teste específico. O descritor de teste usa o seguinte formato:
```
GroupId: group-id
CaseIds: [test-id, test-id] # optional
```
Você deve especificar um `Tests` ou `OneOfTests` para cada recurso na lista `Features`.
`IsRequired`
O valor booleano que define se o recurso é exigido no relatório de teste. O valor padrão é `false`.
**Example**
## Contexto do orquestrador de teste
O contexto do orquestrador de estado é um documento JSON somente para leitura que contém dados que estão disponíveis para o orquestrador de estado durante a execução. O contexto do orquestrador de estado é acessível somente do orquestrador de estado e contém informações que determinam o fluxo de teste. Por exemplo, você pode usar as informações configuradas pelos executores de teste no arquivo `userdata.json` para determinar se é necessário executar um teste específico.
O contexto do orquestrador de teste usa o seguinte formato:
```
{
"pool": {
},
"userData": {
},
"config": {
}
}
```
`pool`
Informações sobre o grupo de dispositivos selecionado para a execução do teste. Para um grupo de dispositivos selecionado, essas informações são recuperadas do elemento correspondente da matriz do grupo de dispositivos de nível superior definido no arquivo `device.json`.
`userData`
As informações no arquivo `userdata.json`.
`config`
As informações no arquivo `config.json`.
É possível consultar o contexto usando a notação JSONPath. A sintaxe para consultas JSONPath nas definições de estado é `{{query}}`. Ao acessar dados do contexto do orquestrador de testes, verifique que cada valor seja avaliado como uma string, um número ou um booleano.
Para obter mais informações sobre o uso da notação JSONPath para acessar dados do contexto, consulte [Use o contexto do IDT](idt-context.md).
# Configure a máquina de estados do IDT
**Importante**
Desde o IDT v4.5.1, esta máquina de estado está obsoleta. É muito recomendado o uso do novo orquestrador de testes. Para obter mais informações, consulte [Configure o orquestrador de testes do IDT](idt-test-orchestrator.md).
Uma máquina de estado é uma estrutura que controla o fluxo de execução do pacote de teste. Ele determina o estado inicial de um pacote de teste, gerencia as transições de estado com base nas regras definidas pelo usuário e continua a transição por esses estados até atingir o estado final.
Se seu pacote de teste não incluir uma máquina de estado definida pelo usuário, o IDT gerará uma máquina de estado para você. A máquina de estado padrão executa as seguintes funções:
+ Fornece aos executores de teste a capacidade de selecionar e executar grupos de testes específicos, em vez de todo o pacote de teste.
+ Se grupos de teste específicos não forem selecionados, executará cada grupo de teste no pacote de teste em uma ordem aleatória.
+ Gera relatórios e imprime um resumo do console que mostra os resultados do teste para cada grupo de teste e caso de teste.
A máquina de estado de um pacote de teste da IDT deve atender aos seguintes critérios:
+ Cada estado corresponde a uma ação a ser executada pelo IDT, como executar um grupo de teste ou produzir um arquivo de relatório.
+ A transição para um estado executa a ação associada ao estado.
+ Cada estado define a regra de transição para o próximo estado.
+ O estado final deve ser `Succeed` ou `Fail`.
## Formato da máquina de estado
É possível usar o modelo a seguir para configurar seu próprio arquivo `/suite/state_machine.json`:
```
{
"Comment": "",
"StartAt": "",
"States": {
"": {
"Type": "",
// Additional state configuration
}
// Required states
"Succeed": {
"Type": "Succeed"
},
"Fail": {
"Type": "Fail"
}
}
}
```
Todos os campos que contêm valores são necessários, conforme descrito aqui:
`Comment`
Uma descrição da máquina de estado.
`StartAt`
O nome do estado em que o IDT começa a executar o pacote de teste. O valor de `StartAt` deve ser definido como um dos estados listados no objeto `States`.
`States`
Um objeto que mapeia nomes de estados definidos pelo usuário para estados IDT válidos. Cada estado. *state-name*objeto contém a definição de um estado válido mapeado para o. *state-name*
O objeto `States` deve incluir os estados `Succeed` e `Fail`. Para obter informações sobre estados válidos, consulte [Estados válidos e definições de estado](#valid-states).
## Estados válidos e definições de estado
Esta seção descreve as definições de estado de todos os estados válidos que podem ser usados na máquina de estados IDT. Alguns dos estados a seguir são compatíveis com configurações no nível do caso de teste. No entanto, é recomendado configurar as regras de transição de estado no nível do grupo de teste em vez do nível do caso de teste, a menos que seja absolutamente necessário.
**Topics**
+ [RunTask](#state-runtask)
+ [Escolha](#state-choice)
+ [Paralelo](#state-parallel)
+ [AddProductFeatures](#state-addproductfeatures)
+ [Relatório](#state-report)
+ [LogMessage](#state-logmessage)
+ [SelectGroup](#state-selectgroup)
+ [Falha](#state-fail)
+ [Êxito](#state-succeed)
### RunTask
O estado `RunTask` executa casos de teste de um grupo de teste definido no pacote de teste.
```
{
"Type": "RunTask",
"Next": "",
"TestGroup": "",
"TestCases": [
""
],
"ResultVar": ""
}
```
Todos os campos que contêm valores são necessários, conforme descrito aqui:
`Next`
O nome do estado para o qual fazer a transição após a execução das ações no estado atual.
`TestGroup`
Opcional. O ID do grupo de teste a ser executado. Se este valor não for especificado, o IDT executará o grupo de teste selecionado pelo executor de testes.
`TestCases`
Opcional. Uma matriz de casos IDs de teste do grupo especificado em`TestGroup`. Com base nos valores de `TestGroup` e `TestCases`, o IDT determina o comportamento da execução do teste da seguinte forma:
+ Quando tanto o `TestGroup` como os `TestCases` são especificados, o IDT executa os casos de teste especificados do grupo de teste.
+ Quando `TestCases` são especificados, mas `TestGroup` não são especificados, o IDT executa os casos de teste especificados.
+ Quando `TestGroup` é especificado, mas `TestCases` não são especificados, o IDT executa os casos no grupo de teste especificado.
+ Quando nem `TestGroup` nem `TestCases` são especificados, o IDT executa todos os casos de teste do grupo de teste que o executor de teste seleciona na CLI do IDT. Para habilitar a seleção de grupos para executores de teste, é preciso incluir ambos os estados `RunTask` e `Choice` em seu arquivo `state_machine.json`. Para ver um exemplo de como isso funciona, consulte [Exemplo de máquina de estado: executar grupos de teste selecionados pelo usuário](#allow-specific-groups).
Para obter mais informações sobre como habilitar os comandos da CLI no IDT, consulte [Habilitar comandos da CLI no IDT](create-test-executables.md#idt-cli-coop).
`ResultVar`
O nome da variável de contexto a ser definida com os resultados da execução do teste. Não especifique este valor se você não especificou um valor para `TestGroup`. O IDT define o valor da variável que você define em `ResultVar` para `true` ou `false` com base no seguinte:
+ Se o nome da variável estiver no formato `text_text_passed`, o valor será definido como se todos os testes do primeiro grupo de teste foram aprovados ou ignorados.
+ Em todos os outros casos, o valor é definido como se todos os testes em todos os grupos de teste tivessem sido aprovados ou ignorados.
Normalmente, você usará o `RunTask` estado para especificar um ID de grupo de teste sem especificar um caso de teste individual IDs, para que o IDT execute todos os casos de teste no grupo de teste especificado. Todos os casos de teste executados por esse estado são executados em paralelo, em uma ordem aleatória. No entanto, se todos os casos de teste exigirem a execução de um dispositivo e apenas um único dispositivo estiver disponível, os casos de teste serão executados em sequência.
**Como tratar erros**
Se algum dos grupos de teste ou caso de teste IDs especificados não for válido, esse estado emitirá o erro de `RunTaskError` execução. Se o estado encontrar um erro de execução, ele também definirá a variável `hasExecutionError` no contexto da máquina de estado como `true`.
### Escolha
O estado `Choice` permite definir dinamicamente o próximo estado para o qual fazer a transição com base em condições definidas pelo usuário.
```
{
"Type": "Choice",
"Default": "",
"FallthroughOnError": true | false,
"Choices": [
{
"Expression": "",
"Next": ""
}
]
}
```
Todos os campos que contêm valores são necessários, conforme descrito aqui:
`Default`
O estado padrão para o qual fazer a transição se nenhuma das expressões definidas em `Choices` puder ser avaliada como `true`.
`FallthroughOnError`
Opcional. Especifica o comportamento quando o estado se depara com um erro na avaliação de expressões. Defina como `true` se deseja ignorar uma expressão, caso a avaliação resulte em um erro. Se não houver correspondência de expressão, a máquina de estado fará a transição para o estado `Default`. Se o valor `FallthroughOnError` não for especificado, o valor padrão será `false`.
`Choices`
Uma matriz de expressões e estados para determinar para qual estado fazer a transição depois de executar as ações no estado atual.
`Choices.Expression`
Uma string de expressão que deve ser avaliada para um valor booleano. Se a expressão for avaliada como `true`, a máquina de estado fará a transição para o estado definido em `Choices.Next`. As strings de expressão recuperam valores do contexto da máquina de estado e, em seguida, executam operações neles para chegar a um valor booleano. Para obter informações sobre como acessar o contexto da máquina de estado, consulte [Contexto da máquina de estado](#state-machine-context).
`Choices.Next`
O nome do estado para o qual fazer a transição caso a expressão definida em `Choices.Expression` seja avaliada como `true`.
**Como tratar erros**
O estado `Choice` pode exigir o tratamento de erros nos seguintes casos:
+ Algumas variáveis nas expressões de escolha não existem no contexto da máquina de estado.
+ O resultado de uma expressão não é um valor booleano.
+ O resultado de uma pesquisa JSON não é uma string, número ou booleano.
Não é possível usar um bloco `Catch` para tratar erros nesse estado. Se quiser parar de executar a máquina de estado quando ela encontrar um erro, defina `FallthroughOnError` como `false`. No entanto, é recomendado configurar `FallthroughOnError` e `true`, e dependendo do seu caso de uso, executar uma das seguintes etapas:
+ Se uma variável que você está acessando não existir em alguns casos, use o valor de `Default` e blocos `Choices` adicionais para especificar o próximo estado.
+ Se uma variável que estiver acessando sempre existir, defina o estado `Default` como `Fail`.
### Paralelo
O estado `Parallel` permite que você defina e execute novas máquinas de estado em paralelo.
```
{
"Type": "Parallel",
"Next": "",
"Branches": [
]
}
```
Todos os campos que contêm valores são necessários, conforme descrito aqui:
`Next`
O nome do estado para o qual fazer a transição após a execução das ações no estado atual.
`Branches`
Uma matriz de definições de máquina de estado a serem executadas. Cada definição de máquina de estado deve conter os próprios estados `StartAt`, `Succeed` e `Fail`. As definições de máquina de estado nesta matriz não podem fazer referência a estados de fora da definição deles.
Como cada máquina de estado de ramificação compartilha o mesmo contexto de máquina de estado, definir variáveis em uma ramificação e depois lê-las de outra ramificação pode resultar em um comportamento inesperado.
O estado `Parallel` passa para o próximo estado somente depois de executar todas as máquinas de estado da ramificação. Todo estado que necessita um dispositivo aguardará para ser executado até que o dispositivo esteja disponível. Se vários dispositivos estiverem disponíveis, este estado executará casos de teste a partir de vários grupos em paralelo. Se não houver dispositivos suficientes disponíveis, os casos de teste serão executados em sequência. Como os casos de teste são executados em uma ordem aleatória quando executados em paralelo, podem ser usados dispositivos diferentes para executar testes a partir do mesmo grupo de teste.
**Como tratar erros**
Certifique-se que tanto a máquina de estado da ramificação quanto a máquina de estado pai fazem a transição para o estado `Fail` para tratar erros de execução.
Como as máquinas de estado de ramificação não transmitem erros de execução para a máquina de estado principal, você não pode usar um bloco `Catch` para lidar com erros de execução em máquinas de estado de ramificação. Em vez disso, use o valor `hasExecutionErrors` no contexto da máquina de estado compartilhada. Para obter um exemplo de como isso funciona, consulte [Exemplo de máquina de estado: execute dois grupos de testes em paralelo](#run-in-parallel).
### AddProductFeatures
O estado `AddProductFeatures` permite adicionar recursos do produto ao arquivo `awsiotdevicetester_report.xml` gerado pelo IDT.
Um recurso do produto é uma informação definida pelo usuário sobre critérios específicos que um dispositivo pode atender. Por exemplo, o recurso do produto `MQTT` pode indicar que o dispositivo publica mensagens MQTT corretamente. No relatório, os recursos do produto são definidas como `supported`, `not-supported` ou um valor personalizado, com base na aprovação dos testes especificados.
**nota**
O estado `AddProductFeatures` não gera relatórios por conta própria. Esse estado deve passar para o [estado `Report`](#state-report) para gerar relatórios.
```
{
"Type": "Parallel",
"Next": "",
"Features": [
{
"Feature": "",
"Groups": [
""
],
"OneOfGroups": [
""
],
"TestCases": [
""
],
"IsRequired": true | false,
"ExecutionMethods": [
""
]
}
]
}
```
Todos os campos que contêm valores são necessários, conforme descrito aqui:
`Next`
O nome do estado para o qual fazer a transição após a execução das ações no estado atual.
`Features`
Uma matriz de recursos do produto para mostrar no arquivo `awsiotdevicetester_report.xml`.
`Feature`
O nome do recurso
`FeatureValue`
Opcional. O valor personalizado a ser usado no relatório em vez de `supported`. Se esse valor não for especificado, com base nos resultados do teste, o valor do recurso será definido como `supported` ou `not-supported`.
Se você usar um valor personalizado para `FeatureValue`, poderá testar o mesmo recurso com condições diferentes e o IDT concatenará os valores do recurso para as condições compatíveis. Por exemplo, o trecho a seguir mostra o recurso `MyFeature` com dois valores de recurso separados:
```
...
{
"Feature": "MyFeature",
"FeatureValue": "first-feature-supported",
"Groups": ["first-feature-group"]
},
{
"Feature": "MyFeature",
"FeatureValue": "second-feature-supported",
"Groups": ["second-feature-group"]
},
...
```
Se os dois grupos de teste forem aprovados, o valor do recurso será definido como `first-feature-supported, second-feature-supported`.
`Groups`
Opcional. Uma matriz de grupos de teste IDs. Todos os testes dentro de cada grupo de teste especificado devem ser aprovados para que o recurso seja compatível.
`OneOfGroups`
Opcional. Uma matriz de grupos de teste IDs. Todos os testes dentro de pelo menos um dos grupos de teste especificados devem ser aprovados para que o recurso seja compatível.
`TestCases`
Opcional. Uma variedade de casos de teste IDs. Se especificar este valor, o seguinte se aplica:
+ Todos os casos de teste especificados devem ser aprovados para que o recurso seja compatível.
+ `Groups` deve conter somente um ID de grupo de teste.
+ `OneOfGroups` não deve ser especificado.
`IsRequired`
Opcional. Defina como `false` para marcar este recurso como um recurso opcional no relatório. O valor padrão é `true`.
`ExecutionMethods`
Opcional. Uma matriz de métodos de execução que correspondem ao valor `protocol` especificado no arquivo `device.json`. Se esse valor for especificado, os executores de teste deverão especificar um valor `protocol` que corresponda a um dos valores dessa matriz para incluir o recurso no relatório. Se esse valor não for especificado, o recurso sempre será incluído no relatório.
Para usar o estado `AddProductFeatures`, você deve definir o valor de `ResultVar` no estado `RunTask` como um dos seguintes valores:
+ Se você especificou um caso de teste individual IDs, `ResultVar` defina como`group-id_test-id_passed`.
+ Se você não especificou um caso de teste individual IDs, `ResultVar` defina como`group-id_passed`.
O estado `AddProductFeatures` verifica os resultados dos testes da seguinte maneira:
+ Se você não especificou nenhum caso de teste IDs, o resultado de cada grupo de teste será determinado a partir do valor da `group-id_passed` variável no contexto da máquina de estado.
+ Se você especificou o caso de teste IDs, o resultado de cada um dos testes será determinado a partir do valor da `group-id_test-id_passed` variável no contexto da máquina de estado.
**Como tratar erros**
Se um ID de grupo fornecido neste estado não for um ID de grupo válido, este estado resultará no erro de execução `AddProductFeaturesError`. Se o estado encontrar um erro de execução, ele também definirá a variável `hasExecutionErrors` no contexto da máquina de estado como `true`.
### Relatório
O estado `Report` gera os arquivos `suite-name_Report.xml` e `awsiotdevicetester_report.xml`. Este estado também transmite o relatório para o console.
```
{
"Type": "Report",
"Next": ""
}
```
Todos os campos que contêm valores são necessários, conforme descrito aqui:
`Next`
O nome do estado para o qual fazer a transição após a execução das ações no estado atual.
É sempre necessário fazer a transição para o estado `Report` perto do final do fluxo de execução do teste para que os executores de teste possam visualizar os resultados do teste. Normalmente, o próximo estado após este estado é `Succeed`.
**Como tratar erros**
Se este estado se deparar com problemas ao gerar relatórios, ele emitirá o erro de execução `ReportError`.
### LogMessage
O estado `LogMessage` gera o arquivo `test_manager.log` e transmite a mensagem de log para o console.
```
{
"Type": "LogMessage",
"Next": ""
"Level": "info | warn | error"
"Message": ""
}
```
Todos os campos que contêm valores são necessários, conforme descrito aqui:
`Next`
O nome do estado para o qual fazer a transição após a execução das ações no estado atual.
`Level`
O nível de erro no qual criar a mensagem de log. Se especificar um nível que não seja válido, este estado irá gerar uma mensagem de erro e a descartará.
`Message`
A mensagem a ser registrada.
### SelectGroup
O estado `SelectGroup` atualiza o contexto da máquina de estado para indicar quais grupos estão selecionados. Os valores definidos por esse estado são usados por qualquer estado `Choice` seguinte.
```
{
"Type": "SelectGroup",
"Next": ""
"TestGroups": [
"
]
}
```
Todos os campos que contêm valores são necessários, conforme descrito aqui:
`Next`
O nome do estado para o qual fazer a transição após a execução das ações no estado atual.
`TestGroups`
Uma matriz de grupos de teste que serão marcados como selecionados. Para cada ID de grupo de teste nesta matriz, a variável `group-id_selected` é definida como `true` no contexto. Certifique-se de fornecer um grupo de teste válido IDs porque o IDT não valida se os grupos especificados existem.
### Falha
O estado `Fail` indica que a máquina de estado não foi executada corretamente. Este é um estado final para a máquina de estados e cada definição de máquina de estado deve incluir este estado.
```
{
"Type": "Fail"
}
```
### Êxito
O estado `Succeed` indica que a máquina de estado foi executada corretamente. Este é um estado final para a máquina de estados e cada definição de máquina de estado deve incluir este estado.
```
{
"Type": "Succeed"
}
```
## Contexto da máquina de estado
O contexto da máquina de estado é um documento JSON somente para leitura que contém dados que estão disponíveis para a máquina de estado durante a execução. O contexto da máquina de estado é acessível somente da máquina de estado e contém informações que determinam o fluxo de teste. Por exemplo, você pode usar as informações configuradas pelos executores de teste no arquivo `userdata.json` para determinar se é necessário executar um teste específico.
O contexto da máquina de estado usa o seguinte formato:
```
{
"pool": {
},
"userData": {
},
"config": {
},
"suiteFailed": true | false,
"specificTestGroups": [
""
],
"specificTestCases": [
""
],
"hasExecutionErrors": true
}
```
`pool`
Informações sobre o grupo de dispositivos selecionado para a execução do teste. Para um grupo de dispositivos selecionado, essas informações são recuperadas do elemento correspondente da matriz do grupo de dispositivos de nível superior definido no arquivo `device.json`.
`userData`
As informações no arquivo `userdata.json`.
`config`
As informações fixadas no arquivo `config.json`.
`suiteFailed`
O valor é definido como `false` quando a máquina de estado for iniciada. Se um grupo de teste falhar em um estado `RunTask`, este valor será definido como `true` para a duração restante da execução da máquina de estado.
`specificTestGroups`
Se o executor de teste selecionar grupos de teste específicos para execução em vez de toda a suíte de testes, essa chave será criada e conterá a lista de grupos de testes específicos. IDs
`specificTestCases`
Se o executor de teste selecionar casos de teste específicos para execução em vez de todo o conjunto de testes, essa chave será criada e conterá a lista de casos de teste específicos. IDs
`hasExecutionErrors`
Não saia quando a máquina de estado é iniciada. Se algum estado encontrar um erro de execução, esta variável será criada e definida como `true` para a duração restante da execução da máquina de estado.
Você pode consultar o contexto usando a JSONPath notação. A sintaxe para JSONPath consultas em definições de estado é. `{{$.query}}` Você pode usar JSONPath consultas como cadeias de caracteres de espaço reservado em alguns estados. O IDT substitui as cadeias de caracteres de espaço reservado pelo valor da JSONPath consulta avaliada do contexto. É possível usar espaços reservados para os seguintes valores:
+ O valor `TestCases` nos estados `RunTask`.
+ O valor de `Expression` no estado `Choice`.
Ao acessar dados do contexto da máquina de estado, verifique se as seguintes condições são atendidas:
+ Seus caminhos JSON devem começar com `$.`
+ Cada valor deve ser avaliado como uma string, um número ou um booleano.
Para obter mais informações sobre o uso JSONPath da notação para acessar dados do contexto, consulte[Use o contexto do IDT](idt-context.md).
## Erros de execução
Os erros de execução são erros na definição da máquina de estado que a máquina de estado encontra ao executar um estado. O IDT registra informações sobre cada erro no arquivo `test_manager.log` e transmite a mensagem de log para o console.
É possível usar os seguintes métodos para lidar com erros de execução:
+ Adicione um [bloco `Catch`](#catch) na definição do estado.
+ Verifique o valor do [valor `hasExecutionErrors`](#context) no contexto da máquina de estado.
### Catch
Para usar `Catch`, adicione o seguinte à sua definição de estado:
```
"Catch": [
{
"ErrorEquals": [
""
]
"Next": ""
}
]
```
Todos os campos que contêm valores são necessários, conforme descrito aqui:
`Catch.ErrorEquals`
Uma matriz dos tipos de erro a serem capturados. Se um erro de execução corresponder a um dos valores especificados, a máquina de estado fará a transição para o estado especificado em `Catch.Next`. Consulte cada definição de estado para obter informações sobre o tipo de erro que ela produz.
`Catch.Next`
O próximo estado para o qual fazer a transição se o estado atual encontrar um erro de execução que corresponder a um dos valores especificados em `Catch.ErrorEquals`.
Os blocos de captura são manuseados de maneira sequencial até que um deles corresponda. Se os erros não corresponderem aos listados nos blocos Catch, as máquinas de estado continuarão a ser executadas. Como os erros de execução são resultado de definições de estado incorretas, recomendamos que você faça a transição para o estado Falha quando um estado encontrar um erro de execução.
### hasExecutionError
Quando alguns estados encontram erros de execução, além de emitirem o erro, eles também definem o valor `hasExecutionError` como `true` no contexto da máquina de estado. É possível usar este valor para detectar quando ocorre um erro e, em seguida, usar um estado `Choice` para fazer a transição da máquina de estado para o estado `Fail`.
Este método tem as características a seguir.
+ A máquina de estado não inicia com nenhum valor atribuído para `hasExecutionError` e este valor não está disponível até que um determinado estado a defina. Isto significa que é preciso definir explicitamente o `FallthroughOnError` como `false` para os estados `Choice` que acessam este valor para evitar que a máquina de estado pare se nenhum erro de execução ocorrer.
+ Depois de definido como `true`, `hasExecutionError` nunca é definido como falso ou removido do contexto. Isto significa que esse valor é útil somente na primeira vez em que é definido como `true` e, para todos os estados subsequentes, não fornece um valor significativo.
+ O valor `hasExecutionError` é compartilhado com todas as máquinas de estado da filial no estado`Parallel`, o que pode resultar em resultados inesperados, dependendo da ordem em que é acessado.
Por conta dessas características, não é recomendado usar este método, e sim, usar um bloco Catch.
## Exemplo de máquinas de estado
Esta seção fornece alguns exemplos de configurações de máquina de estado.
**Topics**
+ [Exemplo de máquina de estado: execute um único grupo de teste](#single-test-group)
+ [Exemplo de máquina de estado: execute grupos de teste selecionados pelo usuário](#allow-specific-groups)
+ [Exemplo de máquina de estado: execute um único grupo de teste com recursos do produto](#run-with-product-features)
+ [Exemplo de máquina de estado: execute dois grupos de testes em paralelo](#run-in-parallel)
### Exemplo de máquina de estado: execute um único grupo de teste
Esta máquina de estado:
+ Executa o grupo de teste com o ID `GroupA`, que deve estar presente no pacote em um arquivo `group.json`.
+ Verifica se há erros de execução e transições de `Fail` para ver se algum foi encontrado.
+ Gera um relatório e faz a transição para `Succeed` se não houver erros e, caso contrário, `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"
}
}
}
```
### Exemplo de máquina de estado: execute grupos de teste selecionados pelo usuário
Esta máquina de estado:
+ Verifica se o executor do teste selecionou grupos de teste específicos. A máquina de estado não verifica casos de teste específicos porque os executores de teste não podem selecionar casos de teste sem também selecionar um grupo de teste.
+ Se os grupos de teste forem selecionados:
+ Executa os casos de teste nos grupos de teste selecionados. Para fazer isso, a máquina de estado não especifica explicitamente nenhum grupo de teste ou caso de teste no estado `RunTask`.
+ Gera um relatório após executar todos os testes e sai.
+ Se os grupos de teste não forem selecionados:
+ Executa testes no grupo de teste `GroupA`.
+ Gera relatórios e sai.
```
{
"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"
}
}
}
```
### Exemplo de máquina de estado: execute um único grupo de teste com recursos do produto
Esta máquina de estado:
+ Executa o grupo de teste `GroupA`.
+ Verifica se há erros de execução e transições de `Fail` para ver se algum foi encontrado.
+ Adiciona o recurso `FeatureThatDependsOnGroupA` ao arquivo `awsiotdevicetester_report.xml`:
+ Se `GroupA` for aprovado, o recurso será definido como `supported`.
+ O recurso não está marcado como opcional no relatório.
+ Gera um relatório e faz a transição para `Succeed` se não houver erros e, caso contrário, `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"
}
}
}
```
### Exemplo de máquina de estado: execute dois grupos de testes em paralelo
Esta máquina de estado:
+ Executa os grupos de teste `GroupA` e `GroupB` em paralelo. As variáveis `ResultVar` armazenadas no contexto pelos estados `RunTask` nas máquinas de estado da ramificação estão disponíveis para o estado `AddProductFeatures`.
+ Verifica se há erros de execução e transições de `Fail` para ver se algum foi encontrado. Esta máquina de estado não usa um bloco `Catch` porque este método não detecta erros de execução em máquinas de estado de ramificação.
+ Adiciona recursos ao arquivo `awsiotdevicetester_report.xml` com base nos grupos que passam
+ Se `GroupA` for aprovado, o recurso será definido como `supported`.
+ O recurso não está marcado como opcional no relatório.
+ Gera um relatório e faz a transição para `Succeed` se não houver erros e, caso contrário, `Fail`
Se dois dispositivos estiverem configurados no grupo de dispositivos, tanto o `GroupA` como o `GroupB` poderão ser executados ao mesmo tempo. No entanto, se um `GroupA` ou `GroupB` tiver vários testes, os dois dispositivos poderão ser alocados para esses testes. Se somente um dispositivo estiver configurado, os grupos de testes serão executados sequencialmente.
```
{
"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"
}
}
}
```
# Criar executáveis de casos de teste do IDT
Você pode criar e colocar executáveis de casos de teste em uma pasta de conjuntos de testes das seguintes formas:
+ Para conjuntos de testes que usam argumentos ou variáveis de ambiente dos arquivos `test.json` para determinar quais testes executar, você pode criar um caso de teste executável único para todo o conjunto de testes ou um executável de teste para cada grupo de testes no conjunto de testes.
+ Para um pacote de teste em que você deseja executar testes específicos com base em comandos especificados, você cria um caso de teste executável para cada caso de teste no pacote de teste.
Como redator de teste, é possível determinar qual abordagem é apropriada para seu caso de uso e estruturar o executável do caso de teste de acordo. Certifique-se de fornecer o caminho correto do executável do caso de teste em cada arquivo `test.json` e de que o executável especificado seja executado corretamente.
Quando todos os dispositivos estiverem prontos para a execução de um caso de teste, o IDT lê os seguintes arquivos:
+ O `test.json` para o caso de teste selecionado determina os processos a serem iniciados e as variáveis de ambiente a serem definidas.
+ O `suite.json` para o pacote de teste determina as variáveis de ambiente a serem definidas.
O IDT inicia o processo executável de teste necessário com base nos comandos e argumentos especificados no arquivo `test.json` e passa as variáveis de ambiente necessárias para o processo.
## Use o SDK do cliente do IDT
Os SDKs do IDT Client permitem simplificar a forma como a lógica de teste é escrita em seu executável de teste com comandos de API que podem ser usados para interagir com o IDT e seus dispositivos em teste. No momento, o IDT fornece os seguintes SDKs:
+ SDK do cliente IDT para Python
+ SDK do cliente IDT para Go
+ SDK do cliente IDT para Java
Estes SDKs estão localizados na pasta `/sdks`. Ao criar um novo executável de caso de teste, é preciso copiar o SDK que deseja usar para a pasta que contém o executável do caso de teste e referenciar o SDK em seu código. Esta seção fornece uma breve descrição dos comandos de API disponíveis que você pode usar nos executáveis do seu caso de teste.
**Topics**
+ [Interação do dispositivo](#api-device-interaction)
+ [Interação do IDT](#api-idt-interaction)
+ [Interação do host](#api-host-interaction)
### Interação do dispositivo
Os comandos a seguir permitem que a comunicação com o dispositivo em teste sem precisar implementar nenhuma interação adicional com o dispositivo e as funções de gerenciamento de conectividade.
`ExecuteOnDevice`
Permite que pacotes de teste executem comandos shell em um dispositivo compatível com conexões SSH ou Docker shell.
`CopyToDevice`
Permite que os pacotes de teste copiem um arquivo local da máquina host que executa o IDT para um local especificado em um dispositivo que suporte conexões SSH ou Docker shell.
`ReadFromDevice`
Permite que os pacotes de teste leiam a partir da porta serial de dispositivos compatíveis com conexões UART.
**nota**
Como o IDT não gerencia conexões diretas com dispositivos que são feitas usando as informações de acesso a dispositivos do contexto, recomendamos usar esses comandos da API de interação de dispositivos em seus executáveis de casos de teste. No entanto, se esses comandos não atenderem aos requisitos do caso de teste, você poderá recuperar as informações de acesso ao dispositivo do contexto do IDT e usá-las para fazer uma conexão direta com o dispositivo do pacote de teste.
Para fazer uma conexão direta, recupere as informações nos campos `device.connectivity` e `resource.devices.connectivity` do dispositivo em teste e dos dispositivos de recursos, respectivamente. Para obter mais informações sobre como usar contexto do IDT, consulte [Use o contexto do IDT](idt-context.md).
### Interação do IDT
Os comandos a seguir permitem que os conjuntos de teste se comuniquem com o IDT.
`PollForNotifications`
Permite que os pacotes de teste verifiquem as notificações do IDT.
`GetContextValue ` e `GetContextString`
Permite que os pacotes de teste recuperem valores do contexto do IDT. Para obter mais informações, consulte [Use o contexto do IDT](idt-context.md).
`SendResult`
Permite que os pacotes de teste relatem os resultados dos casos de teste ao IDT. Este comando deve ser chamado no final de cada caso de teste em um pacote de teste.
### Interação do host
O comando a seguir permite que seus pacotes de teste se comuniquem com a máquina host.
`PollForNotifications`
Permite que os pacotes de teste verifiquem as notificações do IDT.
`GetContextValue ` e `GetContextString`
Permite que os pacotes de teste recuperem valores do contexto do IDT. Para obter mais informações, consulte [Use o contexto do IDT](idt-context.md).
`ExecuteOnHost`
Permite que os pacotes de teste executem comandos na máquina local e permite que o IDT gerencie o ciclo de vida do executável do caso de teste.
## Habilitar comandos da CLI no IDT
O comando `run-suite` da CLI do IDT fornece várias opções que permitem que o executor de teste personalize a execução do teste. Para permitir que os executores de teste usem estas opções para executar seu pacote de teste personalizado, você implementa o suporte para a CLI do IDT. Se não implementar o suporte, os executores de teste ainda poderão executar testes, mas algumas opções da CLI não funcionarão corretamente. Para fornecer uma experiência ideal ao cliente, recomendamos que você implemente o suporte para os seguintes argumentos para o comando `run-suite` na CLI do IDT:
`timeout-multiplier`
Especifica um valor maior que 1,0 que será aplicado a todos os tempos limite durante a execução dos testes.
Os executores de teste podem usar esse argumento para aumentar o tempo limite dos casos de teste que desejam executar. Quando um executor de teste especifica esse argumento em seu comando `run-suite`, o IDT o usa para calcular o valor da variável de ambiente IDT\$1TEST\$1TIMEOUT e define o campo `config.timeoutMultiplier` no contexto do IDT. Para apoiar este argumento, você deve fazer o seguinte:
+ Em vez de usar diretamente o valor de tempo limite do arquivo `test.json`, leia a variável de ambiente IDT\$1TEST\$1TIMEOUT para obter o valor de tempo limite calculado corretamente.
+ Recupere o valor `config.timeoutMultiplier` do contexto do IDT e aplique-o a tempos limite de execução prolongados.
Para obter mais informações sobre como sair mais cedo por conta de eventos de tempo limite, consulte [Especifique o comportamento de saída](#test-exec-exiting).
`stop-on-first-failure`
Especifica que o IDT deve parar de executar todos os testes se encontrar uma falha.
Quando um executor de teste especifica esse argumento no comando `run-suite`, o IDT interrompe a execução dos testes assim que encontrar uma falha. No entanto, se os casos de teste estiverem sendo executados em paralelo, isso poderá levar a resultados inesperados. Para implementar o suporte, certifique-se de que, se o IDT encontrar esse evento, sua lógica de teste instrua todos os casos de teste em execução a parar, limpar recursos temporários e relatar o resultado do teste ao IDT. Para obter mais informações sobre sair antecipadamente em falhas, consulte [Especifique o comportamento de saída](#test-exec-exiting).
`group-id` e da `test-id`
Especifica que o IDT deve executar somente os grupos de teste ou casos de teste selecionados.
Os executores de teste podem usar esses argumentos com os comandos `run-suite` para especificar o seguinte comportamento de execução do teste:
+ Execute todos os testes dentro dos grupos de teste especificados.
+ Execute uma seleção de testes de dentro de um grupo de teste especificado.
Para dar suporte a esses argumentos, o orquestrador de testes do seu conjunto de testes deve incluir um conjunto específico de estados `RunTask` e `Choice` no seu orquestrador de testes. Se você não estiver usando uma máquina de estado personalizada, o orquestrador de testes IDT padrão incluirá os estados necessários para você e não será necessário realizar nenhuma ação adicional. Entretanto, se você estiver usando um orquestrador de testes personalizado, use [Exemplo de máquina de estado: execute grupos de teste selecionados pelo usuário](idt-state-machine.md#allow-specific-groups) como exemplo para adicionar os estados necessários no seu orquestrador de testes.
Para obter mais informações sobre os comandos da CLI no IDT, consulte [Depure e execute conjuntos de teste personalizados](run-debug-custom-tests.md).
## Gravar logs de eventos
Enquanto o teste está sendo executado, você envia dados para `stdout` e `stderr` e grava logs de eventos e mensagens de erro no console. Para obter informações sobre o formato das mensagens do console, consulte [Formato de mensagem do console](idt-review-results-logs.md#idt-console-format).
Quando o IDT terminar de executar o pacote de teste, essas informações também estarão disponíveis no arquivo `test_manager.log` localizado na pasta `/results//logs`.
É possível configurar cada caso de teste para gravar os logs de sua execução de teste, incluindo logs do dispositivo em teste, no arquivo `_` localizado na pasta `/results/execution-id/logs`. Para fazer isso, recupere o caminho para o arquivo de log do contexto do IDT com a consulta `testData.logFilePath`, crie um arquivo nesse caminho e grave o conteúdo deseja nele. O IDT atualiza automaticamente o caminho com base no caso de teste que está sendo executado. Se você optar por não criar o arquivo de log para um caso de teste, nenhum arquivo será gerado para esse caso de teste.
É possível configurar seu executável de texto para criar arquivos de log adicionais, conforme necessário, na pasta `/logs`. É recomendado especificar prefixos exclusivos para nomes de arquivos de log para que seus arquivos não sejam substituídos.
## Relatar resultados ao IDT
O IDT grava os resultados do teste nos arquivos `awsiotdevicetester_report.xml` e `suite-name_report.xml`. Estes arquivos de relatório estão localizados em `/results//`. Ambos os relatórios capturam os resultados da execução do pacote de teste. Para obter mais informações sobre os esquemas que o IDT usa para esses relatórios, consulte [Analise os resultados e logs dos testes do IDT](idt-review-results-logs.md)
Para preencher o conteúdo do arquivo `suite-name_report.xml`, o comando `SendResult` deve ser usado para relatar os resultados do teste ao IDT antes da conclusão da execução do teste. Se o IDT não conseguir localizar os resultados de um teste, ele emitirá um erro para o caso de teste. O seguinte trecho em Python mostra os comandos para enviar um resultado de teste para o IDT:
```
request-variable = SendResultRequest(TestResult(result))
client.send_result(request-variable)
```
Se não reportar os resultados por meio da API, o IDT procurará os resultados do teste na pasta de artefatos de teste. O caminho para essa pasta é armazenado no campo `testData.testArtifactsPath` no contexto do IDT. Nesta pasta, o IDT usa o primeiro arquivo XML classificado em ordem alfabética localizado como resultado do teste.
Se sua lógica de teste produzir resultados XML JUnit, será possível gravar os resultados do teste em um arquivo XML na pasta de artefatos para fornecer os resultados diretamente ao IDT em vez de analisá-los e depois usar a API para enviá-los ao IDT.
Se usar este método, a lógica de teste deverá resumir com precisão os resultados do teste e formatar o arquivo de resultados no mesmo formato do arquivo `suite-name_report.xml`. O IDT não realiza nenhuma validação dos dados fornecidos, com as seguintes exceções:
+ O IDT ignora todas as propriedades da tag `testsuites`. Em vez disso, ele calcula as propriedades da tag a partir dos resultados de outros grupos de teste relatados.
+ Pelo menos uma tag `testsuite` deve existir nos `testsuites`.
Como o IDT usa a mesma pasta de artefatos para todos os casos de teste e não exclui os arquivos de resultados entre as execuções de teste, esse método também pode gerar relatórios incorretos, caso o IDT leia o arquivo incorreto. É recomendado o uso do mesmo nome para o arquivo de resultados XML gerado em todos os casos de teste para sobrescrever os resultados de cada caso de teste e garantir que os resultados corretos estejam disponíveis para o IDT usar. Embora seja possível usar uma abordagem mista para gerar relatórios em pacotes de teste, ou seja, usar um arquivo de resultados XML para alguns casos de teste e enviar resultados por meio da API em outros casos, não recomendamos essa abordagem.
## Especifique o comportamento de saída
Configure seu executável de texto para sempre sair com um código de saída 0, mesmo se um caso de teste relatar uma falha ou um resultado de erro. Use códigos de saída diferentes de zero somente para indicar que um caso de teste não foi executado ou caso o executável do caso de teste não tenha comunicado nenhum resultado ao IDT. Quando o IDT recebe um código de saída diferente de zero, ele marca que o caso de teste se deparou com um erro que o impediu de ser executado.
O IDT pode solicitar ou esperar a interrupção da execução de um caso de teste antes de concluir os eventos a seguir. Use estas informações para configurar o executável do caso de teste para detectar cada um desses eventos do caso de teste:
**Timeout (Tempo limite**
Ocorre quando um caso de teste é executado por mais tempo do que o valor de tempo limite especificado no arquivo `test.json`. Se o executor do teste usou o argumento `timeout-multiplier` para especificar um multiplicador de tempo limite, o IDT calcula o valor do tempo limite com o multiplicador.
Para detectar este evento, use a variável de ambiente IDT\$1TEST\$1TIMEOUT. Quando um executor de teste inicializa um teste, o IDT define o valor da variável de ambiente IDT\$1TEST\$1TIMEOUT como o valor de tempo limite calculado (em segundos) e passa a variável para o executável do caso de teste. É possível ler o valor da variável para definir um cronômetro apropriado.
**Interromper**
Ocorre quando o executor do teste interrompe o IDT. Por exemplo, ao pressionar Ctrl\$1C.
Como os terminais propagam sinais para todos os processos secundários, você pode simplesmente configurar um manipulador de sinais em seus casos de teste para detectar sinais de interrupção.
Como alternativa, é possível sondar periodicamente a API para verificar o valor da `CancellationRequested` booleana na resposta da API `PollForNotifications`. Quando o IDT recebe um sinal de interrupção, ele define o valor do `CancellationRequested` booleano como `true`.
**Interrompa na primeira falha**
Ocorre quando um caso de teste executado paralelamente ao caso de teste atual falha e o executor de teste usa o argumento `stop-on-first-failure` para especificar que o IDT deve interromper ao se deparar com uma falha.
Para detectar esse evento, é possível pesquisar periodicamente a API para verificar o valor `CancellationRequested` do booleano na resposta da API `PollForNotifications`. Quando o IDT encontra uma falha e é configurado para interromper a primeira falha, ele define o valor do `CancellationRequested` booleano como `true`.
Quando um desses eventos ocorre, o IDT espera cinco minutos para que os casos de teste em execução no momento concluam a execução. Se todos os casos de teste em execução não saírem em cinco minutos, o IDT forçará a interrupção de cada um dos processos deles. Se o IDT não tiver recebido os resultados do teste antes da conclusão dos processos, ele marcará os casos de teste como expirados. Como prática recomendada, os seus casos de teste devem executar as seguintes ações quando encontrarem um dos eventos:
1. Interrompa a execução da lógica de teste normal.
1. Limpar todos os recursos temporários, como artefatos de teste no dispositivo em teste.
1. Relate um resultado de teste ao IDT, como uma falha ou erro no teste.
1. Sair.
# Use o contexto do IDT
Quando o IDT executa um pacote de teste, o pacote de teste pode acessar um conjunto de dados que podem ser usados para determinar como cada teste é executado. Estes dados são chamados de contexto do IDT. Por exemplo, a configuração de dados do usuário fornecida pelos executores de teste em um arquivo `userdata.json` é disponibilizada para pacotes de teste no contexto do IDT.
O contexto do IDT pode ser considerado um documento JSON somente para leitura. Os pacotes de teste podem recuperar e gravar dados no contexto usando tipos de dados JSON padrão, como objetos, matrizes, números e assim por diante.
## Esquema de contexto
O contexto do IDT usa o formato a seguir:
```
{
"config": {
"timeoutMultiplier": timeout-multiplier
},
"device": {
},
"devicePool": {
},
"resource": {
"devices": [
{
"name": ""
}
]
},
"testData": {
"awsCredentials": {
"awsAccessKeyId": "",
"awsSecretAccessKey": "",
"awsSessionToken": ""
},
"logFilePath": "/path/to/log/file"
},
"userData": {
}
}
```
`config`
Informações do [arquivo `config.json`](set-custom-idt-config.md#config-json-custom). O campo `config` também contém o seguinte campo adicional:
`config.timeoutMultiplier`
O multiplicador de um valor de tempo limite usado pelo conjunto de testes. Este valor é especificado pelo executor de teste da CLI do IDT. O valor padrão é `1`.
`device`
Informações sobre o dispositivo selecionado para a execução do teste. Estas informações são equivalentes à matriz `devices` definida no [arquivo `device.json`](set-custom-idt-config.md#device-config-custom) do dispositivo selecionado.
`devicePool`
Informações sobre o grupo de dispositivos selecionado para a execução do teste. Estas informações são equivalentes ao elemento de matriz do grupo de dispositivos de nível superior definido no arquivo `device.json` do grupo de dispositivos selecionado.
`resource`
As informações sobre dispositivos de recursos do arquivo `resource.json`.
`resource.devices`
Estas informações são equivalentes à matriz `devices` definida no arquivo `resource.json`. Cada elemento `devices` inclui o seguinte campo adicional:
`resource.device.name`
O nome do dispositivo de recurso. Este valor é definido como o valor `requiredResource.name` no arquivo `test.json`.
`testData.awsCredentials`
As credenciais da AWS usadas pelo teste para se conectar à nuvem da AWS. Estas informações são obtidas do arquivo `config.json`.
`testData.logFilePath`
O caminho para o arquivo de log no qual o caso de teste grava mensagens de log. O pacote de teste criará este arquivo se ele não existir.
`userData`
As informações fornecidas pelo executor de teste no [arquivo `userdata.json`](set-custom-idt-config.md#userdata-config-custom).
## Acessar dados no contexto
É possível consultar o contexto usando a notação JSONPath dos arquivos JSON e do executável de texto com as APIs `GetContextValue` e `GetContextString`. A sintaxe das cadeias de caracteres JSONPath para acessar o contexto do IDT varia da seguinte forma:
+ Em `suite.json` e `test.json`, é usado `{{query}}`. Ou seja, não use o elemento raiz `$.` para iniciar sua expressão.
+ Em `test_orchestrator.yaml`, é usado `{{query}}`.
Se você usa a máquina de estado obsoleta, então em`state_machine.json`, você usa. `{{$.query}}`
+ Nos comandos da API, é usado `query` ou `{{$.query}}`, dependendo do comando. Para obter mais informações, consulte a documentação em linha dos SDKs.
A tabela a seguir descreve os operadores em uma expressão JSONPath típica:
| Operator | Description |
| --- |--- |
| \$1 | The root element. Because the top-level context value for IDT is an object, you will typically use \$1. to start your queries. |
| .childName | Accesses the child element with name childName from an object. If applied to an array, yields a new array with this operator applied to each element. The element name is case sensitive. For example, the query to access the awsRegion value in the config object is \$1.config.awsRegion. |
| [start:end] | Filters elements from an array, retrieving items beginning from the rápido index and going up to the end index, both inclusive. |
| [index1, index2, … , indexN] | Filters elements from an array, retrieving items from only the specified indices. |
| [?(expr)] | Filters elements from an array using the expr expression. This expression must evaluate to a boolean value. |
Para criar expressões de filtro, use a sintaxe a seguir:
```
| operator |
```
Nesta sintaxe:
+ `jsonpath` é um JSONPath que usa a sintaxe JSON padrão.
+ `value` é qualquer valor personalizado que usa a sintaxe JSON padrão.
+ `operator` é um dos seguintes operadores:
+ `<` (Menor que)
+ `<=` (Menor ou igual a)
+ `==` (Igual a)
Se o JSONPath ou o valor em sua expressão for um valor de matriz, booleano ou objeto, este será o único operador binário compatível que será possível usar.
+ `>=` (Maior ou igual a)
+ `>` (Maior que)
+ `=~` (Correspondência de expressão regular). Para usar este operador em uma expressão de filtro, o JSONPath ou valor no lado esquerdo da expressão deve ser avaliado como uma string e o lado direito deve ser um valor padrão que siga a sintaxe [RE2](https://github.com/google/re2/wiki/Syntax).
É possível usar consultas JSONPath no formato \$1\$1*query*\$1\$1 como strings de reserva de espaço nos campos `args` e `environmentVariables` nos arquivos `test.json` e nos campos `environmentVariables` nos arquivos `suite.json`. O IDT realiza uma pesquisa de contexto e preenche os campos com o valor avaliado da consulta. Por exemplo, no arquivo `suite.json`, é possível usar strings de espaço reservado para especificar valores de variáveis de ambiente que mudam com cada caso de teste e o IDT preencherá as variáveis de ambiente com o valor correto para cada caso de teste. No entanto, ao usar strings de caracteres de espaço reservado em arquivos `test.json` e `suite.json`, as seguintes considerações se aplicam às suas consultas:
+ Cada ocorrência da chave `devicePool` em sua consulta deve estar em letras minúsculas. Ou seja, em vez disso, use `devicepool`.
+ Para as matrizes, somente matrizes de strings podem ser usadas. Além disso, as matrizes usam um formato `item1, item2,...,itemN` não padrão. Se a matriz contiver somente um elemento, ela será serializada como `item`, tornando-a indistinguível de um campo de strings.
+ Não é possível usar espaços reservados para recuperar objetos do contexto.
Por conta dessas considerações, é recomendado, sempre que possível, usar a API para acessar o contexto em sua lógica de teste em vez de strings de espaço reservado em arquivos `test.json` e `suite.json`. No entanto, em alguns casos, pode ser mais conveniente usar espaços reservados JSONPath para recuperar strings únicas para definir como variáveis de ambiente.
# Definir configurações para executores de teste
Para executar pacotes de testes personalizados, os executores de teste devem definir suas configurações com base no pacote de teste que desejam executar. As configurações são especificadas com base nos modelos de arquivo de configuração localizados na pasta `/configs/`. Se necessário, os executores de teste também devem configurar as credenciais da AWS que a IDT usará para se conectar à nuvem da AWS.
Como escritor de teste, será necessário configurar esses arquivos para [depurar seu pacote de teste](run-debug-custom-tests.md). É preciso fornecer instruções aos executores de teste para que eles possam definir as seguintes configurações conforme necessário para executar seus pacotes de testes.
## Configurar device.json
O arquivo `device.json` contém informações sobre os dispositivos em que os testes são executados (por exemplo, endereço IP, informações de login, sistema operacional e arquitetura de CPU).
Os executores de teste podem fornecer essas informações usando o seguinte arquivo `device.json` de modelo localizado na pasta `/configs/`.
```
[
{
"id": "",
"sku": "",
"features": [
{
"name": "",
"value": "",
"configs": [
{
"name": "",
"value": ""
}
],
}
],
"devices": [
{
"id": "",
"connectivity": {
"protocol": "ssh | uart | docker",
// ssh
"ip": "",
"port": ,
"auth": {
"method": "pki | password",
"credentials": {
"user": "",
// pki
"privKeyPath": "/path/to/private/key",
// password
"password": "",
}
},
// uart
"serialPort": "",
// docker
"containerId": "",
"containerUser": "",
}
}
]
}
]
```
Todos os campos que contêm valores são necessários, conforme descrito aqui:
`id`
Um ID alfanumérico definido pelo usuário que identifica uma coleção de dispositivos chamada de *grupo de dispositivos*. Os dispositivos que pertencem a um grupo devem ter hardware idêntico. Quando um conjunto de testes é executado, os dispositivos do grupo são usados para paralelizar a workload. Vários dispositivos são usados para executar testes diferentes.
`sku`
Um valor alfanumérico que identifica exclusivamente o dispositivo em teste. A SKU é usada para rastrear os dispositivos qualificados.
Se você deseja listar sua placa no AWS Partner Device Catalog, a SKU especificada aqui deve corresponder à SKU que você usa no processo de oferta.
`features`
Opcional. Uma matriz que contém recursos compatíveis com o dispositivo. Os recursos do dispositivo são valores definidos pelo usuário que você configura em seu pacote de teste. É preciso fornecer informações aos executores de teste sobre os nomes e valores dos recursos a serem incluídos no arquivo `device.json`. Por exemplo, se desejar testar um dispositivo que funciona como um servidor MQTT em outros dispositivos, você poderá configurar a lógica de teste para validar níveis compatíveis específicos de um recurso chamado `MQTT_QOS`. Os executores de teste fornecem esse nome de recurso e definem o valor do recurso para os níveis de QOS compatíveis com o dispositivo deles. Você pode recuperar as informações fornecidas do [contexto do IDT](idt-context.md) com a consulta `devicePool.features`, ou do [contexto do orquestrador de teste](idt-state-machine.md#state-machine-context) com a consulta `pool.features`.
`features.name`
O nome do recurso.
`features.value`
Os valores dos recursos compatíveis.
`features.configs`
Definições de configuração, se necessárias, para o recurso.
`features.config.name`
O nome do ajuste de configurações.
`features.config.value`
Os valores de configuração compatíveis.
`devices`
Uma matriz de dispositivos no grupo a serem testados. Pelo menos um dispositivo é necessário.
`devices.id`
Um identificador exclusivo, definido pelo usuário, para o dispositivo que está sendo testado.
`connectivity.protocol`
O protocolo de comunicação usado para se comunicar com esse dispositivo. Cada dispositivo em um grupo deve usar o mesmo protocolo.
No momento, os únicos valores compatíveis são `ssh` e `uart` para dispositivos físicos e `docker` para contêineres do Docker.
`connectivity.ip`
O endereço IP do dispositivo que está sendo testado.
Essa propriedade será aplicada somente se `connectivity.protocol` estiver definido como `ssh`.
`connectivity.port`
Opcional. O número da porta usada nas conexões SSH.
O valor padrão é 22.
Essa propriedade será aplicada somente se `connectivity.protocol` estiver definido como `ssh`.
`connectivity.auth`
Informações de autenticação da conexão.
Essa propriedade será aplicada somente se `connectivity.protocol` estiver definido como `ssh`.
`connectivity.auth.method`
O método de autenticação usado para acessar um dispositivo pelo protocolo de conectividade indicado.
Os valores compatíveis são:
+ `pki`
+ `password`
`connectivity.auth.credentials`
As credenciais usadas para autenticação.
`connectivity.auth.credentials.password`
A senha usada para fazer login no dispositivo que está sendo testado.
Esse valor se aplica somente se `connectivity.auth.method` estiver definido como `password`.
`connectivity.auth.credentials.privKeyPath`
O caminho completo para a chave privada usada para fazer login no dispositivo que está sendo testado.
Esse valor se aplica somente se `connectivity.auth.method` estiver definido como `pki`.
`connectivity.auth.credentials.user`
O nome de usuário para fazer login no dispositivo que está sendo testado.
`connectivity.serialPort`
Opcional. A porta serial à qual o dispositivo está conectado.
Essa propriedade será aplicada somente se `connectivity.protocol` estiver definido como `uart`.
`connectivity.containerId`
O ID do contêiner ou o nome do contêiner do Docker que está sendo testado.
Essa propriedade será aplicada somente se `connectivity.protocol` estiver definido como `ssh`.
`connectivity.containerUser`
Opcional. O nome de usuário para o usuário dentro do contêiner. O valor padrão é o usuário fornecido no Dockerfile.
O valor padrão é 22.
Essa propriedade será aplicada somente se `connectivity.protocol` estiver definido como `ssh`.
Para verificar se os executores de teste configuram a conexão incorreta do dispositivo em um teste, você pode recuperar `pool.Devices[0].Connectivity.Protocol` do contexto do orquestrador de teste e comparar com o valor esperado no estado `Choice`. Se um protocolo incorreto for usado, imprima uma mensagem usando o estado `LogMessage` e faça a transição para o estado `Fail`.
Como alternativa, é possível usar o código de tratamento de erros para relatar uma falha no teste para tipos de dispositivos incorretos.
## (Opcional) Configurar userdata.json
O arquivo `userdata.json` contém qualquer informação adicional exigida por um pacote de teste, mas não está especificada no arquivo `device.json`. O formato deste arquivo depende do [arquivo `userdata_scheme.json`](idt-json-config.md#userdata-schema-json) definido no pacote de teste. Se for um redator de testes, certifique-se de fornecer essas informações aos usuários que executarão os pacotes de testes escritos.
## (Opcional) Configurar resource.json
O arquivo `resource.json` contém informações sobre todos os dispositivos que serão usados como dispositivos de recursos. Os dispositivos de recursos são dispositivos necessários para testar determinados recursos de um dispositivo em teste. Por exemplo, para testar a capacidade Bluetooth de um dispositivo, é possível usar um dispositivo de recurso para testar se seu dispositivo consegue se conectar com êxito. Os dispositivos de recursos são opcionais e pode exigir quantos dispositivos de recursos precisar. Como redator de teste, é possível usar o [arquivo test.json](idt-json-config.md#test-json) para definir os recursos do dispositivo de recursos necessários para um teste. Em seguida, os executores de teste usam o arquivo `resource.json` para fornecer um pool de dispositivos de recursos com os recursos necessários. Certifique-se de fornecer essas informações aos usuários que executarão os pacotes de testes escritos.
Os executores de teste podem fornecer essas informações usando o seguinte arquivo `resource.json` de modelo localizado na pasta `/configs/`.
```
[
{
"id": "",
"features": [
{
"name": "",
"version": "",
"jobSlots":
}
],
"devices": [
{
"id": "",
"connectivity": {
"protocol": "ssh | uart | docker",
// ssh
"ip": "",
"port": ,
"auth": {
"method": "pki | password",
"credentials": {
"user": "",
// pki
"privKeyPath": "/path/to/private/key",
// password
"password": "",
}
},
// uart
"serialPort": "",
// docker
"containerId": "",
"containerUser": "",
}
}
]
}
]
```
Todos os campos que contêm valores são necessários, conforme descrito aqui:
`id`
Um ID alfanumérico definido pelo usuário que identifica uma coleção de dispositivos chamada de *grupo de dispositivos*. Os dispositivos que pertencem a um grupo devem ter hardware idêntico. Quando um conjunto de testes é executado, os dispositivos do grupo são usados para paralelizar a workload. Vários dispositivos são usados para executar testes diferentes.
`features`
Opcional. Uma matriz que contém recursos compatíveis com o dispositivo. As informações necessárias neste campo são definidas nos [arquivos test.json](idt-json-config.md#test-json) no pacote de teste e determinam quais testes devem ser executados e como executá-los. Se o pacote de teste não exigir nenhum recurso, este campo não será obrigatório.
`features.name`
O nome do recurso.
`features.version`
A versão do recurso.
`features.jobSlots`
Configuração para indicar quantos testes podem usar o dispositivo simultaneamente. O valor padrão é `1`.
`devices`
Uma matriz de dispositivos no grupo a serem testados. Pelo menos um dispositivo é necessário.
`devices.id`
Um identificador exclusivo, definido pelo usuário, para o dispositivo que está sendo testado.
`connectivity.protocol`
O protocolo de comunicação usado para se comunicar com esse dispositivo. Cada dispositivo em um grupo deve usar o mesmo protocolo.
No momento, os únicos valores compatíveis são `ssh` e `uart` para dispositivos físicos e `docker` para contêineres do Docker.
`connectivity.ip`
O endereço IP do dispositivo que está sendo testado.
Essa propriedade será aplicada somente se `connectivity.protocol` estiver definido como `ssh`.
`connectivity.port`
Opcional. O número da porta usada nas conexões SSH.
O valor padrão é 22.
Essa propriedade será aplicada somente se `connectivity.protocol` estiver definido como `ssh`.
`connectivity.auth`
Informações de autenticação da conexão.
Essa propriedade será aplicada somente se `connectivity.protocol` estiver definido como `ssh`.
`connectivity.auth.method`
O método de autenticação usado para acessar um dispositivo pelo protocolo de conectividade indicado.
Os valores compatíveis são:
+ `pki`
+ `password`
`connectivity.auth.credentials`
As credenciais usadas para autenticação.
`connectivity.auth.credentials.password`
A senha usada para fazer login no dispositivo que está sendo testado.
Esse valor se aplica somente se `connectivity.auth.method` estiver definido como `password`.
`connectivity.auth.credentials.privKeyPath`
O caminho completo para a chave privada usada para fazer login no dispositivo que está sendo testado.
Esse valor se aplica somente se `connectivity.auth.method` estiver definido como `pki`.
`connectivity.auth.credentials.user`
O nome de usuário para fazer login no dispositivo que está sendo testado.
`connectivity.serialPort`
Opcional. A porta serial à qual o dispositivo está conectado.
Essa propriedade será aplicada somente se `connectivity.protocol` estiver definido como `uart`.
`connectivity.containerId`
O ID do contêiner ou o nome do contêiner do Docker que está sendo testado.
Essa propriedade será aplicada somente se `connectivity.protocol` estiver definido como `ssh`.
`connectivity.containerUser`
Opcional. O nome de usuário para o usuário dentro do contêiner. O valor padrão é o usuário fornecido no Dockerfile.
O valor padrão é 22.
Essa propriedade será aplicada somente se `connectivity.protocol` estiver definido como `ssh`.
## (Opcional) Configurar config.json
O arquivo `config.json` contém as informações de configuração do IDT. Normalmente, os executores de teste não precisarão modificar esse arquivo, exceto para fornecer suas credenciais da AWS usuário para o IDT e, opcionalmente, para uma região da AWS. Se as credenciais AWS com as permissões necessárias forem fornecidas, o AWS IoT Device Tester coleta e envia métricas de uso para a AWS. Este é um recurso opcional e é usado para melhorar a funcionalidade do IDT. Para obter mais informações, consulte [Métricas de uso do IDT](idt-usage-metrics.md).
Os executores de teste podem configurar suas credenciais AWS por meio de uma das seguintes maneiras:
+ **Arquivo de credenciais**
O IDT usa o mesmo arquivo de credenciais que a AWS CLI. Para obter mais informações, consulte [Arquivos de configuração e credenciais](https://docs.aws.amazon.com/cli/latest/userguide/cli-config-files.html).
O local do arquivo de credenciais varia de acordo com o sistema operacional que você está usando:
+ macOS, Linux: `~/.aws/credentials`
+ Windows: : `C:\Users\UserName\.aws\credentials`
+ **Variáveis de ambiente**
As variáveis de ambiente são variáveis mantidas pelo sistema operacional e usadas pelos comandos do sistema. As variáveis definidas durante uma sessão SSH não estão disponíveis após o encerramento da sessão. O IDT pode usar as variáveis de ambiente `AWS_ACCESS_KEY_ID` e `AWS_SECRET_ACCESS_KEY` para armazenar suas credenciais da AWS.
Para definir essas variáveis no Linux, macOS ou Unix, use :**export**
```
export AWS_ACCESS_KEY_ID=
export AWS_SECRET_ACCESS_KEY=
```
Para definir essas variáveis no Windows, use :**set**
```
set AWS_ACCESS_KEY_ID=
set AWS_SECRET_ACCESS_KEY=
```
Para configurar as credenciais AWS para o IDT, os executores de teste editam a seção `auth` no arquivo `config.json` localizado na pasta `/configs/`.
```
{
"log": {
"location": "logs"
},
"configFiles": {
"root": "configs",
"device": "configs/device.json"
},
"testPath": "tests",
"reportPath": "results",
"awsRegion": "",
"auth": {
"method": "file | environment",
"credentials": {
"profile": ""
}
}
}
]
```
Todos os campos que contêm valores são necessários, conforme descrito aqui:
**nota**
Todos os caminhos nesse arquivo são definidos em relação ao**.
`log.location`
O caminho para a pasta de logs em **.
`configFiles.root`
O caminho para a pasta que contém os arquivos de configuração.
`configFiles.device`
O caminho para a função `device.json`.
`testPath`
O caminho para a pasta que contém pacotes de teste.
`reportPath`
O caminho para a pasta que conterá os resultados do teste depois que o IDT executar um pacote de teste.
`awsRegion`
Opcional. A região da AWS que os pacotes de teste usarão. Se não for definida, os pacotes de teste usarão a região padrão especificada em cada pacote de teste.
`auth.method`
O método que o IDT usa para recuperar as credenciais da AWS. Os valores aceitos são `file` recuperar credenciais de um arquivo de credenciais e recuperar credenciais `environment` usando variáveis de ambiente.
`auth.credentials.profile`
O perfil de credenciais a ser usado no arquivo de credenciais. Essa propriedade será aplicada somente se `auth.method` estiver definido como `file`.
# Depure e execute conjuntos de teste personalizados
Depois que a [configuração necessária](set-custom-idt-config.md) for definida, o IDT poderá executar seu pacote de teste. O runtime do pacote de testes completo depende do hardware e da composição do pacote de testes. Como referência, leva aproximadamente 30 minutos para concluir o pacote de qualificação completo AWS IoT Greengrass em um Raspberry Pi 3B.
Ao escrever seu pacote de testes, você pode usar o IDT para executar a conjunto de testes no modo de depuração para verificar seu código antes de executá-lo ou fornecê-lo aos executores de teste.
## Executar o IDT no modo de depuração
Como os pacotes de teste dependem do IDT para interagir com dispositivos, fornecer o contexto e receber resultados, não é possível simplesmente depurar seus pacotes de teste em um IDE sem qualquer interação com o IDT. Para fazer isso, a CLI do IDT fornece o comando `debug-test-suite` que permite executar o IDT no modo de depuração. Execute o seguinte comando para visualizar as opções disponíveis para `debug-test-suite`:
```
devicetester_[linux | mac | win_x86-64] debug-test-suite -h
```
Ao executar o IDT no modo de depuração, o IDT na verdade não inicia o pacote de teste nem executa o orquestrador de testes. Em vez disso, ele interage com seu IDE para responder às solicitações feitas do pacote de teste em execução no IDE e imprime os logs no console. O IDT não atinge o tempo limite e espera para sair até ser interrompido manualmente. No modo de depuração, o IDT também não executa o orquestrador de testes e não gera nenhum arquivo de relatório. Para depurar o conjunto de testes, você deve usar seu IDE para fornecer algumas informações que o IDT normalmente obtém dos arquivos JSON de configuração. Forneça as seguintes informações:
+ Variáveis de ambiente e argumentos para cada teste. O IDT não lerá essas informações de `test.json` ou `suite.json`.
+ Argumentos para selecionar os dispositivos de recursos. O IDT não lerá essas informações de `test.json`.
Para depurar seus pacotes de teste, conclua as seguintes etapas:
1. Crie os arquivos de ajuste de configuração necessários para executar o pacote de teste. Por exemplo, se o conjunto de testes necessita do `device.json`, `resource.json` e `user data.json`, configure todos eles conforme necessário.
1. Execute o comando a seguir para colocar o IDT no modo de depuração e selecionar todos os dispositivos necessários para executar o teste.
```
devicetester_[linux | mac | win_x86-64] debug-test-suite [options]
```
Depois de executar esse comando, o IDT aguarda as solicitações do pacote de teste e responde a elas. O IDT também gera as variáveis de ambiente necessárias para o processo de caso do SDK do cliente de IDT.
1. No seu IDE, use a configuração `run` ou `debug` para fazer o seguinte:
1. Defina os valores das variáveis de ambiente geradas pelo IDT.
1. Defina o valor de qualquer variável de ambiente ou argumento que você especificou em seu arquivo `test.json` e `suite.json`.
1. Definir pontos de interrupção, conforme necessário.
1. Execute o pacote de teste em seu IDE.
É possível depurar e executar novamente o pacote de teste quantas vezes for necessário. O IDT não atinge o tempo limite no modo de depuração.
1. Depois de concluir a depuração, interrompa o IDT para sair do modo de depuração.
## Comandos da CLI do IDT para executar testes
As seções a seguir descrevem os comandos da CLI do IDT.
------
#### [ IDT v4.0.0 ]
`help`
Lista as informações sobre o comando especificado.
`list-groups`
Lista os grupos em um determinado conjunto de teste.
`list-suites`
Lista os conjuntos de teste disponíveis.
`list-supported-products`
Lista os produtos compatíveis com a sua versão, neste caso, versões do AWS IoT Greengrass e versões do pacote de testes de qualificação AWS IoT Greengrass disponíveis para a versão atual do IDT.
`list-test-cases`
Lista os casos de teste em um grupo de teste. A seguinte opção é compatível:
+ `group-id`. O grupo de teste a ser pesquisado. Esta opção é necessária e deve especificar um único grupo.
`run-suite`
Executa um conjunto de testes em um grupo de dispositivos. Algumas opções comumente usadas a seguir:
+ `suite-id`. A versão do pacote de teste a ser executada. Se não for especificado, o IDT usará a versão mais recente na pasta `tests`.
+ `group-id`. Os grupos de teste a serem executados, como uma lista separada por vírgulas. Se não for especificado, o IDT executa todos os grupos de teste no conjunto de testes.
+ `test-id`. Os casos de teste a serem executados, como uma lista separada por vírgulas. Quando especificado, `group-id` deve especificar um único grupo.
+ `pool-id`. O grupo de dispositivos a ser testado. É preciso especificar um grupo se houver vários grupos de dispositivos definidos no arquivo `device.json`.
+ `timeout-multiplier`. Configura o IDT para modificar o tempo limite de execução do teste especificado no arquivo `test.json` para um teste com um multiplicador definido pelo usuário.
+ `stop-on-first-failure`. Configura o IDT de modo a interromper a execução na primeira falha. Essa opção deve ser usada com para depurar os grupos de teste especificados `group-id`.
+ `userdata`. Define o arquivo que contém as informações de dados do usuário necessárias para executar o pacote de teste. Isto é necessário somente se `userdataRequired` estiver definido como verdadeiro no arquivo `suite.json` do pacote de teste.
Para obter mais informações sobre as opções `run-suite`, use a opção `help`:
```
devicetester_[linux | mac | win_x86-64] run-suite -h
```
`debug-test-suite`
Execute o pacote de teste no modo de depuração. Para obter mais informações, consulte [Executar o IDT no modo de depuração](#idt-debug-mode).
------
# Analise os resultados e logs dos testes do IDT
Esta seção descreve o formato no qual o IDT gera logs do console e relatórios de teste.
## Formato de mensagem do console
O AWS IoT Device Tester usa um formato padrão para imprimir mensagens no console quando ele inicia um pacote de teste. O trecho a seguir mostra um exemplo de uma mensagem de console gerada pelo IDT.
```
time="2000-01-02T03:04:05-07:00" level=info msg=Using suite: MyTestSuite_1.0.0
executionId=9a52f362-1227-11eb-86c9-8c8590419f30
```
A maioria das mensagens detalhadas do console consiste nos seguintes campos:
`time`
Um carimbo de data/hora ISO 8601 completo para o evento registrado.
`level`
O nível da mensagem para o evento registrado. Normalmente, o nível da mensagem registrada é um `info`, `warn` ou `error`. O IDT emite uma mensagem `fatal` ou `panic` se encontrar um evento esperado que faça com que ele saia antecipadamente.
`msg`
A mensagem registrada.
`executionId`
Uma string de ID exclusiva para o processo atual do IDT. Este ID é usado para diferenciar entre execuções individuais de IDT.
As mensagens do console geradas de um pacote de teste fornecem informações adicionais sobre o dispositivo em teste e o pacote de teste, o grupo de teste e os casos de teste que o IDT executa. O trecho a seguir mostra um exemplo de uma mensagem de console gerada de um pacote de teste.
```
time="2000-01-02T03:04:05-07:00" level=info msg=Hello world! suiteId=MyTestSuite
groupId=myTestGroup testCaseId=myTestCase deviceId=my-device
executionId=9a52f362-1227-11eb-86c9-8c8590419f30
```
A parte específica do pacote de teste da mensagem do console contém os seguintes campos:
`suiteId`
O nome do pacote de teste em execução no momento.
`groupId`
O ID do grupo de teste em execução no momento.
`testCaseId`
O ID do caso de teste em execução no momento.
`deviceId`
Um ID do dispositivo em teste que o caso de teste atual está usando.
Para exibir um resumo do teste no console quando um IDT terminar de executar um teste, você deve incluir um [estado `Report`](idt-state-machine.md#state-report) no orquestrador de testes. O resumo do teste contém informações sobre o pacote de teste, os resultados de cada grupo executado e os locais dos logs e arquivos de logs gerados. O exemplo a seguir mostra uma mensagem de resume do teste.
```
========== Test Summary ==========
Execution Time: 5m00s
Tests Completed: 4
Tests Passed: 3
Tests Failed: 1
Tests Skipped: 0
----------------------------------
Test Groups:
GroupA: PASSED
GroupB: FAILED
----------------------------------
Failed Tests:
Group Name: GroupB
Test Name: TestB1
Reason: Something bad happened
----------------------------------
Path to IoT Device Tester Report: /path/to/awsiotdevicetester_report.xml
Path to Test Execution Logs: /path/to/logs
Path to Aggregated JUnit Report: /path/to/MyTestSuite_Report.xml
```
## esquema de relatório do AWS IoT Device Tester
`awsiotdevicetester_report.xml` é um relatório assinado que contém as seguintes informações:
+ A versão IDT.
+ A versão do pacote de teste.
+ A assinatura do relatório e a chave usada para assinar o relatório.
+ A SKU do dispositivo e o nome de grupo do dispositivo especificados no arquivo `device.json`.
+ A versão do produto e os recursos do dispositivo que foram testados.
+ O resumo agregado dos resultados de teste. Estas informações são as mesmas contidas no arquivo `suite-name_report.xml`.
```
idt-version
test-suite-version
signature
keyname
execution-id
start-time
end-time
product-name
product-version
device-sku
device-name
ssh | uart | docker
```
O arquivo `awsiotdevicetester_report.xml` contém uma tag `` com informações sobre o produto que está sendo testado e os recursos do produto que foram validados após a execução de um pacote de testes.recursos usados na tag ``
`name`
O nome do produto testado.
`version`
A versão do produto testado.
`features`
Os recursos validados. Os recursos marcados como `required` são necessários para que o pacote de teste valide o dispositivo. O trecho a seguir mostra como essas informações aparecem no arquivo `awsiotdevicetester_report.xml`.
```
```
Os recursos marcados como não `optional` são necessários para validação. Os seguintes trechos mostram recursos opcionais.
```
```
## Esquema do relatório do pacote de teste
O relatório `suite-name_Result.xml` está no [formato JUnit XML](https://llg.cubic.org/docs/junit/). Você pode integrá-lo em plataformas de integração e implantação como [Jenkins](https://jenkins.io/), [Bamboo](https://www.atlassian.com/software/bamboo) e assim por diante. O relatório contém um resumo agregado dos resultados de teste.
```
reason
reason
reason
```
A seção de relatório tanto em `awsiotdevicetester_report.xml` como em `suite-name_report.xml` lista os testes que foram executados e os resultados.
A primeira tag XML `` contém o resumo da execução do teste. Por exemplo:
```
```recursos usados na tag ``
`name`
O nome do conjunto de testes.
`time`
O tempo, em segundos, necessário para executar o pacote de teste.
`tests`
O número de testes executados.
`failures`
O número de testes que foram executados, mas não foram aprovados.
`errors`
O número de testes que não puderam ser executados pelo IDT.
`disabled`
Esse recurso não é usado e pode ser ignorado.
Se houver falhas de teste ou erros, você poderá identificar o teste com falha analisando as tags XML ``. As tags XML `` dentro da tag `` mostram o resumo do resultado do teste para um grupo de testes. Por exemplo:
```
```
O formato é semelhante à tag ``, mas com um recurso `skipped` que não é usado e pode ser ignorado. Dentro de cada tag XML ``, há tags `` para cada teste executado para um grupo de testes. Por exemplo:
```
>
```recursos usados na tag ``
`name`
O nome do teste.
`attempts`
O número de vezes que o IDT executou o caso de teste.
Quando um teste falha ou ocorre um erro, as tags `` ou `` são adicionadas à tag `` com informações para a solução de problemas. Por exemplo:
```
Reason for the test failure
Reason for the test execution error
```
# Métricas de uso do IDT
Se você fornecer AWS credenciais com as permissões necessárias, AWS IoT Device Tester coletará e enviará métricas de uso para. AWS Este é um recurso opcional e é usado para melhorar a funcionalidade do IDT. O IDT coleta informações como as seguintes:
+ O Conta da AWS ID usado para executar o IDT
+ Os AWS CLI comandos IDT usados para executar testes
+ Os pacotes de teste que são executados
+ As suítes de teste na ** pasta
+ O número de dispositivos configurados no grupo de dispositivos
+ Nomes de casos de teste e tempos de execução
+ Informações do resultado do teste, como se os testes foram aprovados, falharam, encontraram erros ou foram ignorados
+ recursos testados do produto
+ Comportamento de saída do IDT, como saídas inesperadas ou antecipadas
Todas as informações enviadas pelo IDT também são registradas em um arquivo `metrics.log` na pasta `/results//`. Você pode visualizar o arquivo de log para ver as informações que foram coletadas durante a execução de um teste. Este arquivo é gerado somente se optar por coletar métricas de uso.
Para desativar a coleta de métricas, não é necessário tomar nenhuma outra medida. Simplesmente não armazene suas AWS credenciais e, se você tiver AWS credenciais armazenadas, não configure o `config.json` arquivo para acessá-las.
## Configure suas AWS credenciais
Se você ainda não tem um Conta da AWS, você deve [criar um](#idt-metrics-aws-account). Se você já tem uma Conta da AWS, basta [configurar as permissões necessárias](#idt-metrics-permissions) para sua conta, permitindo que a IDT envie métricas de uso AWS em seu nome.
### Etapa 1: criar um Conta da AWS
Nesta etapa, crie e configure uma Conta da AWS. Se você já tem uma Conta da AWS, pule para [Etapa 2: Configurar permissões para o IDT](#idt-metrics-permissions).
Se você não tiver um Conta da AWS, conclua as etapas a seguir para criar um.
**Para se inscrever em um Conta da AWS**
1. Abra a [https://portal.aws.amazon.com/billing/inscrição.](https://portal.aws.amazon.com/billing/signup)
1. Siga as instruções online.
Parte do procedimento de inscrição envolve receber uma chamada telefônica ou uma mensagem de texto e inserir um código de verificação pelo teclado do telefone.
Quando você se inscreve em um Conta da AWS, um *Usuário raiz da conta da AWS*é criado. O usuário-raiz tem acesso a todos os Serviços da AWS e recursos na conta. Como prática recomendada de segurança, atribua o acesso administrativo a um usuário e use somente o usuário-raiz para executar [tarefas que exigem acesso de usuário-raiz](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_root-user.html#root-user-tasks).
Para criar um usuário administrador, selecione uma das opções a seguir.
****
| Selecionar uma forma de gerenciar o administrador | Para | Por | Você também pode |
| --- | --- | --- | --- |
| Centro de Identidade do IAM (Recomendado) | Usar credenciais de curto prazo para acessar a AWS.Isso está de acordo com as práticas recomendadas de segurança. Para obter informações sobre as práticas recomendadas, consulte [Práticas recomendadas de segurança no IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#bp-users-federation-idp) no *Guia do usuário do IAM*. | Seguindo as instruções em [Conceitos básicos](https://docs.aws.amazon.com//singlesignon/latest/userguide/getting-started.html) no Guia do usuário do Centro de Identidade do AWS IAM . | Configure o acesso programático [configurando o AWS CLI para uso Centro de Identidade do AWS IAM](https://docs.aws.amazon.com//cli/latest/userguide/cli-configure-sso.html) no Guia do AWS Command Line Interface usuário. |
| No IAM (Não recomendado) | Usar credenciais de longo prazo para acessar a AWS. | Seguindo as instruções em [Criar um acesso de emergência para um usuário do IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/getting-started-emergency-iam-user.html) no Guia do usuário do IAM. | Configurar o acesso programático, com base em [Gerenciar chaves de acesso para usuários do IAM](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_credentials_access-keys.html) no Guia do usuário do IAM. |
### Etapa 2: Configurar permissões para o IDT
Nesta etapa, configure as permissões que o IDT para executar testes e coletar dados de uso do IDT. Você pode usar o Console de gerenciamento da AWS or AWS Command Line Interface (AWS CLI) para criar uma política do IAM e um usuário para o IDT e, em seguida, anexar políticas ao usuário.
+ [Para configurar permissões para IDT (Console)](#idt-metrics-permissions-console)
+ [Para configurar permissões para o IDT (AWS CLI)](#idt-metrics-permissions-cli)
**Como configurar permissões para o IDT (console)**
Siga estas etapas para usar o console para configurar permissões para IDT para AWS IoT Greengrass.
1. [Faça login no console do IAM](https://console.aws.amazon.com/iam).
1. Crie uma política gerenciada pelo cliente que conceda permissões para criar funções com permissões específicas.
1. No painel de navegação, selecione **Políticas** e, em seguida, **Criar política**.
1. Na guia **JSON**, substitua o conteúdo do espaço reservado pela política a seguir.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot-device-tester:SendMetrics"
],
"Resource": "*"
}
]
}
```
------
1. Escolha **Review policy (Revisar política)**.
1. Em **Name (Nome)**, insira **IDTUsageMetricsIAMPermissions**. Em **Summary (Resumo)**, revise as permissões concedidas pela política.
1. Escolha **Create policy (Criar política)**.
1. Crie um usuário do IAM e anexe permissões ao usuário.
1. Criar um usuário do IAM. Siga as etapas de 1 a 5 em [Criando usuários do IAM (console)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html#id_users_create_console) no *Guia do usuário do IAM*. Se você já tiver criado um usuário do IAM, vá para a próxima etapa.
1. Anexe as permissões ao usuário do IAM:
1. Na página **Set permissions (Definir permissões)**, selecione **Attach existing policies to user directly (Anexar políticas existentes diretamente ao usuário)**.
1. Pesquise a IAMPermissions política de **IDTUsagemétricas** que você criou na etapa anterior. Marque a caixa de seleção.
1. Selecione **Next: Tags (Próximo: tags)**.
1. Selecione **Next: Review (Próximo: revisar)** para exibir um resumo das suas escolhas.
1. Selecione **Criar usuário**.
1. Para visualizar as chaves de acesso do usuário (chave de acesso IDs e chaves de acesso secretas), escolha **Mostrar** ao lado da senha e da chave de acesso. Para salvar as chaves de acesso, selecione **Download.csv (Fazer download do .csv)** e salve o arquivo em um local seguro. Você usa essas informações posteriormente para configurar seu arquivo de AWS credenciais.
**Como configurar permissões para o IDT (AWS CLI)**
Siga estas etapas para usar o AWS CLI para configurar as permissões do IDT para AWS IoT Greengrass.
1. No seu computador, instale e configure o, AWS CLI se ainda não estiver instalado. Siga as etapas em [Installing the (Instalando a) AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-install.html) no *Guia do usuário do AWS Command Line Interface *.
**nota**
AWS CLI É uma ferramenta de código aberto que você pode usar para interagir com AWS serviços do seu shell de linha de comando.
1. Crie a seguinte política gerenciada pelo cliente que concede permissões para gerenciar IDT e AWS IoT Greengrass funções.
------
#### [ Linux or Unix ]
```
aws iam create-policy --policy-name IDTUsageMetricsIAMPermissions --policy-document '{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot-device-tester:SendMetrics"
],
"Resource": "*"
}
]
}'
```
------
#### [ Windows command prompt ]
```
aws iam create-policy --policy-name IDTUsageMetricsIAMPermissions --policy-document
'{\"Version\": \"2012-10-17\", \"Statement\": [{\"Effect\": \"Allow\", \"Action\": [\"iot-device-tester:SendMetrics\"], \"Resource": \"*\"}]}'
```
**nota**
Esta etapa inclui um exemplo de prompt de comando do Windows porque ele usa uma sintaxe JSON diferente dos comandos de terminal Linux, macOS ou Unix.
------
#### [ PowerShell ]
```
aws iam create-policy --policy-name IDTUsageMetricsIAMPermissions --policy-document '{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot-device-tester:SendMetrics"
],
"Resource": "*"
}
]
}'
```
------
1. Crie um usuário do IAM e anexe as permissões exigidas pelo IDT para o AWS IoT Greengrass.
1. Criar um usuário do IAM.
```
aws iam create-user --user-name user-name
```
1. Anexe a política de `IDTUsageMetricsIAMPermissions` criada para o novo usuário do IAM. *user-name*Substitua pelo nome de usuário do IAM e, ** no comando, pelo ID do seu Conta da AWS.
```
aws iam attach-user-policy --user-name user-name --policy-arn arn:aws:iam:::policy/IDTGreengrassIAMPermissions
```
1. Crie uma chave de acesso secreta para o usuário.
```
aws iam create-access-key --user-name user-name
```
Armazene a saída em um local seguro. Você usa essas informações posteriormente para configurar seu arquivo de AWS credenciais.
## Forneça AWS credenciais ao IDT
Para permitir que o IDT acesse suas AWS credenciais e envie métricas para AWS, faça o seguinte:
1. Armazene as AWS credenciais do seu usuário do IAM como variáveis de ambiente ou em um arquivo de credenciais:
1. Para usar as variáveis de ambiente, execute os comandos a seguir.
------
#### [ Linux or Unix ]
```
export AWS_ACCESS_KEY_ID=access-key
export AWS_SECRET_ACCESS_KEY=secret-access-key
```
------
#### [ Windows Command Prompt (CMD) ]
```
set AWS_ACCESS_KEY_ID=access-key
set AWS_SECRET_ACCESS_KEY=secret-access-key
```
------
#### [ PowerShell ]
```
$env:AWS_ACCESS_KEY_ID="access-key"
$env:AWS_SECRET_ACCESS_KEY="secret-access-key"
```
------
1. Para o arquivo de credenciais, adicione as seguintes informações para o arquivo `~/.aws/credentials`.
```
[profile-name]
aws_access_key_id=access-key
aws_secret_access_key=secret-access-key
```
1. Configure a seção `auth` do arquivo `config.json`. Para obter mais informações, consulte [(Opcional) Configurar config.json](set-custom-idt-config.md#config-json-custom).