{"id":13750797,"url":"https://github.com/ChristopheBougere/stepfunctions-local","last_synced_at":"2025-05-09T16:32:02.175Z","repository":{"id":57370805,"uuid":"111790339","full_name":"ChristopheBougere/stepfunctions-local","owner":"ChristopheBougere","description":"Execute AWS Step Functions locally","archived":false,"fork":false,"pushed_at":"2020-07-21T12:40:41.000Z","size":483,"stargazers_count":126,"open_issues_count":0,"forks_count":15,"subscribers_count":11,"default_branch":"master","last_synced_at":"2024-04-23T01:21:52.105Z","etag":null,"topics":["aws","nodejs","stepfunctions","stepfunctions-local"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ChristopheBougere.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-11-23T09:35:28.000Z","updated_at":"2024-03-11T19:56:22.000Z","dependencies_parsed_at":"2022-09-18T10:42:19.694Z","dependency_job_id":null,"html_url":"https://github.com/ChristopheBougere/stepfunctions-local","commit_stats":null,"previous_names":["airware/stepfunctions-local"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChristopheBougere%2Fstepfunctions-local","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChristopheBougere%2Fstepfunctions-local/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChristopheBougere%2Fstepfunctions-local/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChristopheBougere%2Fstepfunctions-local/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ChristopheBougere","download_url":"https://codeload.github.com/ChristopheBougere/stepfunctions-local/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224869049,"owners_count":17383308,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws","nodejs","stepfunctions","stepfunctions-local"],"created_at":"2024-08-03T08:00:52.938Z","updated_at":"2024-11-16T02:31:33.162Z","avatar_url":"https://github.com/ChristopheBougere.png","language":"JavaScript","funding_links":[],"categories":["Uncategorized"],"sub_categories":["Uncategorized"],"readme":"# **stepfunctions-local**\n\n[![license](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://github.com/airware/stepfunctions-local/blob/master/LICENSE)\n[![CircleCI](https://circleci.com/gh/airware/stepfunctions-local/tree/master.svg?style=shield\u0026circle-token=75641357fe0d5c8f643d714aa37009fa65037f40)](https://circleci.com/gh/airware/stepfunctions-local/tree/master)\n[![codecov](https://codecov.io/gh/airware/stepfunctions-local/branch/master/graph/badge.svg)](https://codecov.io/gh/airware/stepfunctions-local)\n\n[![NPM](https://nodei.co/npm/stepfunctions-local.png?stars=true)](https://www.npmjs.com/package/stepfunctions-local)\n\nStepfunctions-local provides a local AWS Step Functions server.\nThis package only aims at replacing AWS Step Functions in a local context.\nIts API is totally compliant with AWS service, thus you can use it for your tests.\n\n## Project status\nIn [February 2019](https://aws.amazon.com/about-aws/whats-new/2019/02/develop-and-test-aws-step-functions-workflows-locally/), AWS released an **offical local version of Step Functions**, available as a [docker image](https://hub.docker.com/r/amazon/aws-stepfunctions-local). We will still accept pull requests, but we encourage you to use the official local version.\n\nMore information: [Setting Up Step Functions Local (Downloadable Version)](https://docs.aws.amazon.com/step-functions/latest/dg/sfn-local.html)\n\n## Why **stepfunctions-local**?\n- Ease development and tests. You don't have to upload all your resources on AWS to run a state machine.\n- 100% compliant with AWS API. You can query it using the AWS cli by changing the endpoint. Errors and responses follow the same format.\n- Works well with [localstack](https://github.com/localstack/localstack).\n\n## Use cases\n### I want to run a local state machine with activities\nYou only need to configure your activity worker to use this `stepfunctions` instance. In javascript:\n```js\nAWS.config.stepfunctions = {\n  region: 'local',\n  endpoint: 'http://localhost:4584',\n}\n```\nThen, start `stepfunctions-local` server and you will be able to execute requests to StepFunctions API (`GetActivityTask`, `SendTaskSuccess`, ...).\n\n### I want to run a local state machine with distant Lambdas\nSimply configure your lambda endpoint and region when starting the server:\n```bash\n$\u003e stepfunctions-local start --lambda-endpoint http://hostname.com:1337 --lambda-region my-region\n```\n`stepfunctions-local` will directly query lambda using this configuration.\n\n### I want to run a local state machine with local Lambdas\n`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](https://github.com/localstack/localstack) for that. See how to [here](#run-lambdas-with-localstack).\n\n### I want to run a local state machine with distant ECS Tasks\nSimply configure your ECS endpoint and region when starting the server:\n```bash\n$\u003e stepfunctions-local start --ecs-endpoint http://hostname.com:1337 --ecs-region my-region\n```\n`stepfunctions-local` will directly query ECS using this configuration.\n\n### I want to run a local state machine with local ECS Tasks\n`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.\n\n## Prerequisites\n* [AWS Command Line Interface (CLI)](https://aws.amazon.com/cli/)\n* [Node 8 or greater](https://nodejs.org/)\n\n### Install\n```bash\n# Use it using command lines\n$\u003e npm install -g stepfunctions-local\n\n# Use it in your code\n$\u003e cd /your/project/using/stepfunctions\n$\u003e npm install --save stepfunctions-local\n```\n\n### Or build docker container\n\n```bash\n$\u003e docker build -t stepfunctions-local .\n```\n\n## How to use it ?\n\nYou will find some help on the [Wiki](https://github.com/airware/stepfunctions-local/wiki) page.\n\n### Start a server\n#### Using command line\n```bash\n$\u003e stepfunctions-local start\n\nOptions:\n\n  -V, --version                        output the version number\n  --port \u003cport\u003e                        the port the server should run on\n  --region \u003cregion\u003e                    the region the server should run on\n  --lambda-region \u003clambda-region\u003e      the region for lambda\n  --lambda-endpoint \u003clambda-endpoint\u003e  the endpoint for lambda\n  --ecs-region \u003cecs-region\u003e            the region for ECS\n  --ecs-endpoint \u003cecs-endpoint\u003e        the endpoint for ECS\n  -h, --help                           output usage information\n```\n\n#### Using docker\n```bash\n# Options are same as above\n$\u003e docker run -it --rm -p 4584:4584 stepfunctions-local start \u003coptions\u003e  \n```\n\n#### From your code\n```js\nconst stepfunctionsLocal = require('stepfunctions-local');\n\nstepfunctionsLocal.start({\n  port: 4584,\n  region: 'local',\n  lambdaRegion: 'local',\n  lambdaEndpoint: 'http://localhost:4574',\n  ecsRegion: 'local',\n  ecsEndpoint: 'http://localhost:4600',\n});\n```\n\n#### Default parameters:\n- port: 4584\n- region: local\n- lambda-region: local\n- lambda-endpoint: http://localhost:4574\n- ecs-region: local\n- ecs-endpoint: http://localhost:4600\n\n### Configure logs\nThe service does not log anything by default. It uses the [debug](https://www.npmjs.com/package/debug) package which is based on the `DEBUG` environment variable. You can log process info by setting it.\n\nExample:\n ```bash\n $\u003e DEBUG=stepfunctions-local:* stepfunctions-local start\n ```\n\n### Play with it\n```bash\n# List state machines\n$\u003e aws stepfunctions --endpoint http://localhost:4584 list-state-machines\n\n# Create a new state machine\n$\u003e 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/MyRole\n\n# Describe state machine\n$\u003e aws stepfunctions --endpoint http://localhost:4584 describe-state-machine --state-machine-arn arn:aws:states:local:0123456789:stateMachine:my-state-machine\n\n# Start state machine execution\n$\u003e 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 !\"}'\n\n# List state machine executions\n$\u003e aws stepfunctions --endpoint http://localhost:4584 list-executions --state-machine-arn arn:aws:states:local:0123456789:stateMachine:my-state-machine\n\n# Describe execution\n$\u003e aws stepfunctions --endpoint http://localhost:4584 describe-execution --execution-arn arn:aws:states:local:0123456789:execution:my-state-machine:my-execution\n\n# Describe state machine related to execution\n$\u003e aws stepfunctions --endpoint http://localhost:4584 describe-state-machine-for-execution --execution-arn arn:aws:states:local:0123456789:execution:my-state-machine:my-execution\n\n# Get execution history\n$\u003e aws stepfunctions --endpoint http://localhost:4584 get-execution-history --execution-arn arn:aws:states:local:0123456789:execution:my-state-machine:my-execution\n```\n\n### Run Lambdas with Localstack\n\nStart a local Lambda server using `localstack` (you need to clone the repository first):\n```bash\n$\u003e docker-compose up\n```\nNote: you may have to run `TMPDIR=/private$TMPDIR docker-compose up` if you are on Mac OS.\n\nIf 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.\n\nFor instance, in a NodeJS Lambda function, you can use the following to access S3 functions:\n```js\nconst s3 = new AWS.S3({\n  endpoint: 'http://' + process.env.LOCALSTACK_HOSTNAME + ':4572',\n});\ns3.listBuckets({}, function(err, data) {\n  // your callback\n});\n```\n\nConfigure your Lambda endpoint and region when starting the server:\n```bash\n$\u003e stepfunctions-local start --lambda-endpoint http://localhost:4574 --lambda-region local\n```\n`stepfunctions-local` will directly query lambda using this configuration.\n\n## Compatibility with AWS CLI\n### Actions compatibility\n| Actions | Support |\n| ------ | ------ |\n| ***CreateActivity*** | Following errors are not thrown: *ActivityLimitExceeded* |\n| ***CreateStateMachine***  | Following errors are not thrown: *StateMachineDeleting*, *StateMachineLimitExceeded* |\n| ***DeleteActivity*** | * |\n| ***DeleteStateMachine*** | * |\n| ***DescribeActivity*** | * |\n| ***DescribeStateMachine*** | * |\n| ***DescribeStateMachineForExecution*** | * |\n| ***GetActivityTask*** | Following errors are not thrown: *ActivityWorkerLimitExceeded* |\n| ***GetExecutionHistory*** | * |\n| ***ListActivities*** | * |\n| ***ListExecutions*** | * |\n| ***ListStateMachines*** | * |\n| ***SendTaskFailure*** | * |\n| ***SendTaskHeartbeat*** | * |\n| ***SendTaskSuccess*** | * |\n| ***StartExecution*** | Following errors are not thrown: *ExecutionLimitExceeded* |\n| ***StopExecution*** | * |\n| ***UpdateStateMachine*** | Following errors are not thrown: *StateMachineDeleting* |\n\n### Supported service integrations\nAWS added support for executing [a variety of AWS services](https://docs.aws.amazon.com/step-functions/latest/dg/connectors-supported-services.html) from Step Functions. For now, only Lambda and ECS are supported. Adding new integrations should be quite straightforward (see [#44](https://github.com/airware/stepfunctions-local/pull/44)), feel free to submit pull requests.\n\n| Service | Support |\n| ------- | ------ |\n| ***AWS Lambda*** | * |\n| ***AWS Batch*** | Not yet |\n| ***Amazon DynamoDB*** | Not yet |\n| ***Amazon ECS/Fargate*** | * |\n| ***Amazon SNS*** | Not yet |\n| ***Amazon SQS*** | Not yet |\n| ***AWS Glue*** | Not yet |\n| ***Amazon SageMaker*** | Not yet |\n\n### States compatibility\n| States | Support |\n| ------ | ------ |\n| ***Pass*** | * |\n| ***Task*** | * |\n| ***Choice*** | * |\n| ***Wait*** | * |\n| ***Succeed*** | * |\n| ***Fail*** | * |\n| ***Parallel*** | * |\n\n## Want to contribute ?\n**Wow, that's great !**\nFeedback, bug reports and pull requests are more than welcome !\n\nTo run the tests, you must first [authenticate to AWS](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html),\nincluding setting a default region. You can do this via the `aws configure` command or by setting environment variables:\n\n```bash\n$\u003e export AWS_ACCESS_KEY_ID=(your access key)\n$\u003e export AWS_SECRET_ACCESS_KEY=(your secret key)\n$\u003e export AWS_DEFAULT_REGION=us-east-1\n```\n\nYou can then run the tests as follows:\n\n```bash\n\n$\u003e npm run lint\n$\u003e npm run test\n```\n\n\n## See also\n- [AWS Step Functions Documentation](https://docs.aws.amazon.com/step-functions/latest/dg/welcome.html)\n- [AWS Step Functions SDK](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/StepFunctions.html)\n\n## TODO\n- Add execution abortion related history events\n- Continue services integration\n\n## License\nSee [LICENSE](./LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FChristopheBougere%2Fstepfunctions-local","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FChristopheBougere%2Fstepfunctions-local","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FChristopheBougere%2Fstepfunctions-local/lists"}