Setting Up Step Functions Local and Docker Setting Up Step Functions Local - Java Version Configuring Step Functions Local Options Running Step Functions Local

Testing state machines with Step Functions Local (unsupported)

Step Functions Local is unsupported

Step Functions Local does not provide feature parity and is unsupported.

You might consider third party solutions that emulate Step Functions for testing purposes.

With AWS Step Functions Local, a downloadable version of Step Functions, you can test applications with Step Functions running in your own development environment.

When running Step Functions Local, you can use one of the following ways to invoke service integrations:

Configuring local endpoints for AWS Lambda and other services.
Making calls directly to an AWS service from Step Functions Local.
Mocking the response from service integrations.

AWS Step Functions Local is available as a JAR package or a self-contained Docker image that runs on Microsoft Windows, Linux, macOS, and other platforms that support Java or Docker.

Warning

You should only use Step Functions Local for testing and never to process sensitive information.

Topics

Setting Up Step Functions Local and Docker
Setting Up Step Functions Local - Java Version
Configuring Step Functions Local Options
Running Step Functions Local
Tutorial: Testing using Step Functions and AWS SAM CLI Local
Testing with mocked service integrations

Setting Up Step Functions Local (Downloadable Version) in Docker

The Step Functions Local Docker image enables you to get started with Step Functions Local quickly by using a Docker image with all the needed dependencies. The Docker image enables you to include Step Functions Local in your containerized builds and as part of your continuous integration testing.

To get the Docker image for Step Functions Local, see https://hub.docker.com/r/amazon/aws-stepfunctions-local, or enter the following Docker pull command.


docker pull amazon/aws-stepfunctions-local

To start the downloadable version of Step Functions on Docker, run the following Docker run command


docker run -p 8083:8083 amazon/aws-stepfunctions-local

To interact with AWS Lambda or other supported services, you need to configure your credentials and other configuration options first. For more information, see the following topics:

Setting Configuration Options for Step Functions Local
Credentials and configuration for Docker

Setting Up Step Functions Local (Downloadable Version) - Java Version

The downloadable version of AWS Step Functions is provided as an executable JAR file and as a Docker image. The Java application runs on Windows, Linux, macOS, and other platforms that support Java. In addition to Java, you need to install the AWS Command Line Interface (AWS CLI). For information about installing and configuring the AWS CLI, see the AWS Command Line Interface User Guide.

To set up and run Step Functions on your computer

Download Step Functions using the following links.

Download Links	Checksum
.tar.gz	.tar.gz.md5
.zip	.zip.md5

Extract the .zip file.

Test the download and view version information.


$ java -jar StepFunctionsLocal.jar -v
Step Function Local
Version: 2.0.0
Build: 2024-05-18

(Optional) View a listing of available commands.
```
$ java -jar StepFunctionsLocal.jar -h
```
To start Step Functions on your computer, open a command prompt, navigate to the directory where you extracted StepFunctionsLocal.jar, and enter the following command.
```
java -jar StepFunctionsLocal.jar
```
To access Step Functions running locally, use the --endpoint-url parameter. For example, using the AWS CLI, you would specify Step Functions commands as follows:
```
aws stepfunctions --endpoint-url http://localhost:8083 command
```

Note

By default, Step Functions Local uses a local test account and credentials, and the AWS Region is set to US East (N. Virginia). To use Step Functions Local with AWS Lambda, or other supported services, you must configure your credentials and Region.

If you use Express workflows with Step Functions Local, the execution history will be stored in a log file. It is not logged to CloudWatch Logs. The log file path will be based on the CloudWatch Logs log group ARN provided when you create the local state machine. The log file will be stored in /aws/states/log-group-name/${execution_arn}.log relative to the location where you are running Step Functions Local. For example, if the execution ARN is:

arn:aws:states:us-east-1:123456789012:express:test:example-ExpressLogGroup-wJalrXUtnFEMI

the log file will be:

aws/states/log-group-name/arn:aws:states:us-east-1:123456789012:express:test:example-ExpressLogGroup-wJalrXUtnFEMI.log

Setting Configuration Options for Step Functions Local

When you start AWS Step Functions Local by using the JAR file, you can set configuration options by using the AWS Command Line Interface (AWS CLI), or by including them in the system environment. For Docker, you must specify these options in a file that you reference when starting Step Functions Local.

Configuration Options

When you configure the Step Functions Local container to use an override endpoint such as Lambda Endpoint and Batch Endpoint, and make calls to that endpoint, Step Functions Local doesn't use the credentials you specify. Setting these endpoint overrides is optional.

