Skip to content

Conversation

@tiurin
Copy link
Contributor

@tiurin tiurin commented Nov 26, 2025

Motivation

New capabilities have recently been added to TestState API. This PR adds the following support for the new capabilities:

  • Add mocking support – Mock state outputs and errors without invoking downstream services
  • Add support for Map (inline and distributed) states
  • Add support to test specific states within a full state machine definition using the new stateName parameter.

Changes

Add StateName support
Adds support for StateName parameter to TestState API. Extends TestStatePreprocessor and TestStateAmazonStateLanguageParser to accept an optional state_name parameter. This signals to the parse function that we should be parsing a full state machine (not just a single state), and also allows the preprocessor to construct a TestStateProgram using this state_name.

Apply TestState mock to Task state result

Support mocked errors, Map states, and improve mock abstractions Adds support for mocking errors, map states, fixes inspection data population, improves mock abstractions, and adds a boatload more tests. Leverages new abstraction to improve the mocking/wrapping of states. Adds stateConfiguration tests.
Adds support for mocked error types
Supports adding inspection data both from preprocessor and during execution.

Support Catch and Retry fields

Rename mocking package to local_mocking
Clearly mark mocking functionality related to Step Functions Local. This will help to distinguish between Local mocks and TestState mocks in the upcoming work.

Adds support for field validation modes

Adds support for context object mocking

Tests

Related

@tiurin tiurin added this to the 4.12 milestone Nov 26, 2025
@tiurin tiurin requested a review from gregfurman November 26, 2025 09:07
@tiurin tiurin self-assigned this Nov 26, 2025
@tiurin tiurin added aws:stepfunctions AWS Step Functions semver: minor Non-breaking changes which can be included in minor releases, but not in patch releases docs: skip Pull request does not require documentation changes notes: needed Pull request should be mentioned in the release notes labels Nov 26, 2025
@localstack-bot
Copy link
Contributor

Currently, only patch changes are allowed on main. Your PR labels (aws:stepfunctions, semver: minor, docs: skip, notes: needed) indicate that it cannot be merged into the main at this time.

2 similar comments
@localstack-bot
Copy link
Contributor

Currently, only patch changes are allowed on main. Your PR labels (aws:stepfunctions, semver: minor, docs: skip, notes: needed) indicate that it cannot be merged into the main at this time.

@localstack-bot
Copy link
Contributor

Currently, only patch changes are allowed on main. Your PR labels (aws:stepfunctions, semver: minor, docs: skip, notes: needed) indicate that it cannot be merged into the main at this time.

@github-actions
Copy link

github-actions bot commented Nov 26, 2025

Test Results - Preflight, Unit

22 669 tests  ±0   20 901 ✅ ±0   5m 52s ⏱️ -5s
     1 suites ±0    1 768 💤 ±0 
     1 files   ±0        0 ❌ ±0 

Results for commit 890ce8f. ± Comparison against base commit c5aa22c.

♻️ This comment has been updated with latest results.

@tiurin tiurin changed the title [Step functions] Add new TestState API capabilities [SFN] Add new TestState API capabilities Nov 26, 2025
@github-actions
Copy link

github-actions bot commented Nov 26, 2025

Test Results (amd64) - Acceptance

7 tests  ±0   5 ✅ ±0   3m 24s ⏱️ +3s
1 suites ±0   2 💤 ±0 
1 files   ±0   0 ❌ ±0 

Results for commit 890ce8f. ± Comparison against base commit c5aa22c.

♻️ This comment has been updated with latest results.

@github-actions
Copy link

github-actions bot commented Nov 26, 2025

Test Results (amd64) - Integration, Bootstrap

    5 files      5 suites   2h 41m 43s ⏱️
5 476 tests 4 925 ✅ 551 💤 0 ❌
5 482 runs  4 925 ✅ 557 💤 0 ❌

Results for commit 890ce8f.

♻️ This comment has been updated with latest results.

@github-actions
Copy link

github-actions bot commented Nov 26, 2025

LocalStack Community integration with Pro

    2 files  ±  0      2 suites  ±0   2h 4m 41s ⏱️ + 3m 10s
5 102 tests +123  4 711 ✅ +110  391 💤 +13  0 ❌ ±0 
5 104 runs  +123  4 711 ✅ +110  393 💤 +13  0 ❌ ±0 

Results for commit 890ce8f. ± Comparison against base commit c5aa22c.

