localstack-core 4.10.1.dev42__py3-none-any.whl → 4.12.1.dev18__py3-none-any.whl

localstack/services/stepfunctions/asl/static_analyser/test_state/test_state_analyser.py

@@ -1,12 +1,50 @@
-from typing import Final
+import json
+from typing import Any, Final
 
+# Botocore shape classes to drive validation
+from botocore.model import (
+    ListShape,
+    MapShape,
+    Shape,
+    StringShape,
+    StructureShape,
+)
+
+from localstack.aws.api.stepfunctions import (
+    Definition,
+    InvalidDefinition,
+    MockInput,
+    MockResponseValidationMode,
+    StateName,
+    TestStateInput,
+    ValidationException,
+)
 from localstack.services.stepfunctions.asl.antlr.runtime.ASLParser import ASLParser
-from localstack.services.stepfunctions.asl.component.state.state_execution.state_task.service.resource import (
-    ActivityResource,
-    Resource,
-    ServiceResource,
+from localstack.services.stepfunctions.asl.component.state.state import CommonStateField
+from localstack.services.stepfunctions.asl.component.state.state_execution.state_map.state_map import (
+    StateMap,
+)
+from localstack.services.stepfunctions.asl.component.state.state_execution.state_parallel.state_parallel import (
+    StateParallel,
+)
+from localstack.services.stepfunctions.asl.component.state.state_execution.state_task.service.state_task_service import (
+    StateTaskService,
+)
+from localstack.services.stepfunctions.asl.component.state.state_execution.state_task.service.state_task_service_api_gateway import (
+    StateTaskServiceApiGateway,
+)
+from localstack.services.stepfunctions.asl.component.state.state_execution.state_task.state_task import (
+    StateTask,
+)
+from localstack.services.stepfunctions.asl.component.state.state_fail.state_fail import StateFail
+from localstack.services.stepfunctions.asl.component.state.state_pass.state_pass import StatePass
+from localstack.services.stepfunctions.asl.component.state.state_succeed.state_succeed import (
+    StateSucceed,
 )
 from localstack.services.stepfunctions.asl.component.state.state_type import StateType
+from localstack.services.stepfunctions.asl.component.test_state.program.test_state_program import (
+    TestStateProgram,
+)
 from localstack.services.stepfunctions.asl.parse.test_state.asl_parser import (
     TestStateAmazonStateLanguageParser,
 )
@@ -14,6 +52,11 @@ from localstack.services.stepfunctions.asl.static_analyser.static_analyser impor
 
 
 class TestStateStaticAnalyser(StaticAnalyser):
+    state_name: StateName | None
+
+    def __init__(self, state_name: StateName | None = None):
+        self.state_name = state_name
+
     _SUPPORTED_STATE_TYPES: Final[set[StateType]] = {
         StateType.Task,
         StateType.Pass,
@@ -21,10 +64,216 @@ class TestStateStaticAnalyser(StaticAnalyser):
         StateType.Choice,
         StateType.Succeed,
         StateType.Fail,
+        StateType.Map,
     }
 
-    def analyse(self, definition) -> None:
-        _, parser_rule_context = TestStateAmazonStateLanguageParser.parse(definition)
+    @staticmethod
+    def is_state_in_definition(definition: Definition, state_name: StateName) -> bool:
+        test_program, _ = TestStateAmazonStateLanguageParser.parse(definition, state_name)
+        if not isinstance(test_program, TestStateProgram):
+            raise ValueError("expected parsed EvalComponent to be of type TestStateProgram")
+
+        return test_program.test_state is not None
+
+    @staticmethod
+    def validate_role_arn_required(
+        mock_input: MockInput, definition: Definition, state_name: StateName
+    ) -> None:
+        test_program, _ = TestStateAmazonStateLanguageParser.parse(definition, state_name)
+        test_state = test_program.test_state
+        if isinstance(test_state, StateTask) and mock_input is None:
+            raise ValidationException("RoleArn must be specified when testing a Task state")
+
+    @staticmethod
+    def validate_mock(test_state_input: TestStateInput) -> None:
+        test_program, _ = TestStateAmazonStateLanguageParser.parse(
+            test_state_input.get("definition"), test_state_input.get("stateName")
+        )
+        test_state = test_program.test_state
+        mock_input = test_state_input.get("mock")
+
+        TestStateStaticAnalyser.validate_test_state_allows_mocking(
+            mock_input=mock_input, test_state=test_state
+        )
+
+        if mock_input is None:
+            return
+
+        if test_state_input.get("revealSecrets"):
+            raise ValidationException(
+                "TestState does not support RevealSecrets when a mock is specified."
+            )
+
+        if {"result", "errorOutput"} <= mock_input.keys():
+            raise ValidationException(
+                "A test mock should have only one of the following fields: [result, errorOutput]."
+            )
+
+        mock_result_raw = mock_input.get("result")
+        if mock_result_raw is None:
+            return
+        try:
+            mock_result = json.loads(mock_result_raw)
+        except json.JSONDecodeError:
+            raise ValidationException("Mocked result must be valid JSON")
+
+        if isinstance(test_state, StateMap):
+            TestStateStaticAnalyser.validate_mock_result_matches_map_definition(
+                mock_result=mock_result, test_state=test_state
+            )
+
+        if isinstance(test_state, StateTaskService):
+            field_validation_mode = mock_input.get(
+                "fieldValidationMode", MockResponseValidationMode.STRICT
+            )
+            TestStateStaticAnalyser.validate_mock_result_matches_api_shape(
+                mock_result=mock_result,
+                field_validation_mode=field_validation_mode,
+                test_state=test_state,
+            )
+
+    @staticmethod
+    def validate_test_state_allows_mocking(
+        mock_input: MockInput, test_state: CommonStateField
+    ) -> None:
+        if mock_input is None and isinstance(test_state, (StateMap, StateParallel)):
+            # This is a literal message when a Map or Parallel state is not accompanied by a mock in a test state request.
+            # The message is the same for both cases and is not parametrised anyhow.
+            raise InvalidDefinition(
+                "TestState API does not support Map or Parallel states. Supported state types include: [Task, Wait, Pass, Succeed, Fail, Choice]"
+            )
+
+        if mock_input is not None and isinstance(test_state, (StatePass, StateFail, StateSucceed)):
+            raise ValidationException(
+                f"State type '{test_state.state_type.name}' is not supported when a mock is specified"
+            )
+
+    @staticmethod
+    def validate_mock_result_matches_map_definition(mock_result: Any, test_state: StateMap):
+        if test_state.result_writer is not None and not isinstance(mock_result, dict):
+            raise ValidationException("Mocked result must be a JSON object.")
+
+        if test_state.result_writer is None and not isinstance(mock_result, list):
+            raise ValidationException("Mocked result must be an array.")
+
+    @staticmethod
+    def validate_mock_result_matches_api_shape(
+        mock_result: Any,
+        field_validation_mode: MockResponseValidationMode,
+        test_state: StateTaskService,
+    ):
+        # apigateway:invoke: has no equivalent in the AWS SDK service integration.
+        # Hence, the validation against botocore doesn't apply.
+        # See the note in https://docs.aws.amazon.com/step-functions/latest/dg/connect-api-gateway.html
+        # TODO do custom validation for apigateway:invoke:
+        if isinstance(test_state, StateTaskServiceApiGateway):
+            return
+
+        if field_validation_mode == MockResponseValidationMode.NONE:
+            return
+
+        boto_service_name = test_state._get_boto_service_name()
+        service_action_name = test_state._get_boto_service_action()
+        output_shape = test_state._get_boto_operation_model(
+            boto_service_name=boto_service_name, service_action_name=service_action_name
+        ).output_shape
+
+        # If the operation has no output, there's nothing to validate
+        if output_shape is None:
+            return
+
+        def _raise_type_error(expected_type: str, field_name: str) -> None:
+            raise ValidationException(
+                f"Mock result schema validation error: Field '{field_name}' must be {expected_type}"
+            )
+
+        def _validate_value(value: Any, shape: Shape, field_name: str | None = None) -> None:
+            # Document type accepts any JSON value
+            if shape.type_name == "document":
+                return
+
+            if isinstance(shape, StructureShape):
+                if not isinstance(value, dict):
+                    # this is a defensive check, the mock result is loaded from JSON before, so should always be a dict
+                    raise ValidationException(
+                        f"Mock result must be a valid JSON object, but got '{type(value)}' instead"
+                    )
+                # Build a mapping from SFN-normalised member keys -> botocore member shapes
+                members = shape.members
+                sfn_key_to_member_shape: dict[str, Shape] = {
+                    StateTaskService._to_sfn_cased(member_key): member_shape
+                    for member_key, member_shape in members.items()
+                }
+                if field_validation_mode == MockResponseValidationMode.STRICT:
+                    # Ensure required members are present, using SFN-normalised keys
+                    for required_key in shape.required_members:
+                        sfn_required_key = StateTaskService._to_sfn_cased(required_key)
+                        if sfn_required_key not in value:
+                            raise ValidationException(
+                                f"Mock result schema validation error: Required field '{sfn_required_key}' is missing"
+                            )
+                # Validate present fields (match SFN-normalised keys to member shapes)
+                for mock_field_name, mock_field_value in value.items():
+                    member_shape = sfn_key_to_member_shape.get(mock_field_name)
+                    if member_shape is None:
+                        # Fields that are present in mock but are not in the API spec should not raise validation errors - forward compatibility
+                        continue
+                    _validate_value(mock_field_value, member_shape, mock_field_name)
+                return
+
+            if isinstance(shape, ListShape):
+                if not isinstance(value, list):
+                    _raise_type_error("an array", field_name)
+                member_shape = shape.member
+                for list_item in value:
+                    _validate_value(list_item, member_shape, field_name)
+                return
+
+            if isinstance(shape, MapShape):
+                if not isinstance(value, dict):
+                    _raise_type_error("an object", field_name)
+                value_shape = shape.value
+                for _, map_item_value in value.items():
+                    _validate_value(map_item_value, value_shape, field_name)
+                return
+
+            # Primitive shapes and others
+            type_name = shape.type_name
+            match type_name:
+                case "string" | "timestamp":
+                    if not isinstance(value, str):
+                        _raise_type_error("a string", field_name)
+                    # Validate enum if present
+                    if isinstance(shape, StringShape):
+                        enum = getattr(shape, "enum", None)
+                        if enum and value not in enum:
+                            raise ValidationException(
+                                f"Mock result schema validation error: Field '{field_name}' is not an expected value"
+                            )
+
+                case "integer" | "long":
+                    if not isinstance(value, int) or isinstance(value, bool):
+                        _raise_type_error("a number", field_name)
+
+                case "float" | "double":
+                    if not (isinstance(value, (int, float)) or isinstance(value, bool)):
+                        _raise_type_error("a number", field_name)
+
+                case "boolean":
+                    if not isinstance(value, bool):
+                        _raise_type_error("a boolean", field_name)
+
+                case "blob":
+                    if not (isinstance(value, (str, bytes))):
+                        _raise_type_error("a string", field_name)
+
+        # Perform validation against the output shape
+        _validate_value(mock_result, output_shape)
+
+    def analyse(self, definition: str) -> None:
+        _, parser_rule_context = TestStateAmazonStateLanguageParser.parse(
+            definition, self.state_name
+        )
         self.visit(parser_rule_context)
 
     def visitState_type(self, ctx: ASLParser.State_typeContext) -> None:
@@ -32,18 +281,3 @@ class TestStateStaticAnalyser(StaticAnalyser):
         state_type = StateType(state_type_value)
         if state_type not in self._SUPPORTED_STATE_TYPES:
             raise ValueError(f"Unsupported state type for TestState runs '{state_type}'.")
-
-    def visitResource_decl(self, ctx: ASLParser.Resource_declContext) -> None:
-        resource_str: str = ctx.string_literal().getText()[1:-1]
-        resource = Resource.from_resource_arn(resource_str)
-
-        if isinstance(resource, ActivityResource):
-            raise ValueError(
-                f"ActivityResources are not supported for TestState runs {resource_str}."
-            )
-
-        if isinstance(resource, ServiceResource):
-            if resource.condition is not None:
-                raise ValueError(
-                    f"Service integration patterns are not supported for TestState runs {resource_str}."
-                )

localstack/services/stepfunctions/backend/execution.py

@@ -1,9 +1,8 @@
 from __future__ import annotations
 
 import datetime
-import json
 import logging
-from typing import Final
+from typing import Any, Final
 
 from localstack.aws.api.events import PutEventsRequestEntry
 from localstack.aws.api.stepfunctions import (
@@ -59,7 +58,7 @@ from localstack.services.stepfunctions.backend.state_machine import (
     StateMachineInstance,
     StateMachineVersion,
 )
-from localstack.services.stepfunctions.mocking.mock_config import MockTestCase
+from localstack.services.stepfunctions.local_mocking.mock_config import LocalMockTestCase
 
 LOG = logging.getLogger(__name__)
 
@@ -108,10 +107,10 @@ class Execution:
     state_machine_version_arn: Final[Arn | None]
     state_machine_alias_arn: Final[Arn | None]
 
-    mock_test_case: Final[MockTestCase | None]
+    local_mock_test_case: Final[LocalMockTestCase | None]
 
     start_date: Final[Timestamp]
-    input_data: Final[json | None]
+    input_data: Final[dict[str, Any] | None]
     input_details: Final[CloudWatchEventsExecutionDataDetails | None]
     trace_header: Final[TraceHeader | None]
     _cloud_watch_logging_session: Final[CloudWatchLoggingSession | None]
@@ -119,7 +118,7 @@ class Execution:
     exec_status: ExecutionStatus | None
     stop_date: Timestamp | None
 
-    output: json | None
+    output: dict[str, Any] | None
     output_details: CloudWatchEventsExecutionDataDetails | None
 
     error: SensitiveError | None
@@ -141,10 +140,10 @@ class Execution:
         start_date: Timestamp,
         cloud_watch_logging_session: CloudWatchLoggingSession | None,
         activity_store: dict[Arn, Activity],
-        input_data: json | None = None,
+        input_data: dict[str, Any] | None = None,
         trace_header: TraceHeader | None = None,
         state_machine_alias_arn: Arn | None = None,
-        mock_test_case: MockTestCase | None = None,
+        local_mock_test_case: LocalMockTestCase | None = None,
     ):
         self.name = name
         self.sm_type = sm_type
@@ -173,7 +172,7 @@ class Execution:
         self.error = None
         self.cause = None
         self._activity_store = activity_store
-        self.mock_test_case = mock_test_case
+        self.local_mock_test_case = local_mock_test_case
 
     def _get_events_client(self):
         return connect_to(aws_access_key_id=self.account_id, region_name=self.region_name).events
@@ -304,7 +303,7 @@ class Execution:
             exec_comm=self._get_start_execution_worker_comm(),
             cloud_watch_logging_session=self._cloud_watch_logging_session,
             activity_store=self._activity_store,
-            mock_test_case=self.mock_test_case,
+            local_mock_test_case=self.local_mock_test_case,
         )
 
     def start(self) -> None:
