oshikiri / fake-step-functions

An unit testing toolkit for Amazon States Language

fake-step-functions

A lightweight unit testing toolkit for Amazon States Language.

const { FakeStateMachine } = require('fake-step-functions');

describe('FakeStateMachine.run', () => {
  const definition = {
    Comment: 'https://states-language.net/spec.html#data',
    StartAt: 'AddNumbers',
    States: {
      AddNumbers: {
        Type: 'Task',
        Resource: 'arn:aws:lambda:us-east-1:123456789012:function:Add',
        InputPath: '$.numbers',
        ResultPath: '$.sum',
        End: true,
      },
    },
  };
  const fakeResources = {
    'arn:aws:lambda:us-east-1:123456789012:function:Add': numbers => numbers.val1 + numbers.val2,
  };
  const fakeStateMachine = new FakeStateMachine(definition, fakeResources);

  test('should execute the state machine with fakeResource', async () => {
    const runStateResult = await fakeStateMachine.run({
      title: 'Numbers to add',
      numbers: { val1: 3, val2: 4 },
    });

    expect(runStateResult.data).toEqual({
      title: 'Numbers to add',
      numbers: { val1: 3, val2: 4 },
      sum: 7,
    });
  });
});

Release

In order to release new version to npm, create a commit using npm version patch -m "Release %s" and push it. See the npm-publish-action step in .github/workflows/publish.yml.

References

Specifications

• Amazon States Language specification https://states-language.net/spec.html
• Amazon States Language - AWS Step Functions https://docs.aws.amazon.com/step-functions/latest/dg/concepts-amazon-states-language.html

Similar projects

At 2022, AWS Step Functions Local is a primary choice to test ASL locally. See "Testing Step Functions State Machines Locally".

• airware/stepfunctions-local
• wmfs/statebox
• mikeparisstuff/stateslang-js
• coinbase/step (Golang)
• validators
  • airware/asl-validator
  • awslabs/statelint (Ruby)

fake-step-functions's Issues

Add executed states to field for validating execution path in tests.

User Story

We have quite complicated StepFunctions which have many branching choices. A nice feature that I saw with one of the other libraries was an execution path of the states. This allows us to test for the execution path and not just the end state.

Crude Implementation

Reading the code, I think that this could be crudely implemented into the runState function where by before the Switch statement we have an array property which we push the state name into each time the function is called.

Use Case

    test('should not throw an Error', async () => {
      const definition = require('./fixtures/definitions/pass-state-undefined-resultpath.json');
      const fakeStateMachine = new FakeStateMachine(definition, {});

      await fakeStateMachine.run({
        changed: 'TBD',
        unchanged: 'unchanged',
      });

      expect(fakeStateMachine.executionPath).toEqual([
        "Pass0",
        "Choice1",
        "Branch2",
        "Done"
      ]);
    });

[Question] Intrinsic Function

Hi.

I have a State Machine with an intrinsic function, e.g. serviceUrl.$": "States.Format('https://service.{}.domain.com', $.meta.stage)"

This gives a

Lexical error on line 1. Unrecognized text.
    States.Format('https://service

when executing the test

Are there any plans to support them?

Support for complex Choices rules

This is a great lib.
It would be great to add complex Choices rules support (And/Or/Not/...Path ones) though.
I can assist with that.

Support Map state

This library looks really promising!
Are there any plans to add support for the Map state?

https://docs.aws.amazon.com/step-functions/latest/dg/amazon-states-language-map-state.html

[Question] Retry/Catch

Hi there.

I love how simple it is to to mocking with this library. So much more intuitive than with the official testing approach for Step Functions.

Now I have a StateMachine Definition that has a Catch in it (more of a hack for a http:invoke Task, but 🤷🏼‍♂️).

"Catch": [
        {
          "ErrorEquals": ["States.Http.StatusCode.409"],
          "Comment": "Certificate Exists",
          "Next": "Success"
        }
      ]

Is there a way to test this with this library?

I guess the same applies for Retries, e.g.

"Retry": [
        {
          "ErrorEquals": [
            "Lambda.ServiceException",
            "Lambda.AWSLambdaException",
            "Lambda.SdkClientException",
            "Lambda.TooManyRequestsException"
          ],
          "IntervalSeconds": 1,
          "MaxAttempts": 3,
          "BackoffRate": 2
        }
      ],