Framework for unit testing AWS Step Functions state machine behavior using TestState and mocks
$ dotnet add package Toxon.StepFunctionTestingTest AWS Step Functions state logic from .NET by running states through TestState with mocks.
dotnet add package Toxon.StepFunctionTesting
ThenReturn, ThenFail)StepFunctionResult containing the typed result (Success, Failed, CaughtError, Retriable) and state invocation historystates:TestState)states:TestStateThis library calls the AWS Step Functions TestState API, so tests are not fully offline.
using Amazon.StepFunctions;
using Toxon.StepFunctionTesting.Framework;
var definition = """
{
"StartAt": "Work",
"States": {
"Work": {
"Type": "Task",
"Resource": "arn:aws:states:::lambda:invoke",
"End": true
}
}
}
""";
var runner = new StepFunctionRunner(
new AmazonStepFunctionsClient(),
definition,
new StepFunctionRunnerOptions { RequireMocks = true });
var mocks = new Dictionary<string, IMockProvider>
{
["Work"] = new MockSequence()
.ThenReturn("{\"ok\":true}")
};
var result = await runner.RunAsync("{}", mocks);
if (result.Result is StepFunctionStateResult.Success success)
{
Console.WriteLine(success.Output);
}
foreach (var invocation in result.Invocations)
{
Console.WriteLine($"{invocation.State.StateName}: {invocation.Result.GetType().Name}");
}
var mocks = new Dictionary<string, IMockProvider>
{
["Fetch"] = new MockSequence()
.ThenFail("RetryableError")
.ThenReturn("{\"value\":123}"),
["Validate"] = new MockSequence()
.ThenFail("ValidationError", "missing required field")
};
RequireMocks is true, ALL task states must have mocks.SkipWaitStates is recommended for test speed, but will not evaluate any expression for wait duration or any assignments/state transformation on Wait statesIf you run tests in CI, ensure AWS credentials are available (for example via GitHub OIDC) and the assumed role includes states:TestState.