@@ -391,7 +390,7 @@ class SyncExecution(Execution):
             exec_comm=self._get_start_execution_worker_comm(),
             cloud_watch_logging_session=self._cloud_watch_logging_session,
             activity_store=self._activity_store,
-            mock_test_case=self.mock_test_case,
+            local_mock_test_case=self.local_mock_test_case,
         )
 
     def _get_start_execution_worker_comm(self) -> BaseExecutionWorkerCommunication:

localstack/services/stepfunctions/backend/execution_worker.py

@@ -29,7 +29,7 @@ from localstack.services.stepfunctions.backend.activity import Activity
 from localstack.services.stepfunctions.backend.execution_worker_comm import (
     ExecutionWorkerCommunication,
 )
-from localstack.services.stepfunctions.mocking.mock_config import MockTestCase
+from localstack.services.stepfunctions.local_mocking.mock_config import LocalMockTestCase
 from localstack.utils.common import TMP_THREADS
 
 
@@ -37,7 +37,7 @@ class ExecutionWorker:
     _evaluation_details: Final[EvaluationDetails]
     _execution_communication: Final[ExecutionWorkerCommunication]
     _cloud_watch_logging_session: Final[CloudWatchLoggingSession | None]
-    _mock_test_case: Final[MockTestCase | None]
+    _local_mock_test_case: Final[LocalMockTestCase | None]
     _activity_store: dict[Arn, Activity]
 
     env: Environment | None