Option	Command Line	Environment
Account	-account, --aws-account	AWS_ACCOUNT_ID
Region	-region, --aws-region	AWS_DEFAULT_REGION
Wait Time Scale	-waitTimeScale, --wait-time-scale	WAIT_TIME_SCALE
Lambda Endpoint	-lambdaEndpoint, --lambda-endpoint	LAMBDA_ENDPOINT
Batch Endpoint	-batchEndpoint, --batch-endpoint	BATCH_ENDPOINT
DynamoDB Endpoint	-dynamoDBEndpoint, --dynamodb-endpoint	DYNAMODB_ENDPOINT
ECS Endpoint	-ecsEndpoint, --ecs-endpoint	ECS_ENDPOINT
Glue Endpoint	-glueEndpoint, --glue-endpoint	GLUE_ENDPOINT
SageMaker Endpoint	-sageMakerEndpoint, --sagemaker-endpoint	SAGE_MAKER_ENDPOINT
SQS Endpoint	-sqsEndpoint, --sqs-endpoint	SQS_ENDPOINT
SNS Endpoint	-snsEndpoint, --sns-endpoint	SNS_ENDPOINT
Step Functions Endpoint	-stepFunctionsEndpoint, --step-functions-endpoint	STEP_FUNCTIONS_ENDPOINT

Credentials and configuration for Docker

To configure Step Functions Local for Docker, create the following file: aws-stepfunctions-local-credentials.txt.

This file contains your credentials and other configuration options. The following can be used as a template when creating the aws-stepfunctions-local-credentials.txt file.


AWS_DEFAULT_REGION=AWS_REGION_OF_YOUR_AWS_RESOURCES
AWS_ACCESS_KEY_ID=YOUR_AWS_ACCESS_KEY
AWS_SECRET_ACCESS_KEY=YOUR_AWS_SECRET_KEY
WAIT_TIME_SCALE=VALUE
LAMBDA_ENDPOINT=VALUE
BATCH_ENDPOINT=VALUE
DYNAMODB_ENDPOINT=VALUE
ECS_ENDPOINT=VALUE
GLUE_ENDPOINT=VALUE
SAGE_MAKER_ENDPOINT=VALUE
SQS_ENDPOINT=VALUE
SNS_ENDPOINT=VALUE
STEP_FUNCTIONS_ENDPOINT=VALUE

Once you have configured your credentials and configuration options in aws-stepfunctions-local-credentials.txt, start Step Functions with the following command.


docker run -p 8083:8083 --env-file aws-stepfunctions-local-credentials.txt amazon/aws-stepfunctions-local

Note

It is recommended to use the special DNS name host.docker.internal, which resolves to the internal IP address that the host uses, such as http://host.docker.internal:8000. For more information, see Docker documentation for Mac and Windows at Networking features in Docker Desktop for Mac and Networking features in Docker Desktop for Windows respectively.

Running Step Functions Local on Your Computer

Use the local version of Step Functions to configure, develop and test state machines on your computer.

Run a HelloWorld state machine locally

After you run Step Functions locally with the AWS Command Line Interface (AWS CLI), you can start a state machine execution.

Create a state machine from the AWS CLI by escaping out the state machine definition.


aws stepfunctions --endpoint-url http://localhost:8083 create-state-machine --definition "{\
  \"Comment\": \"A Hello World example of the Amazon States Language using a Pass state\",\
  \"StartAt\": \"HelloWorld\",\
  \"States\": {\
    \"HelloWorld\": {\
      \"Type\": \"Pass\",\
      \"End\": true\
    }\
  }}" --name "HelloWorld" --role-arn "arn:aws:iam::012345678901:role/DummyRole"

Note

The role-arn is not used for Step Functions Local, but you must include it with the proper syntax. You can use the Amazon Resource Name (ARN) from the previous example.

If you successfully create the state machine, Step Functions responds with the creation date and the state machine ARN.


{
    "creationDate": 1548454198.202, 
    "stateMachineArn": "arn:aws:states:us-east-1:123456789012:stateMachine:HelloWorld"
}

Start an execution using the ARN of the state machine you created.


aws stepfunctions --endpoint-url http://localhost:8083 start-execution --state-machine-arn arn:aws:states:us-east-1:123456789012:stateMachine:HelloWorld

Step Functions Local with AWS SAM CLI Local

You can use the local version of Step Functions with a local version of AWS Lambda. To configure this, you must install and configure AWS SAM.

For information about configuring and running AWS SAM, see the following:

When Lambda is running on your local system, you can start Step Functions Local. From the directory where you extracted your Step Functions local JAR files, start Step Functions Local and use the --lambda-endpoint parameter to configure the local Lambda endpoint.


java -jar StepFunctionsLocal.jar --lambda-endpoint http://127.0.0.1:3001 command

For more information about running Step Functions Local with AWS Lambda, see Tutorial: Testing workflows using Step Functions and AWS SAM CLI Local.

Warning Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

Testing with TestState

Tutorial: Testing using Step Functions and AWS SAM CLI Local