Today, we are thrilled to share the latest enhancements in local testing capabilities for AWS Step Functions, a tool designed to coordinate distributed applications using visual workflows. These advancements come through the TestState API, an API that allows developers to simulate and validate their workflow definitions locally on their own development machines. With this update, it is now possible to test error handling patterns, data transformations, and mock service integrations without the need to deploy anything on Amazon Web Services (AWS).
Key Features of the Enhanced TestState API
The enhanced TestState API introduces three major capabilities, each designed to streamline and improve the testing process:
- Mocking Support:
This feature enables developers to mock state outputs and errors, allowing for genuine unit testing of state machine logic without calling downstream services. The API validates these mocked responses against AWS API models using three validation modes:- STRICT: Validates that all required fields are present (default mode).
- PRESENT: Ensures field types and names are correct.
- NONE: No validation, offering flexibility.
- Support for All State Types:
All types of states are now supported, including complex ones like Map states, Parallel states, activity-based Task states, and .sync and .waitForTaskToken service integration patterns. This means developers can test across their entire workflow definitions, verifying control flow logic, state transitions, error handling, and data transformations. - Testing Individual States:
The new stateName parameter allows for testing specific states within a complete state machine definition. By providing the full state machine definition once, developers can test each state individually, allowing for precise control over execution contexts such as retry attempts, Map iteration positions, and error scenarios.Getting Started with Enhanced TestState
Let’s explore these new capabilities with some practical scenarios:
Scenario 1: Mock Successful Results
The mocking support feature allows developers to test workflow logic without invoking actual AWS services or external HTTP requests. This can be done by simulating service responses for quick unit testing or testing with real AWS services for integration testing. Notably, when using mocked responses, AWS Identity and Access Management (IAM) permissions are not required.
For example, to mock a successful AWS Lambda function response, a developer can use the following command:
bash<br /> aws stepfunctions test-state --region us-east-1 \<br /> --definition '{<br /> "Type": "Task",<br /> "Resource": "arn:aws:states:::lambda:invoke",<br /> "Parameters": {"FunctionName": "process-order"},<br /> "End": true<br /> }' \<br /> --mock '{"result":"{\"orderId\":\"12345\",\"status\":\"processed\"}"}' \<br /> --inspection-level DEBUG<br />This command tests a Lambda invocation state without actually calling the function, ensuring that the mock response is validated against the Lambda service API model. The result is a high-fidelity test without making actual AWS service calls.
Scenario 2: Mock Error Conditions
Developers can also simulate error conditions to test error handling logic. For instance, simulating a Lambda service exception can be done with the following command:
bash<br /> aws stepfunctions test-state --region us-east-1 \<br /> --definition '{<br /> "Type": "Task",<br /> "Resource": "arn:aws:states:::lambda:invoke",<br /> "Parameters": {"FunctionName": "process-order"},<br /> "End": true<br /> }' \<br /> --mock '{"errorOutput":{"error":"Lambda.ServiceException","cause":"Function failed"}}' \<br /> --inspection-level DEBUG<br />This simulates an error scenario, allowing developers to verify how their state machine handles failures without triggering actual errors in the AWS environment.
Scenario 3: Test Map States
The TestState API now supports testing of Distributed Map states, which process multiple items concurrently. Here’s how developers can test such a state:
bash<br /> aws stepfunctions test-state --region us-east-1 \<br /> --definition '{<br /> "Type": "Map",<br /> "ItemProcessor": {<br /> "ProcessorConfig": {"Mode": "DISTRIBUTED", "ExecutionType": "STANDARD"},<br /> "StartAt": "ProcessItem",<br /> "States": {<br /> "ProcessItem": {<br /> "Type": "Task", <br /> "Resource": "arn:aws:states:::lambda:invoke",<br /> "Parameters": {"FunctionName": "process-item"},<br /> "End": true<br /> }<br /> }<br /> },<br /> "End": true<br /> }' \<br /> --input '[{"itemId":1},{"itemId":2}]' \<br /> --mock '{"result":"[{\"itemId\":1,\"status\":\"processed\"},{\"itemId\":2,\"status\":\"processed\"}]"}' \<br /> --inspection-level DEBUG<br />The mock result represents the expected output from processing multiple items, ensuring the test data conforms to the expected Map state output format.
Scenario 4: Test Parallel States
Parallel states, which allow for concurrent execution of multiple branches, can also be tested:
bash<br /> aws stepfunctions test-state --region us-east-1 \<br /> --definition '{<br /> "Type": "Parallel",<br /> "Branches": [<br /> {"StartAt": "Branch1", "States": {"Branch1": {"Type": "Pass", "End": true}}},<br /> {"StartAt": "Branch2", "States": {"Branch2": {"Type": "Pass", "End": true}}}<br /> ],<br /> "End": true<br /> }' \<br /> --mock '{"result":"[{\"branch1\":\"data1\"},{\"branch2\":\"data2\"}]"}' \<br /> --inspection-level DEBUG<br />The mock result should be an array with one element per branch, simulating what a real Parallel state execution would produce.
Scenario 5: Test Individual States Within Complete Workflows
Developers can test specific states within a full state machine definition using the stateName parameter:
bash<br /> aws stepfunctions test-state --region us-east-1 \<br /> --definition '{<br /> "Type": "Task",<br /> "Resource": "arn:aws:states:::lambda:invoke",<br /> "Parameters": {"FunctionName": "validate-order"},<br /> "End": true<br /> }' \<br /> --input '{"orderId":"12345","amount":99.99}' \<br /> --mock '{"result":"{\"orderId\":\"12345\",\"validated\":true}"}' \<br /> --inspection-level DEBUG<br />This tests a Lambda invocation state with specific input data, demonstrating how TestState processes and transforms the input through state execution.
Additional Information and Resources
Here are some key points to consider:
- Availability: The enhanced TestState capabilities are available in all AWS Regions where Step Functions is supported.
- Pricing: TestState API calls are included with AWS Step Functions at no additional charge, making it an economical option for developers.
- Framework Compatibility: TestState is compatible with any testing framework capable of making HTTP requests, such as Jest, pytest, and JUnit. This allows developers to integrate TestState into their continuous integration and continuous delivery (CI/CD) pipelines.
- Feature Support: Enhanced TestState supports all Step Functions features, including Distributed Map, Parallel states, error handling, and JSONata expressions.
For detailed options and configurations, developers can refer to the TestState documentation and the API reference.
By integrating the TestState API into your development workflow, you can experience the benefits of enhanced local testing, gaining confidence in your workflows before deploying them to AWS. Get started today and enjoy building reliable applications with AWS Step Functions.
For more Information, Refer to this article.