@@ -48,12 +48,12 @@ class ExecutionWorker:
         exec_comm: ExecutionWorkerCommunication,
         cloud_watch_logging_session: CloudWatchLoggingSession | None,
         activity_store: dict[Arn, Activity],
-        mock_test_case: MockTestCase | None = None,
+        local_mock_test_case: LocalMockTestCase | None = None,
     ):
         self._evaluation_details = evaluation_details
         self._execution_communication = exec_comm
         self._cloud_watch_logging_session = cloud_watch_logging_session
-        self._mock_test_case = mock_test_case
+        self._local_mock_test_case = local_mock_test_case
         self._activity_store = activity_store
         self.env = None
 
@@ -82,7 +82,7 @@ class ExecutionWorker:
             event_history_context=EventHistoryContext.of_program_start(),
             cloud_watch_logging_session=self._cloud_watch_logging_session,
             activity_store=self._activity_store,
-            mock_test_case=self._mock_test_case,
+            local_mock_test_case=self._local_mock_test_case,
         )
 
     def _execution_logic(self):

localstack/services/stepfunctions/backend/test_state/execution.py

@@ -19,7 +19,9 @@ from localstack.services.stepfunctions.asl.eval.program_state import (
     ProgramState,
 )
 from localstack.services.stepfunctions.asl.eval.test_state.program_state import (
+    ProgramCaughtError,
     ProgramChoiceSelected,
+    ProgramRetriable,
 )
 from localstack.services.stepfunctions.asl.utils.encoding import to_json_str
 from localstack.services.stepfunctions.backend.activity import Activity
