Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

使用 TestState API 测试状态机

概述

您可以使用Step Functions控制台中的 TestState 功能或 SDK 来测试支持的状态。AmazonCommand Line Interface (Amazon CLI)

TestStateAPI 接受状态的定义并执行它。它允许您在不创建状态机或更新现有状态机的情况下测试状态。您可以提供：

TestStateAPI 扮演的IAM角色必须包含您所在州访问的资源所需的IAM权限。当你指定模拟时，指定角色成为可选的，这样你就可以在不配置IAM权限的情况下测试状态机逻辑。有关状态可能需要的权限的信息，请参阅IAM使用 TestState API 的权限。

主题

在 TestState API 中使用检查级别

使用 TestStateAPI 测试状态时，可以指定要在测试结果中查看的详细信息量。例如，如果您使用了输入和输出数据处理筛选器，例如InputPath或 ResultPath，则可以查看中间和最终的数据处理结果。 Step Functions提供以下检查级别：

所有这些级别还会返回 status 和 nextState 字段。status 表示状态执行的状态。例如，SUCCEEDED、FAILED、RETRIABLE 和 CAUGHT_ERROR。nextState 表示要过渡到的下一个状态的名称。如果您尚未在定义中定义下一个状态，则此字段会返回一个空值。

有关在 Step Functions 控制台和 Amazon CLI 中使用这些检查级别测试状态的信息，请参阅使用 Ste Amazon p Functions 控制台测试状态和使用测试状态 Amazon CLI。

“信息”检查级别

如果测试成功，此级别会显示状态输出。如果测试失败，此级别会显示错误输出。默认情况下，如果您未指定级别，Step Functions 会将检查级别设置为信息。

“调试”检查级别

如果测试成功，此级别会显示状态输出以及输入和输出数据处理的结果。

如果测试失败，此级别会显示错误输出。此级别显示最多到故障点的中间数据处理结果。例如，假设您测试了一个调用 Lambda 函数的 Task 状态。想象一下，您已向 Task 状态应用 InputPath、Parameters、在 Step Functions 中使用 ResultPath 指定状态输出 和 使用 OutputPath 筛选状态输出 筛选器。假设调用失败。在此例中，DEBUG 级别基于应用的筛选器按以下顺序显示数据处理结果：

此级别中提供的诊断信息可以帮助您排查与服务集成或您可能已定义的输入和输出数据处理流相关的问题。

“跟踪”检查级别

Step Functions 提供用于测试 HTTP 任务的跟踪级别。此级别会返回有关 Step Functions 发出的 HTTP 请求和 HTTPS API 返回的响应的信息。响应可能包含标头和请求正文等信息。此外，您还可以在此级别查看状态输出以及输入和输出数据处理的结果。

如果测试失败，此级别会显示错误输出。

此级别仅适用于 HTTP 任务。如果您将此级别用于其他状态类型，则 Step Functions 会抛出错误。

将检查级别设置为 TRACE 时，您还可以查看EventBridge 连接中包含的密钥。为此，您必须在 TestStateAPI true 中将revealSecrets参数设置为。此外，您必须确保调用 TestState API 的IAM用户拥有该states:RevealSecrets操作的权限。有关设置 states:RevealSecrets 权限的 IAM 策略示例，请参阅IAM使用 TestState API 的权限。如果没有此权限，则 Step Functions 会抛出访问遭拒错误。

如果您将 revealSecrets 参数设置为 false，则 Step Functions 会省略 HTTP 请求和响应数据中的所有密钥。请注意，当启用模拟功能revealSecrets时，您无法使用。如果您在 TestState API 请求中同时指定了两者revealSecrets并指定了模拟，Step Functions则会返回验证异常。

IAM使用 TestState API 的权限

调用 TestState API 的IAM用户必须拥有执行states:TestState操作的权限。当你不使用模拟时，IAM用户还必须有权执行将执行角色传递给的iam:PassRole操作。Step Functions此外，如果将revealSecrets参数设置为true，则IAM用户必须具有执行states:RevealSecrets操作的权限。如果没有此权限，则 Step Functions 会抛出访问遭拒错误。

请注意，当你在 TestState API 请求中指定模拟时，无需提供执行角色即可测试状态机逻辑（更多详情请参阅 Mocking 服务集成）。当你不使用模拟时，你必须提供一个执行角色，其中包含你的州访问的资源所需的权限。有关状态可能需要的权限的信息，请参阅管理执行角色。

使用 Ste Amazon p Functions 控制台测试状态

您可以在控制台中测试状态，并检查状态输出或输入和输出数据处理流。对于 HTTP 任务，您可以测试原始 HTTP 请求和响应。

使用测试状态 Amazon CLI

您可以使用中的 TestStateAPI 来测试状态Amazon CLI。此 API 会接受状态的定义并执行它。

对于每种状态，您可以指定要在测试结果中查看的详细信息量。这些详细信息提供有关状态执行的额外信息，包括其输入和输出数据处理结果以及 HTTP 请求和响应信息。以下示例展示了您可以为 TestState API 指定的不同检查级别。

本部分包含以下示例，它们说明了如何使用 Step Functions 在 Amazon CLI 中提供的不同检查级别：

示例 1：使用 INFO inspectionLevel 来测试 Choice 状态

