Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Tutorial: Testing workflows using Step Functions and Amazon SAM CLI Local

With both Amazon Step Functions and Amazon Lambda running on your local machine, you can test your state machine and Lambda functions without deploying your code to Amazon.

For more information, see the following topics:

Step 1: Set Up Amazon SAM

Amazon Serverless Application Model (Amazon SAM) CLI Local requires the Amazon Command Line Interface, Amazon SAM, and Docker to be installed.

Step 2: Test Amazon SAM CLI Local

Now that you have installed Amazon SAM and created the Hello World Lambda function, you can test the function. In the sam-app directory, enter the following command:

sam local start-api

This launches a local instance of your Lambda function. You should see output similar to the following:

2019-01-31 16:40:27 Found credentials in shared credentials file: ~/.aws/credentials
2019-01-31 16:40:27 Mounting HelloWorldFunction at http://127.0.0.1:3000/hello [GET]
2019-01-31 16:40:27 You can now browse to the above endpoints to invoke your functions. You do not need to restart/reload SAM CLI while working on your functions changes will be reflected instantly/automatically. You only need to restart SAM CLI if you update your AWS SAM template
2019-01-31 16:40:27  * Running on http://127.0.0.1:3000/ (Press CTRL+C to quit)

Open a browser and enter the following:

http://127.0.0.1:3000/hello

This will output a response similar to the following:

{"message": "hello world", "location": "72.21.198.66"}

Enter CTRL+C to end the Lambda API.

Step 3: Start Amazon SAM CLI Local

Now that you've tested that the function works, start Amazon SAM CLI Local. In the sam-app directory, enter the following command:

sam local start-lambda

This starts Amazon SAM CLI Local and provides the endpoint to use, similar to the following output:

2019-01-29 15:33:32 Found credentials in shared credentials file: ~/.aws/credentials
2019-01-29 15:33:32 Starting the Local Lambda Service. You can now invoke your Lambda Functions defined in your template through the endpoint.
2019-01-29 15:33:32  * Running on http://127.0.0.1:3001/ (Press CTRL+C to quit)

Step 4: Start Step Functions Local

JAR File

If you're using the .jar file version of Step Functions Local, start Step Functions and specify the Lambda endpoint. In the directory where you extracted the .jar files, enter the following command:

java -jar StepFunctionsLocal.jar --lambda-endpoint http://localhost:3001

When Step Functions Local starts, it checks the environment, and then the credentials configured in your ~/.aws/credentials file. By default, it starts using a fictitious user ID, and is listed as region us-east-1.

2019-01-29 15:38:06.324: Failed to load credentials from environment because Unable to load AWS credentials from environment variables (AWS_ACCESS_KEY_ID (or AWS_ACCESS_KEY) and AWS_SECRET_KEY (or AWS_SECRET_ACCESS_KEY))
2019-01-29 15:38:06.326: Loaded credentials from profile: default
2019-01-29 15:38:06.326: Starting server on port 8083 with account 123456789012, region us-east-1

Docker

If you're using the Docker version of Step Functions Local, launch Step Functions with the following command:

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

For information about installing the Docker version of Step Functions, see Setting Up Step Functions Local (Downloadable Version) in Docker.

Step 5: Create a State Machine That References Your Amazon SAM CLI Local Function

After Step Functions Local is running, create a state machine that references the HelloWorldFunction that you initialized in Step 1: Set Up Amazon SAM.

aws stepfunctions --endpoint http://localhost:8083 create-state-machine --definition "{\
  \"Comment\": \"A Hello World example of the Amazon States Language using an AWS Lambda Local function\",\
  \"StartAt\": \"HelloWorld\",\
  \"States\": {\
    \"HelloWorld\": {\
      \"Type\": \"Task\",\
      \"Resource\": \"arn:aws:lambda:us-east-1:123456789012:function:HelloWorldFunction\",\
      \"End\": true\
    }\
  }\
}\" --name "HelloWorld" --role-arn "arn:aws:iam::012345678901:role/DummyRole"

This will create a state machine and provide an Amazon Resource Name (ARN) that you can use to start an execution.

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

Step 6: Start an Execution of Your Local State Machine

Once you have created a state machine, start an execution. You'll need to reference the endpoint and state machine ARN when using the following aws stepfunctions command:

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

This starts an execution named test of your HelloWorld state machine.

{
    "startDate": 1548810641.52, 
    "executionArn": "arn:aws:states:us-east-1:123456789012:execution:HelloWorld:test"
}

Now that Step Functions is running locally, you can interact with it using the Amazon CLI. For example, to get information about this execution, use the following command:

aws stepfunctions --endpoint http://localhost:8083 describe-execution --execution-arn arn:aws:states:us-east-1:123456789012:execution:HelloWorld:test

Calling describe-execution for an execution provides more complete details, similar to the following output:

{
    "status": "SUCCEEDED", 
    "startDate": 1549056334.073, 
    "name": "test", 
    "executionArn": "arn:aws:states:us-east-1:123456789012:execution:HelloWorld:test", 
    "stateMachineArn": "arn:aws:states:us-east-1:123456789012:stateMachine:HelloWorld", 
    "stopDate": 1549056351.276, 
    "output": "{\"statusCode\": 200, \"body\": \"{\\\"message\\\": \\\"hello world\\\", \\\"location\\\": \\\"72.21.198.64\\\"}\"}", 
    "input": "{}"
}