このトピックの主要概念ステップ 1: モック設定ファイルでモックサービス統合を指定するステップ 2: Step Functions Local にモック設定ファイルを提供するステップ 3: モックサービス統合テストを実行する

モックサービス統合の使用

Step Functions Local では、モックサービス統合を使用して、統合サービスを実際に呼び出さなくてもステートマシンの実行パスをテストできます。モックサービス統合を使用するようにステートマシンを設定するには、モック設定ファイルを作成します。このファイルでは、サービス統合に必要な出力をモックレスポンスとして定義し、モックレスポンスを使用して実行パスをシミュレートする実行をテストケースとして定義します。

Step Functions Local にモック設定ファイルを提供して、実際のサービス統合呼び出しを行う代わりに、テストケースで指定されたモックレスポンスを使用するステートマシンを実行して、サービス統合呼び出しをテストできます。

注記

モック設定ファイルでモックサービス統合レスポンスを指定しない場合、Step Functions Local は Step Functions Local のセットアップ時に設定したエンドポイントを使用して AWS サービス統合を呼び出します。Step Functions Local のエンドポイントの設定については、「Step Functions Local の設定オプションを指定する」を参照してください。

トピック

このトピックの主要概念
ステップ 1: モック設定ファイルでモックサービス統合を指定する
ステップ 2: Step Functions Local にモック設定ファイルを提供する
ステップ 3: モックサービス統合テストを実行する
モックサービス統合の設定ファイル

このトピックの主要概念

このトピックでは、以下のリストに定義されているいくつかの概念を使用しています。

モックサービス統合 - 実際のサービス呼び出しを実行する代わりにモックレスポンスを使用するように設定された Task ステートを指します。
モックレスポンス - Task ステートが使用するように設定できるモックデータを指します。
テストケース - モックサービス統合を使用するように設定されたステートマシン実行を指します。
モック設定ファイル - JSON を含むモック設定ファイルを指します。JSON はモックサービス統合、モックレスポンス、テストケースを定義します。

ステップ 1: モック設定ファイルでモックサービス統合を指定する

Step Functions AWS SDK と最適化されたサービス統合は、Step Functions Local を使用してテストできます。以下のイメージは、[ステートマシンの定義] タブで定義されているステートマシンを示しています。

そのためには、モック設定の構造の紹介で定義されているセクションを含むモック設定ファイルを作成する必要があります。

モックサービス統合を含むテストを設定するための MockConfigFile.json という名前のファイルを作成します。

