AWS Step Functions Local: Mocking Services, HTTP Endpoints Limitations

AWS Step Functions Local is a useful tool for testing workflows without deploying them to the cloud. It allows developers to run state machines locally using Docker, enabling faster iteration and debugging. 

However, while testing our Step Function locally, we encountered significant limitations, particularly when trying to mock an http:endpoint task.

Issue: HTTP Task Mocking Not Supported in Step Functions Local

During our local testing, we successfully mocked various AWS services, such as:

• AWS Lambda
• Parallel execution tasks
•  Choice states

However, when attempting to mock an http:endpoint task, we encountered the following error:

{
  "Type": "ExecutionFailed",
  "PreviousEventId": 7,
  "ExecutionFailedEventDetails": {
    "Error": "States.Runtime",
    "Cause": "An error occurred while scheduling the state 'Create ******'. The provided ARN 'arn:aws:states:us-east-1:123456789012:http:invoke' is invalid. Please refer to Integrating optimized services with Step Functions - AWS Step Functions for valid service ARNs."
  }
}

This error indicates that AWS Step Functions Local does not support http:endpoint tasks, despite being able to mock other AWS-integrated services.

AWS Support's Response

We reached out to AWS Support regarding this limitation, and they confirmed that:

• Step Functions Local is outdated and does not fully support all features available in the cloud.
• The HTTP Task feature is not supported in the current local version.
• AWS has no specific timeline for when a new version will support this feature.
• AWS recommends using the Test State API for testing state machines and HTTP task states instead of relying on Step Functions Local.

Other Unsupported Services in Step Functions Local

If you are relying on Step Functions Local for testing, keep in mind that several AWS services may not be fully supported or mockable. Some of these include:

• HTTP Endpoints (http:endpoint task)
•  DynamoDB Streams
•  Certain AWS SDK integrations
•  EventBridge and SNS in some scenarios

Alternative Approaches

Given these limitations, here are some alternative strategies for testing AWS Step Functions:

1. Use AWS Test State API

AWS recently introduced the Test State API, which allows you to test individual states within a state machine. Example 3 in the official AWS documentation provides guidance on testing HTTP Task states.

2. Deploy to a Sandbox AWS Account

If you need to test full Step Function execution, consider deploying it to a dedicated AWS sandbox account. This ensures that all services are available while keeping costs low.

3. Use Local AWS Mocks (Where Applicable)

For services like Lambda, S3, and DynamoDB, you can use:

• LocalStack for simulating AWS services
• Moto (for Python) or AWS SDK Mocks (for JavaScript) to mock API responses

Final Thoughts

While AWS Step Functions Local is useful for basic testing, it does not fully support all AWS services and integrations. If your workflow relies on http:endpoint or other unsupported services, you may need to use the Test State API, deploy to AWS for testing, or explore alternative mocking strategies.

Have you faced similar limitations while testing AWS Step Functions locally? Let us know in the comments!