@@ -31,6 +33,7 @@ from localstack.services.stepfunctions.backend.state_machine import StateMachine
 from localstack.services.stepfunctions.backend.test_state.execution_worker import (
     TestStateExecutionWorker,
 )
+from localstack.services.stepfunctions.backend.test_state.test_state_mock import TestStateMock
 
 LOG = logging.getLogger(__name__)
 
@@ -38,6 +41,8 @@ LOG = logging.getLogger(__name__)
 class TestStateExecution(Execution):
     exec_worker: TestStateExecutionWorker | None
     next_state: str | None
+    state_name: str | None
+    mock: TestStateMock | None
 
     class TestCaseExecutionWorkerCommunication(BaseExecutionWorkerCommunication):
         _execution: TestStateExecution
@@ -48,6 +53,16 @@ class TestStateExecution(Execution):
                 self.execution.exec_status = ExecutionStatus.SUCCEEDED
                 self.execution.output = self.execution.exec_worker.env.states.get_input()
                 self.execution.next_state = exit_program_state.next_state_name
+            elif isinstance(exit_program_state, ProgramCaughtError):
+                self.execution.exec_status = ExecutionStatus.SUCCEEDED
+                self.execution.error = exit_program_state.error
+                self.execution.cause = exit_program_state.cause
+                self.execution.output = self.execution.exec_worker.env.states.get_input()
+                self.execution.next_state = exit_program_state.next_state_name
+            elif isinstance(exit_program_state, ProgramRetriable):
+                self.execution.exec_status = ExecutionStatus.SUCCEEDED
+                self.execution.error = exit_program_state.error
+                self.execution.cause = exit_program_state.cause
             else:
                 self._reflect_execution_status()
 