次の例は、LambdaState と SQSState という名前の 2 つのステートが定義されているステートマシンを参照するモック設定ファイルを示しています。
Mock configuration file example
以下は、Lambda 関数を呼び出して Amazon SQS にメッセージを送信するレスポンスをモックする方法を示すモック設定ファイルの例です。この例では、LambdaSQSIntegration ステートマシンには、HappyPath、RetryPath、HybridPath という名前の 3 つのテストケースがあり、これらは LambdaState およびSQSState という名前の Task ステートをモックします。これらのステートは MockedLambdaSuccess、MockedSQSSuccess、MockedLambdaRetry およびモックサービスのレスポンスを使用します。これらのモックサービスのレスポンスはファイルの MockedResponses セクションで定義されています。
```
{
  "StateMachines":{
    "LambdaSQSIntegration":{
      "TestCases":{
        "HappyPath":{
          "LambdaState":"MockedLambdaSuccess",
          "SQSState":"MockedSQSSuccess"
        },
        "RetryPath":{
          "LambdaState":"MockedLambdaRetry",
          "SQSState":"MockedSQSSuccess"
        },
        "HybridPath":{
          "LambdaState":"MockedLambdaSuccess"
        }
      }
    }
  },
  "MockedResponses":{
    "MockedLambdaSuccess":{
      "0":{
        "Return":{
          "StatusCode":200,
          "Payload":{
            "StatusCode":200,
            "body":"Hello from Lambda!"
          }
        }
      }
    },
    "LambdaMockedResourceNotReady":{
      "0":{
        "Throw":{
          "Error":"Lambda.ResourceNotReadyException",
          "Cause":"Lambda resource is not ready."
        }
      }
    },
    "MockedSQSSuccess":{
      "0":{
        "Return":{
          "MD5OfMessageBody":"3bcb6e8e-7h85-4375-b0bc-1a59812c6e51",
          "MessageId":"3bcb6e8e-8b51-4375-b0bc-1a59812c6e51"
        }
      }
    },
    "MockedLambdaRetry":{
      "0":{
        "Throw":{
          "Error":"Lambda.ResourceNotReadyException",
          "Cause":"Lambda resource is not ready."
        }
      },
      "1-2":{
        "Throw":{
          "Error":"Lambda.TimeoutException",
          "Cause":"Lambda timed out."
        }
      },
      "3":{
        "Return":{
          "StatusCode":200,
          "Payload":{
            "StatusCode":200,
            "body":"Hello from Lambda!"
          }
        }
      }
    }
  }
}
```
State machine definition
以下は、LambdaState および SQSState という名前の 2 つのサービス統合タスクステートを定義する LambdaSQSIntegration というステートマシン定義の例です。LambdaState には、States.ALL に基づく再試行ポリシーが含まれています。
```
{
  "Comment":"This state machine is called: LambdaSQSIntegration",
  "StartAt":"LambdaState",
  "States":{
    "LambdaState":{
      "Type":"Task",
      "Resource":"arn:aws:states:::lambda:invoke",
      "Parameters":{
        "Payload.$":"$",
        "FunctionName":"HelloWorldFunction"
      },
      "Retry":[
        {
          "ErrorEquals":[
            "States.ALL"
          ],
          "IntervalSeconds":2,
          "MaxAttempts":3,
          "BackoffRate":2
        }
      ],
      "Next":"SQSState"
    },
    "SQSState":{
      "Type":"Task",
      "Resource":"arn:aws:states:::sqs:sendMessage",
      "Parameters":{
        "QueueUrl":"https://sqs.us-east-1.amazonaws.com/123456789012/myQueue",
        "MessageBody.$":"$"
      },
      "End": true
    }
  }
}
```
以下のテストケースのいずれかを使用して、モック設定ファイルで参照されている LambdaSQSIntegration ステートマシン定義を実行できます。
- HappyPath - このテストでは、それぞれ MockedLambdaSuccess と MockedSQSSuccess を使用して LambdaState と SQSState の出力をモックします。
  - LambdaState は次の値を返します。
    
    "0":{ "Return":{ "StatusCode":200, "Payload":{ "StatusCode":200, "body":"Hello from Lambda!" } } }
  - SQSState は次の値を返します。
    
    "0":{ "Return":{ "MD5OfMessageBody":"3bcb6e8e-7h85-4375-b0bc-1a59812c6e51", "MessageId":"3bcb6e8e-8b51-4375-b0bc-1a59812c6e51" } }
- RetryPath - このテストでは、それぞれ MockedLambdaRetry と MockedSQSSuccess を使用して LambdaState と SQSState の出力をモックします。また、LambdaState は 4 回再試行するように設定されています。これらの試行に対するモックレスポンスは MockedLambdaRetry ステートで定義され、インデックス化されます。
  - 最初の試行は、次の例に示すように、原因とエラーメッセージを含むタスク失敗で終了します。
    
    "0":{ "Throw": { "Error": "Lambda.ResourceNotReadyException", "Cause": "Lambda resource is not ready." } }
  - 1 回目と 2 回目の再試行は、次の例に示すように、原因とエラーメッセージを含むタスク失敗で終了します。
    
    "1-2":{ "Throw": { "Error": "Lambda.TimeoutException", "Cause": "Lambda timed out." } }
  - 3 回目の再試行は、モックされた Lambda レスポンスの Payload セクションからのステート結果を含むタスク成功で終了します。
    
    "3":{ "Return": { "StatusCode": 200, "Payload": { "StatusCode": 200, "body": "Hello from Lambda!" } } }
    
    注記
    
    再試行ポリシーが設定されているステートでは、Step Functions Local は成功レスポンスを受け取るまで、ポリシーに設定された再試行回数を使い果たします。つまり、モックの再試行を連続する試行回数で示し、成功レスポンスを返すまですべての再試行を実施する必要があります。
    再試行「3」のように、特定の再試行に対してモックレスポンスを指定しないと、ステートマシンの実行は失敗します。
- HybridPath - このテストは LambdaState の出力をモックします。LambdaState が正常に実行され、モックされたデータをレスポンスとして受信したら、SQSState は本番環境で指定されたリソースに対して実際のサービス呼び出しを実行します。
モックサービス統合を使用してテスト実行を開始する方法については、「ステップ 3: モックサービス統合テストを実行する」を参照してください。
モックレスポンスの構造が、統合サービス呼び出しを行うときに受け取る実際のサービスレスポンスの構造と一致していることを確認してください。モックレスポンスの構造要件については、「モックサービス統合の設定」を参照してください。

前述のモック設定ファイルの例では、MockedLambdaSuccess および MockedLambdaRetry で定義されたモック応答は、HelloFromLambda の呼び出しから返される実際の応答の構造に準拠しています。

