Add initial documentation for Step Functions mocked service integrations (v4.4) #1747

MEPalma · 2025-04-30T20:17:24Z

This PR adds initial documentation for the AWS Step Functions mocked service integrations feature, introduced in LocalStack v4.4. The new docs cover the basic structure and usage of mock configuration files, including test cases and mocked responses. Future updates will expand on this foundation with LocalStack usage examples, detailed behavioral notes, and advanced mock scenarios.

github-actions · 2025-04-30T20:17:37Z

🎊 PR Preview has been successfully built and deployed to https://localstack-docs-preview-pr-1747.surge.sh 🎊

joe4dev

That's a comprehensive example for the Step Functions mocking feature, kinda like a full announcement blog post 👏

My main suggestions are:

clarifying the connection to the AWS mocking feature or motivating (in the PR description) why not. Can/should we link to AWS documentation instead of re-documenting what the AWS documentation already provides for advanced features?
add the new configuration SFN_MOCK_CONFIG to the config docs

Otherwise, I added several minor suggestions.

I tested the example and can confirm it works (after adjusting the ARNs to using us-east-1).

Sidenote: the preview link https://localstack-docs-preview-pr-1747.surge.sh/user-guide/aws/stepfunctions/ didn't render for me (maybe outdated), but I can confirm rendering works locally.

joe4dev · 2025-05-05T12:35:54Z

content/en/user-guide/aws/stepfunctions/index.md

+
+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.
+They key components are:


joe4dev · 2025-05-05T12:39:42Z

content/en/user-guide/aws/stepfunctions/index.md


+## Mocked Service Integrations
+
+Mocked service integrations allow you to test AWS Step Functions without calling LocalStack's emulated AWS services.


Would it be helpful to link the AWS documentation from StepFunctions Local here? https://docs.aws.amazon.com/step-functions/latest/dg/sfn-local-test-sm-exec.html
Knowing that we are providing a drop-in replacement seems pretty relevant here, given that it was one of the primary reasons why we built this feature.