@@ -61,7 +76,9 @@ class TestStateExecution(Execution):
         state_machine: StateMachineInstance,
         start_date: Timestamp,
         activity_store: dict[Arn, Activity],
+        state_name: str | None = None,
         input_data: dict | None = None,
+        mock: TestStateMock | None = None,
     ):
         super().__init__(
             name=name,
@@ -79,6 +96,8 @@ class TestStateExecution(Execution):
         )
         self._execution_terminated_event = threading.Event()
         self.next_state = None
+        self.state_name = state_name
+        self.mock = mock
 
     def _get_start_execution_worker_comm(self) -> BaseExecutionWorkerCommunication:
         return self.TestCaseExecutionWorkerCommunication(self)
@@ -93,6 +112,8 @@ class TestStateExecution(Execution):
             exec_comm=self._get_start_execution_worker_comm(),
             cloud_watch_logging_session=self._cloud_watch_logging_session,
             activity_store=self._activity_store,
+            state_name=self.state_name,
+            mock=self.mock,
         )
 
     def publish_execution_status_change_event(self):
@@ -117,6 +138,21 @@ class TestStateExecution(Execution):
             test_state_output = TestStateOutput(
                 status=TestExecutionStatus.SUCCEEDED, nextState=self.next_state, output=output_str
             )
