Recommended Free Tools
iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
You can test an AWS Step Functions state without deploying or changing a state machine by calling AWS’s TestState API from pytest. Use it to check state output, data transformations, mocked service responses, and error paths. For fully local development, an emulator can help—but AWS says Step Functions Local is unsupported and does not have feature parity, so validate important integration behavior in an isolated AWS environment.
How do I call TestState from pytest?
TestState runs an individual state definition, rather than a deployed workflow. AWS makes it available through the console, AWS CLI, and SDK. For a repeatable Python test suite, use the SDK client and assert on the response’s behavior—not merely that the API call succeeded. AWS’s TestState documentation covers the API, supported testing capabilities, and required permissions.
The example below shows the test structure. It uses a simple Pass state to illustrate calling TestState and checking its returned output; it has not been run or verified here. Supply the AWS credentials, region, and permission for the API call through your normal test configuration.
import json
import boto3
import pytest
@pytest.fixture
def sfn_client():
return boto3.client("stepfunctions", region_name="us-east-1")
def test_pass_state_returns_expected_output(sfn_client):
definition = json.dumps({"Type": "Pass", "Result": {"approved": True}, "End": True})
response = sfn_client.test_state(
definition=definition,
input=json.dumps({"request_id": "test-123"}),
)
assert response["status"] == "SUCCEEDED"
assert json.loads(response["output"]) == {"approved": True}Use a small, deterministic definition and input for each test. Keep test inputs and expected outputs in fixtures or nearby test data so a failure makes the intended behavior clear. The example uses a fixed region for readability; choose the region and credentials explicitly for your environment, and do not let a test unexpectedly run against production.
#1 Best Overall
What should the tests assert?
TestState is useful when a state’s behavior can be evaluated independently. Build separate cases around the state’s expected success, transformation, and failure behavior instead of treating one successful response as proof that the state is correct.
- Status and output: Check the returned status and parse the output JSON to verify the exact result.
- Input and output transformations: Provide representative input and assert which fields the state passes through, changes, or removes.
- Service integration behavior: Mock the integration response where supported, then verify how the state handles that response without depending on a live service call.
- Error handling: Exercise the intended error or retry path and check the resulting status or output, including catch behavior where applicable.
AWS says TestState 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 every API enhancement; use the CLI or SDK for advanced state and context tests that the console does not support. Consult the current TestState guide for the operation’s current parameters and permissions.
Can I mock a service integration?
Yes. TestState supports mocked service-integration responses, so a focused state test can check how workflow logic responds without calling the integrated service. Define the mock response to match the case under test, then assert the state’s output and error handling. This separates checks of state logic from checks that a live service, IAM policy, or account configuration is working.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Mocks are not evidence that a real integration will succeed. They cannot establish that the deployed workflow has the right permissions, that a service accepts the request, or that account-specific and runtime behavior matches the test. Use an AWS test environment for those checks.
Should I use Step Functions Local or LocalStack?
Choose based on what you need to learn from a test. TestState is suited to isolated state logic; an emulator can support a local development loop; an AWS sandbox is needed for confidence in deployed integrations and account-specific behavior.
| Route | Does it require a deployed state machine? | What it can help test | Important limitation |
|---|---|---|---|
| AWS TestState through SDK or CLI | No. It tests a state definition without creating or updating a state machine. | State output, data flow, mocked integrations, and error behavior supported by the API. | A focused state test does not prove the full deployed workflow, IAM, live integrations, account boundaries, or runtime behavior. |
| Step Functions Local | No deployed AWS state machine is needed for a local emulator workflow. | A local development loop using the emulator’s supported behavior. | AWS explicitly calls it unsupported and warns it lacks feature parity, including gaps in optimized service integrations, cross-account access, and Distributed Map. |
| LocalStack | Not necessarily; it provides an emulated local environment. | Local development and tests against its implemented Step Functions behavior. | Its compatibility depends on the features it implements; a passing emulated test does not establish AWS behavior. Confirm current capability for the specific feature you rely on. |
| Isolated AWS test environment | For deployed-workflow integration checks, yes. | Real AWS integrations, permissions, account boundaries, and deployed execution behavior. | Requires deliberate account, credential, and resource management so tests stay isolated from production. |
AWS’s testing and debugging guidance identifies TestState as an alternative for testing state behavior and describes Step Functions Local’s limitations. The Step Functions Local documentation explains its setup and warnings. AWS states: “Step Functions Local is unsupported.” It also says: “Step Functions Local does not provide feature parity. For example, there is no support for optimized service integrations, cross-account access, or distributed map.”
LocalStack is another emulator option, but its coverage can change over time. The AWS Samples TestState API sample includes pytest examples and an endpoint configuration for LocalStack. Treat that configuration as an example, not a guarantee that every Step Functions feature is supported by your installed LocalStack version.
How can tests target an emulator or AWS?
Keep endpoint selection in test configuration rather than baking it into individual tests. For an emulator, boto3 accepts an endpoint_url; the AWS sample demonstrates configuring a LocalStack endpoint. For direct TestState calls, use the normal AWS endpoint and credentials with only the permissions required for the test. Keep local and AWS test settings explicit so a local run cannot silently target a production account.
If an integration test creates real AWS resources, isolate it in a suitable test account and clean up resources it creates. Do not put sensitive information into Step Functions Local: AWS says to use it only for testing and never to process sensitive information.
What TestState and emulators do not prove
TestState checks a state definition in isolation; it is not a substitute for executing the full deployed workflow. Emulator tests check the emulator’s implementation, not AWS. Neither establishes that a deployed workflow has the right IAM permissions, that a live integration works, or that account-specific behavior is correct. Add a separate integration stage in an appropriately isolated AWS environment for those questions, and use the local tests for fast, deterministic checks of state logic.
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.
