翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# TestState API を使用したステートマシンのテスト
**注記**
2025 年 11 月以降、TestState API には、AWSStep Functions ワークフローの自動ユニットテストを構築できる機能強化が含まれています。これらの機能強化は、 AWS CLIおよび SDKsを通じて利用できます。主な機能強化が追加されました。
実際のAWSサービスを呼び出さずに HTTP タスク状態を介して呼び出されたモックサービス統合またはサービスをテストする
モックレスポンスを使用してマップ、並列、アクティビティの状態などの高度な状態をテストする
実行コンテキストを制御して、特定の再試行、マップ反復位置、エラーシナリオをテストする
## 概要:
Step Functions コンソール、、AWSCommand Line Interface (AWS CLI)または SDK の TestState 機能を使用して、[サポートされている状態](https://docs.aws.amazon.com/step-functions/latest/dg/test-state-isolation.html#supported-test-states)をテストできます。
[TestState](https://docs.aws.amazon.com/step-functions/latest/apireference/API_TestState.html) API は、状態の定義を受け入れて実行します。これにより、ステートマシンを作成したり、既存のステートマシンを更新したりすることなく、ステートをテストできます。以下を指定できます。
+ 単一の状態定義
+ `stateName` パラメータを使用したステートマシンの完全な定義
`TestState` API は、状態がアクセスするリソースに必要なIAMアクセス許可を含む必要がある IAMロールを引き受けます。モックを指定すると、ロールの指定はオプションになり、IAMアクセス許可を設定せずにステートマシンロジックをテストできます。ステートに必要なアクセス許可については、「[TestState API を使用するための IAM アクセス許可](#test-state-permissions)」を参照してください。
**トピック**
+ [TestState API で検査レベルを使用する](#how-test-state-works)
+ [TestState API を使用するための IAM アクセス許可](#test-state-permissions)
+ [AWSStep Functions コンソールを使用した状態テスト](#test-state-console)
+ [を使用して状態をテストするAWS CLI](#test-state-cli)
+ [入力データと出力データフローのテストとデバッグ](#test-state-input-output-dataflow)
+ [TestState API でテストおよびアサートできる内容](#what-you-can-test-assert)
+ [サービス統合のモッキング](#mocking-service-integrations)
+ [マップと並列状態のテスト](#testing-map-parallel-states)
+ [Activity、.sync、.waitForTaskToken の状態のテスト](#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には、次の検査レベルが用意されています。
+ [INFO](#test-state-info-level)
+ [DEBUG](#test-state-debug-level)
+ [TRACE](#test-state-trace-level)
これらのレベルはすべて、`status` および `nextState` フィールドも返します。`status` は、ステート実行のステータスを示します。例えば、`SUCCEEDED`、`FAILED`、`RETRIABLE`、および `CAUGHT_ERROR` などです。`nextState` は、次に遷移するステートの名前を示します。定義に次のステートを定義していない場合、このフィールドは空の値を返します。
Step Functions コンソールおよび AWS CLI でこれらの検査レベルを使用してステートをテストする方法については、「[AWSStep Functions コンソールを使用した状態テスト](#test-state-console)」および「[を使用して状態をテストするAWS CLI](#test-state-cli)」を参照してください。
### INFO inspectionLevel
テストが成功すると、このレベルにはステート出力が表示されます。テストが失敗した場合、このレベルにはエラー出力が表示されます。レベルを指定しない場合、デフォルトで Step Functions は **[検査レベル]** を **[INFO]** に設定します。
#### INFO レベルで成功したテストの例
次の図は、成功のテストを示しています。このステートの **[検査レベル]** は **[INFO]** に設定され、ステートの出力が **[出力]** タブに表示されます。
#### INFO レベルで失敗したテストの例
以下の画像は、**[検査レベル]** が **[INFO]** に設定されている場合に、タスクステートに対して失敗したテストを示しています。**[出力]** タブには、エラー名とそのエラーの原因の詳細な説明を含むエラー出力が表示されます。
### DEBUG inspectionLevel
テストが成功すると、このレベルにはステート出力と入出力データ処理の結果が表示されます。
テストが失敗した場合、このレベルにはエラー出力が表示されます。このレベルには、障害発生時点までの中間データ処理結果が表示されます。例えば、Lambda 関数を呼び出すタスクステートをテストしたとします。タスクステートに、[InputPath](input-output-inputpath-params.md#input-output-inputpath)、[パラメータ](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)フローに関連する問題のトラブルシューティングに役立ちます。
#### DEBUG レベルで成功したテストの例
次の図は、成功したテストのパスステートを示しています。このステートの **[検査レベル]** は **[DEBUG]** に設定されています。以下の画像の **[入出力処理]** タブには、このステートに提供された入力に [`Parameters`](input-output-inputpath-params.md#input-output-parameters) を適用した結果が表示されます。
#### DEBUG レベルで失敗したテストの例
以下の画像は、**[検査レベル]** が **[DEBUG]** に設定されている場合にタスクステートに対して失敗したテストを示しています。以下の画像の **[入出力処理タブ]** には、障害発生時点までのステートの入出力データ処理結果が表示されます。
### TRACE inspectionLevel
Step Functions は [HTTP タスク](call-https-apis.md)をテストするための **[TRACE]** レベルを提供します。このレベルでは、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 で `revealSecrets` パラメータを `true` に設定する必要があります。さらに、TestState API を呼び出す IAM ユーザーに `states:RevealSecrets` アクションのアクセス許可があることを確認する必要があります。`states:RevealSecrets` アクセス許可を付与する IAM ポリシーの例については、「[TestState API を使用するための IAM アクセス許可](#test-state-permissions)」を参照してください。このアクセス許可がない場合、Step Functions はアクセス拒否エラーをスローします。
`revealSecrets` パラメータを `false` に設定すると、Step Functions はHTTP リクエストとレスポンスのデータに含まれるすべてのシークレットを省略します。モックが有効になってい`revealSecrets`る場合は、 を使用できないことに注意してください。TestState API リクエストで `revealSecrets`とモックの両方を指定すると、 は検証例外Step Functionsを返します。
#### TRACE レベルで成功したテストの例
次の図は、成功した HTTP タスクのテストを示しています。このステートの **[検査レベル]** は **[TRACE]** に設定されています。次の画像の **[HTTP リクエストおよびレスポンス]** タブには、HTTPS API コールの結果が表示されます。
## TestState API を使用するための IAM アクセス許可
`TestState` API を呼び出すIAMユーザーには、`states:TestState`アクションを実行するアクセス許可が必要です。モックを使用しない場合、IAMユーザーは実行ロールを に渡す`iam:PassRole`アクションを実行するアクセス許可も持っている必要がありますStep Functions。さらに、 `revealSecrets`パラメータを に設定した場合`true`、IAMユーザーは `states:RevealSecrets`アクションを実行するアクセス許可を持っている必要があります。このアクセス許可がない場合、Step Functions はアクセス拒否エラーをスローします。
TestState API リクエストでモックを指定すると、実行ロールを指定せずにステートマシンロジックをテストできることに注意してください (詳細については、[「サービス統合のモッキング](#mocking-service-integrations)」を参照してください）。モックを使用していない場合は、状態がアクセスするリソースに必要なアクセス許可を含む実行ロールを指定する必要があります。ステートが必要とするアクセス許可については、「[実行ロールの管理](manage-state-machine-permissions.md)」を参照してください。
## AWSStep Functions コンソールを使用した状態テスト
コンソールでステートをテストし、ステートの出力または入出力データの処理フローを確認できます。[HTTP タスク](call-https-apis.md)では、未加工の HTTP リクエストとレスポンスをテストできます。
**注記**
コンソール TestState 機能は、モックサービス統合、マップと並列状態のテスト、アクティビティ、.sync、.waitForTaskToken パターンなど、このドキュメントで説明されている機能強化の一部をまだサポートしていません。これらの機能は、現在、 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. **[検査レベル]** では、表示したい値に基づいて以下のオプションのいずれかを選択します。
+ [INFO](#test-state-info-level) — テストが成功すると、**[出力]** タブにステート出力が表示されます。テストが失敗した場合、**[INFO]** はエラー名とそのエラーの原因の詳細な説明を含むエラー出力を表示します。レベルを選択しない場合、Step Functions はデフォルトで **[検査レベル]** を **[INFO]** に設定します。
+ [DEBUG](#test-state-debug-level) — テストが成功した場合、ステート出力と入出力データ処理の結果を表示します。テストが失敗した場合、**[DEBUG]** はエラー名とそのエラーの原因の詳細な説明を含むエラー出力を表示します。
+ [TRACE](#test-state-trace-level) — 未加工の HTTP リクエストとレスポンスを表示し、ヘッダー、クエリパラメータ、その他の API 固有の詳細を確認するのに役立ちます。このオプションは [HTTP タスク](call-https-apis.md)でのみ使用できます。
オプションで **[シークレットを公開]** を選択することもできます。この設定を **[TRACE]** と組み合わせると、API キーなど、EventBridge 接続によって挿入される機密データを表示できます。コンソールへのアクセスに使用する IAM ユーザー ID には、`states:RevealSecrets` アクションを実行するアクセス許可が必要です。このアクセス許可がない場合、Step Functions はテストの開始時にアクセス拒否エラーをスローします。`states:RevealSecrets` アクセス許可を付与する IAM ポリシーの例については、「[TestState API を使用するための IAM アクセス許可](#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)
+ [DEBUG inspectionLevel の使用](#test-trace-level-cli)
+ [AWS CLI で jq ユーティリティを使用して、TestState API が返す HTTP レスポンスをフィルタリングして印刷する](#cli-readable-output)
### 例 1: INFO inspectionLevel を使用して Choice ステートをテストする
の `INFO` [inspectionLevel](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 ステートの入出力データ処理をデバッグする
の `DEBUG` [inspectionLevel](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`、`パラメータ`、`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 リクエストを検査する
`TRACE` [inspectionLevel](https://docs.aws.amazon.com/step-functions/latest/apireference/API_TestState.html#StepFunctions-TestState-request-inspectionLevel) と の [revealSecrets](https://docs.aws.amazon.com/step-functions/latest/apireference/API_TestState.html#StepFunctions-TestState-request-revealSecrets) パラメータを使用して [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` およびインストール手順の詳細については、GitHub **の「[jq](https://stedolan.github.io/jq/)」を参照してください。
```
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)、[パラメータ](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 は各フィールドを特定の順序で適用します。以下の図は、これらのフィールドがタスクステート内のデータに適用される順序を示しています。
以下のリストは、図に示されている入力処理フィールドと出力処理フィールドの適用順序を示しています。
1. ステート入力**は、前のステートから現在のステートに渡された JSON データです。
1. [InputPath](input-output-inputpath-params.md#input-output-inputpath) は未加工のステート入力の一部をフィルタリングします。
1. [パラメータ](input-output-inputpath-params.md#input-output-parameters) は[タスク](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 データです。
これらの入力処理フィールドと出力処理フィールドはオプションです。状態定義でこれらのフィールドを使用しない場合、タスクは raw 状態入力を消費し、タスク結果を状態出力として返します。
### TestState を使用して入出力処理を検査する
`TestState` API を呼び出して `inspectionLevel` パラメータを `DEBUG` に設定すると、API レスポンスには `inspectionData` というオブジェクトが含まれます。このオブジェクトには、実行時にステート内でデータがどのようにフィルタリングまたは操作されたかを調べるのに役立つフィールドが含まれています。次の例は、`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` オブジェクト内の対応するフィールドにマッピングしています。
TestState API を使用して入出力処理をデバッグする例については、以下を参照してください。
+ [Step Functions コンソールの DEBUG 検査レベルを使用してステートをテストする](#test-state-debug-level)
+ [で DEBUG 検査レベルを使用して状態をテストするAWS CLI](#test-debug-level-cli)
特にマップ状態の場合、 `inspectionLevel`を に設定すると`DEBUG`、`inspectionData`オブジェクトには、マップ状態が項目を抽出および変換する方法を検査するのに役立つ追加のフィールドが含まれます。これらのフィールドの詳細については、[「マップ状態検査データについて](#understanding-map-inspection-data)」セクションを参照してください。
### マップ状態検査データについて
を `inspectionLevel`に設定して Map 状態をテストすると`DEBUG`、TestState API レスポンスには、Map 状態がデータを処理する方法を示す追加のフィールドが `inspectionData` オブジェクトに含まれます。
**注記**
`afterItemsPath` は、クエリ言語として JSONPath を使用する場合にのみ入力されます。
+ `afterItemsPath` (文字列) – ItemsPath フィルターが適用された後の有効な入力。これは、入力から抽出された項目の配列を示します。
+ `afterItemsPointer` (文字列) – ItemsPointer フィルターが適用された後の有効な入力。これは JSON 入力にのみ適用されます (JSONata ではありません）。
+ `afterItemSelector` (文字列の配列) – ItemSelector 変換が適用された後の入力値を含む配列。配列内の各要素は、変換された 1 つの項目を表します。このフィールドは、マップ状態をテストする場合にのみ存在します。
+ `afterItemBatcher` (文字列の配列) – ItemBatcher グループが適用された後の入力値を含む配列。これは、項目をバッチにグループ化する方法を示しています。このフィールドは、マップ状態をテストする場合にのみ存在します。
+ `toleratedFailureCount` (数値) – Map 状態の反復回数として表される Map 状態の許容失敗しきい値。この値は、ToleratedFailureCount で指定された値、または ToleratedFailureCountPath から実行時に評価された値から算出されます。
+ `toleratedFailurePercentage` (数値) – Map 状態の反復の割合で表される Map 状態の許容される障害しきい値。この値は、ToleratedFailurePercentage で指定された値、または ToleratedFailurePercentagePath から実行時に評価された値から算出されます。
+ `maxConcurrency` (数値) – Map 状態の最大同時実行数の設定。
これらのフィールドを使用すると、デプロイ前にマップ状態のデータ変換と障害耐性設定が正しく機能することを検証できます。
## TestState API でテストおよびアサートできる内容
TestState API を使用すると、ステートマシンの包括的なユニットテストを作成できます。ステートマシンロジックの複数の側面でアサートできます。これには、以下が含まれます。
+ [エラー処理: 適用するキャッチまたは再試行](#error-handling-catch-retry)
+ [データ変換: 入出力処理](#data-transformations-assert)
+ [マップ状態変換: ItemSelector、ItemsPath、ItemBatcher、ItemsPointer](#map-state-transformations-assert)
+ [マップ状態の障害しきい値: States.ExceedToleratedFailureThreshold のテスト](#map-failure-thresholds-assert)
+ [マップ状態と並列状態のエラー伝達](#error-propagation-assert)
### エラー処理: 適用するキャッチまたは再試行
エラーをモックするときは、TestState API を使用して、どのエラーハンドラーがアクティブ化されるかを確認できます。
キャッチブロックの場合、以下をアサートできます。
+ どのキャッチハンドラーがエラーをキャッチするか (レスポンス`catchIndex`で 経由)
+ 次の状態とは (レスポンス`nextState`で 経由)
+ エラーハンドラーに流れるデータ (ResultPath を考慮してレスポンス`output`で 経由)
再試行ブロックでは、以下をアサートできます。
+ どの再試行が適用されるか (レスポンス`retryIndex`で 経由)
+ バックオフ期間 (レスポンス`retryBackoffIntervalSeconds`で 経由)
+ 再試行が枯渇してエラーがキャッチされるかどうか
### データ変換: 入出力処理
TestState API を使用すると、処理の各段階で状態データの変換方法を検証できます。
以下に対してアサートできます。
+ InputPath フィルター後の入力 (`afterInputPath`)
+ パラメータ/引数変換後のデータ (`afterParameters` または `afterArguments`)
+ ResultSelector の後の結果 (`afterResultSelector`)
+ ResultPath の後の出力 (`afterResultPath`)
+ OutputPath 後の最終出力 (`output`)
### マップ状態変換: ItemSelector、ItemsPath、ItemBatcher、ItemsPointer
Map 状態の場合、TestState API を使用して、項目がどのように抽出および変換されるかを確認できます。
以下に対してアサートできます。
+ ItemsPath フィルター後の項目 (`afterItemsPath`)
+ ItemsPointer フィルター後の項目 (`afterItemsPointer`)
+ ItemSelector 変換後の項目 (`afterItemSelector`)
+ ItemBatcher グループ化後の項目 (`afterItemBatcher`)
### マップ状態の障害しきい値: States.ExceedToleratedFailureThreshold のテスト
特定の回数の失敗した反復が許容される失敗しきい値をトリガーするかどうかをテストします。
以下に対してアサートできます。
+ マップ状態が States.ExceedToleratedFailureThreshold で失敗するかどうか
### マップ状態と並列状態のエラー伝達
マップ状態または並列状態内で状態をテストすると、エラーは実際の実行時と同様に親状態エラーハンドラーに伝播されます。
#### errorCausedByState を使用したエラーソースの指定
マップ状態または並列状態のエラーをモックするときは、 `stateConfiguration.errorCausedByState`パラメータを使用してエラーの原因となったサブ状態を指定する必要があります。これは、 などのワイルドカードエラーをテストするときに特に重要です`States.TaskFailed`。 `States.TaskFailed`は、タスク状態の障害に適用されるワイルドカードエラーです。マップ状態または並列状態がこのエラーをどのように処理するかをテストするには、それをスローした特定のサブ状態を特定する必要があります。以下の例を参照してください。
```
aws stepfunctions test-state \
--definition '{...Map or Parallel state definition...}' \
--input '[...]' \
--state-configuration '{"errorCausedByState": "ProcessItem"}' \
--mock '{"errorOutput": {"error": "States.TaskFailed", "cause": "Task execution failed"}}'
```
この例では、 は、Map/Parallel ワークフロー内のProcessItem」状態がエラーをスローしたことを TestState `errorCausedByState`に伝えます。親マップ/並列状態のキャッチハンドラーまたは再試行ハンドラーは、実際の実行時と同じようにエラーを処理します。レスポンスの `nextState`フィールドには、エラーを検出したエラーハンドラーが表示されます。以下に対してアサートできます。
+ 子状態エラーが親 Catch ハンドラーによってキャッチされるかどうか
+ 子状態エラーが親再試行ポリシーをトリガーするかどうか
+ エラー伝播後の次の状態
## サービス統合のモッキング
TestState API は、サービス統合の結果のモックをサポートしているため、実際のAWSサービスを呼び出すことなくステートマシンロジックをテストできます。
### モックを使用するタイミング
モッキングは、次の場合に便利です。
+ ステートマシン定義を個別にユニットテストする
+ エラー処理と再試行ロジックのテスト
+ 入出力データ変換の検証
+ さまざまなサービスレスポンスとエラー条件のシミュレーション
+ IAM アクセス許可を設定せずにテストする
モックを指定すると、 `roleArn`パラメータはオプションになり、アクセス許可関連の問題に対処することなく、ステートマシン定義のテストに集中できます。
**注記**
マップ、並列、アクティビティ、.sync サービス統合、waitForTaskToken サービス統合などの状態タイプまたはサービス統合パターンをテストする必要がある場合は、モッキングが必要です。
### 基本的なモック構文
サービス統合結果をモックするには:
```
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`パラメータを使用して制御できます。
+ **STRICT (デフォルト)** – AWSAPI モデルからフィールドの命名、サイズ、シェイプ、データ型の制約を適用します。すべての必須フィールドが正しい型で存在している必要があります。このモードは、モックが実際のサービスレスポンスを正確に表すのに役立ちます。
+ **PRESENT** – モックに存在するフィールドのみを検証します。不明なフィールドは無視されます。このモードは、柔軟性はあるものの、既知のフィールドでの検証が必要な場合に便利です。
+ **NONE** – 検証を完全にスキップします。実際の実行とは異なる誤ったテストの仮定や動作につながる可能性があるため、注意が必要です。
**注記**
検証は、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 コール、および EKS RunJob 統合ではサポートされていません。
## マップと並列状態のテスト
TestState API は、モックが指定されている場合のマップ状態と並列状態のテストをサポートしています。これにより、これらのフロー状態の入出力処理をテストできます。
### マップ状態テストについて
TestState API を使用してマップ状態をテストする場合、内部で反復を実行せずにマップ状態の入力および出力処理をテストします。このアプローチにより、以下をテストできます。
+ ItemsPath または ItemsPointer 入力からの抽出
+ 各項目に適用される ItemSelector 変換
+ ItemBatcher のグループ化 (指定されている場合)
+ マップ状態の出力処理 (ResultPath、OutputPath)
+ 許容される失敗しきい値
ItemProcessor (各項目を処理する状態) 内で何が起こるかをテストしていません。
### マップ状態のテスト
Map 状態をテストする場合、モック結果は Map 状態全体の出力を表す必要があります。モック結果は、マップ状態設定に応じて有効な JSON 配列または JSON オブジェクトである必要があります。以下の例を参照してください。
```
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 が ItemReader を使用して S3 から読み取る場合は、データを (S3 から既に読み取られているかのように) 入力に直接入力します。例えば、次のようになります。
```
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": "..."}'
```
**注記**
分散マップ状態 (モードを DISTRIBUTED に設定) をテストする場合、mapIterationFailureCount でアサートすることもできます。このフィールドの値は、入力内の項目数、またはマップ内の状態をテストするときの項目数を超えることはできません。
### 自動コンテキストポピュレーション
`context` パラメータを指定せずにマップ状態 ( `stateName`パラメータを使用) の状態をテストすると、TestState は Context オブジェクトにデフォルト値を自動的に入力します。これには、次のようなマップ固有のコンテキストフィールドが含まれます。
+ `$$.Map.Item.Index` = `0` (最初の反復)
+ `$$.Map.Item.Value` = 入力値
+ `$$.Map.Item.Key` (特定の ItemReader 設定の分散マップの場合)
+ `$$.Map.Item.Source` (項目のソースを示す分散マップの場合)
### 並列状態のテスト
並列状態をテストする場合、モック結果はブランチごとに 1 つの要素を持つ JSON 配列で、定義に表示されるのと同じ順序である必要があります。
## Activity、.sync、.waitForTaskToken の状態のテスト
TestState API は、モックが指定されている場合、アクティビティ状態、.sync サービス統合パターン、.waitForTaskToken パターンのテストをサポートしています。モックがない場合、TestState API を介してこれらの状態を呼び出すと、検証例外が返されます。
**注記**
TestState API を使用して .sync 統合をテストする場合、モックレスポンスはポーリング API のスキーマに対して検証されます。たとえば、 をテストする場合`startExecution.sync:2`、モックは`DescribeExecution`レスポンスではなくレスポンススキーマ (ステータスをStep Functionsポーリングする) と一致する必要があります`StartExecution`。
## ステートマシン定義の反復処理
TestState API に完全なステートマシン定義を指定し、 `stateName`パラメータを使用してテストする状態を指定できます。これにより、ステートマシン全体のコンテキスト内で特定の状態をテストできます。1 つのテストから次のテストへの入力として、出力と nextState を使用してテストを連鎖させることもできます。これにより、ステートマシン内の部分的または完全な実行パスをテストできます。
## TestState API でのコンテキストフィールドの使用
`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
```
レスポンスには inspectionData にエラーの詳細が含まれます。
```
{
"status": "RETRIABLE",
"inspectionData": {
"errorDetails": {
"retryBackoffIntervalSeconds": 4,
"retryIndex": 0
}
}
}
```
このレスポンスは以下を示します。
+ エラーは再試行可能です (ステータス: RETRIABLE)
+ バックオフ期間は 4 秒 (2 × 2.0^1)
+ 最初の再試行 (インデックス 0) が適用されます
### キャッチハンドラーのテスト
エラーがモックされ、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\_ERROR)
+ 次の状態は HandleThrottling です。
+ エラー情報が ResultPath を介して出力に追加されます。
+ 最初のキャッチハンドラー (インデックス 0) がエラーを検出しました
コンテキストオブジェクトの RetryCount 値を増やすことで、すべての再試行回数が枯渇したときに何が起こるかをテストすることもできます。