+        elif isinstance(exit_program_state, ProgramCaughtError):
+            output_str = to_json_str(self.output)
+            test_state_output = TestStateOutput(
+                status=TestExecutionStatus.CAUGHT_ERROR,
+                nextState=self.next_state,
+                output=output_str,
+                error=exit_program_state.error,
+                cause=exit_program_state.cause,
+            )
+        elif isinstance(exit_program_state, ProgramRetriable):
+            test_state_output = TestStateOutput(
+                status=TestExecutionStatus.RETRIABLE,
+                error=exit_program_state.error,
+                cause=exit_program_state.cause,
+            )
         else:
             # TODO: handle other statuses
             LOG.warning(

localstack/services/stepfunctions/backend/test_state/execution_worker.py

@@ -1,8 +1,13 @@
+from localstack.aws.api.stepfunctions import Arn, StateName
 from localstack.services.stepfunctions.asl.component.eval_component import EvalComponent
 from localstack.services.stepfunctions.asl.eval.environment import Environment
+from localstack.services.stepfunctions.asl.eval.evaluation_details import EvaluationDetails
 from localstack.services.stepfunctions.asl.eval.event.event_manager import (
     EventHistoryContext,
 )
+from localstack.services.stepfunctions.asl.eval.event.logging import (
+    CloudWatchLoggingSession,
+)
 from localstack.services.stepfunctions.asl.eval.states import (
     ContextObjectData,
     ExecutionData,
@@ -12,15 +17,41 @@ from localstack.services.stepfunctions.asl.eval.test_state.environment import Te
 from localstack.services.stepfunctions.asl.parse.test_state.asl_parser import (
     TestStateAmazonStateLanguageParser,
 )
+from localstack.services.stepfunctions.backend.activity import Activity
 from localstack.services.stepfunctions.backend.execution_worker import SyncExecutionWorker
+from localstack.services.stepfunctions.backend.execution_worker_comm import (
+    ExecutionWorkerCommunication,
+)
+from localstack.services.stepfunctions.backend.test_state.test_state_mock import TestStateMock
 
 
 class TestStateExecutionWorker(SyncExecutionWorker):
     env: TestStateEnvironment | None
+    state_name: str | None = None
+    mock: TestStateMock | None
+
+    def __init__(
+        self,
+        evaluation_details: EvaluationDetails,
+        exec_comm: ExecutionWorkerCommunication,
+        cloud_watch_logging_session: CloudWatchLoggingSession | None,
+        activity_store: dict[Arn, Activity],
+        state_name: StateName | None = None,
+        mock: TestStateMock | None = None,
+    ):
+        super().__init__(
+            evaluation_details,
+            exec_comm,
+            cloud_watch_logging_session,
+            activity_store,
+            local_mock_test_case=None,  # local mock is only applicable to SFN Local, but not for TestState
+        )
+        self.state_name = state_name
+        self.mock = mock
 
     def _get_evaluation_entrypoint(self) -> EvalComponent:
         return TestStateAmazonStateLanguageParser.parse(
-            self._evaluation_details.state_machine_details.definition
+            self._evaluation_details.state_machine_details.definition, self.state_name
         )[0]
 
     def _get_evaluation_environment(self) -> Environment:
@@ -43,4 +74,5 @@ class TestStateExecutionWorker(SyncExecutionWorker):
             event_history_context=EventHistoryContext.of_program_start(),
             cloud_watch_logging_session=self._cloud_watch_logging_session,
             activity_store=self._activity_store,
+            mock=self.mock,
         )