This pull request removes 19 and adds 142 tests. Note that renamed tests count towards both.
tests.aws.services.stepfunctions.v2.mocking.test_aws_scenarios.TestBaseScenarios ‑ test_lambda_sqs_integration_happy_path
tests.aws.services.stepfunctions.v2.mocking.test_aws_scenarios.TestBaseScenarios ‑ test_lambda_sqs_integration_hybrid_path
tests.aws.services.stepfunctions.v2.mocking.test_aws_scenarios.TestBaseScenarios ‑ test_lambda_sqs_integration_retry_path
tests.aws.services.stepfunctions.v2.mocking.test_base_callbacks.TestBaseScenarios ‑ test_sfn_start_execution_sync[SFN_SYNC2]
tests.aws.services.stepfunctions.v2.mocking.test_base_callbacks.TestBaseScenarios ‑ test_sfn_start_execution_sync[SFN_SYNC]
tests.aws.services.stepfunctions.v2.mocking.test_base_callbacks.TestBaseScenarios ‑ test_sqs_wait_for_task_token
tests.aws.services.stepfunctions.v2.mocking.test_base_callbacks.TestBaseScenarios ‑ test_sqs_wait_for_task_token_task_failure
tests.aws.services.stepfunctions.v2.mocking.test_base_scenarios.TestBaseScenarios ‑ test_dynamodb_put_get_item
tests.aws.services.stepfunctions.v2.mocking.test_base_scenarios.TestBaseScenarios ‑ test_events_put_events
tests.aws.services.stepfunctions.v2.mocking.test_base_scenarios.TestBaseScenarios ‑ test_lambda_invoke
…
tests.aws.services.s3.test_s3_api.TestS3BucketObjectTagging ‑ test_head_object_with_tags
tests.aws.services.s3control.test_s3control.TestS3ControlTagging ‑ test_tag_lifecycle
tests.aws.services.s3control.test_s3control.TestS3ControlTagging ‑ test_tag_operation_no_bucket
tests.aws.services.s3control.test_s3control.TestS3ControlTagging ‑ test_tag_resource_validation
tests.aws.services.stepfunctions.v2.local_mocking.test_aws_scenarios.TestBaseScenarios ‑ test_lambda_sqs_integration_happy_path
tests.aws.services.stepfunctions.v2.local_mocking.test_aws_scenarios.TestBaseScenarios ‑ test_lambda_sqs_integration_hybrid_path
tests.aws.services.stepfunctions.v2.local_mocking.test_aws_scenarios.TestBaseScenarios ‑ test_lambda_sqs_integration_retry_path
tests.aws.services.stepfunctions.v2.local_mocking.test_base_callbacks.TestBaseScenarios ‑ test_sfn_start_execution_sync[SFN_SYNC2]
tests.aws.services.stepfunctions.v2.local_mocking.test_base_callbacks.TestBaseScenarios ‑ test_sfn_start_execution_sync[SFN_SYNC]
tests.aws.services.stepfunctions.v2.local_mocking.test_base_callbacks.TestBaseScenarios ‑ test_sqs_wait_for_task_token
…

♻️ This comment has been updated with latest results.

@tiurin tiurin force-pushed the feature/step-functions/test-state-main branch from c61f3e1 to 7bf7ea6 Compare November 27, 2025 11:22
@github-actions
Copy link

Helper Script Tests

34 tests   34 ✅  0s ⏱️
 2 suites   0 💤
 1 files     0 ❌

Results for commit 7bf7ea6.

@github-actions
Copy link

S3 Image Test Results (AMD64 / ARM64)

    2 files    2 suites   8m 17s ⏱️
  539 tests 487 ✅  52 💤 0 ❌
1 078 runs  974 ✅ 104 💤 0 ❌

Results for commit 7bf7ea6.

@tiurin tiurin force-pushed the feature/step-functions/test-state-main branch from 7bf7ea6 to c5d5aab Compare November 27, 2025 11:30
tiurin and others added 3 commits November 28, 2025 15:40
See https://aws.amazon.com/blogs/aws/accelerate-workflow-development-with-enhanced-local-testing-in-aws-step-functions/ for the overview of improvements.

Rename `mocking` package to `local_mocking`
Clearly mark mocking functionality related to Step Functions Local. This will help to distinguish between Local mocks and TestState mocks in the upcoming work.

feat(sfn): Add StateName support
Adds support for StateName parameter to TestState API.
Extends TestStatePreprocessor and TestStateAmazonStateLanguageParser to accept an optional state_name parameter.
This signals to the parse function that we should be parsing a full state machine (not just a single state), and also allows the preprocessor to construct a TestStateProgram using this state_name.

Apply TestState mock to Task state result

feat: Support mocked errors, Map states, and improve mock abstractions
Adds support for mocking errors, map states, fixes inspection data population, improves mock abstractions, and adds a boatload more tests.
Leverages new abstraction to improve the mocking/wrapping of states.
Adds stateConfiguration tests.
Adds support for mocked error types
Supports adding inspection data both from preprocessor and during execution.

feat(test_state): Support Catch and Retry fields

Co-authored-by: Greg Furman <[email protected]>
Adds limited support for mocking a ContextObject in the SFN TestState API.

Empty context case is not accounted for.

Changes
Uses pydantic (and some python magic) to validate that passed in context, and bubble up a validationexception.
Reworks the inspectionData approach to instead patch each _eval_body and add appended results for a given key
@tiurin tiurin force-pushed the feature/step-functions/test-state-main branch from 5eb1f18 to 37ee009 Compare November 28, 2025 14:40
Add test for the upcoming blog post scenario.

Closes DRG-260.

Adds new validated test.

Also, adjusts validation for API Gateway Service Task state. Turns out that apigateway:invoke: has no equivalent in the AWS SDK service integration. Hence, the validation against botocore doesn't apply. A custom validation is needed for API Gateway Service Task state. Added a skip and TODO for now, to avoid failing validation.
@tiurin tiurin marked this pull request as ready for review November 28, 2025 16:10
@tiurin tiurin removed the request for review from joe4dev November 28, 2025 16:11
Copy link
Contributor

@gregfurman gregfurman left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

:shipit:

@tiurin tiurin merged commit 42ed9a1 into main Nov 28, 2025
42 checks passed
@tiurin tiurin deleted the feature/step-functions/test-state-main branch November 28, 2025 17:40
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

aws:stepfunctions AWS Step Functions docs: skip Pull request does not require documentation changes notes: needed Pull request should be mentioned in the release notes semver: minor Non-breaking changes which can be included in minor releases, but not in patch releases

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants