A local AWS Step Functions server
npm install stepfunctions-local



Stepfunctions-local provides a local AWS Step Functions server.
This package only aims at replacing AWS Step Functions in a local context.
Its API is totally compliant with AWS service, thus you can use it for your tests.
More information: Setting Up Step Functions Local (Downloadable Version)
stepfunctions instance. In javascript:js
AWS.config.stepfunctions = {
region: 'local',
endpoint: 'http://localhost:4584',
}
`
Then, start stepfunctions-local server and you will be able to execute requests to StepFunctions API (GetActivityTask, SendTaskSuccess, ...).$3
Simply configure your lambda endpoint and region when starting the server:
`bash
$> stepfunctions-local start --lambda-endpoint http://hostname.com:1337 --lambda-region my-region
`
stepfunctions-local will directly query lambda using this configuration.$3
stepfunctions-local does not aim to emulate Lambda. To do this you need a local Lambda server that is compliant to AWS API. We recommand to use localstack for that. See how to here.$3
Simply configure your ECS endpoint and region when starting the server:
`bash
$> stepfunctions-local start --ecs-endpoint http://hostname.com:1337 --ecs-region my-region
`
stepfunctions-local will directly query ECS using this configuration.$3
stepfunctions-local does not aim to emulate ECS. To do this you need a local ECS server that is compliant to AWS API. You may have to create a mock server to do this yourself.Prerequisites
* AWS Command Line Interface (CLI)
* Node 8 or greater$3
`bash
Use it using command lines
$> npm install -g stepfunctions-localUse it in your code
$> cd /your/project/using/stepfunctions
$> npm install --save stepfunctions-local
`$3
`bash
$> docker build -t stepfunctions-local .
`How to use it ?
You will find some help on the Wiki page.
$3
#### Using command line
`bash
$> stepfunctions-local startOptions:
-V, --version output the version number
--port the port the server should run on
--region the region the server should run on
--lambda-region the region for lambda
--lambda-endpoint the endpoint for lambda
--ecs-region the region for ECS
--ecs-endpoint the endpoint for ECS
-h, --help output usage information
`#### Using docker
`bash
Options are same as above
$> docker run -it --rm -p 4584:4584 stepfunctions-local start
`#### From your code
`js
const stepfunctionsLocal = require('stepfunctions-local');stepfunctionsLocal.start({
port: 4584,
region: 'local',
lambdaRegion: 'local',
lambdaEndpoint: 'http://localhost:4574',
ecsRegion: 'local',
ecsEndpoint: 'http://localhost:4600',
});
`#### Default parameters:
- port: 4584
- region: local
- lambda-region: local
- lambda-endpoint: http://localhost:4574
- ecs-region: local
- ecs-endpoint: http://localhost:4600
$3
The service does not log anything by default. It uses the debug package which is based on the DEBUG environment variable. You can log process info by setting it.Example:
`bash
$> DEBUG=stepfunctions-local:* stepfunctions-local start
`$3
`bash
List state machines
$> aws stepfunctions --endpoint http://localhost:4584 list-state-machinesCreate a new state machine
$> aws stepfunctions --endpoint http://localhost:4584 create-state-machine --name my-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}}}' --role-arn arn:aws:iam::0123456789:role/service-role/MyRoleDescribe state machine
$> aws stepfunctions --endpoint http://localhost:4584 describe-state-machine --state-machine-arn arn:aws:states:local:0123456789:stateMachine:my-state-machineStart state machine execution
$> aws stepfunctions --endpoint http://localhost:4584 start-execution --state-machine-arn arn:aws:states:local:0123456789:stateMachine:my-state-machine --name my-execution --input '{"comment":"I am a great input !"}'List state machine executions
$> aws stepfunctions --endpoint http://localhost:4584 list-executions --state-machine-arn arn:aws:states:local:0123456789:stateMachine:my-state-machineDescribe execution
$> aws stepfunctions --endpoint http://localhost:4584 describe-execution --execution-arn arn:aws:states:local:0123456789:execution:my-state-machine:my-executionDescribe state machine related to execution
$> aws stepfunctions --endpoint http://localhost:4584 describe-state-machine-for-execution --execution-arn arn:aws:states:local:0123456789:execution:my-state-machine:my-executionGet execution history
$> aws stepfunctions --endpoint http://localhost:4584 get-execution-history --execution-arn arn:aws:states:local:0123456789:execution:my-state-machine:my-execution
`$3
Start a local Lambda server using
localstack (you need to clone the repository first):
`bash
$> docker-compose up
`
Note: you may have to run TMPDIR=/private$TMPDIR docker-compose up if you are on Mac OS.If you need to access AWS services from within your Lambda, the variable
LOCALSTACK_HOSTNAME will contain the name of the host where Localstack services are available.For instance, in a NodeJS Lambda function, you can use the following to access S3 functions:
`js
const s3 = new AWS.S3({
endpoint: 'http://' + process.env.LOCALSTACK_HOSTNAME + ':4572',
});
s3.listBuckets({}, function(err, data) {
// your callback
});
`Configure your Lambda endpoint and region when starting the server:
`bash
$> stepfunctions-local start --lambda-endpoint http://localhost:4574 --lambda-region local
`
stepfunctions-local will directly query lambda using this configuration.Compatibility with AWS CLI
$3
| Actions | Support |
| ------ | ------ |
| CreateActivity | Following errors are not thrown: ActivityLimitExceeded |
| CreateStateMachine | Following errors are not thrown: StateMachineDeleting, StateMachineLimitExceeded |
| DeleteActivity | * |
| DeleteStateMachine | * |
| DescribeActivity | * |
| DescribeStateMachine | * |
| DescribeStateMachineForExecution | * |
| GetActivityTask | Following errors are not thrown: ActivityWorkerLimitExceeded |
| GetExecutionHistory | * |
| ListActivities | * |
| ListExecutions | * |
| ListStateMachines | * |
| SendTaskFailure | * |
| SendTaskHeartbeat | * |
| SendTaskSuccess | * |
| StartExecution | Following errors are not thrown: ExecutionLimitExceeded |
| StopExecution | * |
| UpdateStateMachine | Following errors are not thrown: StateMachineDeleting |$3
AWS added support for executing a variety of AWS services from Step Functions. For now, only Lambda and ECS are supported. Adding new integrations should be quite straightforward (see #44), feel free to submit pull requests.| Service | Support |
| ------- | ------ |
| AWS Lambda | * |
| AWS Batch | Not yet |
| Amazon DynamoDB | Not yet |
| Amazon ECS/Fargate | * |
| Amazon SNS | Not yet |
| Amazon SQS | Not yet |
| AWS Glue | Not yet |
| Amazon SageMaker | Not yet |
$3
| States | Support |
| ------ | ------ |
| Pass | * |
| Task | * |
| Choice | * |
| Wait | * |
| Succeed | * |
| Fail | * |
| Parallel | * |Want to contribute ?
Wow, that's great !
Feedback, bug reports and pull requests are more than welcome !To run the tests, you must first authenticate to AWS,
including setting a default region. You can do this via the
aws configure command or by setting environment variables:`bash
$> export AWS_ACCESS_KEY_ID=(your access key)
$> export AWS_SECRET_ACCESS_KEY=(your secret key)
$> export AWS_DEFAULT_REGION=us-east-1
`You can then run the tests as follows:
`bash$> npm run lint
$> npm run test
``