(or their announcement blog: https://aws.amazon.com/blogs/compute/mocking-service-integrations-with-aws-step-functions-local/)

Absolutely; I added a Compatibility with AWS Step Functions Local paragraph

Well done highlighting the strengths of LocalStack beyond what SFN local can provide 👏 🥇

joe4dev · 2025-05-05T12:43:01Z

content/en/user-guide/aws/stepfunctions/index.md

+- **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.


praise: great clarification ✨

joe4dev · 2025-05-05T12:43:28Z

content/en/user-guide/aws/stepfunctions/index.md

+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.
+Supported patterns include `.sync`, `.sync2`, and `.waitForTaskToken`.


The supported ...

joe4dev · 2025-05-05T12:44:36Z

content/en/user-guide/aws/stepfunctions/index.md

+
+{{< callout >}}
+LocalStack does not validate response formats.
+Ensure the payload structure matches what the real service expects.


Shall we clarify?

payload structure in the mocked responses matches

joe4dev · 2025-05-05T12:57:08Z

content/en/user-guide/aws/stepfunctions/index.md

+services:
+  localstack:
+    container_name: "${LOCALSTACK_DOCKER_NAME:-localstack-main}"
+    image: localstack/localstack-pro


Are we intentionally using the pro image for showcasing a community feature?
Using the community compose could simplify things a bit.

I used the pro image as it is used for the LDM, but I agree this is best if presented with the community version

joe4dev · 2025-05-05T12:58:31Z

content/en/user-guide/aws/stepfunctions/index.md

+
+### Provide the Mock Configuration to LocalStack
+
+Set the `SFN_MOCK_CONFIG` configuration variable to the path of the mock configuration file.  


Can we document SFN_MOCK_CONFIG in the configuration section as well?

joe4dev · 2025-05-05T13:01:04Z

content/en/user-guide/aws/stepfunctions/index.md

+{{< /tab >}}
+{{< /tabpane >}}
+
+This tells LocalStack to use the specified file for mocked service integrations during Step Functions execution.


Does this sentence after the code pane add extra value?
suggestion: better specify any preview (what it does) and required information before the code section.

joe4dev · 2025-05-05T13:44:10Z

content/en/user-guide/aws/stepfunctions/index.md

+    --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) or [StartSyncExecution](https://docs.aws.amazon.com/step-functions/latest/apireference/API_StartSyncExecution.html) APIs.


nit: intentional ` and non-` ?

joe4dev · 2025-05-05T13:53:45Z

content/en/user-guide/aws/stepfunctions/index.md

+
+{{< command >}}
+$ awslocal stepfunctions start-execution \
+    --state-machine arn:aws:states:ca-central-1:000000000000:stateMachine:LambdaSQSIntegration#BaseCase \


Would it make sense to adopt the default LocalStack region us-east-1 everywhere?

joe4dev

LGTM. Thank you for polishing ✨ @MEPalma

Waiting for 👀 from docs maintainers 🚀

joe4dev · 2025-05-06T14:51:30Z

content/en/user-guide/aws/stepfunctions/index.md


 You can provide one or more mocked payloads per Task state.
-Supported patterns include `.sync`, `.sync2`, and `.waitForTaskToken`.
+The Supported patterns include `.sync`, `.sync2`, and `.waitForTaskToken`.


typo: The supported

joe4dev · 2025-05-06T14:55:07Z

content/en/references/configuration.md

+
+| Variable | Example Values | Description |
+| - | - | - |
+| `SFN_MOCK_CONFIG` | `/tmp/MockConfigFile.json` | Specifies the file path to the mock configuration file that defines mock service integrations for Step Functions. |


💡 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/

joe4dev · 2025-05-06T14:56:37Z

content/en/user-guide/aws/stepfunctions/index.md


+## Mocked Service Integrations
+
+Mocked service integrations allow you to test AWS Step Functions without calling LocalStack's emulated AWS services.


Well done highlighting the strengths of LocalStack beyond what SFN local can provide 👏 🥇

quetzalliwrites

quetzalliwrites · 2025-05-08T00:59:37Z

I've reviewed the doc preview and it looks good to merge:
https://localstack-docs-preview-pr-1747.surge.sh/user-guide/aws/stepfunctions/

initial documentation on step functions mock

176484f

MEPalma added the documentation Improvements or additions to documentation label Apr 30, 2025

MEPalma self-assigned this Apr 30, 2025

MEPalma added 4 commits April 30, 2025 22:24

lint

cb67c29

more lints

49c24e0

more lints

3f194a6

minor

6f7bbec

HarshCasper requested review from HarshCasper and quetzalliwrites May 1, 2025 11:31

push some improvements

b21cbec

HarshCasper requested review from gregfurman and joe4dev as code owners May 1, 2025 12:34

joe4dev approved these changes May 5, 2025

View reviewed changes

pr items

efe83c8

MEPalma requested a review from joe4dev May 6, 2025 11:14

joe4dev approved these changes May 6, 2025

View reviewed changes

MEPalma and others added 3 commits May 7, 2025 09:29

fix caps

947c3cd

improved mocked service integrations section

da6fd0e

improved more stuff

9c39030

quetzalliwrites approved these changes May 8, 2025

View reviewed changes

quetzalliwrites merged commit a7b2b06 into main May 8, 2025
3 of 5 checks passed

quetzalliwrites deleted the MEP-SFN-initial_sfn_mock branch May 8, 2025 01:00


		## Mocked Service Integrations

		Mocked service integrations allow you to test AWS Step Functions without calling LocalStack's emulated AWS services.


		### Provide the Mock Configuration to LocalStack

		Set the `SFN_MOCK_CONFIG` configuration variable to the path of the mock configuration file.

Add initial documentation for Step Functions mocked service integrations (v4.4) #1747

Add initial documentation for Step Functions mocked service integrations (v4.4) #1747

Uh oh!

Conversation

MEPalma commented Apr 30, 2025

Uh oh!

github-actions bot commented Apr 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

joe4dev left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

joe4dev left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

quetzalliwrites left a comment

Choose a reason for hiding this comment

Uh oh!

quetzalliwrites commented May 8, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

github-actions bot commented Apr 30, 2025 •

edited

Loading