Local testing of CDK-defined Step Functions state machine

CDK-defined state machine


State machine definition


1. Using outputs

“DirectBankAccountCreation”: {
workflowStateMachineDefinitionE0E0A7BF”: “{\”StartAt\”:\”Input checks\”,\”States\”:{\”Input checks\”:{\”Type\”:\”Parallel\”,\”Next\”:\”Create User\”,\”Branches\”:[{\”StartAt\”:\”Extract info from ID\”,\”States\”:{\”Extract info from ID\”:{\”Next\”:\”Crosscheck Identity\”,\”Retry\”:...\”User created, account creation initiated\”:{\”Type\”:\”Succeed\”}}}”, “userCreationAPIBankAccountCreationApiEndpoint1A0514D2”: “https://9xko5dgqbf.execute-api.eu-west-1.amazonaws.com/prod/"
jq -r ‘.DirectBankAccountCreation|with_entries(select(.key | startswith(“workflowStateMachineDefinition”))) | to_entries | .[].value’ cdk.out/output.json > cdk.out/state_machine.asl.json

2. Using a 3rd party tool

  • First install the tool: npm install -g cdk-asl-extractor
  • Second, use the CDK CLI and the cdk synth command to synthesise the CloudFormation template. It will generate the template in JSON format in the cdk.out folder (named [stackname].template.json).
  • Finally, run the tool with this template as parameter. In my case:
  • It will generate as many files as there are state machines in the template. Files are named asl-0.json, asl-1.json, …
  • First, it doesn’t require to deploy the stack on AWS. Nothing deployed means faster to do and no cost (actually, a state machine is free when it doesn’t run).
  • Second, we don’t have a useless output (which can be quite big).
  • And finally, you don’t need to fight with jq for hours to find how to extract a key with a random string 🌀🌩 ☠️❗️💥🤯…

Step Functions local

Mocked Service Integrations

Unit Testing dependencies not being mocker
Unit tests should be independent from external factors
  • One or several test cases (TestCases section).
  • Each tests case list the mocked states and the mocked response names.
  • Below, in the MockedResponses section, we have the definitions of each mock: either a Return with the expected payload returned by the mocked service, or a Throw to simulate an error.
  • You can get more details on this file in the doc.
  • The name of the state machine: DirectIntegrationTest (line 3)
  • The name of the test case: HappyPath (line 5)

Starting Step Functions local 🚀

docker run -p 8083:8083 -d --rm --name stepfunctions-local \
--mount type=bind,readonly,source=$(ROOT_DIR)/test/MockConfigFile.json,destination=/home/StepFunctionsLocal/MockConfigFile.json \
-e SFN_MOCK_CONFIG=”/home/StepFunctionsLocal/MockConfigFile.json” \ amazon/aws-stepfunctions-local

Creating the state machine

aws stepfunctions create-state-machine \
--endpoint-url http://localhost:8083 \
# we can also use the asl-0.json file here
--definition file://cdk.out/state_machine.asl.json \
--name “DirectIntegrationTest” \
--role-arn “arn:aws:iam::123456789012:role/DummyRole” \


Unit tests, Unit tests everywhere


Unit tests





Solution Architect @AWS - software craftsman, agile and devops enthusiastic, cloud advocate. Opinions are my own.

Love podcasts or audiobooks? Learn on the go with our new app.

Recommended from Medium

Sequencing Architecture Modernization: Risk Averse vs Risk Tolerant

A Performance Analysis of C and Go

Kubernetes Tips: Give Access To Your Cluster With A Client Certificate

Simplifying Distribution for NatCorder and NatDevice API

The NatML stack.

5 Mistakes That Engineering Managers Make

A book on a desk. The cover mentions turning mistakes into successes.

Customizing gRPC Generated Code

The Power of Cloud CLI in Data Integration

The Everything Guide to Lambda Throttling, Reserved Concurrency, and Execution Limits

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Jérôme Van Der Linden

Jérôme Van Der Linden

Solution Architect @AWS - software craftsman, agile and devops enthusiastic, cloud advocate. Opinions are my own.

More from Medium

Integrating JIRA with your AWS Services (instead of building a UI)

Efficient APIs with GraphQL and Serverless

Build a Twitter Leaderboard app with Redis and AWS Lambda (part 2)

Node Js Tracing