Step Functions

Lightweight, dependency-free fake of AWS Step Functions (Amazon States Language / SFN) that speaks the real Step Functions AWS JSON 1.0 wire protocol, so application code using @aws-sdk/client-sfn can run against it with zero cost and zero side effects. It ships a compact but real Amazon States Language interpreter, so executions actually run.

Host prefix. On real AWS, StartSyncExecution and TestState use a sync- host prefix (e.g. sync-states.us-east-1.amazonaws.com). When pointing the SDK at this fake, construct the client with disableHostPrefix: true so those two operations reach the single listener. Every operation is served from POST /.

Quick Start

Start the server:

import { StepfunctionsServer } from "./services/stepfunctions/src/server.js";

const server = new StepfunctionsServer(4577);
await server.start();
// ... use it ...
await server.stop();

Connect with the real AWS SDK client:

import {
  SFNClient,
  CreateStateMachineCommand,
  StartExecutionCommand,
  DescribeExecutionCommand,
} from "@aws-sdk/client-sfn";

const sfn = new SFNClient({
  region: "us-east-1",
  endpoint: "http://127.0.0.1:4577",
  credentials: { accessKeyId: "parlel", secretAccessKey: "parlel" },
  disableHostPrefix: true, // needed for StartSyncExecution / TestState
});

const definition = JSON.stringify({
  StartAt: "Greet",
  States: {
    Greet: { Type: "Pass", Result: { greeting: "hello" }, ResultPath: "$.added", Next: "Done" },
    Done: { Type: "Succeed" },
  },
});

// Create a state machine.
const { stateMachineArn } = await sfn.send(
  new CreateStateMachineCommand({
    name: "greeter",
    definition,
    roleArn: "arn:aws:iam::123456789012:role/parlel",
  }),
);

// Start an execution.
const { executionArn } = await sfn.send(
  new StartExecutionCommand({ stateMachineArn, input: JSON.stringify({ a: 1 }) }),
);

// Inspect the result.
const result = await sfn.send(new DescribeExecutionCommand({ executionArn }));
console.log(result.status); // "SUCCEEDED"
console.log(JSON.parse(result.output)); // { a: 1, added: { greeting: "hello" } }

Implemented operations

All 37 operations exposed by @aws-sdk/client-sfn are implemented.

State machines

• CreateStateMachine — STANDARD & EXPRESS, optional publish, tag attach, idempotent re-create
• UpdateStateMachine — definition / role / logging / tracing / encryption, optional publish
• DescribeStateMachine — by ARN, version ARN, or alias ARN
• DeleteStateMachine — idempotent
• ListStateMachines — paginated
• ValidateStateMachineDefinition — returns OK / FAIL with diagnostics

Versions

• PublishStateMachineVersion
• ListStateMachineVersions — paginated
• DeleteStateMachineVersion

Aliases

• CreateStateMachineAlias — weighted routingConfiguration (weights must sum to 100)
• UpdateStateMachineAlias
• DescribeStateMachineAlias
• ListStateMachineAliases — paginated
• DeleteStateMachineAlias

Executions

• StartExecution — runs the ASL interpreter; idempotent on (name, input)
• StartSyncExecution — EXPRESS only; returns output inline
• StopExecution — marks ABORTED, makes execution redrivable
• DescribeExecution
• ListExecutions — filter by state machine + statusFilter, paginated
• GetExecutionHistory — real event stream, reverseOrder supported, paginated
• DescribeStateMachineForExecution
• RedriveExecution — re-runs a failed/aborted (redrivable) execution

Activities

• CreateActivity — idempotent, tag attach
• DescribeActivity
• DeleteActivity
• ListActivities — paginated
• GetActivityTask — dequeues a pending .waitForTaskToken activity task (returns empty immediately if none)

Task tokens (callback pattern)

• SendTaskSuccess — resolves a .waitForTaskToken task with output
• SendTaskFailure — fails the task (drives Retry/Catch)
• SendTaskHeartbeat — records a heartbeat for a live token

Map runs (distributed map)

• DescribeMapRun
• ListMapRuns — paginated
• UpdateMapRun

State testing

• TestState — runs a single state definition against an input, returns output / nextState / error

Tags

• TagResource
• UntagResource
• ListTagsForResource

Amazon States Language interpreter

StartExecution / StartSyncExecution actually execute the state machine. Supported state types and features:

Intrinsic functions

States.Format, States.StringToJson, States.JsonToString, States.Array, States.ArrayLength, States.ArrayGetItem, States.ArrayContains, States.ArrayRange, States.ArrayPartition, States.ArrayUnique, States.MathAdd, States.MathRandom, States.StringSplit, States.UUID, States.Base64Encode, States.Base64Decode, States.Hash, States.JsonMerge.

Task resolution (parlel extension)

By default a Task state is an identity task: it returns its effective input as the result, which is enough to test most flow logic. To return real values, register a resolver keyed by the Resource ARN on the server instance:

server.taskResolvers.set(
  "arn:aws:lambda:us-east-1:123456789012:function:work",
  async (input, ctx) => ({ doubled: input.value * 2 }),
);

For .waitForTaskToken resources, complete the task out of band with SendTaskSuccess / SendTaskFailure using the token surfaced to your resolver (or to a paired activity via GetActivityTask).

Surface coverage

This emulator faithfully replicates the API surface most application code and agents exercise. Anything below the supported lines is either an intentional design choice for a fast, zero-cost local emulator (✓ By design) or a candidate for a future release (⟳ Roadmap) — never a silent inaccuracy.

Legend: ✅ fully supported · ◐ accepted (stored, not strictly enforced) · ✓ by design · ⟳ on the roadmap.

Error codes & shapes

Errors are returned with a non-2xx status, the x-amzn-errortype: <Code> header, and a JSON body:

{ "__type": "StateMachineDoesNotExist", "message": "State Machine Does Not Exist: '<arn>'." }

Modeled error codes returned by this fake:

Internal endpoints

Two non-AWS helper endpoints are exposed for test orchestration:

• GET /_parlel/health → { status, service, stateMachines, executions, activities }
• POST /_parlel/reset → clears all in-memory state

You can also reset programmatically with server.reset().

Configuration — test.env

Copy these into your test.env (used by the bridge sidecar flow). Tokens are Parlel's seeded test credentials — any non-empty value is accepted by the emulator, so you rarely need to change them. Swap in real credentials only when pointing at the live service in prod.env.

AWS_ACCESS_KEY_ID=parlel
AWS_SECRET_ACCESS_KEY=parlel
AWS_REGION=us-east-1
AWS_ENDPOINT_URL_STEP_FUNCTIONS=http://parlel-bridge:4577
AWS_ENDPOINT_URL=http://parlel-bridge:4577