You can test AWS Step Functions state logic from pytest without deploying or changing a state machine: call the TestState API with a state definition and input, then assert its status and output. For local development, an emulator may help, but AWS says Step Functions Local is unsupported and does not provide feature parity. Use an isolated AWS environment to verify behavior that an emulator or a focused state test cannot establish.
What pytest can test without deploying a state machine
TestState runs an individual state definition, so it is useful for checking state logic independently of a deployed workflow. AWS documents access through the console, AWS CLI, and SDK. The API can test data flow and error handling, and can mock service integrations so a test can focus on how the state handles a response rather than invoking the real service.
As an Amazon Associate I earn from qualifying purchases.
AWS says enhancements for automated unit tests began in November 2025, including mocked service integrations, advanced states with mocked responses, and execution-context control. The console does not expose all API enhancements; use the CLI or SDK for advanced state and context tests where console support is absent. See AWS’s TestState API guide for current operation details and requirements.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
These are focused state-logic checks, not proof that a deployed workflow will work end to end. They do not establish the workflow’s IAM permissions, real integration behavior, account boundaries, or runtime behavior. Test those in an appropriately isolated AWS environment.
#1 Best Overall
How do I call TestState from pytest?
Use a small, deterministic state definition and input. Configure a boto3 Step Functions client for the intended target, call TestState, and assert the outcome that matters to the state. The following is a structural example; adapt the request fields and mock configuration to the state and the current TestState API requirements.
import json
import os
import boto3
import pytest
@pytest.fixture
def stepfunctions_client():
# Set this explicitly for the test run; omit endpoint_url for AWS.
endpoint_url = os.getenv("STEPFUNCTIONS_ENDPOINT_URL")
options = {"region_name": os.getenv("AWS_REGION", "us-east-1")}
if endpoint_url:
options["endpoint_url"] = endpoint_url
return boto3.client("stepfunctions", **options)
def test_pass_state_returns_expected_output(stepfunctions_client):
definition = json.dumps({
"Type": "Pass",
"Parameters": {"result": "ok", "source.$": "$.source"},
"End": True,
})
response = stepfunctions_client.test_state(
definition=definition,
input=json.dumps({"source": "pytest"}),
)
assert response["status"] == "SUCCEEDED"
assert json.loads(response["output"]) == {
"result": "ok",
"source": "pytest",
}This example demonstrates the shape of a state-level test; it is not a claim that the code was executed. Check the SDK version and the current API reference for accepted parameters and response fields, especially when adding mock or context options.
Keep AWS access deliberate
For direct AWS TestState calls, use the normal AWS endpoint with explicit region and credentials configured for a test account or role. Grant only the permissions needed by the test. Avoid relying on whichever account happens to be active in a developer shell or CI runner; make the target environment explicit so a test cannot accidentally run against production.
Free tools Windows power users keep installed
One-click scans. No signup required.
Assert behavior, not merely a response
Check the returned status and parse the output to verify the expected value and shape. Add separate cases for meaningful branches: input/output transformations, a mocked service response, a retry or catch path, and a failure the state is expected to report. Keep fixtures isolated so one test’s input or mock does not affect another.
Can I mock a service integration?
Yes. TestState supports mocked service integrations, letting you supply a response for a state to process without making the corresponding service call. This is useful for checking how the state transforms a successful response or handles a failure, while keeping the test focused and repeatable. Follow the API guide for the mock configuration supported by the state and operation you are testing: Testing state machines with TestState API.
A mocked response does not verify that the real integration is configured correctly, that the execution role has the required permissions, or that a target service behaves the same way. Cover those questions with an integration test in an isolated AWS account or environment.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Should I use Step Functions Local or LocalStack?
Choose the route according to what the test needs to establish. TestState is the direct AWS-supported option for isolated state tests; an emulator is a convenience for local development, not evidence of full AWS compatibility.
| Route | Deploy a state machine? | Mocks and focus | What it establishes |
|---|---|---|---|
| TestState API via SDK or CLI | No; test an individual state definition. | Supports mocked service integrations and state-level logic checks. | State behavior for the supplied definition, input, mock responses, and test context; not the full deployed workflow. |
| Step Functions Local | No deployed AWS state machine is needed for local execution. | Provides a local development and execution loop; feature coverage is incomplete. | Behavior within the emulator only. AWS explicitly says it is unsupported and lacks feature parity, including optimized service integrations, cross-account access, and Distributed Map. See AWS testing and debugging guidance. |
| LocalStack | Intended for local AWS emulation; exact workflow depends on its configuration and capabilities. | The AWS sample repository includes a pytest example configured with a LocalStack endpoint. | Behavior supported by the configured emulator, not a guarantee of AWS behavior. Consult the AWS sample and current LocalStack documentation for feature availability. |
| Isolated AWS integration environment | Use deployed resources when testing deployed-workflow behavior. | Exercises real AWS integrations rather than mocked responses. | More realistic evidence for IAM, service integration, account-specific, and runtime behavior, limited to the environment and scenarios tested. |
AWS documents Step Functions Local setup options and endpoint configuration in its Step Functions Local guide. If you target an emulator from pytest, make the endpoint a deliberate test configuration choice; the AWS sample shows an endpoint configuration for LocalStack. Do not infer that an emulator supports every TestState feature or state type.
AWS warns that Step Functions Local is for testing and should never process sensitive information. A passing emulator test does not validate features the emulator does not implement or implements differently; verify important integration behavior in AWS.
A practical test split
- State unit tests: call TestState through boto3 or the CLI with deterministic definitions, inputs, and mocks. Assert status, output, transformations, and intended error paths.
- Optional emulator loop: configure an endpoint explicitly for local iteration when emulator support is adequate. Keep its results distinct from AWS-backed results.
- AWS integration tests: deploy or invoke the relevant workflow in an isolated AWS environment to check real permissions, service integrations, account boundaries, and runtime behavior. Clean up any resources created by these tests.
This division keeps fast state checks separate from the checks that require AWS itself, without treating an emulator as a substitute for either.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
