@chrisdobby/step-by-step

This is the @chrisdobby/step-by-step library.

The library allows developers to test full AWS Step Function State Machines or subsets of states using the TestState API.

Installation

To install the package use

npm install @chrisdobby/step-by-step

Getting started

The library uses two environment variables that must be available:

AWS_ROLE_ARN - the AWS role to use to execute the states AWS_REGION - the AWS region

The package can be imported using

import { testSingleState, testFunction, testSubset } from '@chrisdobby/step-by-step

step-by-step can test a full State Machine, a single state or a subset of states.

Test a full State Machine by passing the definition json and an optional input:

const result = await testFunction({
  functionDefinition: {
    StartAt: "State 1",
    States: {
      "State 1": {
        Type: "Pass",
        Parameters: {
          result: "state1",
        },
        Next: "State 2",
      },
      "State 2": {
        Type: "Pass",
        End: true,
      },
    },
  },
  input: { test: "hello" },
})

Test a single state passing just the state definition json and an optional input:

const result = await testSingleState({
  stateDefinition: { Type: "Pass", Next: "state 2" },
  input: { test: "hello" },
})

Test a subset of states by passing the function definition json, start and stop states, and an optional input:

const result = await testSubset({
  functionDefinition: {
    StartAt: "State 1",
    States: {
      "State 1": {
        Type: "Pass",
        Parameters: {
          result: "state1",
        },
        Next: "State 2",
      },
      "State 2": {
        Type: "Pass",
        End: true,
      },
    },
  },
  input: { test: "hello" },
  startState: "State 1",
  endState: "State 2",
})

API

testFunction([options]) => Promise<[result]>

options

Type: Object

Options object

functionDefinition

Type: Object

JSON definition of an AWS Step Function State Machine

input

Type: Object Default: undefined

Optional input to pass to the state machine

result

Type: Object

Test result

status

Type: 'SUCCEEDED' | 'FAILED' Default: undefined

The execution status of the test

output

Type: Object Default: undefined

The output of the state machine

error

Type: Object Default: undefined

stack

Type: Array

Call stack

testSingleState([options]) => Promise<[result]>

options

Type: Object

Options object

state

Type: Object

JSON definition of a single AWS Step Function State

input

Type: Object Default: undefined

Optional input to pass to the state machine

result

Type: Object

Test result

status

Type: 'SUCCEEDED' | 'FAILED' Default: undefined

The execution status of the test

output

Type: Object Default: undefined

The output of the state

error

Type: Object Default: undefined

nextState

Type: string Default: undefined

The next state returned

testSubset([options]) => Promise<[result]>

options

Type: Object

Options object

functionDefinition

Type: Object

JSON definition of an AWS Step Function State Machine

input

Type: Object Default: undefined

Optional input to pass to the state machine

startState

Type: string

The name of the state to start testing

endState

Type: string

The name of the state to stop testing

result

Type: Object

Test result

status

Type: 'SUCCEEDED' | 'FAILED' Default: undefined

The execution status of the test

output

Type: Object Default: undefined

The output of the state

error

Type: Object Default: undefined

nextState

Type: string Default: undefined

The next state returned

Demo

The demo will run a number of tests using vitest. Ensure the environment variables are set and run

npm run test

This will build the library and run the tests.