要使用中的 Insp INFO ectionLevel 测试状态Amazon 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 状态根据您提供的数字输入来确定该状态的执行路径。默认情况下，如果您未设置级别，Step Functions 会将 inspectionLevel 设置为 INFO。

Step Functions 返回以下输出：

{
    "output": "{\"number\": 2}",
    "nextState": "Equals 2",
    "status": "SUCCEEDED"
}

示例 2：使用 DEBUG inspectionLevel 针对 Pass 状态调试输入和输出数据处理

要使用中的 Insp DEBUG ectionLevel 测试状态Amazon 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 工作流程状态 状态来展示 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 和中的 revealSecret s 参数测试 HTTP 任务Amazon 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 数据。以下Amazon CLI示例扩展了示例 3，并使用该jq实用程序筛选和打印 TestState API 以人类可读的格式返回的 HTTP 响应。有关信息jq及其安装说明，请参阅 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 中处理输入和输出。

Amazon States Language (ASL) 中的所有状态类型（Task、Parallel、Map、Pass、Wait、Choice、Succeed 和 Fail）共用一组公共字段，来筛选和处理经历它们的 JSON 数据。这些字段包括：InputPath、Parameters、ResultSelector、在 Step Functions 中使用 ResultPath 指定状态输出 和 使用 OutputPath 筛选状态输出。对每个字段的支持因状态而异。在运行时，Step Functions 按特定顺序应用每个字段。下图显示了在 Task 状态内这些字段应用于数据的顺序：

以下列表说明了图中显示的输入和输出处理字段的应用顺序。

这些输入和输出处理字段是可选的。如果您在状态定义中未使用这些字段中的任何一个，则任务将消耗原始状态输入，并将任务结果作为状态输出返回。

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 定义字段映射到 inspectionData 对象中的相应字段：

有关使用 TestState API 调试输入和输出处理的示例，请参阅以下内容：

具体而言，对于地图状态，当设置inspectionLevel为时DEBUG，inspectionData对象将包括其他字段，这些字段可帮助您检查地图状态如何提取和转换项目。您可以在 “了解地图状态检查数据” 部分中了解更多这些字段。

了解地图状态检查数据

当你在inspectionLevel设置为的情况下测试地图状态时DEBUG， TestState API 响应会在inspectionData对象中包含其他字段，用于显示地图状态如何处理数据：

这些字段允许您在部署之前验证地图状态的数据转换和容错配置是否正常运行。

你可以使用 API 测试和断言什么 TestState

TestState API 使您能够为状态机编写全面的单元测试。你可以对状态机逻辑的多个方面进行断言，包括：

错误处理：哪个 Catch 或 Retry 适用

当你模拟错误时，你可以使用 TestState API 来查看激活了哪个错误处理程序。

对于 Catch 方块，你可以断言：

对于重试块，你可以断言：

数据转换：输入和输出处理

使用 TestState API，您可以验证状态数据在每个处理阶段是如何转换的。

你可以断言：

地图状态转换： ItemSelector、、 ItemsPath、 ItemBatcher ItemsPointer

对于地图状态，您可以使用 TestState API 来查看项目是如何提取和转换的。

你可以断言：

地图状态失败阈值：测试状态。 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字段显示哪个错误处理程序捕获了错误。你可以断言：

模拟服务集成

该 TestState API 支持模拟服务集成的结果，允许您在不调用实际服务的情况下测试状态机逻辑。Amazon

何时使用嘲笑

Mocking 对以下方面很有用：

当您指定模拟时，该roleArn参数将变为可选参数，这样您就可以专注于测试状态机定义，而不必处理与权限相关的问题。

基本的模拟语法

要模拟服务集成结果，请执行以下操作：

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"}}'

模拟验证模式

TestState API 会根据Amazon服务 API 模型验证模拟响应，以确保正确性。您可以使用以下fieldValidationMode参数控制验证行为：

验证模式示例：

aws stepfunctions test-state \
  --definition '{
    "Type": "Task",
    "Resource": "arn:aws:states:::dynamodb:putItem",
    "Parameters": {...},
    "End": true
  }' \
  --input '{"key": "value"}' \
  --mock '{"fieldValidationMode": "STRICT", "result": "{\"Attributes\": {...}}"}'

测试地图和并行状态

当指定模拟时， TestState API 支持测试映射和并行状态。这允许您测试这些流状态的输入和输出处理。

了解地图状态测试

当你使用 TestState API 测试地图状态时，你是在测试地图状态的输入和输出处理，而无需在内部执行迭代。这种方法允许您测试：

你不是在测试 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": "..."}'

自动上下文填充

在不提供参数的情况下测试 Map 状态（使用stateName参数）内的状态时， TestState 会自动使用默认值填充 Context 对象。context这包括特定于地图的上下文字段，例如：

测试并行状态

在测试 Parallel 状态时，模拟结果必须是一个 JSON 数组，每个分支都有一个元素，其顺序与分支在定义中出现的顺序相同。

测试活动、.sync 和。 waitForTask代币状态

TestState API 支持测试活动状态、.sync 服务集成模式和。 waitForTask指定模拟时的代币模式。如果没有模拟，通过 TestState API 调用这些状态将返回验证异常。

遍历状态机定义

您可以为 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
    }
  }
}

此响应表明：

测试 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
    }
  }
}

此响应表明：

您还可以通过增加上下文对象中的 RetryCount 值来测试当所有重试尝试都用尽时会发生什么。