重要
AWS サービスレスポンスの構造は、サービスによって異なる場合があります。Step Functions Local は、モックレスポンス構造が実際のサービスレスポンス構造に準拠しているかどうかを検証しません。テストする前に、モックレスポンスが実際のレスポンスと一致していることを確認する必要があります。サービスレスポンスの構造を確認するには、Step Functions を使用して実際のサービス呼び出しを実行するか、それらのサービスのドキュメントを参照してください。

ステップ 2: Step Functions Local にモック設定ファイルを提供する

Step Functions Local には、次のいずれかの方法でモック設定ファイルを提供できます。

Docker

注記

Docker バージョンの Step Functions Local を使用している場合、環境変数のみを使用してモック設定ファイルを指定できます。また、サーバーの初回起動時に Step Functions Local コンテナにモック設定ファイルをマウントする必要があります。

Step Functions Local コンテナ内の任意のディレクトリにモック設定ファイルをマウントします。次に、コンテナ内のモック設定ファイルへのパスを含む SFN_MOCK_CONFIG という名前の環境変数を設定します。この方法では、環境変数にファイルパスと名前が含まれている限り、モック設定ファイルに任意の名前を付けることができます。

以下のコマンドは Docker イメージを開始する形式を示しています。


docker run -p 8083:8083 
--mount type=bind,readonly,source={absolute path to mock config file},destination=/home/StepFunctionsLocal/MockConfigFile.json 
-e SFN_MOCK_CONFIG="/home/StepFunctionsLocal/MockConfigFile.json" amazon/aws-stepfunctions-local

次の例では、コマンドを使用して Docker イメージを開始します。


docker run -p 8083:8083 
--mount type=bind,readonly,source=/Users/admin/Desktop/workplace/MockConfigFile.json,destination=/home/StepFunctionsLocal/MockConfigFile.json 
-e SFN_MOCK_CONFIG="/home/StepFunctionsLocal/MockConfigFile.json" amazon/aws-stepfunctions-local

JAR File

以下のいずれかの方法を使用してモック設定ファイルを Step Functions Local に提供します。

モック設定ファイルを Step FunctionsLocal.jar と同じディレクトリに置きます。この方法を使用するときは、モック設定ファイル MockConfigFile.json に名前を付ける必要があります。
Step Functions Local を実行しているセッションで、SFN_MOCK_CONFIG という名前の環境変数をモック設定ファイルのフルパスに設定します。この方法では、環境変数にそのファイルパスと名前が含まれている限り、モック設定ファイルに任意の名前を付けることができます。次の例では、SFN_MOCK_CONFIG 変数は /home/workspace ディレクトリにある EnvSpecifiedMockConfig.json という名前のモック設定ファイルを指すように設定されています。
```
export SFN_MOCK_CONFIG="/home/workspace/EnvSpecifiedMockConfig.json"
```

注記

Step Functions Local に環境変数 SFN_MOCK_CONFIG を指定しない場合、デフォルトでは、Step Functions Local を起動したディレクトリにある MockConfigFile.json という名前のモック設定ファイルを読み込もうとします。
モック設定ファイルを Step FunctionsLocal.jar と同じディレクトリに配置して環境変数 SFN_MOCK_CONFIG を設定すると、Step Functions Local は環境変数で指定されたファイルを読み取ります。

ステップ 3: モックサービス統合テストを実行する

モック設定ファイルを作成して Step Functions Local に提供したら、モック設定ファイルに設定されたステートマシンをモックサービス統合を使用して実行します。次に API アクションを使用して実行結果を確認します。

モック設定ファイル内の前述の定義に基づいてステートマシンを作成します。


aws stepfunctions create-state-machine \
    --endpoint http://localhost:8083 \
    --definition "{\"Comment\":\"Thisstatemachineiscalled:LambdaSQSIntegration\",\"StartAt\":\"LambdaState\",\"States\":{\"LambdaState\":{\"Type\":\"Task\",\"Resource\":\"arn:aws:states:::lambda:invoke\",\"Parameters\":{\"Payload.$\":\"$\",\"FunctionName\":\"arn:aws:lambda:us-east-1:123456789012:function:HelloWorldFunction\"},\"Retry\":[{\"ErrorEquals\":[\"States.ALL\"],\"IntervalSeconds\":2,\"MaxAttempts\":3,\"BackoffRate\":2}],\"Next\":\"SQSState\"},\"SQSState\":{\"Type\":\"Task\",\"Resource\":\"arn:aws:states:::sqs:sendMessage\",\"Parameters\":{\"QueueUrl\":\"https://sqs.us-east-1.amazonaws.com/123456789012/myQueue\",\"MessageBody.$\":\"$\"},\"End\":true}}}" \
    --name "LambdaSQSIntegration" --role-arn "arn:aws:iam::123456789012:role/service-role/LambdaSQSIntegration"

