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 |
|---|---|---|
|
|
@@ -137,7 +137,7 @@ LocalStack's Step Functions emulation supports the following AWS services: | |
|
|
||
| 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. | ||
|
|
@@ -148,66 +148,71 @@ During execution, each Task state defined in the mock file returns its correspon | |
| 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. | ||
|
|
@@ -273,7 +278,7 @@ In the example above: | |
| - `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: | ||
|
|
@@ -383,11 +388,10 @@ localstack start --volume /path/to/MockConfigFile.json:/tmp/MockConfigFile.json | |
| 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} | ||
|
|
@@ -399,8 +403,6 @@ services: | |
| {{< /tab >}} | ||
| {{< /tabpane >}} | ||
|
|
||
| ### Run Test Cases with Mocked Integrations | ||
|
|
||
| Create the state machine to match the name defined in the mock configuration file. | ||
|
|
@@ -413,15 +415,15 @@ $ awslocal stepfunctions create-state-machine \ | |
| --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 >}} | ||
|
|
@@ -433,15 +435,15 @@ You can inspect the execution using the [`DescribeExecution`](https://docs.aws.a | |
|
|
||
| {{< 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": "...", | ||
|
|
@@ -461,7 +463,7 @@ You can also use the [`GetExecutionHistory`](https://docs.aws.amazon.com/step-fu | |
|
|
||
| {{< 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. | ||
|
|
||
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/