本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 使用 TestState API 测试状态机
**注意**
从 2025 年 11 月起，该 TestState API 包括一些增强功能，使您能够为 AWS Step Functions 工作流程构建自动单元测试。这些增强功能可通过AWS CLI和获得 SDKs。新增的主要增强功能：
模拟AWS服务集成或通过 HTTP 任务状态调用的服务，无需调用实际服务即可测试状态逻辑
使用模拟响应测试高级状态，例如地图、并行和活动状态
控制执行上下文以测试特定的重试尝试、映射迭代位置和错误场景
## 概述
您可以使用Step Functions控制台中的 TestState 功能或 SDK 来测试[支持的状态](https://docs.aws.amazon.com/step-functions/latest/dg/test-state-isolation.html#supported-test-states)。AWSCommand Line Interface (AWS CLI)
[TestState](https://docs.aws.amazon.com/step-functions/latest/apireference/API_TestState.html)API 接受状态的定义并执行它。它允许您在不创建状态机或更新现有状态机的情况下测试状态。您可以提供：
+ 单一状态定义
+ 带有`stateName`参数的完整状态机定义
`TestState`API 扮演的IAM角色必须包含您所在州访问的资源所需的IAM权限。当你指定模拟时，指定角色成为可选的，这样你就可以在不配置IAM权限的情况下测试状态机逻辑。有关状态可能需要的权限的信息，请参阅[IAM使用 TestState API 的权限](#test-state-permissions)。
**主题**
+ [在 TestState API 中使用检查级别](#how-test-state-works)
+ [IAM使用 TestState API 的权限](#test-state-permissions)
+ [使用 Ste AWS p Functions 控制台测试状态](#test-state-console)
+ [使用测试状态 AWS CLI](#test-state-cli)
+ [测试和调试输入和输出数据流](#test-state-input-output-dataflow)
+ [你可以使用 API 测试和断言什么 TestState](#what-you-can-test-assert)
+ [模拟服务集成](#mocking-service-integrations)
+ [测试地图和并行状态](#testing-map-parallel-states)
+ [测试活动、.sync 和。 waitForTask代币状态](#testing-activity-sync-waitfortasktoken)
+ [遍历状态机定义](#iterating-through-state-machine-definitions)
+ [在 TestState API 中使用上下文字段](#using-context-field)
+ [测试重试和错误处理](#testing-retry-error-handling)
## 在 TestState API 中使用检查级别
使用 [TestState](https://docs.aws.amazon.com/step-functions/latest/apireference/API_TestState.html)API 测试状态时，可以指定要在测试结果中查看的详细信息量。例如，如果您使用了输入和输出数据处理筛选器，例如[`InputPath`](input-output-inputpath-params.md#input-output-inputpath)或 [`ResultPath`](input-output-resultpath.md)，则可以查看中间和最终的数据处理结果。 Step Functions提供以下检查级别：
+ [信息](#test-state-info-level)
+ [调试](#test-state-debug-level)
+ [跟踪](#test-state-trace-level)
所有这些级别还会返回 `status` 和 `nextState` 字段。`status` 表示状态执行的状态。例如，`SUCCEEDED`、`FAILED`、`RETRIABLE` 和 `CAUGHT_ERROR`。`nextState` 表示要过渡到的下一个状态的名称。如果您尚未在定义中定义下一个状态，则此字段会返回一个空值。
有关在 Step Functions 控制台和 AWS CLI 中使用这些检查级别测试状态的信息，请参阅[使用 Ste AWS p Functions 控制台测试状态](#test-state-console)和[使用测试状态 AWS CLI](#test-state-cli)。
### “信息”检查级别
如果测试成功，此级别会显示状态输出。如果测试失败，此级别会显示错误输出。默认情况下，如果您未指定级别，Step Functions 会将**检查级别**设置为**信息**。
#### 使用信息级别时测试成功的示例
下图显示了成功的 Pass 状态测试。此状态的**检查级别**设置为**信息**，该状态的输出显示在**输出**选项卡中。
![\[已通过的测试的 INFO 级别的输出屏幕截图。\]](http://docs.aws.amazon.com/zh_cn/step-functions/latest/dg/images/test-state-info-success.png)
#### 使用信息级别时测试失败的示例
下图显示了当**检查级别**设置为**信息**时失败的 Task 状态测试。**输出**选项卡会显示错误输出，其中包含错误名称和错误原因的详细说明。
![\[已失败的测试的 INFO 级别的输出屏幕截图。\]](http://docs.aws.amazon.com/zh_cn/step-functions/latest/dg/images/test-state-info-failed.png)
### “调试”检查级别
如果测试成功，此级别会显示状态输出以及输入和输出数据处理的结果。
如果测试失败，此级别会显示错误输出。此级别显示最多到故障点的中间数据处理结果。例如，假设您测试了一个调用 Lambda 函数的 Task 状态。想象一下，您已向 Task 状态应用 [InputPath](input-output-inputpath-params.md#input-output-inputpath)、[Parameters](input-output-inputpath-params.md#input-output-parameters)、[在 Step Functions ResultPath 中使用指定状态输出](input-output-resultpath.md) 和 [使用 OutputPath 筛选状态输出](input-output-example.md#input-output-outputpath) 筛选器。假设调用失败。在此例中，`DEBUG` 级别基于应用的筛选器按以下顺序显示数据处理结果：
+ `input`：原始状态输入
+ `afterInputPath`：Step Functions 应用 `InputPath` 筛选器后的输入。
+ `afterParameters`：Step Functions 应用 `Parameters` 筛选器后的有效输入。
此级别中提供的诊断信息可以帮助您排查与[服务集成](integrate-services.md)或您可能已定义的[输入和输出数据处理](#test-state-input-output-dataflow)流相关的问题。
#### 使用调试级别时测试成功的示例
下图显示了成功的 Pass 状态测试。此状态的**检查级别**设置为**调试**。下图中的**输入/输出处理**选项卡显示了在针对提供的输入应用 [`Parameters`](input-output-inputpath-params.md#input-output-parameters) 后此状态的结果。
![\[已通过的测试的 DEBUG 级别的输出屏幕截图。\]](http://docs.aws.amazon.com/zh_cn/step-functions/latest/dg/images/test-state-debug-success.png)
#### 使用调试级别时测试失败的示例
下图显示了当**检查级别**设置为**调试**时失败的 Task 状态测试。下图中的**输入/输出处理**选项卡显示了此状态最多到故障点的输入和输出数据处理结果。
![\[已失败的测试的 DEBUG 级别的输出屏幕截图。\]](http://docs.aws.amazon.com/zh_cn/step-functions/latest/dg/images/test-state-debug-failed.png)
### “跟踪”检查级别
Step Functions 提供用于测试 [HTTP 任务](call-https-apis.md)的**跟踪**级别。此级别会返回有关 Step Functions 发出的 HTTP 请求和 HTTPS API 返回的响应的信息。响应可能包含标头和请求正文等信息。此外，您还可以在此级别查看状态输出以及输入和输出数据处理的结果。
如果测试失败，此级别会显示错误输出。
此级别仅适用于 HTTP 任务。如果您将此级别用于其他状态类型，则 Step Functions 会抛出错误。
将**检查级别**设置为 **TRACE** 时，您还可以查看[EventBridge 连接](call-https-apis.md#http-task-authentication)中包含的密钥。为此，您必须在 [TestState](https://docs.aws.amazon.com/step-functions/latest/apireference/API_TestState.html)API `true` 中将`revealSecrets`参数设置为。此外，您必须确保调用 TestState API 的IAM用户拥有该`states:RevealSecrets`操作的权限。有关设置 `states:RevealSecrets` 权限的 IAM 策略示例，请参阅[IAM使用 TestState API 的权限](#test-state-permissions)。如果没有此权限，则 Step Functions 会抛出访问遭拒错误。
如果您将 `revealSecrets` 参数设置为 `false`，则 Step Functions 会省略 HTTP 请求和响应数据中的所有密钥。请注意，当启用模拟功能`revealSecrets`时，您无法使用。如果您在 TestState API 请求中同时指定了两者`revealSecrets`并指定了模拟，Step Functions则会返回验证异常。
#### 使用跟踪级别时测试成功的示例
下图显示了成功的 HTTP 任务测试。此状态的**检查级别**设置为**跟踪**。下图中的 **HTTP 请求和响应**选项卡显示了 HTTPS API 调用的结果。
![\[已通过的测试的 TRACE 级别的输出屏幕截图。\]](http://docs.aws.amazon.com/zh_cn/step-functions/latest/dg/images/test-state-trace-success.png)
## IAM使用 TestState API 的权限
调用 `TestState` API 的IAM用户必须拥有执行`states:TestState`操作的权限。当你不使用模拟时，IAM用户还必须有权执行将执行角色传递给的`iam:PassRole`操作。Step Functions此外，如果将`revealSecrets`参数设置为`true`，则IAM用户必须具有执行`states:RevealSecrets`操作的权限。如果没有此权限，则 Step Functions 会抛出访问遭拒错误。
请注意，当你在 TestState API 请求中指定模拟时，无需提供执行角色即可测试状态机逻辑（更多详情请参阅 [Mocking 服务集成](#mocking-service-integrations)）。当你不使用模拟时，你必须提供一个执行角色，其中包含你的州访问的资源所需的权限。有关状态可能需要的权限的信息，请参阅[管理执行角色](manage-state-machine-permissions.md)。
## 使用 Ste AWS p Functions 控制台测试状态
您可以在控制台中测试状态，并检查状态输出或输入和输出数据处理流。对于 [HTTP 任务](call-https-apis.md)，您可以测试原始 HTTP 请求和响应。
**注意**
控制台 TestState 功能尚不支持本文档中描述的某些增强功能，例如模拟服务集成、测试 Map 和 Parallel 状态，或者 Activity、.sync 和。 waitForTask代币模式。这些功能目前只能通过使用AWS CLI或 SDK TestState 的 API 获得。
**测试状态**
1. 打开 [Step Functions 控制台](https://console.aws.amazon.com/states/home?region=us-east-1#/)。
1. 选择**创建状态机**开始创建状态机，或选择一个现有状态机。
1. 在 Workflow Studio 的[设计模式](workflow-studio.md#wfs-interface-design-mode)中，选择要测试的状态。
1. 在 Workflow Studio 中选择**测试状态**。[检查器面板](workflow-studio.md#workflow-studio-components-formdefinition)
1. 在**测试状态**对话框中，执行以下操作：
1. 对于**执行角色**，选择一个执行角色来测试状态。请确保您对要测试的状态具有必需的 [IAM 权限](#test-state-permissions)。
1. （可选）针对测试提供所选状态需要的任何 JSON 输入。
1. 对于**检查级别**，根据要查看的值选择以下选项之一：
+ [信息](#test-state-info-level)：如果测试成功，此级别会在**输出**选项卡中显示状态输出。如果测试失败，**信息**级别会显示错误输出，其中包含错误名称和错误原因的详细说明。默认情况下，如果您未选择级别，Step Functions 会将**检查级别**设置为**信息**。
+ [调试](#test-state-debug-level)：如果测试成功，此级别会显示状态输出以及输入和输出数据处理的结果。如果测试失败，**调试**级别会显示错误输出，其中包含错误名称和错误原因的详细说明。
+ [跟踪](#test-state-trace-level)：此级别会显示原始的 HTTP 请求和响应，对于验证标头、查询参数和其他特定于 API 的详细信息非常有用。此选项仅适用于 [HTTP 任务](call-https-apis.md)。
您可以根据需要选择**显示密钥**。结合**跟踪**检查级别，此设置可让您查看 EventBridge 连接插入的敏感数据，例如 API 密钥。您用于访问控制台的 IAM 用户身份必须具有执行 `states:RevealSecrets` 操作的权限。如果没有此权限，则在您开始测试时 Step Functions 会抛出访问遭拒错误。有关设置 `states:RevealSecrets` 权限的 IAM 策略示例，请参阅[IAM使用 TestState API 的权限](#test-state-permissions)。
1. 选择**开始测试**。
## 使用测试状态 AWS CLI
您可以使用中的 [TestState](https://docs.aws.amazon.com/step-functions/latest/apireference/API_TestState.html)API 来测试状态AWS CLI。此 API 会接受状态的定义并执行它。
对于每种状态，您可以指定要在测试结果中查看的详细信息量。这些详细信息提供有关状态执行的额外信息，包括其输入和输出数据处理结果以及 HTTP 请求和响应信息。以下示例展示了您可以为 TestState API 指定的不同检查级别。
本部分包含以下示例，它们说明了如何使用 Step Functions 在 AWS CLI 中提供的不同检查级别：
+ [使用 INFO inspectionLevel](#test-info-level-cli)
+ [使用 DEBUG inspectionLevel](#test-debug-level-cli)
+ [使用 TRACE inspectionLevel](#test-trace-level-cli)
+ [在中AWS CLI使用 jq 实用程序筛选和打印 TestState API 返回的 HTTP 响应](#cli-readable-output)
### 示例 1：使用 INFO inspectionLevel 来测试 Choice 状态
要使用中的 Insp `INFO` [ectionLevel](https://docs.aws.amazon.com/step-functions/latest/apireference/API_TestState.html#StepFunctions-TestState-request-inspectionLevel) 测试状态AWS CLI，请按以下示例所示运行`test-state`命令。
```
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}'
```
此示例使用 [Choice](state-choice.md) 状态根据您提供的数字输入来确定该状态的执行路径。默认情况下，如果您未设置级别，Step Functions 会将 `inspectionLevel` 设置为 `INFO`。
Step Functions 返回以下输出：
```
{
"output": "{\"number\": 2}",
"nextState": "Equals 2",
"status": "SUCCEEDED"
}
```
### 示例 2：使用 DEBUG inspectionLevel 针对 Pass 状态调试输入和输出数据处理
要使用中的 Insp `DEBUG` [ectionLevel](https://docs.aws.amazon.com/step-functions/latest/apireference/API_TestState.html#StepFunctions-TestState-request-inspectionLevel) 测试状态AWS CLI，请按以下示例所示运行`test-state`命令。
```
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
```
此示例使用 [Pass 工作流程状态](state-pass.md) 状态来展示 Step Functions 如何使用输入和输出数据处理筛选器来筛选和处理输入 JSON 数据。此示例使用以下筛选器：`InputPath`、`Parameters`、`在 Step Functions ResultPath 中使用指定状态输出` 和 `使用 OutputPath 筛选状态输出`。
Step Functions 返回以下输出：
```
{
"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"
}
```
### 示例 3：使用 TRACE inspectionLevel 和 revealSecrets 检查发送到 HTTPS API 的 HTTP 请求
要使用 Insp `TRACE` [ectionLevel 和](https://docs.aws.amazon.com/step-functions/latest/apireference/API_TestState.html#StepFunctions-TestState-request-inspectionLevel)[中的 revealSecret](https://docs.aws.amazon.com/step-functions/latest/apireference/API_TestState.html#StepFunctions-TestState-request-revealSecrets) s 参数测试 [HTTP 任务](call-https-apis.md)AWS CLI，请按以下`test-state`示例所示运行命令。
```
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
```
此示例测试 HTTP 任务是否会调用指定的 HTTPS API，`https://httpbin.org/`。它还会显示 API 调用的 HTTP 请求和响应数据。
Step Functions返回的输出与当前文档中的原始示例类似。
### 示例 4：使用 jq 实用程序筛选并打印 TestState API 返回的响应
TestState API 在其响应中以转义字符串形式返回 JSON 数据。以下AWS CLI[示例扩展了示例 3](#test-trace-level-cli)，并使用该`jq`实用程序筛选和打印 TestState API 以人类可读的格式返回的 HTTP 响应。有关信息`jq`及其安装说明，请参阅 [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'
```
以下示例显示了以人类可读的格式返回的输出。
```
{
"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"
}
```
## 测试和调试输入和输出数据流
`TestState` API 有助于测试和调试流经您的工作流的数据。本节提供了一些关键概念，并说明了如何 TestState 为此目的使用。
### 重要概念
在 Step Functions 中，在 JSON 数据经历状态机中的状态时对其进行筛选和处理的过程称为*输入和输出处理*。有关其工作方式的信息，请参阅[在 Step Functions 中处理输入和输出](concepts-input-output-filtering.md)。
[Amazon States Language](concepts-amazon-states-language.md) (ASL) 中的所有[状态](workflow-states.md)类型（Task、Parallel、Map、Pass、Wait、Choice、Succeed 和 Fail）共用一组公共字段，来筛选和处理经历它们的 JSON 数据。这些字段包括：[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)、[在 Step Functions ResultPath 中使用指定状态输出](input-output-resultpath.md) 和 [使用 OutputPath 筛选状态输出](input-output-example.md#input-output-outputpath)。对每个字段的支持[因状态而异](https://states-language.net/spec.html#state-type-table)。在运行时，Step Functions 按特定顺序应用每个字段。下图显示了在 Task 状态内这些字段应用于数据的顺序：
![\[筛选器的顺序： InputPath、参数 ResultSelector、 ResultPath、和 OutputPath。\]](http://docs.aws.amazon.com/zh_cn/step-functions/latest/dg/images/input-output-processing.png)
以下列表说明了图中显示的输入和输出处理字段的应用顺序。
1. *状态输入*是从先前状态传递到当前状态的 JSON 数据。
1. [InputPath](input-output-inputpath-params.md#input-output-inputpath) 筛选部分原始状态输入。
1. [Parameters](input-output-inputpath-params.md#input-output-parameters) 配置要传递给 [Task](state-task.md) 的一组值。
1. 任务执行工作并返回结果。
1. [ResultSelector](input-output-inputpath-params.md#input-output-resultselector) 从任务结果中选择一组要保留的值。
1. [在 Step Functions ResultPath 中使用指定状态输出](input-output-resultpath.md) 将结果与原始状态输入合并，或者用它替换结果。
1. [使用 OutputPath 筛选状态输出](input-output-example.md#input-output-outputpath) 筛选输出的一部分以传递到下一状态。
1. *状态输出*是从当前状态传递到下一状态的 JSON 数据。
这些输入和输出处理字段是可选的。如果您在状态定义中未使用这些字段中的任何一个，则任务将消耗原始状态输入，并将任务结果作为状态输出返回。
### TestState 用于检查输入和输出处理
当您调用 `TestState` API 并将 `inspectionLevel` 参数设置为 `DEBUG` 时，API 响应会包含一个名为 `inspectionData` 的对象。此对象包含一些字段，可帮助您检查在相应状态执行时，数据是如何筛选或处理的。以下示例显示了 Task 状态的 `inspectionData` 对象。
```
"inspectionData": {
"input": string,
"afterInputPath": string,
"afterParameters": string,
"result": string,
"afterResultSelector": string,
"afterResultPath": string,
"output": string
}
```
在此示例中，每个包含 `after` 前缀的字段都显示特定字段应用后的数据。例如，`afterInputPath` 显示应用 `InputPath` 字段以筛选原始状态输入的效果。下图将每个 [ASL 定义](concepts-amazon-states-language.md)字段映射到 `inspectionData` 对象中的相应字段：
![\[该图显示了 ASL 字段与 inspectionData 的映射。\]](http://docs.aws.amazon.com/zh_cn/step-functions/latest/dg/images/inspection-data-after-fields.png)
有关使用 TestState API 调试输入和输出处理的示例，请参阅以下内容：
+ [在 Step Functions 控制台中使用调试检查级别测试状态](#test-state-debug-level)
+ [使用中的 DEBUG 检查级别测试状态 AWS CLI](#test-debug-level-cli)
具体而言，对于地图状态，当设置`inspectionLevel`为时`DEBUG`，`inspectionData`对象将包括其他字段，这些字段可帮助您检查地图状态如何提取和转换项目。您可以在 “了解[地图状态检查数据” 部分中了解](#understanding-map-inspection-data)更多这些字段。
### 了解地图状态检查数据
当你在`inspectionLevel`设置为的情况下测试地图状态时`DEBUG`， TestState API 响应会在`inspectionData`对象中包含其他字段，用于显示地图状态如何处理数据：
**注意**
`afterItemsPath`仅在 JSONPath 用作查询语言时才会填充。
+ `afterItemsPath`（字符串）-应用 ItemsPath 过滤器后的有效输入。这显示了从您的输入中提取的项目数组。
+ `afterItemsPointer`（字符串）-应用 ItemsPointer 过滤器后的有效输入。这仅适用于 JSON 输入（不适用 JSONata）。
+ `afterItemSelector`（字符串数组）-一个包含应用 ItemSelector 转换后的输入值的数组。数组中的每个元素代表一个变换后的项目。此字段仅在测试地图状态时才会出现。
+ `afterItemBatcher`（字符串数组）-包含应用分组后的输入值的数 ItemBatcher 组。这显示了项目是如何分组成批的。此字段仅在测试地图状态时才会出现。
+ `toleratedFailureCount`（数字）-地图状态的容忍失败阈值，表示为地图状态迭代次数。该值来自中指定的值 ToleratedFailureCount 或运行时从中计算的值 ToleratedFailureCountPath。
+ `toleratedFailurePercentage`（数字）-地图状态的容忍失败阈值，以占地图状态迭代的百分比表示。该值来自中指定的值 ToleratedFailurePercentage 或运行时从中计算的值 ToleratedFailurePercentagePath。
+ `maxConcurrency`（数字）-地图状态的最大并发设置。
这些字段允许您在部署之前验证地图状态的数据转换和容错配置是否正常运行。
## 你可以使用 API 测试和断言什么 TestState
TestState API 使您能够为状态机编写全面的单元测试。你可以对状态机逻辑的多个方面进行断言，包括：
+ [错误处理：哪个 Catch 或 Retry 适用](#error-handling-catch-retry)
+ [数据转换：输入和输出处理](#data-transformations-assert)
+ [地图状态转换： ItemSelector、、 ItemsPath、 ItemBatcher ItemsPointer](#map-state-transformations-assert)
+ [地图状态失败阈值：测试状态。 ExceedToleratedFailureThreshold](#map-failure-thresholds-assert)
+ [地图和并行状态下的错误传播](#error-propagation-assert)
### 错误处理：哪个 Catch 或 Retry 适用
当你模拟错误时，你可以使用 TestState API 来查看激活了哪个错误处理程序。
对于 Catch 方块，你可以断言：
+ 哪个 Catch 处理程序捕获了错误（通过`catchIndex`在响应中）
+ 下一个状态会是什么样子（通过`nextState`在响应中）
+ 哪些数据流向错误处理程序（考虑通过响应`output`中的数据 ResultPath）
对于重试块，你可以断言：
+ 哪种重试适用（通过`retryIndex`在响应中）
+ 退避持续时间是多少（通过`retryBackoffIntervalSeconds`在响应中）
+ 是否已用尽重试次数并捕捉到错误
### 数据转换：输入和输出处理
使用 TestState API，您可以验证状态数据在每个处理阶段是如何转换的。
你可以断言：
+ InputPath 过滤器后输入 (`afterInputPath`)
+ Parameters/Arguments 转换后的数据（`afterParameters`或`afterArguments`）
+ ResultSelector (`afterResultSelector`) 之后的结果
+ ResultPath (`afterResultPath`) 之后的输出
+ OutputPath (`output`) 之后的最终输出
### 地图状态转换： ItemSelector、、 ItemsPath、 ItemBatcher ItemsPointer
对于地图状态，您可以使用 TestState API 来查看项目是如何提取和转换的。
你可以断言：
+ ItemsPath 筛选后的项目 (`afterItemsPath`)
+ ItemsPointer 筛选后的项目 (`afterItemsPointer`)
+ ItemSelector 变身后的物品 (`afterItemSelector`)
+ ItemBatcher 分组后的项目 (`afterItemBatcher`)
### 地图状态失败阈值：测试状态。 ExceedToleratedFailureThreshold
测试特定次数的失败迭代是否会触发容忍的失败阈值。
你可以断言：
+ 地图状态是否在状态下失败。 ExceedToleratedFailureThreshold
### 地图和并行状态下的错误传播
在 Map 或 Parallel 状态下测试状态时，错误会传播到父状态错误处理程序，就像在实际执行中一样。
#### 使用 errorCausedBy State 指定错误源
在模拟 Map 或 Parallel 状态的错误时，必须使用参数指定哪个子状态导致了`stateConfiguration.errorCausedByState`错误。在测试通配符错误时，这一点尤其重要，比如`States.TaskFailed`。 `States.TaskFailed`是适用于任何任务状态失败的通配符错误。要测试您的 Map 或 Parallel 状态如何处理此错误，您需要确定引发该错误的特定子状态。参见以下示例：
```
aws stepfunctions test-state \
--definition '{...Map or Parallel state definition...}' \
--input '[...]' \
--state-configuration '{"errorCausedByState": "ProcessItem"}' \
--mock '{"errorOutput": {"error": "States.TaskFailed", "cause": "Task execution failed"}}'
```
在此示例中，`errorCausedByState` TestState 告诉 Map/Parallel 工作流程中的 ProcessItem “” 状态引发了错误。父 Map/Parallel 状态的 Catch 或 Retry 处理程序将像在实际执行期间一样处理错误。响应中的`nextState`字段显示哪个错误处理程序捕获了错误。你可以断言：
+ 父级 Catch 处理程序是否捕获到子状态错误
+ 子状态错误是否会触发父级 “重试” 策略
+ 错误传播之后的下一个状态是什么
## 模拟服务集成
该 TestState API 支持模拟服务集成的结果，允许您在不调用实际服务的情况下测试状态机逻辑。AWS
### 何时使用嘲笑
Mocking 对以下方面很有用：
+ 孤立地对状态机定义进行单元测试
+ 测试错误处理和重试逻辑
+ 验证输入和输出数据转换
+ 模拟各种服务响应和错误情况
+ 在不配置IAM权限的情况下进行测试
当您指定模拟时，该`roleArn`参数将变为可选参数，这样您就可以专注于测试状态机定义，而不必处理与权限相关的问题。
**注意**
如果您需要测试以下状态类型或服务集成模式（地图、并行、活动、.sync 服务集成和 waitForTask令牌服务集成），则必须进行模拟。
### 基本的模拟语法
要模拟服务集成结果，请执行以下操作：
```
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\"}}"}'
```
要模拟错误，请执行以下操作：
```
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"}}'
```
**注意**
您不能在同一 API 调用`mock.errorOutput`中同时提供两者`mock.result`。这会导致验证异常。
### 模拟验证模式
TestState API 会根据AWS服务 API 模型验证模拟响应，以确保正确性。您可以使用以下`fieldValidationMode`参数控制验证行为：
+ **严格（默认）**— 强制执行 AWS API 模型中的字段命名、大小、形状和数据类型限制。所有必填字段的类型必须正确。此模式有助于确保您的模拟准确地代表真实的服务响应。
+ **PRESENT — 仅验证模拟中存在的字段。**未知字段将被忽略。当您想要灵活性但仍需要对已知字段进行验证时，此模式非常有用。
+ **无** — 完全跳过验证。请谨慎使用，因为这可能会导致错误的测试假设和行为与实际执行不同。
**注意**
仅对AWS服务 API 模型中定义的字段执行验证。无论验证模式如何，在验证过程中，API 模型中未指定的任何字段都将被忽略。例如，如果对未定义 “必填” 字段的 API 使用 STRICT 模式，则空的模拟响应将通过验证。
验证模式示例：
```
aws stepfunctions test-state \
--definition '{
"Type": "Task",
"Resource": "arn:aws:states:::dynamodb:putItem",
"Parameters": {...},
"End": true
}' \
--input '{"key": "value"}' \
--mock '{"fieldValidationMode": "STRICT", "result": "{\"Attributes\": {...}}"}'
```
**重要**
[HTTP 任务](call-https-apis.md)、API Gateway、EKS Call 和 EKS RunJob 集成不支持模拟验证。
## 测试地图和并行状态
当指定模拟时， TestState API 支持测试映射和并行状态。这允许您测试这些流状态的输入和输出处理。
### 了解地图状态测试
当你使用 TestState API 测试地图状态时，你是在测试地图状态的输入和输出处理，而无需在内部执行迭代。这种方法允许您测试：
+ ItemsPath 或者从输入中 ItemsPointer 提取
+ ItemSelector 对每个项目应用转换
+ ItemBatcher 分组（如果已指定）
+ 地图状态的输出处理 (ResultPath, OutputPath)
+ 容许的故障阈值
你不是在测试 ItemProcessor （处理每件物品的状态）内部会发生什么。
### 测试地图状态
测试地图状态时，模拟结果必须代表整个地图状态的输出。模拟结果必须是有效的 JSON 数组或 JSON 对象，具体取决于您的 Map 状态配置。参见以下示例：
```
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
```
### 测试分布式地图状态
分布式地图状态的测试方式与内联地图状态类似。当您的 Map 使用从 S3 读取数据时，请直接在输入中提供数据（就好像已经从 S3 读取数据一样）。 ItemReader 例如：
```
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": "..."}'
```
**注意**
在测试分布式地图状态（模式设置为 “分布”）时，也可以在 C mapIterationFailure ount 上进行断言。在地图中测试状态时，此字段的值不能超过输入中的项目数，也不能等于项目数。
### 自动上下文填充
在不提供参数的情况下测试 Map 状态（使用`stateName`参数）内的状态时， TestState 会自动使用默认值填充 Context 对象。`context`这包括特定于地图的上下文字段，例如：
+ `$$.Map.Item.Index`=`0`（第一次迭代）
+ `$$.Map.Item.Value`= 您的输入值
+ `$$.Map.Item.Key`（适用于具有特定 ItemReader 配置的分布式地图）
+ `$$.Map.Item.Source`（对于分布式地图，指明物品的来源）
### 测试并行状态
在测试 Parallel 状态时，模拟结果必须是一个 JSON 数组，每个分支都有一个元素，其顺序与分支在定义中出现的顺序相同。
## 测试活动、.sync 和。 waitForTask代币状态
TestState API 支持测试活动状态、.sync 服务集成模式和。 waitForTask指定模拟时的代币模式。如果没有模拟，通过 TestState API 调用这些状态将返回验证异常。
**注意**
为了使用 TestState API 测试.sync 集成，将根据轮询 API 的架构验证模拟的响应。例如，在测试时`startExecution.sync:2`，您的模拟必须匹配`DescribeExecution`响应架构（Step Functions轮询状态），而不是`StartExecution`响应。
## 遍历状态机定义
您可以为 TestState API 提供完整的状态机定义，并使用`stateName`参数指定要测试的状态。这允许您在整个状态机的上下文中测试该特定状态。您还可以使用一个测试的输出和 nextState 作为输入到下一个测试的输入，将测试链接起来。这允许您在状态机中测试部分或全部执行路径。
## 在 TestState API 中使用上下文字段
该`context`参数允许您为 Context 对象提供通常在执行期间填充的值。这对于测试引用上下文值（例如执行 ID、状态名称或输入时间）的状态非常有用。以下示例演示了如何在 TestState API 调用中使用 Context 对象：
```
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\"}"}'
```
## 测试重试和错误处理
该 TestState API 允许您通过指定重试尝试和模拟错误来模拟重试场景和测试错误处理逻辑。
### 模拟重试尝试
```
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
```
响应中包含检查数据中的错误详情：
```
{
"status": "RETRIABLE",
"inspectionData": {
"errorDetails": {
"retryBackoffIntervalSeconds": 4,
"retryIndex": 0
}
}
}
```
此响应表明：
+ 错误可以重试（状态：可重试）
+ 退避持续时间为 4 秒 (2 × 2.0^1)
+ 第一次重试（索引 0）适用
### 测试 catch 处理程序
当错误被模拟并与 Catch 处理程序匹配时， TestState API 响应中的`nextState`字段会指示哪个状态将处理该错误。在下面的例子中：
对于下面给定 TestState 的 API 请求，
```
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
```
预期的 API 响应应为：
```
{
"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
}
}
}
```
此响应表明：
+ 错误被捕获（状态：CAUGHT\$1ERROR）
+ 下一个状态是 HandleThrottling
+ 错误信息通过以下方式添加到输出中 ResultPath
+ 第一个 Catch 处理程序（索引 0）捕获了错误
您还可以通过增加上下文对象中的 RetryCount 值来测试当所有重试尝试都用尽时会发生什么。