モックサービス統合を使用してステートマシンを実行します。

モック設定ファイルを使用するには、モック設定ファイルに設定されているステートマシンで StartExecution API 呼び出しを行います。これを行うには、StartExecution が使用するステートマシン ARN にサフィックス、#test_name を追加します。test_name はテストケースで、同じモック設定ファイルでステートマシン用に設定されます。

以下のコマンドは、LambdaSQSIntegration ステートマシンとモックコンフィグレーションを使用する例です。この例では、ステップ 1: モック設定ファイルでモックサービス統合を指定するで定義された HappyPath テストを使用して LambdaSQSIntegration ステートマシンが実行されます。HappyPath テストには、LambdaState ステートおよび SQSState ステートが MockedLambdaSuccess および MockedSQSSuccess のモックサービスのレスポンスを使用して行うモックサービス統合呼び出しを処理するための実行設定が含まれています。
```
aws stepfunctions start-execution \
    --endpoint http://localhost:8083 \
    --name executionWithHappyPathMockedServices \
    --state-machine arn:aws:states:us-east-1:123456789012:stateMachine:LambdaSQSIntegration#HappyPath
```
ステートマシンの実行レスポンスを表示します。

モックサービス統合テストを使用した StartExecution の呼び出しに対するレスポンスは、通常の StartExecution の呼び出しに対するレスポンスと同じであり、実行 ARN と開始日を返します。

以下は、モックサービス統合テストを使用した StartExecution の呼び出しに対するレスポンスの例です。
```
{
   "startDate":"2022-01-28T15:03:16.981000-05:00",
   "executionArn":"arn:aws:states:us-east-1:123456789012:execution:LambdaSQSIntegration:executionWithHappyPathMockedServices"
}
```

ListExecutions、DescribeExecution、または GetExecutionHistory API の呼び出しを実行して、実行の結果を確認します。


aws stepfunctions get-execution-history \
    --endpoint http://localhost:8083 \
    --execution-arn arn:aws:states:us-east-1:123456789012:execution:LambdaSQSIntegration:executionWithHappyPathMockedServices

次の例は、ステップ 2 で示したレスポンス例の実行 ARN を使用して GetExecutionHistory の呼び出しに対する応答の一部を示しています。この例では、LambdaState と SQSState の出力は、モック設定ファイルの MockedLambdaSuccess と MockedSQSSuccess で定義されているモックデータです。また、モックデータは、実際のサービス統合呼び出しを実行して返されるデータと同じ方法で使用されます。また、この例では、LambdaState からの出力が入力として SQSState に渡されます。


{
    "events": [
        ...
        {
            "timestamp": "2021-12-02T19:39:48.988000+00:00",
            "type": "TaskStateEntered",
            "id": 2,
            "previousEventId": 0,
            "stateEnteredEventDetails": {
                "name": "LambdaState",
                "input": "{}",
                "inputDetails": {
                    "truncated": false
                }
            }
        },
        ...
        {
            "timestamp": "2021-11-25T23:39:10.587000+00:00",
            "type": "LambdaFunctionSucceeded",
            "id": 5,
            "previousEventId": 4,
            "lambdaFunctionSucceededEventDetails": {
                "output": "{\"statusCode\":200,\"body\":\"\\\"Hello from Lambda!\\\"\"}",
                "outputDetails": {
                    "truncated": false
                }
            }
        },
        ...
            "timestamp": "2021-12-02T19:39:49.464000+00:00",
            "type": "TaskStateEntered",
            "id": 7,
            "previousEventId": 6,
            "stateEnteredEventDetails": {
                "name": "SQSState",
                "input": "{\"statusCode\":200,\"body\":\"\\\"Hello from Lambda!\\\"\"}",
                "inputDetails": {
                    "truncated": false
                }
            }
        },
        ...
        {
            "timestamp": "2021-11-25T23:39:10.652000+00:00",
            "type": "TaskSucceeded",
            "id": 10,
            "previousEventId": 9,
            "taskSucceededEventDetails": {
                "resourceType": "sqs",
                "resource": "sendMessage",
                "output": "{\"MD5OfMessageBody\":\"3bcb6e8e-7h85-4375-b0bc-1a59812c6e51\",\"MessageId\":\"3bcb6e8e-8b51-4375-b0bc-1a59812c6e51\"}",
                "outputDetails": {
                    "truncated": false
                }
            }
        },
        ...
    ]
}

ブラウザで JavaScript が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

Step Functions と AWS SAM CLI Local のテスト

モックサービス統合の設定ファイル