This repository was archived by the owner on Aug 7, 2025. It is now read-only.
Add initial documentation for Step Functions mocked service integrations (v4.4) #1747
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -133,6 +133,375 @@ LocalStack's Step Functions emulation supports the following AWS services: | |
| | | AWS Batch | ✓ | ✓ | | | | ||
| | AWS SDK integrations | All LocalStack services | ✓ | | | ✓ | | ||
|
|
||
| ## Mocked Service Integrations | ||
|
|
||
| Mocked service integrations allow you to test AWS Step Functions without calling LocalStack's emulated AWS services. | ||
|
||
| Instead, Task states return predefined outputs from a mock configuration file. | ||
| The key components are: | ||
|
|
||
| - **Mocked service integrations**: Task states that return predefined responses instead of invoking local AWS services. | ||
| - **Mocked responses**: Static payloads associated with mocked Task states. | ||
| - **Test cases**: State machine executions using mocked responses. | ||
| - **Mock configuration file**: JSON file that defines test cases, mocked states, and their response payloads. | ||
|
|
||
| During execution, each Task state defined in the mock file returns its corresponding mocked response. | ||
| States not listed continue to invoke their real emulated services, allowing a mix of mocked and live interactions. | ||
|
||
|
|
||
| You can provide one or more mocked payloads per Task state. | ||
| The Supported patterns include `.sync`, `.sync2`, and `.waitForTaskToken`. | ||
|
||
| Both success and failure scenarios can be simulated. | ||
|
|
||
| ### Compatibility with AWS Step Functions Local | ||
|
|
||
| LocalStack can also serve as a drop-in replacement for [AWS Step Functions Local testing with mocked service integrations](https://docs.aws.amazon.com/step-functions/latest/dg/sfn-local-test-sm-exec.html). | ||
| It supports test cases with mocked Task states and maintains compatibility with existing Step Functions Local configurations. | ||
| This functionality is extended in LocalStack by providing access to the latest Step Functions features such as [JSONata and Variables](https://blog.localstack.cloud/aws-step-functions-made-easy/), as well as the ability to enable both mocked and emulated service interactions emulated by LocalStack. | ||
|
|
||
| {{< callout >}} | ||
| LocalStack does not validate response formats. | ||
| Ensure the payload structure in the mocked responses matches what the real service expects. | ||
| {{< /callout >}} | ||
|
|
||
| ### Identify a State Machine for Mocked Integrations | ||
|
|
||
| Mocked service integrations apply to specific state machine definitions. | ||
| The first step is to select the state machine where mocked responses will be used. | ||
|
|
||
| In this example, the state machine with the name `LambdaSQSIntegration` state machine will be used with the following definition: | ||
|
|
||
| ```json | ||
| { | ||
| "Comment": "This state machine is called: LambdaSQSIntegration", | ||
| "QueryLanguage": "JSONata", | ||
| "StartAt": "LambdaState", | ||
| "States": { | ||
| "LambdaState": { | ||
| "Type": "Task", | ||
| "Resource": "arn:aws:states:::lambda:invoke", | ||
| "Arguments": { | ||
| "FunctionName": "GreetingsFunction", | ||
| "Payload": { | ||
| "fullname": "{% $states.input.name & ' ' & $states.input.surname %}" | ||
| } | ||
| }, | ||
| "Retry": [ | ||
| { | ||
| "ErrorEquals": [ "States.ALL" ], | ||
| "IntervalSeconds": 2, | ||
| "MaxAttempts": 4, | ||
| "BackoffRate": 2 | ||
| } | ||
| ], | ||
| "Assign": { | ||
| "greeting": "{% $states.result.Payload.greeting %}" | ||
| }, | ||
| "Next": "SQSState" | ||
| }, | ||
| "SQSState": { | ||
| "Type": "Task", | ||
| "Resource": "arn:aws:states:::sqs:sendMessage", | ||
| "Arguments": { | ||
| "QueueUrl": "http://sqs.us-east-1.localhost.localstack.cloud:4566/000000000000/localstack-queue", | ||
| "MessageBody": "{% $greeting %}" | ||
| }, | ||
| "End": true | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| ### Define Mock Integrations in a Configuration File | ||
|
|
||
| Mock integrations are defined in a JSON file with two top-level section: | ||
|
|
||
| - **StateMachines** – Maps each state machine to its test cases, specifying which states use which mocked responses. | ||
| - **MockedResponses** – Defines reusable mock payloads identified by `ResponseID`, which test cases refer to. | ||
|
|
||
| #### `StateMachines` | ||
|
|
||
| This section specifies the Step Functions state machines to mock and their test cases. | ||
| Each test case maps state names to response IDs defined in `MockedResponses`. | ||
|
|
||
| ```json | ||
| "StateMachines": { | ||
| "<StateMachineName>": { | ||
| "TestCases": { | ||
| "<TestCaseName>": { | ||
| "<StateName>": "<ResponseID>", | ||
| ... | ||
| } | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| In the example above: | ||
|
|
||
| - `StateMachineName`: Must match the exact name used during creation in LocalStack. | ||
| - `TestCases`: Named scenarios that define mocked behavior for individual states. | ||
|
|
||
| Each test case maps Task states to mock responses that define expected behavior. | ||
| At runtime, if a test case is selected, the state uses the mock response if defined; otherwise, it calls the emulated service. | ||
|
|
||
| Here is a full example of the `StateMachines` section: | ||
|
|
||
| ```json | ||
| "LambdaSQSIntegration": { | ||
| "TestCases": { | ||
| "LambdaRetryCase": { | ||
| "LambdaState": "MockedLambdaStateRetry", | ||
| "SQSState": "MockedSQSStateSuccess" | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| #### `MockedResponses` | ||
|
|
||
| This section defines mocked responses for Task states. | ||
| Each `ResponseID` contains one or more step keys and either a `Return` or `Throw`. | ||
|
|
||
| ```json | ||
| "MockedResponses": { | ||
| "<ResponseID>": { | ||
| "<step-key>": { "Return": ... }, | ||
| "<step-key>": { "Throw": ... } | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| In the example above: | ||
|
|
||
| - `ResponseID`: Unique identifier referenced in test cases. | ||
| - `step-key`: Indicates the attempt (e.g., `"0"` for first try, `"1-2"` for a range). | ||
| - `Return`: Simulates success with a response payload. | ||
| - `Throw`: Simulates failure with `Error` and `Cause`. | ||
|
|
||
| {{< callout >}} | ||
| Each entry must have **either** `Return` or `Throw`, but cannot have both. | ||
| {{< /callout >}} | ||
|
|
||
| Here is a full example of the `MockedResponses` section: | ||
|
|
||
| ```json | ||
| "MockedLambdaStateRetry": { | ||
| "0": { | ||
| "Throw": { | ||
| "Error": "Lambda.ServiceException", | ||
| "Cause": "An internal service error occurred." | ||
| } | ||
| }, | ||
| "1-2": { | ||
| "Throw": { | ||
| "Error": "Lambda.TooManyRequestsException", | ||
| "Cause": "Invocation rate limit exceeded." | ||
| } | ||
| }, | ||
| "3": { | ||
| "Return": { | ||
| "StatusCode": 200, | ||
| "Payload": { | ||
| "greeting": "Hello John Smith, you’re now testing mocked integrations with LocalStack!" | ||
| } | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| The `MockConfigFile.json` below is used to test the `LambdaSQSIntegration` state machine defined earlier. | ||
|
|
||
| ```json | ||
| { | ||
| "StateMachines":{ | ||
| "LambdaSQSIntegration":{ | ||
| "TestCases":{ | ||
| "BaseCase":{ | ||
| "LambdaState":"MockedLambdaStateSuccess", | ||
| "SQSState":"MockedSQSStateSuccess" | ||
| }, | ||
| "LambdaRetryCase":{ | ||
| "LambdaState":"MockedLambdaStateRetry", | ||
| "SQSState":"MockedSQSStateSuccess" | ||
| }, | ||
| "HybridCase":{ | ||
| "LambdaState":"MockedLambdaSuccess" | ||
| } | ||
| } | ||
| } | ||
| }, | ||
| "MockedResponses":{ | ||
| "MockedLambdaStateSuccess":{ | ||
| "0":{ | ||
| "Return":{ | ||
| "StatusCode":200, | ||
| "Payload":{ | ||
| "greeting":"Hello John Smith, you’re now testing mocked integrations with LocalStack!" | ||
| } | ||
| } | ||
| } | ||
| }, | ||
| "MockedSQSStateSuccess":{ | ||
| "0":{ | ||
| "Return":{ | ||
| "MD5OfMessageBody":"3661896f-1287-45a3-8f89-53bd7b25a9a6", | ||
| "MessageId":"7c9ef661-c455-4779-a9c2-278531e231c2" | ||
| } | ||
| } | ||
| }, | ||
| "MockedLambdaStateRetry":{ | ||
| "0":{ | ||
| "Throw":{ | ||
| "Error":"Lambda.ServiceException", | ||
| "Cause":"An internal service error occurred." | ||
| } | ||
| }, | ||
| "1-2":{ | ||
| "Throw":{ | ||
| "Error":"Lambda.TooManyRequestsException", | ||
| "Cause":"Invocation rate limit exceeded." | ||
| } | ||
| }, | ||
| "3":{ | ||
| "Return":{ | ||
| "StatusCode":200, | ||
| "Payload":{ | ||
| "greeting":"Hello John Smith, you’re now testing mocked integrations with LocalStack!" | ||
| } | ||
| } | ||
| } | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| ### Provide the Mock Configuration to LocalStack | ||
|
|
||
| Set the `SFN_MOCK_CONFIG` configuration variable to the path of the mock configuration file. | ||
|
||
| When running LocalStack in Docker, mount the file and pass the variable as shown below: | ||
|
|
||
| {{< tabpane >}} | ||
| {{< tab header="LocalStack CLI" lang="shell" >}} | ||
| LOCALSTACK_SFN_MOCK_CONFIG=/tmp/MockConfigFile.json \ | ||
| localstack start --volume /path/to/MockConfigFile.json:/tmp/MockConfigFile.json | ||
| {{< /tab >}} | ||
| {{< tab header="Docker Compose" lang="yaml" >}} | ||
| services: | ||
| localstack: | ||
| container_name: "${LOCALSTACK_DOCKER_NAME:-localstack-main}" | ||
| image: localstack/localstack | ||
| ports: | ||
| - "127.0.0.1:4566:4566" # LocalStack Gateway | ||
| - "127.0.0.1:4510-4559:4510-4559" # external services port range | ||
| environment: | ||
| # LocalStack configuration: https://docs.localstack.cloud/references/configuration/ | ||
| - DEBUG=${DEBUG:-0} | ||
| - SFN_MOCK_CONFIG=/tmp/MockConfigFile.json | ||
| volumes: | ||
| - "${LOCALSTACK_VOLUME_DIR:-./volume}:/var/lib/localstack" | ||
| - "/var/run/docker.sock:/var/run/docker.sock" | ||
| - "./MockConfigFile.json:/tmp/MockConfigFile.json" | ||
| {{< /tab >}} | ||
| {{< /tabpane >}} | ||
|
|
||
| ### Run Test Cases with Mocked Integrations | ||
|
|
||
| Create the state machine to match the name defined in the mock configuration file. | ||
| In this example, create the `LambdaSQSIntegration` state machine using: | ||
|
|
||
| {{< command >}} | ||
| $ awslocal stepfunctions create-state-machine \ | ||
| --definition file://LambdaSQSIntegration.json \ | ||
| --name "LambdaSQSIntegration" \ | ||
| --role-arn "arn:aws:iam::000000000000:role/service-role/testrole" | ||
| {{< /command >}} | ||
|
|
||
| After the state machine is created and named correctly, test cases from the mock configuration file can be run using the [`StartExecution`](https://docs.aws.amazon.com/step-functions/latest/apireference/API_StartExecution.html) API. | ||
|
|
||
| To execute a test case, append the test case name to the state machine ARN using `#`. | ||
| This tells LocalStack to apply the mocked responses from the configuration file. | ||
| For example, run the `BaseCase` test case: | ||
|
|
||
| {{< command >}} | ||
| $ awslocal stepfunctions start-execution \ | ||
| --state-machine arn:aws:states:us-east-1:000000000000:stateMachine:LambdaSQSIntegration#BaseCase \ | ||
| --input '{"name": "John", "surname": "smith"}' \ | ||
| --name "MockExecutionBaseCase" | ||
| {{< /command >}} | ||
|
|
||
| During execution, any state mapped in the mock config will use the predefined response. | ||
| States without mock entries invoke the actual emulated service as usual. | ||
|
|
||
| You can inspect the execution using the [`DescribeExecution`](https://docs.aws.amazon.com/step-functions/latest/apireference/API_DescribeExecution.html) API: | ||
|
|
||
| {{< command >}} | ||
| $ awslocal stepfunctions describe-execution \ | ||
| --execution-arn "arn:aws:states:us-east-1:000000000000:execution:LambdaSQSIntegration:MockExecutionBaseCase" | ||
| {{< /command >}} | ||
|
|
||
| The sample output shows the execution details, including the state machine ARN, execution ARN, status, start and stop dates, input, and output: | ||
|
|
||
| ```json | ||
| { | ||
| "executionArn": "arn:aws:states:us-east-1:000000000000:execution:LambdaSQSIntegration:MockExecutionBaseCase", | ||
| "stateMachineArn": "arn:aws:states:us-east-1:000000000000:stateMachine:LambdaSQSIntegration", | ||
| "name": "MockExecutionBaseCase", | ||
| "status": "SUCCEEDED", | ||
| "startDate": "...", | ||
| "stopDate": "...", | ||
| "input": "{\"name\":\"John\",\"surname\":\"smith\"}", | ||
| "inputDetails": { | ||
| "included": true | ||
| }, | ||
| "output": "{\"MessageId\":\"7c9ef661-c455-4779-a9c2-278531e231c2\",\"MD5OfMessageBody\":\"3661896f-1287-45a3-8f89-53bd7b25a9a6\"}", | ||
| "outputDetails": { | ||
| "included": true | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| You can also use the [`GetExecutionHistory`](https://docs.aws.amazon.com/step-functions/latest/apireference/API_GetExecutionHistory.html) API to retrieve the execution history, including the events and their details. | ||
|
|
||
| {{< command >}} | ||
| $ awslocal stepfunctions get-execution-history \ | ||
| --execution-arn "arn:aws:states:us-east-1:000000000000:execution:LambdaSQSIntegration:MockExecutionBaseCase" | ||
| {{< /command >}} | ||
|
|
||
| This will return the full execution history, including entries that indicate how the mocked responses were applied to the Lambda and SQS states. | ||
|
|
||
| ```json | ||
| ... | ||
| { | ||
| "timestamp": "...", | ||
| "type": "TaskSucceeded", | ||
| "id": 5, | ||
| "previousEventId": 4, | ||
| "taskSucceededEventDetails": { | ||
| "resourceType": "lambda", | ||
| "resource": "invoke", | ||
| "output": "{\"StatusCode\": 200, \"Payload\": {\"greeting\": \"Hello John Smith, you\\u2019re now testing mocked integrations with LocalStack!\"}}", | ||
| "outputDetails": { | ||
| "truncated": false | ||
| } | ||
| } | ||
| } | ||
| ... | ||
| { | ||
| "timestamp": "...", | ||
| "type": "TaskSucceeded", | ||
| "id": 10, | ||
| "previousEventId": 9, | ||
| "taskSucceededEventDetails": { | ||
| "resourceType": "sqs", | ||
| "resource": "sendMessage", | ||
| "output": "{\"MessageId\": \"7c9ef661-c455-4779-a9c2-278531e231c2\", \"MD5OfMessageBody\": \"3661896f-1287-45a3-8f89-53bd7b25a9a6\"}", | ||
| "outputDetails": { | ||
| "truncated": false | ||
| } | ||
| } | ||
| } | ||
| ... | ||
| ``` | ||
|
|
||
| ## Resource Browser | ||
|
|
||
| The LocalStack Web Application provides a Resource Browser for managing Step Functions state machines. | ||
|
|
||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
💡 idea (for future): Would a standardized default value within the container simplify the setup, because then users only need to provide the volume mount?
We might want to standardize this following the LocalStack file system layout: https://docs.localstack.cloud/references/filesystem/