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á.
# Testando máquinas de estado com TestState API
**nota**
A partir de novembro de 2025, a TestState API inclui aprimoramentos que permitem criar testes de unidade automatizados para seus fluxos de trabalho do AWS Step Functions. Esses aprimoramentos estão disponíveis por meio AWS CLI de e. SDKs Principais aprimoramentos adicionados:
Simule integrações AWS de serviços ou serviços invocados por meio do estado de tarefa HTTP para testar a lógica do estado sem chamar o serviço real
Teste estados avançados, como mapas, paralelos e estados de atividade, com respostas simuladas
Controle o contexto de execução para testar tentativas específicas de repetição, mapear posições de iteração e cenários de erro
## Visão geral do
Você pode testar um [estado compatível](https://docs.aws.amazon.com/step-functions/latest/dg/test-state-isolation.html#supported-test-states) usando o TestState recurso no Step Functions console ou no SDK. AWSCommand Line Interface (AWS CLI)
A [TestState](https://docs.aws.amazon.com/step-functions/latest/apireference/API_TestState.html)API aceita a definição de um estado e a executa. Ele permite testar um estado sem criar uma máquina de estado ou atualizar uma máquina de estado existente. Você pode fornecer:
+ Uma definição de estado único
+ Uma definição completa da máquina de estado com `stateName` parâmetro
A `TestState` API assume uma IAM função que deve conter IAM as permissões necessárias para os recursos que seu estado acessa. Quando você especifica uma simulação, especificar a função se torna opcional, permitindo testar a lógica da máquina de estado sem configurar IAM permissões. Para obter informações sobre as permissões necessárias a um estado, consulte [IAMpermissões para usar a TestState API](#test-state-permissions).
**Tópicos**
+ [Usando níveis de inspeção na TestState API](#how-test-state-works)
+ [IAMpermissões para usar a TestState API](#test-state-permissions)
+ [Testando um estado usando o console AWS Step Functions](#test-state-console)
+ [Testando um estado usando AWS CLI](#test-state-cli)
+ [Testar e depurar o fluxo de dados de entrada e de saída.](#test-state-input-output-dataflow)
+ [O que você pode testar e afirmar com a API TestState](#what-you-can-test-assert)
+ [Simulando integrações de serviços](#mocking-service-integrations)
+ [Mapa de teste e estados paralelos](#testing-map-parallel-states)
+ [Atividade de teste, .sync e. waitForTaskEstados do token](#testing-activity-sync-waitfortasktoken)
+ [Iterando por meio de definições de máquina de estado](#iterating-through-state-machine-definitions)
+ [Usando o campo de contexto na TestState API](#using-context-field)
+ [Tentativa de teste e tratamento de erros](#testing-retry-error-handling)
## Usando níveis de inspeção na TestState API
Ao testar um estado usando a [TestState](https://docs.aws.amazon.com/step-functions/latest/apireference/API_TestState.html)API, você pode especificar a quantidade de detalhes que deseja visualizar nos resultados do teste. Por exemplo, se você usou filtros de processamento de dados de entrada e saída, como [`InputPath`](input-output-inputpath-params.md#input-output-inputpath)ou [`ResultPath`](input-output-resultpath.md), você pode visualizar os resultados intermediários e finais do processamento de dados. Step Functionsfornece os seguintes níveis de inspeção:
+ [INFO](#test-state-info-level)
+ [DEBUG](#test-state-debug-level)
+ [TRACE](#test-state-trace-level)
Todos esses níveis também exibem os campos `status` e `nextState`. O `status` indica o status da execução do estado. Por exemplo, `SUCCEEDED`, `FAILED`, `RETRIABLE` e `CAUGHT_ERROR`. `nextState` indica o nome do próximo estado para o qual fazer a transição. Se você não definiu o próximo estado na definição, esse campo exibirá um valor vazio.
Para obter informações sobre como testar um estado usando esses níveis de inspeção no console do Step Functions e na AWS CLI, consulte [Testando um estado usando o console AWS Step Functions](#test-state-console) e [Testando um estado usando AWS CLI](#test-state-cli).
### Nível de inspeção INFO
Se o teste for bem-sucedido, esse nível mostrará a saída do estado. Se o teste falhar, esse nível mostrará a saída do erro. Por padrão, o Step Functions define o **Nível de inspeção** como **INFO** se você não especificar um nível.
#### Exemplo de teste com o nível INFO bem-sucedido
A imagem a seguir mostra um teste bem-sucedido para um estado Aprovado. O **Nível de inspeção** desse estado é definido como **INFO** e a saída do estado é exibida na guia **Saída**.
#### Exemplo de teste com o nível INFO com falha
A imagem a seguir mostra um teste que falhou em um estado de Tarefa quando o **Nível de inspeção** está definido como **INFO**. A guia **Saída** mostra a saída do erro que inclui o nome e uma explicação detalhada da causa desse erro.
### Nível de inspeção DEBUG
Se o teste for bem-sucedido, esse nível mostrará a saída do estado e o resultado do processamento dos dados de entrada e de saída.
Se o teste falhar, esse nível mostrará a saída do erro. Esse nível mostra os resultados intermediários do processamento de dados até o ponto de falha. Por exemplo, digamos que você testou um estado de Tarefa que invoque uma função do Lambda. Imagine que você tenha aplicado os filtros [InputPath](input-output-inputpath-params.md#input-output-inputpath), [Parâmetros](input-output-inputpath-params.md#input-output-parameters), [Especificando a saída de estado usando ResultPath em Step Functions](input-output-resultpath.md) e [Filtrar a saída de estado usando OutputPath](input-output-example.md#input-output-outputpath) ao estado de Tarefa. Digamos que a invocação tenha falhado. Nesse caso, o nível `DEBUG` mostra os resultados do processamento de dados com base na aplicação dos filtros na seguinte ordem:
+ `input`: entrada de estado bruto.
+ `afterInputPath`: entrada após o Step Functions aplicar o filtro `InputPath`.
+ `afterParameters`: a entrada efetiva após o Step Functions aplicar o filtro `Parameters`.
As informações de diagnóstico disponíveis nesse nível podem ajudar a solucionar problemas relacionados a uma [integração de serviços](integrate-services.md) ou ao fluxo de [processamento de dados de entrada e de saída](#test-state-input-output-dataflow) definido.
#### Exemplo de teste com nível DEBUG bem-sucedido
A imagem a seguir mostra um teste bem-sucedido para um estado Aprovado. O **Nível de inspeção** para esse estado é definido como **DEBUG**. A guia **Processamento de entrada/saída** na imagem a seguir mostra o resultado da aplicação de [`Parameters`](input-output-inputpath-params.md#input-output-parameters) na entrada fornecida para esse estado.
#### Exemplo de teste com o nível DEBUG com falha
A imagem a seguir mostra um teste que falhou em um estado de Tarefa quando o **Nível de inspeção** está definido como **DEBUG**. A guia **Processamento de entrada/saída** na imagem a seguir mostra o resultado do processamento de dados de entrada e de saída para o estado até o ponto da falha.
### Nível de inspeção TRACE
O Step Functions oferece o nível **TRACE** para testar uma [tarefa HTTP](call-https-apis.md). Esse nível retorna informações sobre a solicitação HTTP feita pelo Step Functions e a resposta que uma API HTTPS exibe. A resposta pode conter informações, como cabeçalhos e corpo da solicitação. Além disso, é possível visualizar a saída do estado e o resultado do processamento de dados de entrada e de saída nesse nível.
Se o teste falhar, esse nível mostrará a saída do erro.
Esse nível é aplicável somente para tarefas HTTP. O Step Functions vai gerar um erro se você usar esse nível para outros tipos de estado.
Ao definir o **nível de inspeção** como **TRACE**, você também pode visualizar os segredos incluídos na [EventBridge conexão](call-https-apis.md#http-task-authentication). Para fazer isso, você deve definir o `revealSecrets` parâmetro como `true` na [TestState](https://docs.aws.amazon.com/step-functions/latest/apireference/API_TestState.html)API. Além disso, você deve garantir que o IAM usuário que chama a TestState API tenha permissão para a `states:RevealSecrets` ação. Para ver um exemplo de política do IAM que concede a permissão `states:RevealSecrets`, consulte [IAMpermissões para usar a TestState API](#test-state-permissions). Sem essa permissão, o Step Functions gera um erro de acesso negado.
Se você definir o parâmetro `revealSecrets` como `false`, o Step Functions omitirá todos os segredos nos dados de solicitação e resposta HTTP. Observe que você não pode usar `revealSecrets` quando a simulação está ativada. Se você especificar ambos `revealSecrets` e uma simulação na solicitação da TestState API, Step Functions retornará uma exceção de validação.
#### Exemplo de teste com o nível TRACE bem-sucedido
A imagem a seguir mostra um teste bem-sucedido para uma tarefa HTTP. O **Nível de inspeção** para esse estado é definido como **TRACE**. A guia **Solicitação e resposta HTTP** na imagem a seguir mostra o resultado da chamada de API HTTPS.
## IAMpermissões para usar a TestState API
O IAM usuário que chama a `TestState` API precisa ter permissão para realizar a `states:TestState` ação. Quando você não está usando simulação, o IAM usuário também deve ter permissão para realizar a `iam:PassRole` ação para a qual passar a Step Functions função de execução. Além disso, se você definir o `revealSecrets` parâmetro como`true`, o IAM usuário deverá ter permissão para realizar a `states:RevealSecrets` ação. Sem essa permissão, o Step Functions gera um erro de acesso negado.
Observe que, ao especificar uma simulação na solicitação da TestState API, você pode testar a lógica da máquina de estado sem fornecer uma função de execução (veja mais detalhes em [Simulação de integrações de serviços](#mocking-service-integrations)). Quando não estiver usando simulações, você deve fornecer uma função de execução que contenha as permissões necessárias para os recursos que seu estado acessa. Para obter informações sobre as permissões que o estado pode precisar, consulte [Gerenciar perfis de execução](manage-state-machine-permissions.md).
## Testando um estado usando o console AWS Step Functions
É possível testar um estado no console e conferir a saída do estado ou o fluxo de processamento de dados de entrada e de saída. Para uma [tarefa HTTP](call-https-apis.md), é possível testar a solicitação e a resposta HTTP brutas.
**nota**
O TestState recurso do console ainda não oferece suporte a alguns dos aprimoramentos descritos neste documento, como simulação de integrações de serviços, teste de estados de mapa e paralelo ou Activity, .sync e. waitForTaskPadrões de token. Atualmente, esses recursos estão disponíveis somente por meio da TestState API usando o AWS CLI ou SDK.
**Como testar um estado**
1. Abra o [console do Step Functions](https://console.aws.amazon.com/states/home?region=us-east-1#/).
1. Selecione **Criar uma máquina de estado** para começar a criar uma máquina de estado ou escolha uma máquina de estado existente.
1. No [Modo de design](workflow-studio.md#wfs-interface-design-mode) do Workflow Studio, selecione um estado que deseja testar.
1. Escolha **o estado do teste** no [Painel Inspetor](workflow-studio.md#workflow-studio-components-formdefinition) Workflow Studio.
1. Na caixa de diálogo **Testar estado**, faça o seguinte:
1. Em **Perfil de execução**, selecione um perfil de execução para testar o estado. Tenha as [permissões do IAM](#test-state-permissions) necessárias para o estado que deseja testar.
1. (Opcional) Forneça todas as entradas JSON de que o estado selecionado precise para o teste.
1. Em **Nível de inspeção**, selecione uma das seguintes opções com base nos valores que você deseja visualizar:
+ [INFO](#test-state-info-level): mostrará a saída do estado na guia **Saída** se o teste for bem-sucedido. Se o teste falhar, **INFO** mostrará a saída do erro que inclui o nome e uma explicação detalhada da causa desse erro. Por padrão, o Step Functions definirá o **Nível de inspeção** como **INFO** se você não especificar um nível.
+ [DEBUG](#test-state-debug-level): mostrará a saída do estado e o resultado do processamento dos dados de entrada e de saída se o teste for bem-sucedido. Se o teste falhar, **DEBUG** mostrará a saída do erro que inclui o nome e uma explicação detalhada da causa desse erro.
+ [TRACE](#test-state-trace-level): mostra a solicitação e a resposta HTTP brutas e é útil para verificar cabeçalhos, parâmetros de consulta e outros detalhes específicos da API. Essa opção só está disponível para a [tarefa HTTP](call-https-apis.md).
Também é possível selecionar **Revelar segredos**. Em combinação com **TRACE**, essa configuração permite que você veja os dados confidenciais que a conexão com o EventBridge insere, como chaves de API. A identidade do usuário do IAM que você usa para acessar o console deve ter permissão para realizar a ação `states:RevealSecrets`. Sem essa permissão, o Step Functions gera um erro de acesso negado ao iniciar o teste. Para ver um exemplo de política do IAM que concede essas permissões `states:RevealSecrets`, consulte [IAMpermissões para usar a TestState API](#test-state-permissions).
1. Selecione **Iniciar teste**.
## Testando um estado usando AWS CLI
Você pode testar um estado usando a [TestState](https://docs.aws.amazon.com/step-functions/latest/apireference/API_TestState.html)API noAWS CLI. A API aceita a definição de um estado e a executa.
Para cada estado, é possível especificar a quantidade de detalhes que você deseja visualizar nos resultados do teste. Esses detalhes fornecem informações adicionais sobre a execução do estado, incluindo o resultado do processamento de dados de entrada e de saída e as informações de solicitação e resposta HTTP. Os exemplos a seguir mostram os diferentes níveis de inspeção que você pode especificar para a TestState API.
Esta seção contém os seguintes exemplos que descrevem como usar os diferentes níveis de inspeção fornecidos pelo Step Functions na AWS CLI:
+ [Usar o nível de inspeção INFO](#test-info-level-cli)
+ [Usar o nível de inspeção DEBUG](#test-debug-level-cli)
+ [Usar o nível de inspeção TRACE](#test-trace-level-cli)
+ [Usando o utilitário jq in AWS CLI para filtrar e imprimir a resposta HTTP que a TestState API retorna](#cli-readable-output)
### Exemplo 1: Usar o nível de inspeção INFO para testar um estado de escolha
Para testar um estado usando o `INFO` [InspectionLevel](https://docs.aws.amazon.com/step-functions/latest/apireference/API_TestState.html#StepFunctions-TestState-request-inspectionLevel) noAWS CLI, execute o `test-state` comando conforme mostrado no exemplo a seguir.
```
aws stepfunctions test-state \
--definition '{"Type": "Choice", "Choices": [{"Variable": "$.number", "NumericEquals": 1, "Next": "Equals 1"}, {"Variable": "$.number", "NumericEquals": 2, "Next": "Equals 2"}], "Default": "No Match"}' \
--role-arn arn:aws:iam::{{account-id}}:role/{{myRole}} \
--input '{"number": 2}'
```
Este exemplo usa um estado de [escolha](state-choice.md) para determinar o caminho de execução do estado com base na entrada numérica fornecida. Por padrão, o Step Functions definirá o `inspectionLevel` como `INFO` se você não definir um nível.
O Step Functions exibe a saída a seguir.
```
{
"output": "{\"number\": 2}",
"nextState": "Equals 2",
"status": "SUCCEEDED"
}
```
### Exemplo 2: Usar o Nível de inspeção DEBUG para depurar o processamento de dados de entrada e de saída em um estado Aprovado
Para testar um estado usando o `DEBUG` [InspectionLevel](https://docs.aws.amazon.com/step-functions/latest/apireference/API_TestState.html#StepFunctions-TestState-request-inspectionLevel) noAWS CLI, execute o `test-state` comando conforme mostrado no exemplo a seguir.
```
aws stepfunctions test-state \
--definition '{"Type": "Pass", "InputPath": "$.payload", "Parameters": {"data": 1}, "ResultPath": "$.result", "OutputPath": "$.result.data", "Next": "Another State"}' \
--role-arn arn:aws:iam::{{account-id}}:role/{{myRole}} \
--input '{"payload": {"foo": "bar"}}' \
--inspection-level DEBUG
```
Este exemplo usa um estado [Estado de passagem do fluxo de trabalho](state-pass.md) para mostrar como o Step Functions filtra e manipula os dados JSON de entrada usando os filtros de processamento de dados de entrada e de saída. Este exemplo usa estes filtros: `InputPath`, `Parâmetros`, `Especificando a saída de estado usando ResultPath em Step Functions` e `Filtrar a saída de estado usando OutputPath`.
O Step Functions exibe a saída a seguir.
```
{
"output": "1",
"inspectionData": {
"input": "{\"payload\": {\"foo\": \"bar\"}}",
"afterInputPath": "{\"foo\":\"bar\"}",
"afterParameters": "{\"data\":1}",
"afterResultSelector": "{\"data\":1}",
"afterResultPath": "{\"payload\":{\"foo\":\"bar\"},\"result\":{\"data\":1}}"
},
"nextState": "Another State",
"status": "SUCCEEDED"
}
```
### Exemplo 3: usar o TRACE inspectionLevel e revealSecrets para inspecionar a solicitação HTTP enviada a uma API HTTPS
Para testar uma [tarefa HTTP](call-https-apis.md) usando o `TRACE` [InspectionLevel](https://docs.aws.amazon.com/step-functions/latest/apireference/API_TestState.html#StepFunctions-TestState-request-inspectionLevel) junto com o parâmetro [revealSecrets](https://docs.aws.amazon.com/step-functions/latest/apireference/API_TestState.html#StepFunctions-TestState-request-revealSecrets) noAWS CLI, execute o `test-state` comando conforme mostrado no exemplo a seguir.
```
aws stepfunctions test-state \
--definition '{"Type": "Task", "Resource": "arn:aws:states:::http:invoke", "Parameters": {"Method": "GET", "Authentication": {"ConnectionArn": "arn:aws:events:{{region}}:{{account-id}}:connection/{{MyConnection/0000000-0000-0000-0000-000000000000"}}}, "ApiEndpoint": "https://httpbin.org/get", "Headers": {"definitionHeader": "h1"}, "RequestBody": {"message": "Hello from Step Functions!"}, "QueryParameters": {"queryParam": "q1"}}, "End": true}' \
--role-arn arn:aws:iam::{{account-id}}:role/{{myRole}} \
--inspection-level TRACE \
--reveal-secrets
```
Este exemplo testa se a tarefa HTTP chama a API HTTPS especificada, `https://httpbin.org/`. Ele também mostra os dados de solicitação e resposta HTTP para a chamada de API.
Step Functionsretorna uma saída semelhante ao exemplo original na documentação atual.
### Exemplo 4: Usando o utilitário jq para filtrar e imprimir a resposta que a TestState API retorna
A TestState API retorna dados JSON como sequências de caracteres de escape em sua resposta. O AWS CLI exemplo a seguir estende o [Exemplo 3](#test-trace-level-cli) e usa o `jq` utilitário para filtrar e imprimir a resposta HTTP que a TestState API retorna em um formato legível por humanos. Para obter informações `jq` e instruções de instalação, consulte [jq](https://stedolan.github.io/jq/) on *GitHub*.
```
aws stepfunctions test-state \
--definition '{"Type": "Task", "Resource": "arn:aws:states:::http:invoke", "Parameters": {"Method": "GET", "Authentication": {"ConnectionArn": "arn:aws:events:{{region}}:{{account-id}}:connection/{{MyConnection/0000000-0000-0000-0000-000000000000"}}}, "ApiEndpoint": "https://httpbin.org/get", "Headers": {"definitionHeader": "h1"}, "RequestBody": {"message": "Hello from Step Functions!"}, "QueryParameters": {"queryParam": "q1"}}, "End": true}' \
--role-arn arn:aws:iam::{{account-id}}:role/{{myRole}} \
--inspection-level TRACE \
--reveal-secrets \
| jq '.inspectionData.response.body | fromjson'
```
O exemplo a seguir mostra a saída exibida em formato legível.
```
{
"args": {
{{"QueryParam1": "QueryParamValue1",
"queryParam": "q1"}}
},
"headers": {
"Authorization": "Basic XXXXXXXX",
"Content-Type": "application/json; charset=UTF-8",
"Customheader1": "CustomHeaderValue1",
"Definitionheader": "h1",
"Host": "httpbin.org",
"Range": "bytes=0-262144",
"Transfer-Encoding": "chunked",
"User-Agent": "Amazon|StepFunctions|HttpInvoke|{{region}}",
"X-Amzn-Trace-Id": "Root=1-0000000-0000-0000-0000-000000000000"
},
"origin": "{{12.34.567.891}}",
"url": "{{https://httpbin.org/get?queryParam=q1&QueryParam1=QueryParamValue1}}"
}
```
## Testar e depurar o fluxo de dados de entrada e de saída.
A API `TestState` é útil para testar e depurar os dados que fluem pelo fluxo de trabalho. Esta seção fornece alguns conceitos-chave e explica como usar o TestState para essa finalidade.
### Principais conceitos
No Step Functions, o processo de filtrar e manipular dados JSON à medida que eles passam pelos estados na máquina de estado é chamado de *processamento de entrada e de saída*. Para obter informações sobre como isso funciona, consulte [Processar entrada e saída no Step Functions](concepts-input-output-filtering.md).
Todos os tipos de [estado](workflow-states.md) no [Amazon States Language](concepts-amazon-states-language.md) (ASL) (Tarefa, Paralelo, Mapa, Aprovar, Aguardar, Escolha, Êxito e Falha) compartilham um conjunto de campos comuns para filtrar e manipular os dados JSON que passam por eles. Esses campos são: [InputPath](input-output-inputpath-params.md#input-output-inputpath), [Parâmetros](input-output-inputpath-params.md#input-output-parameters), [ResultSelector](input-output-inputpath-params.md#input-output-resultselector), [Especificando a saída de estado usando ResultPath em Step Functions](input-output-resultpath.md) e [Filtrar a saída de estado usando OutputPath](input-output-example.md#input-output-outputpath). O suporte para cada campo [varia de acordo com os estados](https://states-language.net/spec.html#state-type-table). Em runtime, o Step Functions aplica cada campo em uma ordem específica. O diagrama a seguir mostra a ordem na qual esses campos são aplicados aos dados em um estado de Tarefa:
A lista a seguir descreve a ordem de aplicação dos campos de processamento de entrada e de saída mostrados no diagrama.
1. A *entrada de estado* são os dados JSON transmitidos para o estado atual a partir de um estado anterior.
1. O [InputPath](input-output-inputpath-params.md#input-output-inputpath) filtra uma parte da entrada de estado bruto.
1. O [Parâmetros](input-output-inputpath-params.md#input-output-parameters) configura o conjunto de valores a serem passados para a [Tarefa](state-task.md).
1. A tarefa executa o trabalho e exibe um resultado.
1. O [ResultSelector](input-output-inputpath-params.md#input-output-resultselector) seleciona um conjunto de valores a ser excluído do resultado da tarefa.
1. O [Especificando a saída de estado usando ResultPath em Step Functions](input-output-resultpath.md) combina o resultado com a entrada de estado bruto ou substitui o resultado por ela.
1. O [Filtrar a saída de estado usando OutputPath](input-output-example.md#input-output-outputpath) filtra uma parte da saída para passar para o próximo estado.
1. A *entrada de estado* são os dados JSON transmitidos do estado atual para o próximo estado.
Esses campos de processamento de entrada e de saída são opcionais. Se você não usar nenhum desses campos em sua definição de estado, a tarefa consumirá a entrada do estado bruto e retornará o resultado da tarefa como a saída do estado.
### Usando TestState para inspecionar o processamento de entrada e saída
Ao chamar a API `TestState` e definir o parâmetro `inspectionLevel` como `DEBUG`, a resposta da API incluirá um objeto chamado `inspectionData`. Esse objeto contém campos para ajudar a inspecionar como os dados foram filtrados ou manipulados no estado durante a execução. O exemplo a seguir mostra o objeto `inspectionData` para o estado de Tarefa.
```
"inspectionData": {
"input": string,
"afterInputPath": string,
"afterParameters": string,
"result": string,
"afterResultSelector": string,
"afterResultPath": string,
"output": string
}
```
Neste exemplo, cada campo que contém o prefixo `after` mostra os dados após a aplicação de um campo específico. Por exemplo, `afterInputPath` mostra o efeito da aplicação do campo `InputPath` para filtrar a entrada de estado bruto. O diagrama a seguir associa cada campo [Definição de ASL](concepts-amazon-states-language.md) ao campo correspondente no objeto `inspectionData`:
Para exemplos de uso da TestState API para depurar o processamento de entrada e saída, consulte o seguinte:
+ [Testar um estado usando o nível de inspeção DEBUG no console do Step Functions](#test-state-debug-level)
+ [Testando um estado usando o nível de inspeção DEBUG no AWS CLI](#test-debug-level-cli)
Especificamente para o estado do Mapa, quando `inspectionLevel` está definido como`DEBUG`, o `inspectionData` objeto inclui campos adicionais que ajudam você a inspecionar como o estado do Mapa extrai e transforma itens. Você pode aprender mais sobre esses campos na seção [Compreendendo os dados de inspeção do estado do Mapa](#understanding-map-inspection-data).
### Compreendendo os dados de inspeção do estado do mapa
Quando você testa um estado do Mapa com `inspectionLevel` definido como`DEBUG`, a resposta da TestState API inclui campos adicionais no `inspectionData` objeto que mostram como o estado do Mapa processa os dados:
**nota**
`afterItemsPath`só é preenchido quando usado JSONPath como linguagem de consulta.
+ `afterItemsPath`(String) — A entrada efetiva após a aplicação do ItemsPath filtro. Isso mostra a matriz de itens extraídos da sua entrada.
+ `afterItemsPointer`(String) — A entrada efetiva após a aplicação do ItemsPointer filtro. Isso só se aplica às entradas JSON (não JSONata).
+ `afterItemSelector`(Array of Strings) — Uma matriz contendo os valores de entrada após a aplicação da ItemSelector transformação. Cada elemento na matriz representa um item transformado. Esse campo só está presente ao testar um estado do Mapa.
+ `afterItemBatcher`(Matriz de cadeias de caracteres) — Uma matriz contendo os valores de entrada após a aplicação do ItemBatcher agrupamento. Isso mostra como os itens são agrupados em lotes. Esse campo só está presente ao testar um estado do Mapa.
+ `toleratedFailureCount`(Número) — O limite de falha tolerado para um estado do Mapa expresso como uma contagem de iterações do estado do Mapa. Esse valor é derivado do valor especificado em ToleratedFailureCount ou do valor avaliado em tempo de execução de ToleratedFailureCountPath.
+ `toleratedFailurePercentage`(Número) — O limite de falha tolerado para um estado do Mapa expresso como uma porcentagem das iterações do estado do Mapa. Esse valor é derivado do valor especificado em ToleratedFailurePercentage ou do valor avaliado em tempo de execução de ToleratedFailurePercentagePath.
+ `maxConcurrency`(Número) — A configuração máxima de simultaneidade do estado do Mapa.
Esses campos permitem que você valide se as transformações de dados e as configurações de tolerância a falhas do seu estado do Mapa funcionam corretamente antes da implantação.
## O que você pode testar e afirmar com a API TestState
A TestState API permite que você escreva testes de unidade abrangentes para suas máquinas de estado. Você pode afirmar sobre vários aspectos da lógica da sua máquina de estados, incluindo o seguinte:
+ [Tratamento de erros: qual captura ou nova tentativa se aplica](#error-handling-catch-retry)
+ [Transformações de dados: processamento de entrada e saída](#data-transformations-assert)
+ [Transformações de estado do mapa: ItemSelector,, ItemsPath, ItemBatcher ItemsPointer](#map-state-transformations-assert)
+ [Mapeie os limites de falha do estado: estados de teste. ExceedToleratedFailureThreshold](#map-failure-thresholds-assert)
+ [Propagação de erros nos estados Mapa e Paralelo](#error-propagation-assert)
### Tratamento de erros: qual captura ou nova tentativa se aplica
Ao simular um erro, você pode usar a TestState API para ver qual manipulador de erros é ativado.
Para blocos Catch, você pode afirmar:
+ Qual manipulador Catch detecta o erro (via `catchIndex` na resposta)
+ Qual será o próximo estado (via `nextState` na resposta)
+ Quais dados fluem para o manipulador de erros (via `output` na resposta, considerando ResultPath)
Para blocos de repetição, você pode afirmar:
+ Qual nova tentativa se aplica (via `retryIndex` na resposta)
+ Qual é a duração do recuo (via `retryBackoffIntervalSeconds` na resposta)
+ Se as novas tentativas foram esgotadas e o erro foi detectado
### Transformações de dados: processamento de entrada e saída
Usando a TestState API, você pode validar como seus dados de estado são transformados em cada estágio do processamento.
Você pode afirmar sobre:
+ Entrada após o InputPath filtro (`afterInputPath`)
+ Dados após a Parameters/Arguments transformação (`afterParameters`ou`afterArguments`)
+ Resultado após ResultSelector (`afterResultSelector`)
+ Saída após ResultPath (`afterResultPath`)
+ Saída final após OutputPath (`output`)
### Transformações de estado do mapa: ItemSelector,, ItemsPath, ItemBatcher ItemsPointer
Para estados do mapa, você pode usar a TestState API para ver como os itens são extraídos e transformados.
Você pode afirmar sobre:
+ Itens após o ItemsPath filtro (`afterItemsPath`)
+ Itens após o ItemsPointer filtro (`afterItemsPointer`)
+ Itens após ItemSelector a transformação (`afterItemSelector`)
+ Itens após o ItemBatcher agrupamento () `afterItemBatcher`
### Mapeie os limites de falha do estado: estados de teste. ExceedToleratedFailureThreshold
Teste se um número específico de iterações com falha aciona o limite de falha tolerado.
Você pode afirmar sobre:
+ Se o estado do Mapa falha com os Estados. ExceedToleratedFailureThreshold
### Propagação de erros nos estados Mapa e Paralelo
Ao testar estados nos estados Map ou Parallel, os erros se propagam para os manipuladores de erros do estado pai da mesma forma que fariam em uma execução real.
#### Especificando a fonte de erro com o estado errorCausedBy
Ao simular erros para os estados Mapa ou Paralelo, você deve especificar qual subestado causou o erro usando o `stateConfiguration.errorCausedByState` parâmetro. Isso é particularmente importante ao testar erros curinga, como`States.TaskFailed`. `States.TaskFailed`é um erro curinga que se aplica a qualquer falha no estado da tarefa. Para testar como seu estado de Mapa ou Paralelo lida com esse erro, você precisa identificar o subestado específico que o gerou. Veja o exemplo abaixo:
```
aws stepfunctions test-state \
--definition '{...Map or Parallel state definition...}' \
--input '[...]' \
--state-configuration '{"errorCausedByState": "ProcessItem"}' \
--mock '{"errorOutput": {"error": "States.TaskFailed", "cause": "Task execution failed"}}'
```
Neste exemplo, `errorCausedByState` informa TestState que o estado "ProcessItem" dentro do Map/Parallel fluxo de trabalho gerou o erro. Os manipuladores Catch or Retry do Map/Parallel estado pai processarão o erro da mesma forma que fariam durante a execução real. O `nextState` campo na resposta mostra qual manipulador de erros detectou o erro. Você pode afirmar sobre:
+ Se os erros do estado filho são detectados pelos manipuladores do Catch dos pais
+ Se os erros do estado secundário acionam as políticas de repetição dos pais
+ Qual é o próximo estado após a propagação do erro
## Simulando integrações de serviços
A TestState API oferece suporte à simulação dos resultados das integrações de serviços, permitindo que você teste a lógica da máquina de estado sem invocar serviços reais. AWS
### Quando usar a zombaria
A zombaria é útil para:
+ Definições de máquina de estado de teste unitário isoladamente
+ Testando o tratamento de erros e a lógica de repetição
+ Validando transformações de dados de entrada e saída
+ Simulação de várias respostas de serviço e condições de erro
+ Testando sem configurar permissões IAM
Quando você especifica uma simulação, o `roleArn` parâmetro se torna opcional, permitindo que você se concentre em testar sua definição de máquina de estado sem lidar com problemas relacionados a permissões.
**nota**
A simulação é necessária se você precisar testar os seguintes tipos de estado ou padrões de integração de serviços: Map, Parallel, Activity, integrações de serviços.sync e integrações de serviços waitForTask Token.
### Sintaxe básica de simulação
Para simular um resultado de integração de serviços:
```
aws stepfunctions test-state \
--definition '{
"Type": "Task",
"Resource": "arn:aws:states:::lambda:invoke",
"Arguments": {
"FunctionName": "MyFunction",
"Payload.$": "$"
},
"End": true
}' \
--input '{"key": "value"}' \
--mock '{"result": "{\"Payload\": {\"statusCode\": 200, \"body\": \"Success\"}}"}'
```
Para simular um erro:
```
aws stepfunctions test-state \
--definition '{
"Type": "Task",
"Resource": "arn:aws:states:::lambda:invoke",
"Arguments": {...},
"End": true
}' \
--input '{"key": "value"}' \
--mock '{"errorOutput": {"error": "Lambda.ServiceException", "cause": "Service unavailable"}}'
```
**nota**
Você não pode fornecer os dois `mock.result` e `mock.errorOutput` na mesma chamada de API. Isso resulta em uma exceção de validação.
### Modos de validação simulados
A TestState API valida respostas simuladas em relação aos modelos de API AWS de serviço para garantir a exatidão. Você pode controlar o comportamento de validação usando o `fieldValidationMode` parâmetro:
+ **STRICT (padrão)** — impõe restrições de nomenclatura, tamanho, forma e tipo de dados de campos dos modelos de API. AWS Todos os campos obrigatórios devem estar presentes com os tipos corretos. Esse modo ajuda a garantir que suas simulações representem com precisão as respostas reais do serviço.
+ **PRESENTE** — Valida somente os campos que estão presentes na simulação. Campos desconhecidos são ignorados. Esse modo é útil quando você deseja flexibilidade, mas ainda deseja validação em campos conhecidos.
+ **NENHUM** — Ignora totalmente a validação. Use com cuidado, pois isso pode levar a suposições e comportamentos de teste incorretos que diferem das execuções reais.
**nota**
A validação é realizada somente em campos definidos no modelo AWS de API de serviço. Todos os campos não especificados no modelo da API são ignorados durante a validação, independentemente do modo de validação. Por exemplo, se estiver usando o modo STRICT para uma API que não define campos “Obrigatórios”, uma resposta simulada vazia passará pela validação.
Exemplo com modo de validação:
```
aws stepfunctions test-state \
--definition '{
"Type": "Task",
"Resource": "arn:aws:states:::dynamodb:putItem",
"Parameters": {...},
"End": true
}' \
--input '{"key": "value"}' \
--mock '{"fieldValidationMode": "STRICT", "result": "{\"Attributes\": {...}}"}'
```
**Importante**
A validação simulada não é compatível com as RunJob integrações [HTTP Task](call-https-apis.md), API Gateway, EKS Call e EKS.
## Mapa de teste e estados paralelos
A TestState API oferece suporte ao teste de estados Map e Parallel quando uma simulação é especificada. Isso permite testar o processamento de entrada e saída desses estados de fluxo.
### Entendendo o teste de estado do mapa
Ao testar um estado do Mapa com a TestState API, você está testando o processamento de entrada e saída do estado do Mapa sem executar as iterações internas. Essa abordagem permite que você teste:
+ ItemsPath ou ItemsPointer extração da entrada
+ ItemSelector transformação aplicada a cada item
+ ItemBatcher agrupamento (se especificado)
+ O processamento de saída do estado do Mapa (ResultPath, OutputPath)
+ Limites de falha tolerados
Você não está testando o que acontece dentro do ItemProcessor (os estados que processam cada item).
### Testando um estado do mapa
Ao testar um estado do Mapa, o resultado simulado deve representar a saída de todo o estado do Mapa. O resultado da simulação deve ser uma matriz JSON ou objeto JSON válido, dependendo da configuração do estado do mapa. Veja o exemplo abaixo:
```
aws stepfunctions test-state \
--definition '{
"Type": "Map",
"ItemsPath": "$.items",
"ItemSelector": {
"value.$": "$$.Map.Item.Value",
"index.$": "$$.Map.Item.Index"
},
"ItemProcessor": {
"ProcessorConfig": {"Mode": "INLINE"},
"StartAt": "ProcessItem",
"States": {
"ProcessItem": {
"Type": "Task",
"Resource": "arn:aws:states:::lambda:invoke",
"End": true
}
}
},
"End": true
}' \
--input '{"items": [1, 2, 3, 4, 5]}' \
--mock '{"result": "[10, 20, 30, 40, 50]"}' \
--inspection-level DEBUG
```
### Testando estados de mapas distribuídos
Os estados do mapa distribuído são testados de forma semelhante aos estados do mapa embutido. Quando seu mapa usa um ItemReader para ler do S3, forneça os dados diretamente na entrada (como se já tivessem sido lidos do S3). Por exemplo:
```
aws stepfunctions test-state \
--definition '{
"Type": "Map",
"ItemReader": {
"Resource": "arn:aws:states:::s3:getObject",
"Parameters": {
"Bucket": "my-bucket",
"Key": "orders.json"
}
},
"ItemsPath": "$.orders",
"ItemProcessor": {
"ProcessorConfig": {"Mode": "DISTRIBUTED"},
...
},
"ToleratedFailureCount": 5,
"End": true
}' \
--input '{
"orders": [
{"orderId": "123"},
{"orderId": "456"},
{"orderId": "789"}
]
}' \
--mock '{"result": "..."}'
```
**nota**
Ao testar o estado do Mapa Distribuído (Modo definido como DISTRIBUÍDO), você também pode afirmar em mapIterationFailure Contagem. O valor desse campo não pode exceder o número de itens na entrada ou ser igual ao número de itens ao testar um estado em um Mapa.
### Preenchimento automático de contexto
Ao testar um estado dentro de um estado do Mapa (usando o `stateName` parâmetro) sem fornecer um `context` parâmetro, preenche TestState automaticamente o objeto Context com valores padrão. Isso inclui campos de contexto específicos do mapa, como:
+ `$$.Map.Item.Index`= `0` (primeira iteração)
+ `$$.Map.Item.Value`= seu valor de entrada
+ `$$.Map.Item.Key`(para mapas distribuídos com determinadas ItemReader configurações)
+ `$$.Map.Item.Source`(para mapas distribuídos, indicando a origem do item)
### Testando estados paralelos
Ao testar um estado paralelo, o resultado simulado deve ser uma matriz JSON com um elemento para cada ramificação, na mesma ordem em que as ramificações aparecem na definição.
## Atividade de teste, .sync e. waitForTaskEstados do token
A TestState API é compatível com testes de estados de atividade, padrões de integração de serviços.sync e. waitForTaskPadrões de token quando uma simulação é especificada. Sem uma simulação, invocar esses estados por meio da TestState API retornará uma exceção de validação.
**nota**
Para testar integrações de .sync usando a TestState API, a resposta simulada é validada em relação ao esquema da API de pesquisa. Por exemplo, ao testar`startExecution.sync:2`, sua simulação deve corresponder ao esquema de `DescribeExecution` resposta (que Step Functions pesquisa o status), não à resposta. `StartExecution`
## Iterando por meio de definições de máquina de estado
Você pode fornecer uma definição completa da máquina de estado para a TestState API e especificar qual estado testar usando o `stateName` parâmetro. Isso permite que você teste esse estado específico dentro do contexto de sua máquina de estado completa. Você também pode encadear testes usando a saída e o nextState de um teste como entrada para o próximo. Isso permite testar caminhos de execução parciais ou completos em sua máquina de estado.
## Usando o campo de contexto na TestState API
O `context` parâmetro permite que você forneça valores para o objeto Context que normalmente seriam preenchidos durante a execução. Isso é útil para testar estados que fazem referência a valores de contexto, como ID de execução, nome do estado ou hora inserida. O exemplo abaixo demonstra como você pode usar o objeto Context na sua chamada de TestState API:
```
aws stepfunctions test-state \
--definition '{
"Type": "Task",
"Resource": "arn:aws:states:::lambda:invoke",
"Arguments": {
"FunctionName": "MyFunction",
"Payload": {
"executionId.$": "$$.Execution.Id",
"stateName.$": "$$.State.Name",
"enteredTime.$": "$$.State.EnteredTime"
}
},
"End": true
}' \
--input '{"data": "value"}' \
--context '{
"Execution": {
"Id": "arn:aws:states:us-east-1:123456789012:execution:MyStateMachine:test-exec-123",
"Name": "test-exec-123",
"StartTime": "2024-01-01T10:00:00.000Z"
},
"State": {
"Name": "ProcessData",
"EnteredTime": "2024-01-01T10:00:05.000Z"
}
}' \
--mock '{"result": "{\"status\": \"success\"}"}'
```
## Tentativa de teste e tratamento de erros
A TestState API permite simular cenários de repetição e testar a lógica de tratamento de erros especificando tentativas de repetição e erros de simulação.
### Simulando tentativas de repetição
```
aws stepfunctions test-state \
--definition '{
"Type": "Task",
"Resource": "arn:aws:states:::lambda:invoke",
"Arguments": {...},
"Retry": [{
"ErrorEquals": ["Lambda.ServiceException"],
"IntervalSeconds": 2,
"MaxAttempts": 3,
"BackoffRate": 2.0
}],
"End": true
}' \
--input '{"data": "value"}' \
--state-configuration '{"retrierRetryCount": 1}' \
--mock '{"errorOutput": {"error": "Lambda.ServiceException", "cause": "Service error"}}' \
--inspection-level DEBUG
```
A resposta inclui detalhes do erro nos dados de inspeção:
```
{
"status": "RETRIABLE",
"inspectionData": {
"errorDetails": {
"retryBackoffIntervalSeconds": 4,
"retryIndex": 0
}
}
}
```
Essa resposta indica:
+ O erro é recuperável (status: RECUPERÁVEL)
+ A duração do recuo é de 4 segundos (2 × 2,0^1)
+ A primeira tentativa (índice 0) se aplica
### Testando manipuladores de catch
Quando um erro é simulado e corresponde a um manipulador Catch, o `nextState` campo na resposta da TestState API indica qual estado tratará o erro. No exemplo abaixo:
Para a solicitação de TestState API fornecida abaixo,
```
aws stepfunctions test-state \
--definition '{
"Type": "Task",
"Resource": "arn:aws:states:::lambda:invoke",
"Arguments": {...},
"Catch": [{
"ErrorEquals": ["Lambda.TooManyRequestsException"],
"ResultPath": "$.error",
"Next": "HandleThrottling"
}],
"Next": "Success"
}' \
--input '{"data": "value"}' \
--mock '{"errorOutput": {"error": "Lambda.TooManyRequestsException", "cause": "Rate exceeded"}}' \
--inspection-level DEBUG
```
A resposta esperada da API deve ser:
```
{
"status": "CAUGHT_ERROR",
"nextState": "HandleThrottling",
"error": "Lambda.TooManyRequestsException",
"cause": "Rate exceeded",
"output": "{\"data\": \"value\", \"error\": {\"Error\": \"Lambda.TooManyRequestsException\", \"Cause\": \"Rate exceeded\"}}",
"inspectionData": {
"errorDetails": {
"catchIndex": 0
}
}
}
```
Essa resposta indica que:
+ o erro foi detectado (status: CAUGHT\_ERROR)
+ o próximo estado é HandleThrottling
+ as informações de erro são adicionadas à saída via ResultPath
+ o primeiro manipulador Catch (índice 0) detectou o erro
Você também pode testar o que acontece quando todas as tentativas de repetição se esgotam aumentando RetryCount os valores em seu objeto de contexto.