Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.
# Probar máquinas de estado con TestState API
**nota**
A partir de noviembre de 2025, la TestState API incluye mejoras que le permiten crear pruebas unitarias automatizadas para sus flujos de trabajo de AWS Step Functions. Estas mejoras están disponibles en AWS CLI y SDKs. Mejoras clave agregadas:
Simule las integraciones de servicios o los servicios invocados mediante el estado de la tarea HTTP para probar la lógica del estado sin llamar al AWS servicio real
Pruebe estados avanzados como los estados de mapa, paralelo y actividad con respuestas simuladas
Controle el contexto de ejecución para probar reintentos específicos, posiciones de iteración del mapa y escenarios de error
## Descripción general de
Puede probar un [estado compatible](https://docs.aws.amazon.com/step-functions/latest/dg/test-state-isolation.html#supported-test-states) mediante la TestState función de la Step Functions consola o AWSCommand Line Interface (AWS CLI) el SDK.
La [TestState](https://docs.aws.amazon.com/step-functions/latest/apireference/API_TestState.html)API acepta la definición de un estado y la ejecuta. Le permite probar un estado sin crear una máquina de estados ni actualizar una máquina de estados existente. Puede proporcionar:
+ Una definición de estado único
+ Una definición completa de la máquina de estados con `stateName` parámetros
La `TestState` API asume una IAM función que debe contener los IAM permisos necesarios para los recursos a los que accede su estado. Cuando especificas un simulacro, especificar el rol pasa a ser opcional, lo que te permite probar la lógica de la máquina de estados sin configurar IAM los permisos. Para obtener información acerca de los permisos que podría necesitar un estado, consulte [IAMpermisos para usar la TestState API](#test-state-permissions).
**Temas**
+ [Uso de niveles de inspección en la TestState API](#how-test-state-works)
+ [IAMpermisos para usar la TestState API](#test-state-permissions)
+ [Prueba de un estado mediante la consola AWS Step Functions](#test-state-console)
+ [Probar un estado usando AWS CLI](#test-state-cli)
+ [Prueba y depuración del flujo de datos de entrada y de salida](#test-state-input-output-dataflow)
+ [Qué puede probar y comprobar con la TestState API](#what-you-can-test-assert)
+ [Simulación de las integraciones de servicios](#mocking-service-integrations)
+ [Probar los estados de mapa y paralelo](#testing-map-parallel-states)
+ [Actividad de prueba, .sync y. waitForTaskEstados simbólicos](#testing-activity-sync-waitfortasktoken)
+ [Repasando en iteraciones las definiciones de las máquinas de estados](#iterating-through-state-machine-definitions)
+ [Uso del campo de contexto en la TestState API](#using-context-field)
+ [Probar, reintentos y manejo de errores](#testing-retry-error-handling)
## Uso de niveles de inspección en la TestState API
Al probar un estado mediante la [TestState](https://docs.aws.amazon.com/step-functions/latest/apireference/API_TestState.html)API, puede especificar la cantidad de detalles que desea ver en los resultados de la prueba. Por ejemplo, si has utilizado filtros de procesamiento de datos de entrada y salida, como [`InputPath`](input-output-inputpath-params.md#input-output-inputpath)o [`ResultPath`](input-output-resultpath.md), puedes ver los resultados del procesamiento de datos intermedio y final. Step Functionsproporciona los siguientes niveles de inspección:
+ [INFO](#test-state-info-level)
+ [DEBUG](#test-state-debug-level)
+ [TRACE](#test-state-trace-level)
Todos estos niveles también devuelven los campos `status` y `nextState`. `status` indica el estado de la ejecución de estado. Por ejemplo, `SUCCEEDED`, `FAILED`, `RETRIABLE` y `CAUGHT_ERROR`. `nextState` indica el nombre del siguiente estado al que se realizará la transición. Si no ha definido un estado siguiente en la definición, este campo devuelve un valor vacío.
Para obtener información sobre cómo probar un estado mediante estos niveles de inspección en la consola de Step Functions y AWS CLI, consulte [Prueba de un estado mediante la consola AWS Step Functions](#test-state-console) y [Probar un estado usando AWS CLI](#test-state-cli).
### INFO inspectionLevel
Si la prueba se realiza correctamente, este nivel muestra la salida de estado. Si la prueba falla, este nivel muestra la salida de error. De forma predeterminada, Step Functions establece **Nivel de inspección** en **INFO** si no se especifica ningún nivel.
#### Ejemplo de prueba con nivel INFO que produce un resultado correcto
En la siguiente imagen se muestra una prueba para un estado Aprobado que se ha realizado correctamente. El **Nivel de inspección** de este estado se estable en **INFO** y el resultado del estado aparece en la pestaña **Salida**.
#### Ejemplo de prueba con nivel INFO con error
La siguiente imagen muestra una prueba que falló para un estado Tarea cuando el **Nivel de inspección** se establece en **INFO**. La pestaña **Salida** muestra la salida de error, que incluye el nombre del error y una explicación detallada de la causa del error.
### DEBUG inspectionLevel
Si la prueba se realiza correctamente, este nivel muestra la salida de estado y el resultado del procesamiento de datos de entrada y salida.
Si la prueba falla, este nivel muestra la salida de error. Este nivel muestra los resultados intermedios del procesamiento de datos hasta el punto de error. Por ejemplo, supongamos que probó un estado Tarea que invoca una función de Lambda. Supongamos que había aplicado los filtros [InputPath](input-output-inputpath-params.md#input-output-inputpath), [Parameters](input-output-inputpath-params.md#input-output-parameters), [Especificación de la salida de estado mediante ResultPath Step Functions](input-output-resultpath.md) y [Filtrado de la salida de estado mediante OutputPath](input-output-example.md#input-output-outputpath) al estado Tarea. Supongamos que la invocación ha producido error. En este caso, el nivel `DEBUG` muestra los resultados del procesamiento de datos en función de la aplicación de los filtros en el siguiente orden:
+ `input`: entrada de estado sin procesar
+ `afterInputPath`: la entrada después de Step Functions aplica el filtro `InputPath`.
+ `afterParameters`: la entrada efectiva después de Step Functions aplica el filtro `Parameters`.
La información de diagnóstico disponible en este nivel puede ayudar a solucionar problemas relacionados con un flujo de [integración de servicios](integrate-services.md) o de [procesamiento de datos de entrada y salida](#test-state-input-output-dataflow) que haya definido.
#### Ejemplo de prueba con nivel DEBUG que produce un resultado correcto
En la siguiente imagen se muestra una prueba para un estado Aprobado que se ha realizado correctamente. El **Nivel de inspección** de este estado se establece en **DEBUG**. La pestaña **Procesamiento de entrada/salida** de la imagen siguiente muestra el resultado de la aplicación de [`Parameters`](input-output-inputpath-params.md#input-output-parameters) a la entrada proporcionada para este estado.
#### Ejemplo de prueba con nivel DEBUG con error
La siguiente imagen muestra una prueba que falló para un estado Tarea cuando el **Nivel de inspección** se establece en **DEBUG**. La pestaña **Procesamiento de entrada/salida** de la imagen siguiente muestra el resultado del procesamiento de los datos de entrada y salida del estado hasta el punto de error.
### TRACE inspectionLevel
Step Functions proporciona el nivel **TRACE** para probar una [Tarea HTTP](call-https-apis.md). Este nivel devuelve información sobre la solicitud HTTP que Step Functions realiza y la respuesta que devuelve una API de HTTPS. La respuesta puede contener información, como los encabezados y el cuerpo de la solicitud. Además, puede ver la salida del estado y el resultado del procesamiento de datos de entrada y salida en este nivel.
Si la prueba falla, este nivel muestra la salida de error.
Este nivel solo es aplicable para una tarea HTTP. Step Functions presenta un error si utiliza este nivel para otros tipos de estado.
Al establecer el **nivel de inspección** en **TRACE**, también puede ver los secretos incluidos en la [EventBridge conexión](call-https-apis.md#http-task-authentication). Para ello, debe configurar el `revealSecrets` parámetro `true` en la [TestState](https://docs.aws.amazon.com/step-functions/latest/apireference/API_TestState.html)API. Además, debes asegurarte de que el IAM usuario que llama a la TestState API tiene permiso para realizar la `states:RevealSecrets` acción. Para ver una política de IAM de ejemplo que establece el permiso `states:RevealSecrets`, consulte [IAMpermisos para usar la TestState API](#test-state-permissions). Sin este permiso, Step Functions produce un error de acceso denegado.
Si establece el parámetro `revealSecrets` en `false`, Step Functions omite todos los secretos de los datos de solicitud y respuesta HTTP. Ten en cuenta que no puedes utilizarla `revealSecrets` cuando la simulación está habilitada. Si especificas ambos elementos `revealSecrets` y un simulacro en la solicitud de TestState API, Step Functions devuelve una excepción de validación.
#### Ejemplo de prueba con nivel TRACE que produce un resultado correcto
En la siguiente imagen se muestra una prueba para una tarea HTTP que se ha realizado correctamente. El **Nivel de inspección** de este estado se establece en **TRACE**. La pestaña **Solicitud y respuesta HTTP** de la siguiente imagen muestra el resultado de la llamada a la API de HTTPS.
## IAMpermisos para usar la TestState API
El IAM usuario que llama a la `TestState` API debe tener permiso para realizar la `states:TestState` acción. Cuando no utilices la función de simulación, el IAM usuario también debe tener permiso para realizar la `iam:PassRole` acción a la que transferirá la función de ejecución. Step Functions Además, si establece el `revealSecrets` parámetro en`true`, el IAM usuario debe tener permiso para realizar la `states:RevealSecrets` acción. Sin este permiso, Step Functions produce un error de acceso denegado.
Ten en cuenta que, si especificas un simulacro en la solicitud de TestState API, puedes probar la lógica de tu máquina de estados sin asignar una función de ejecución (consulta más información en la sección sobre [integraciones de servicios de Mocking](#mocking-service-integrations)). Cuando no utilices simulaciones, debes proporcionar una función de ejecución que contenga los permisos necesarios para los recursos a los que accede tu estado. Para obtener información acerca de los permisos que podría necesitar su estado, consulte [Administración de roles de ejecución](manage-state-machine-permissions.md).
## Prueba de un estado mediante la consola AWS Step Functions
Puede probar un estado en la consola y comprobar la salida del estado o el flujo de procesamiento de datos de entrada y salida. En el caso de una [Tarea HTTP](call-https-apis.md), puede probar la solicitud y la respuesta HTTP sin procesar.
**nota**
La TestState función de consola aún no admite algunas de las mejoras descritas en este documento, como simular las integraciones de servicios, probar los estados de Map y Parallel, o Activity, .sync y. waitForTaskPatrones simbólicos. Actualmente, estas capacidades solo están disponibles a través de la TestState API que utiliza el AWS CLI o el SDK.
**Para probar un estado**
1. Abra la [consola de Step Functions](https://console.aws.amazon.com/states/home?region=us-east-1#/).
1. Seleccione **Crear máquina de estado** para empezar a crear una máquina de estado o elija una máquina de estado existente.
1. En el [Modo Diseño](workflow-studio.md#wfs-interface-design-mode) de Workflow Studio, elija un estado que desea probar.
1. Elija **el estado [Panel del inspector](workflow-studio.md#workflow-studio-components-formdefinition) de prueba** en Workflow Studio.
1. En el cuadro de diálogo **Probar estado**, haga lo siguiente:
1. En **Rol de ejecución**, elija un rol de ejecución para probar el estado. Asegúrese de que cuenta con los [permisos de IAM](#test-state-permissions) necesarios para el estado que desea probar.
1. (Opcional) Proporcione cualquier entrada JSON que necesite el estado seleccionado para la prueba.
1. En **Nivel de inspección**, seleccione una de las siguientes opciones en función de los valores que desee ver:
+ [INFO](#test-state-info-level): muestra la salida del estado en la pestaña **Salida** si la prueba se realiza correctamente. Si la prueba produce error, **INFO** muestra la salida de error, que incluye el nombre del error y una explicación detallada de la causa del error. De forma predeterminada, Step Functions establece **Nivel de inspección** en **INFO** si no se selecciona ningún nivel.
+ [DEBUG](#test-state-debug-level): muestra la salida de estado y el resultado del procesamiento de datos de entrada y salida si la prueba se realiza correctamente. Si la prueba produce error, **DEBUG** muestra la salida de error, que incluye el nombre del error y una explicación detallada de la causa del error.
+ [TRACE](#test-state-trace-level): muestra la solicitud y la respuesta HTTP sin procesar y es útil para verificar encabezados, parámetros de consulta y otros detalles específicos de la API. Esta opción solo está disponible para la [Tarea HTTP](call-https-apis.md).
Si lo desea, puede seleccionar **Revelar secretos**. En combinación con **TRACE**, esta configuración permite ver los datos confidenciales que inserta la conexión de EventBridge, como claves de API. La identidad del usuario de IAM que utilice para acceder a la consola debe tener permiso para realizar la acción `states:RevealSecrets`. Sin este permiso, Step Functions produce un error de acceso denegado al iniciar la prueba. Para ver una política de IAM de ejemplo que establece el permiso `states:RevealSecrets`, consulte [IAMpermisos para usar la TestState API](#test-state-permissions).
1. Seleccione **Iniciar prueba**.
## Probar un estado usando AWS CLI
Puede probar un estado mediante la [TestState](https://docs.aws.amazon.com/step-functions/latest/apireference/API_TestState.html)API delAWS CLI. La API acepta la definición de un estado y la ejecuta.
Para cada estado, puede especificar la cantidad de detalles que desea ver en los resultados de la prueba. Estos detalles proporcionan información adicional sobre la ejecución del estado, incluido el resultado del procesamiento de datos de entrada y salida y la información de solicitud y respuesta HTTP. Los siguientes ejemplos muestran los diferentes niveles de inspección que puede especificar para la TestState API.
Esta sección contiene los siguientes ejemplos que describen cómo puede utilizar los diferentes niveles de inspección que Step Functions proporciona en AWS CLI:
+ [Uso de INFO inspectionLevel](#test-info-level-cli)
+ [Uso de DEBUG inspectionLevel](#test-debug-level-cli)
+ [Uso de TRACE inspectionLevel](#test-trace-level-cli)
+ [Uso de la utilidad jq AWS CLI para filtrar e imprimir la respuesta HTTP que devuelve la TestState API](#cli-readable-output)
### Ejemplo 1: Uso del InspectionLevel INFO para probar un estado Elección
Para probar un estado mediante el `INFO` [InspectionLevel](https://docs.aws.amazon.com/step-functions/latest/apireference/API_TestState.html#StepFunctions-TestState-request-inspectionLevel) delAWS CLI, ejecuta el `test-state` comando como se muestra en el siguiente ejemplo.
```
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}'
```
En este ejemplo se utiliza un estado [Elección](state-choice.md) para determinar la ruta de ejecución del estado en función de la entrada numérica que proporcione. De forma predeterminada, Step Functions establece el `inspectionLevel` en `INFO` si no se establece un nivel.
Step Functions devuelve la siguiente salida.
```
{
"output": "{\"number\": 2}",
"nextState": "Equals 2",
"status": "SUCCEEDED"
}
```
### Ejemplo 2: Uso del InspectionLevel DEBUG para depurar el procesamiento de datos de entrada y salida en un estado Aprobado
Para probar un estado mediante el `DEBUG` [InspectionLevel](https://docs.aws.amazon.com/step-functions/latest/apireference/API_TestState.html#StepFunctions-TestState-request-inspectionLevel) delAWS CLI, ejecute el `test-state` comando como se muestra en el siguiente ejemplo.
```
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
```
En este ejemplo se usa un estado [Estado Pass de un flujo de trabajo](state-pass.md) para mostrar cómo Step Functions filtra y manipula los datos JSON de entrada mediante los filtros de procesamiento de datos de entrada y salida. En este ejemplo se utilizan los siguientes filtros: `InputPath`, `Parameters`, `Especificación de la salida de estado mediante ResultPath Step Functions` y `Filtrado de la salida de estado mediante OutputPath`.
Step Functions devuelve la siguiente salida.
```
{
"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"
}
```
### Ejemplo 3: Uso del inspectionLevel TRACE y revealSecrets para inspeccionar la solicitud HTTP enviada a una API de HTTPS
Para probar una [tarea HTTP](call-https-apis.md) mediante el `TRACE` [InspectionLevel](https://docs.aws.amazon.com/step-functions/latest/apireference/API_TestState.html#StepFunctions-TestState-request-inspectionLevel) junto con el parámetro [RevealSecrets](https://docs.aws.amazon.com/step-functions/latest/apireference/API_TestState.html#StepFunctions-TestState-request-revealSecrets) delAWS CLI, ejecute el `test-state` comando como se muestra en el siguiente ejemplo.
```
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
```
En este ejemplo se comprueba si la tarea HTTP llama a la API de HTTPS especificada, `https://httpbin.org/`. También se muestran los datos de solicitud y respuesta HTTP de la llamada a la API.
Step Functionsdevuelve un resultado similar al ejemplo original de la documentación actual.
### Ejemplo 4: Uso de la utilidad jq para filtrar e imprimir la respuesta que devuelve la TestState API
La TestState API devuelve datos JSON como cadenas de escape en su respuesta. El siguiente AWS CLI ejemplo amplía el [ejemplo 3](#test-trace-level-cli) y utiliza la `jq` utilidad para filtrar e imprimir la respuesta HTTP que devuelve la TestState API en un formato legible para las personas. Para obtener información `jq` y sus instrucciones de instalación, consulte [jq on](https://stedolan.github.io/jq/). *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'
```
En el siguiente ejemplo se muestra la salida devuelta en un formato legible para las personas.
```
{
"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}}"
}
```
## Prueba y depuración del flujo de datos de entrada y de salida
La API `TestState` es útil para probar y depurar los datos que fluyen a través del flujo de trabajo. En esta sección se proporcionan algunos conceptos clave y se explica cómo utilizarlos TestState para este fin.
### Conceptos clave
En Step Functions, el proceso de filtrar y manipular datos JSON a medida que pasan por los estados de su máquina de estado se denomina *procesamiento de entrada y salida*. Para obtener información sobre cómo funciona, consulte [Procesamiento de entradas y salidas en Step Functions](concepts-input-output-filtering.md).
Todos los tipos de [estado](workflow-states.md) del [Amazon States Language](concepts-amazon-states-language.md) (ASL) (Tarea, Paralelo, Mapa, Aprobado, Esperar, Elección, Correcto y Error) comparten un conjunto de campos comunes para filtrar y manipular los datos JSON que pasan por ellos. Estos campos son: [InputPath](input-output-inputpath-params.md#input-output-inputpath), [Parameters](input-output-inputpath-params.md#input-output-parameters), [ResultSelector](input-output-inputpath-params.md#input-output-resultselector), [Especificación de la salida de estado mediante ResultPath Step Functions](input-output-resultpath.md) y [Filtrado de la salida de estado mediante OutputPath](input-output-example.md#input-output-outputpath). La compatibilidad de cada campo [varía según el estado](https://states-language.net/spec.html#state-type-table). En tiempo de ejecución, Step Functions aplica cada campo en un orden específico. El siguiente diagrama muestra el orden en el que se aplican estos campos a los datos en un estado Tarea:
La siguiente lista describe el orden de aplicación de los campos de procesamiento de entrada y salida que se muestran en el diagrama.
1. *Entrada de estado* son los datos JSON pasados al estado actual desde un estado anterior.
1. [InputPath](input-output-inputpath-params.md#input-output-inputpath) filtra una parte de la entrada de estado sin procesar.
1. [Parameters](input-output-inputpath-params.md#input-output-parameters) configura el conjunto de valores que se van a pasar a la [Tarea](state-task.md).
1. La tarea realiza un trabajo y devuelve un resultado.
1. [ResultSelector](input-output-inputpath-params.md#input-output-resultselector) selecciona un conjunto de valores para excluirlos del resultado de la tarea.
1. [Especificación de la salida de estado mediante ResultPath Step Functions](input-output-resultpath.md) combina el resultado con la entrada de estado sin procesar o reemplaza el resultado por ella.
1. [Filtrado de la salida de estado mediante OutputPath](input-output-example.md#input-output-outputpath) filtra una parte de la salida para pasarla al siguiente estado.
1. *Salida de estado* son los datos JSON pasados desde estado actual al siguiente estado.
Estos campos de procesamiento de entrada y de salida son opcionales. Si no utilizas ninguno de estos campos en la definición de estado, la tarea consumirá la entrada de estado sin procesar y devolverá el resultado de la tarea como salida de estado.
### Se utiliza TestState para inspeccionar el procesamiento de entrada y salida
Cuando llama a la API `TestState` y establece el parámetro `inspectionLevel` en `DEBUG`, la respuesta de la API incluye un objeto llamado `inspectionData`. Este objeto contiene campos que ayudan a inspeccionar cómo se filtraron o manipularon los datos en el estado cuando se ejecutaron. En el ejemplo siguiente se muestra el objeto `inspectionData` para un estado Tarea.
```
"inspectionData": {
"input": string,
"afterInputPath": string,
"afterParameters": string,
"result": string,
"afterResultSelector": string,
"afterResultPath": string,
"output": string
}
```
En este ejemplo, cada campo que contiene el prefijo `after` muestra los datos después de aplicar un campo concreto. Por ejemplo, `afterInputPath` muestra el efecto de aplicar el campo `InputPath` para filtrar la entrada de estado sin procesar. El siguiente diagrama asigna cada campo de [definición de ASL](concepts-amazon-states-language.md) a su campo correspondiente en el objeto `inspectionData`:
Para ver ejemplos del uso de la TestState API para depurar el procesamiento de entrada y salida, consulta lo siguiente:
+ [Probar un estado mediante el nivel de inspección DEBUG de la consola de Step Functions](#test-state-debug-level)
+ [Probar un estado mediante el nivel de inspección DEBUG en el AWS CLI](#test-debug-level-cli)
En lo que respecta específicamente al estado del mapa, cuando `inspectionLevel` se establece en`DEBUG`, el `inspectionData` objeto incluye campos adicionales que le ayudan a inspeccionar cómo el estado del mapa extrae y transforma los elementos. Puede obtener más información sobre estos campos en la sección [Descripción de los datos de inspección del estado del mapa](#understanding-map-inspection-data).
### Comprensión de los datos de inspección del estado del mapa
Cuando pruebas un estado del mapa con el valor `inspectionLevel` establecido en`DEBUG`, la respuesta de la TestState API incluye campos adicionales en el `inspectionData` objeto que muestran cómo el estado del mapa procesa los datos:
**nota**
`afterItemsPath`solo se rellena cuando se usa JSONPath como lenguaje de consulta.
+ `afterItemsPath`(Cadena): la entrada efectiva después de aplicar el ItemsPath filtro. Muestra el conjunto de elementos extraídos de la entrada.
+ `afterItemsPointer`(Cadena): la entrada efectiva después de aplicar el ItemsPointer filtro. Esto solo se aplica a las entradas JSON (no JSONata).
+ `afterItemSelector`(Matriz de cadenas): matriz que contiene los valores de entrada una vez aplicada la ItemSelector transformación. Cada elemento de la matriz representa un elemento transformado. Este campo solo está presente cuando se prueba un estado del mapa.
+ `afterItemBatcher`(Matriz de cadenas): matriz que contiene los valores de entrada una vez aplicada la ItemBatcher agrupación. Esto muestra cómo se agrupan los elementos en lotes. Este campo solo está presente cuando se prueba el estado de un mapa.
+ `toleratedFailureCount`(Número): el umbral de error tolerado para un estado del mapa expresado como un recuento de las iteraciones del estado del mapa. Este valor se deriva del valor especificado en ToleratedFailureCount o del valor desde el que se evaluó en tiempo de ToleratedFailureCountPath ejecución.
+ `toleratedFailurePercentage`(Número): el umbral de error tolerado para un estado del mapa expresado como un porcentaje de las iteraciones del estado del mapa. Este valor se deriva del valor especificado en ToleratedFailurePercentage o del valor evaluado en tiempo de ToleratedFailurePercentagePath ejecución.
+ `maxConcurrency`(Número): la configuración de simultaneidad máxima del estado del mapa.
Estos campos le permiten validar que las transformaciones de datos y las configuraciones de tolerancia a errores del estado del mapa funcionan correctamente antes del despliegue.
## Qué puede probar y comprobar con la TestState API
La TestState API le permite escribir pruebas unitarias completas para sus máquinas de estado. Puedes basarte en varios aspectos de la lógica de tu máquina de estados, incluidos los siguientes:
+ [Gestión de errores: ¿Qué captura o reintento se aplica](#error-handling-catch-retry)
+ [Transformaciones de datos: procesamiento de entrada y salida](#data-transformations-assert)
+ [Transformaciones de estado del mapa: ItemSelector, ItemsPath, ItemBatcher, ItemsPointer](#map-state-transformations-assert)
+ [Mapee los umbrales de error del estado: estados de prueba. ExceedToleratedFailureThreshold](#map-failure-thresholds-assert)
+ [Propagación de errores en estados de mapa y paralelo](#error-propagation-assert)
### Gestión de errores: ¿Qué captura o reintento se aplica
Cuando simulas un error, puedes usar la TestState API para ver qué controlador de errores se activa.
En el caso de los bloques Catch, puedes afirmar lo siguiente:
+ Qué controlador de Catch detecta el error (a través de `catchIndex` la respuesta)
+ ¿Cuál será el siguiente estado (a través de `nextState` la respuesta)
+ Qué datos fluyen al controlador de errores (a través de la respuesta, teniendo `output` ResultPath en cuenta)
En el caso de los bloques de reintento, puedes afirmar lo siguiente:
+ Qué reintento se aplica (a través de `retryIndex` la respuesta)
+ Cuál es la duración del retraso (a través de `retryBackoffIntervalSeconds` la respuesta)
+ Si los reintentos se han agotado y se ha detectado el error
### Transformaciones de datos: procesamiento de entrada y salida
Con la TestState API, puede validar cómo se transforman los datos de su estado en cada etapa del procesamiento.
Puede hacer valer lo siguiente:
+ Entrada después del InputPath filtro (`afterInputPath`)
+ Datos después de Parameters/Arguments la transformación (`afterParameters`o`afterArguments`)
+ Resultado después de ResultSelector (`afterResultSelector`)
+ Salida después de ResultPath (`afterResultPath`)
+ Salida final después de OutputPath (`output`)
### Transformaciones de estado del mapa: ItemSelector, ItemsPath, ItemBatcher, ItemsPointer
En el caso de los estados del mapa, puede usar la TestState API para ver cómo se extraen y transforman los elementos.
Puede hacer valer lo siguiente:
+ Elementos después del ItemsPath filtro (`afterItemsPath`)
+ Elementos después del ItemsPointer filtro (`afterItemsPointer`)
+ Elementos tras ItemSelector la transformación (`afterItemSelector`)
+ Elementos después de ItemBatcher agruparlos () `afterItemBatcher`
### Mapee los umbrales de error del estado: estados de prueba. ExceedToleratedFailureThreshold
Compruebe si un número específico de iteraciones fallidas activa el umbral de error tolerado.
Puede hacer valer lo siguiente:
+ Si el estado del mapa falla con los estados. ExceedToleratedFailureThreshold
### Propagación de errores en estados de mapa y paralelo
Al probar estados dentro de los estados de mapa o paralelo, los errores se propagan a los controladores de errores del estado principal tal como lo harían en una ejecución real.
#### Especificar el origen del error con State errorCausedBy
Al simular los errores de los estados de mapa o paralelo, debe especificar qué subestado causó el error mediante el `stateConfiguration.errorCausedByState` parámetro. Esto es especialmente importante cuando se prueban errores comodín como. `States.TaskFailed` `States.TaskFailed`es un error comodín que se aplica a cualquier error de estado de la tarea. Para comprobar cómo gestiona este error tu estado de mapa o paralelo, debes identificar el subestado específico que lo provocó. Consulta el ejemplo que aparece a continuación:
```
aws stepfunctions test-state \
--definition '{...Map or Parallel state definition...}' \
--input '[...]' \
--state-configuration '{"errorCausedByState": "ProcessItem"}' \
--mock '{"errorOutput": {"error": "States.TaskFailed", "cause": "Task execution failed"}}'
```
En este ejemplo, `errorCausedByState` indica TestState que el error se produjo por el estado ProcessItem «» del Map/Parallel flujo de trabajo. Los controladores Catch o Retry del Map/Parallel estado principal procesarán el error como lo harían durante la ejecución real. El `nextState` campo de la respuesta muestra qué controlador de errores detectó el error. Puede hacer valer lo siguiente:
+ Si los controladores de Catch principales detectan los errores de estado secundario
+ Si los errores de estado secundario activan las políticas de reintento principales
+ ¿Cuál es el siguiente estado tras la propagación del error
## Simulación de las integraciones de servicios
La TestState API permite simular los resultados de las integraciones de servicios, lo que le permite probar la lógica de su máquina de estados sin invocar servicios reales. AWS
### ¿Cuándo usar la burla
La burla es útil para:
+ Las pruebas unitarias indican las definiciones de las máquinas de forma aislada
+ Probar el manejo de errores y la lógica de reintentos
+ Validar las transformaciones de los datos de entrada y salida
+ Simulación de diversas respuestas de servicio y condiciones de error
+ Pruebas sin configurar IAM los permisos
Cuando especificas un simulacro, el `roleArn` parámetro pasa a ser opcional, lo que te permite centrarte en probar la definición de tu máquina de estados sin tener que lidiar con problemas relacionados con los permisos.
**nota**
La simulación es necesaria si necesita probar los siguientes tipos de estados o patrones de integración de servicios: integraciones de servicios Map, Parallel, Activity, .sync e integraciones de servicios Token. waitForTask
### Sintaxis de burla básica
Para simular el resultado de una integración de servicios:
```
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 un error:
```
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**
No puedes proporcionar ambos `mock.result` y `mock.errorOutput` en la misma llamada a la API. Esto da como resultado una excepción de validación.
### Modos de validación simulados
La TestState API valida las respuestas simuladas comparándolas con los modelos de API AWS de servicio para garantizar su exactitud. Puede controlar el comportamiento de validación mediante el parámetro: `fieldValidationMode`
+ **ESTRICTO (predeterminado)**: impone las restricciones de nombre, tamaño, forma y tipo de datos de los campos de los modelos de AWS API. Todos los campos obligatorios deben estar presentes con los tipos correctos. Este modo ayuda a garantizar que sus simulacros representen con precisión las respuestas reales del servicio.
+ **PRESENTE**: valida solo los campos que están presentes en el simulacro. Los campos desconocidos se ignoran. Este modo resulta útil cuando se desea flexibilidad pero se desea validar los campos conocidos.
+ **NINGUNO**: omite la validación por completo. Úselo con precaución, ya que esto puede provocar suposiciones de prueba incorrectas y un comportamiento diferente al de las ejecuciones reales.
**nota**
La validación se realiza solo en los campos definidos en el modelo AWS de API del servicio. Los campos no especificados en el modelo de API se ignoran durante la validación, independientemente del modo de validación. Por ejemplo, si utilizas el modo STRICT para una API que no define ningún campo «obligatorio», una respuesta simulada vacía pasará la validación.
Ejemplo con el modo de validación:
```
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**
La validación simulada no es compatible con las RunJob integraciones de [HTTP Task](call-https-apis.md), API Gateway, EKS Call y EKS.
## Probar los estados de mapa y paralelo
La TestState API permite probar los estados de mapa y paralelo cuando se especifica un simulacro. Esto le permite probar el procesamiento de entrada y salida de estos estados de flujo.
### Comprensión de las pruebas de estado del mapa
Cuando pruebas un estado del mapa con la TestState API, estás probando el procesamiento de entrada y salida del estado del mapa sin ejecutar las iteraciones internas. Este enfoque te permite probar:
+ ItemsPath o ItemsPointer extracción de la entrada
+ ItemSelector transformación aplicada a cada elemento
+ ItemBatcher agrupación (si se especifica)
+ El procesamiento de salida del estado del mapa (ResultPath, OutputPath)
+ Umbrales de errores tolerados
No estás probando lo que ocurre dentro de ItemProcessor (los estados que procesan cada elemento).
### Probando el estado de un mapa
Al probar un estado del mapa, el resultado simulado debe representar el resultado de todo el estado del mapa. El resultado simulado debe ser una matriz JSON válida o un objeto JSON, en función de la configuración del estado del mapa. Consulta el siguiente ejemplo:
```
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
```
### Probando los estados de los mapas distribuidos
Los estados del mapa distribuido se prueban de forma similar a los estados del mapa en línea. Cuando su mapa utilice una ItemReader para leer desde S3, proporcione los datos directamente en la entrada (como si ya se hubieran leído desde S3). Por ejemplo:
```
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**
Al probar el estado del mapa distribuido (el modo está establecido en DISTRIBUIDO), también puedes hacer una afirmación en mapIterationFailure Count. El valor de este campo no puede superar el número de elementos de la entrada ni ser igual al número de elementos al probar un estado dentro de un mapa.
### Población de contexto automática
Al probar un estado dentro de un estado del mapa (mediante el `stateName` parámetro) sin proporcionar ningún `context` parámetro, rellena TestState automáticamente el objeto de contexto con los valores predeterminados. Esto incluye campos de contexto específicos del mapa, como:
+ `$$.Map.Item.Index`= `0` (primera iteración)
+ `$$.Map.Item.Value`= su valor de entrada
+ `$$.Map.Item.Key`(para mapas distribuidos con determinadas ItemReader configuraciones)
+ `$$.Map.Item.Source`(en el caso de los mapas distribuidos, indique el origen del elemento)
### Probando estados paralelos
Al probar un estado paralelo, el resultado simulado debe ser una matriz JSON con un elemento para cada rama, en el mismo orden en que aparecen las ramas en la definición.
## Actividad de prueba, .sync y. waitForTaskEstados simbólicos
La TestState API permite probar los estados de actividad, los patrones de integración del servicio.sync y. waitForTaskPatrones de símbolos cuando se especifica un simulacro. Sin una simulación, la invocación de estos estados a través de la TestState API devolverá una excepción de validación.
**nota**
Para probar las integraciones de .sync mediante la TestState API, la respuesta simulada se valida con el esquema de la API de sondeo. Por ejemplo, al realizar una prueba`startExecution.sync:2`, el simulacro debe coincidir con el esquema de `DescribeExecution` respuesta (que Step Functions sondea el estado), no con la respuesta. `StartExecution`
## Repasando en iteraciones las definiciones de las máquinas de estados
Puede proporcionar una definición completa de la máquina de estados a la TestState API y especificar qué estado desea probar mediante el `stateName` parámetro. Esto le permite probar ese estado específico en el contexto de su máquina de estados completa. También puede encadenar pruebas utilizando la salida y nextState de una prueba como entrada a la siguiente. Esto le permite probar rutas de ejecución parciales o completas dentro de su máquina de estados.
## Uso del campo de contexto en la TestState API
El `context` parámetro permite proporcionar valores para el objeto Context que normalmente se rellenarían durante la ejecución. Esto resulta útil para probar estados que hacen referencia a valores de contexto como el identificador de ejecución, el nombre del estado o la hora introducida. En el siguiente ejemplo, se muestra cómo puedes usar el objeto Context en tu llamada a la 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\"}"}'
```
## Probar, reintentos y manejo de errores
La TestState API te permite simular escenarios de reintentos y probar la lógica de gestión de errores especificando los reintentos y simulando los errores.
### Simulación de reintentos
```
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
```
La respuesta incluye detalles del error en los datos de inspección:
```
{
"status": "RETRIABLE",
"inspectionData": {
"errorDetails": {
"retryBackoffIntervalSeconds": 4,
"retryIndex": 0
}
}
}
```
Esta respuesta indica:
+ El error se puede recuperar (estado: RECUPERABLE)
+ La duración del retraso es de 4 segundos (2 × 2,0^1)
+ Se aplica el primer reintento (índice 0)
### Prueba de manipuladores de capturas
Cuando un error es simulado y coincide con un controlador de Catch, el `nextState` campo de la respuesta de la TestState API indica en qué estado se gestionará el error. En el siguiente ejemplo:
Para la solicitud de TestState API que se indica a continuación,
```
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
```
La respuesta de la API esperada debería 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
}
}
}
```
Esta respuesta indica que:
+ se detecta el error (estado: CAUGHT\_ERROR)
+ el siguiente estado es HandleThrottling
+ la información del error se añade a la salida mediante ResultPath
+ el primer controlador de Catch (índice 0) detectó el error
También puedes comprobar qué ocurre cuando se agotan todos los reintentos aumentando RetryCount los valores del objeto de contexto.