localstack-core 4.3.1.dev63__tar.gz → 4.3.1.dev65__tar.gz

{localstack_core-4.3.1.dev63 → localstack_core-4.3.1.dev65}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: localstack-core
-Version: 4.3.1.dev63
+Version: 4.3.1.dev65
 Summary: The core library and runtime of LocalStack
 Author-email: LocalStack Contributors <info@localstack.cloud>
 License-Expression: Apache-2.0

localstack_core-4.3.1.dev65/localstack-core/localstack/services/stepfunctions/asl/component/state/state_execution/state_task/mock_eval_utils.py

@@ -0,0 +1,45 @@
+import copy
+
+from localstack.aws.api.stepfunctions import HistoryEventType, TaskFailedEventDetails
+from localstack.services.stepfunctions.asl.component.common.error_name.custom_error_name import (
+    CustomErrorName,
+)
+from localstack.services.stepfunctions.asl.component.common.error_name.failure_event import (
+    FailureEvent,
+    FailureEventException,
+)
+from localstack.services.stepfunctions.asl.eval.environment import Environment
+from localstack.services.stepfunctions.asl.eval.event.event_detail import EventDetails
+from localstack.services.stepfunctions.mocking.mock_config import (
+    MockedResponse,
+    MockedResponseReturn,
+    MockedResponseThrow,
+)
+
+
+def _eval_mocked_response_throw(env: Environment, mocked_response: MockedResponseThrow) -> None:
+    task_failed_event_details = TaskFailedEventDetails(
+        error=mocked_response.error, cause=mocked_response.cause
+    )
+    error_name = CustomErrorName(mocked_response.error)
+    failure_event = FailureEvent(
+        env=env,
+        error_name=error_name,
+        event_type=HistoryEventType.TaskFailed,
+        event_details=EventDetails(taskFailedEventDetails=task_failed_event_details),
+    )
+    raise FailureEventException(failure_event=failure_event)
+
+
+def _eval_mocked_response_return(env: Environment, mocked_response: MockedResponseReturn) -> None:
+    payload_copy = copy.deepcopy(mocked_response.payload)
+    env.stack.append(payload_copy)
+
+
+def eval_mocked_response(env: Environment, mocked_response: MockedResponse) -> None:
+    if isinstance(mocked_response, MockedResponseReturn):
+        _eval_mocked_response_return(env=env, mocked_response=mocked_response)
+    elif isinstance(mocked_response, MockedResponseThrow):
+        _eval_mocked_response_throw(env=env, mocked_response=mocked_response)
+    else:
+        raise RuntimeError(f"Invalid MockedResponse type '{type(mocked_response)}'")

{localstack_core-4.3.1.dev63 → localstack_core-4.3.1.dev65}/localstack-core/localstack/services/stepfunctions/asl/component/state/state_execution/state_task/service/state_task_service.py

@@ -33,6 +33,9 @@ from localstack.services.stepfunctions.asl.component.common.error_name.states_er
 from localstack.services.stepfunctions.asl.component.state.state_execution.state_task.credentials import (
     StateCredentials,
 )
+from localstack.services.stepfunctions.asl.component.state.state_execution.state_task.mock_eval_utils import (
+    eval_mocked_response,
+)
 from localstack.services.stepfunctions.asl.component.state.state_execution.state_task.service.resource import (
     ResourceRuntimePart,
     ServiceResource,
@@ -44,6 +47,7 @@ from localstack.services.stepfunctions.asl.component.state.state_props import St
 from localstack.services.stepfunctions.asl.eval.environment import Environment
 from localstack.services.stepfunctions.asl.eval.event.event_detail import EventDetails
 from localstack.services.stepfunctions.asl.utils.encoding import to_json_str
+from localstack.services.stepfunctions.mocking.mock_config import MockedResponse
 from localstack.services.stepfunctions.quotas import is_within_size_quota
 from localstack.utils.strings import camel_to_snake_case, snake_to_camel_case, to_bytes, to_str
 
@@ -352,12 +356,16 @@ class StateTaskService(StateTask, abc.ABC):
         normalised_parameters = copy.deepcopy(raw_parameters)
         self._normalise_parameters(normalised_parameters)
 
-        self._eval_service_task(
-            env=env,
-            resource_runtime_part=resource_runtime_part,
-            normalised_parameters=normalised_parameters,
-            state_credentials=state_credentials,
-        )
+        if env.is_mocked_mode():
+            mocked_response: MockedResponse = env.get_current_mocked_response()
+            eval_mocked_response(env=env, mocked_response=mocked_response)
+        else:
+            self._eval_service_task(
+                env=env,
+                resource_runtime_part=resource_runtime_part,
+                normalised_parameters=normalised_parameters,
+                state_credentials=state_credentials,
+            )
 
         output_value = env.stack[-1]
         self._normalise_response(output_value)

{localstack_core-4.3.1.dev63 → localstack_core-4.3.1.dev65}/localstack-core/localstack/services/stepfunctions/asl/eval/environment.py

@@ -34,6 +34,7 @@ from localstack.services.stepfunctions.asl.eval.program_state import (
 from localstack.services.stepfunctions.asl.eval.states import ContextObjectData, States
 from localstack.services.stepfunctions.asl.eval.variable_store import VariableStore
 from localstack.services.stepfunctions.backend.activity import Activity
+from localstack.services.stepfunctions.mocking.mock_config import MockedResponse, MockTestCase
 
 LOG = logging.getLogger(__name__)
 
@@ -51,6 +52,7 @@ class Environment:
     callback_pool_manager: CallbackPoolManager
     map_run_record_pool_manager: MapRunRecordPoolManager
     activity_store: Final[dict[Arn, Activity]]
+    mock_test_case: Optional[MockTestCase] = None
 
     _frames: Final[list[Environment]]
     _is_frame: bool = False
@@ -69,6 +71,7 @@ class Environment:
         cloud_watch_logging_session: Optional[CloudWatchLoggingSession],
         activity_store: dict[Arn, Activity],
         variable_store: Optional[VariableStore] = None,
+        mock_test_case: Optional[MockTestCase] = None,
     ):
         super(Environment, self).__init__()
         self._state_mutex = threading.RLock()
@@ -86,6 +89,8 @@ class Environment:
 
         self.activity_store = activity_store
 
+        self.mock_test_case = mock_test_case
+
         self._frames = list()
         self._is_frame = False
 
@@ -133,6 +138,7 @@ class Environment:
             cloud_watch_logging_session=env.cloud_watch_logging_session,
             activity_store=env.activity_store,
             variable_store=variable_store,
+            mock_test_case=env.mock_test_case,
         )
         frame._is_frame = True
         frame.event_manager = env.event_manager
@@ -262,3 +268,25 @@ class Environment:
 
     def is_standard_workflow(self) -> bool:
         return self.execution_type == StateMachineType.STANDARD
+
+    def is_mocked_mode(self) -> bool:
+        return self.mock_test_case is not None
+
+    def get_current_mocked_response(self) -> MockedResponse:
+        if not self.is_mocked_mode():
+            raise RuntimeError(
+                "Cannot retrieve mocked response: execution is not operating in mocked mode"
+            )
+        state_name = self.next_state_name
+        state_mocked_responses: Optional = self.mock_test_case.state_mocked_responses.get(
+            state_name
+        )
+        if state_mocked_responses is None:
+            raise RuntimeError(f"No mocked response definition for state '{state_name}'")
+        retry_count = self.states.context_object.context_object_data["State"]["RetryCount"]
+        if len(state_mocked_responses.mocked_responses) <= retry_count:
+            raise RuntimeError(
+                f"No mocked response definition for state '{state_name}' "
+                f"and retry number '{retry_count}'"
+            )
+        return state_mocked_responses.mocked_responses[retry_count]

{localstack_core-4.3.1.dev63 → localstack_core-4.3.1.dev65}/localstack-core/localstack/services/stepfunctions/backend/execution.py

@@ -59,6 +59,7 @@ from localstack.services.stepfunctions.backend.state_machine import (
     StateMachineInstance,
     StateMachineVersion,
 )
+from localstack.services.stepfunctions.mocking.mock_config import MockTestCase
 
 LOG = logging.getLogger(__name__)
 
@@ -107,6 +108,8 @@ class Execution:
     state_machine_version_arn: Final[Optional[Arn]]
     state_machine_alias_arn: Final[Optional[Arn]]
 
+    mock_test_case: Final[Optional[MockTestCase]]
+
     start_date: Final[Timestamp]
     input_data: Final[Optional[json]]
     input_details: Final[Optional[CloudWatchEventsExecutionDataDetails]]
@@ -141,6 +144,7 @@ class Execution:
         input_data: Optional[json] = None,
         trace_header: Optional[TraceHeader] = None,
         state_machine_alias_arn: Optional[Arn] = None,
+        mock_test_case: Optional[MockTestCase] = None,
     ):
         self.name = name
         self.sm_type = sm_type
@@ -169,6 +173,7 @@ class Execution:
         self.error = None
         self.cause = None
         self._activity_store = activity_store
+        self.mock_test_case = mock_test_case
 
     def _get_events_client(self):
         return connect_to(aws_access_key_id=self.account_id, region_name=self.region_name).events
@@ -301,6 +306,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,
         )
 
     def start(self) -> None:

{localstack_core-4.3.1.dev63 → localstack_core-4.3.1.dev65}/localstack-core/localstack/services/stepfunctions/backend/execution_worker.py

@@ -29,6 +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.utils.common import TMP_THREADS
 
 
@@ -36,6 +37,7 @@ class ExecutionWorker:
     _evaluation_details: Final[EvaluationDetails]
     _execution_communication: Final[ExecutionWorkerCommunication]
     _cloud_watch_logging_session: Final[Optional[CloudWatchLoggingSession]]
+    _mock_test_case: Final[Optional[MockTestCase]]
     _activity_store: dict[Arn, Activity]
 
     env: Optional[Environment]
@@ -46,10 +48,12 @@ class ExecutionWorker:
         exec_comm: ExecutionWorkerCommunication,
         cloud_watch_logging_session: Optional[CloudWatchLoggingSession],
         activity_store: dict[Arn, Activity],
+        mock_test_case: Optional[MockTestCase] = 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._activity_store = activity_store
         self.env = None
 
@@ -78,6 +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,
         )
 
     def _execution_logic(self):

localstack_core-4.3.1.dev65/localstack-core/localstack/services/stepfunctions/mocking/mock_config.py

@@ -0,0 +1,214 @@
+import abc
+from typing import Any, Final, Optional
+
+from localstack.services.stepfunctions.mocking.mock_config_file import (
+    RawMockConfig,
+    RawResponseModel,
+    RawTestCase,
+    _load_sfn_raw_mock_config,
+)
+
+
+class MockedResponse(abc.ABC):
+    range_start: Final[int]
+    range_end: Final[int]
+
+    def __init__(self, range_start: int, range_end: int):
+        super().__init__()
+        if range_start < 0 or range_end < 0:
+            raise ValueError(
+                f"Invalid range: both '{range_start}' and '{range_end}' must be positive integers."
+            )
+        if range_start != range_end and range_end < range_start + 1:
+            raise ValueError(
+                f"Invalid range: values must be equal or '{range_start}' "
+                f"must be at least one greater than '{range_end}'."
+            )
+        self.range_start = range_start
+        self.range_end = range_end
+
+
+class MockedResponseReturn(MockedResponse):
+    payload: Final[dict[Any, Any]]
+
+    def __init__(self, range_start: int, range_end: int, payload: dict[Any, Any]):
+        super().__init__(range_start=range_start, range_end=range_end)
+        self.payload = payload
+
+
+class MockedResponseThrow(MockedResponse):
+    error: Final[str]
+    cause: Final[str]
+
+    def __init__(self, range_start: int, range_end: int, error: str, cause: str):
+        super().__init__(range_start=range_start, range_end=range_end)
+        self.error = error
+        self.cause = cause
+
+
+class StateMockedResponses:
+    state_name: Final[str]
+    mocked_response_name: Final[str]
+    mocked_responses: Final[list[MockedResponse]]
+
+    def __init__(
+        self, state_name: str, mocked_response_name: str, mocked_responses: list[MockedResponse]
+    ):
+        self.state_name = state_name
+        self.mocked_response_name = mocked_response_name
+        self.mocked_responses = list()
+        last_range_end: int = 0
+        mocked_responses_sorted = sorted(mocked_responses, key=lambda mr: mr.range_start)
+        for mocked_response in mocked_responses_sorted:
+            if not mocked_response.range_start - last_range_end == 0:
+                raise RuntimeError(
+                    f"Inconsistent event numbering detected for state '{state_name}': "
+                    f"the previous mocked response ended at event '{last_range_end}' "
+                    f"while the next response '{mocked_response_name}' "
+                    f"starts at event '{mocked_response.range_start}'. "
+                    "Mock responses must be consecutively numbered. "
+                    f"Expected the next response to begin at event {last_range_end + 1}."
+                )
+            repeats = mocked_response.range_start - mocked_response.range_end + 1
+            self.mocked_responses.extend([mocked_response] * repeats)
+            last_range_end = mocked_response.range_end
+
+
+class MockTestCase:
+    state_machine_name: Final[str]
+    test_case_name: Final[str]
+    state_mocked_responses: Final[dict[str, StateMockedResponses]]
+
+    def __init__(
+        self,
+        state_machine_name: str,
+        test_case_name: str,
+        state_mocked_responses_list: list[StateMockedResponses],
+    ):
+        self.state_machine_name = state_machine_name
+        self.test_case_name = test_case_name
+        self.state_mocked_responses = dict()
+        for state_mocked_response in state_mocked_responses_list:
+            state_name = state_mocked_response.state_name
+            if state_name in self.state_mocked_responses:
+                raise RuntimeError(
+                    f"Duplicate definition of state '{state_name}' for test case '{test_case_name}'"
+                )
+            self.state_mocked_responses[state_name] = state_mocked_response
+
+
+def _parse_mocked_response_range(string_definition: str) -> tuple[int, int]:
+    definition_parts = string_definition.strip().split("-")
+    if len(definition_parts) == 1:
+        range_part = definition_parts[0]
+        try:
+            range_value = int(range_part)
+            return range_value, range_value
+        except Exception:
+            raise RuntimeError(
+                f"Unknown mocked response retry range value '{range_part}', not a valid integer"
+            )
+    elif len(definition_parts) == 2:
+        range_part_start = definition_parts[0]
+        range_part_end = definition_parts[1]
+        try:
+            return int(range_part_start), int(range_part_end)
+        except Exception:
+            raise RuntimeError(
+                f"Unknown mocked response retry range value '{range_part_start}:{range_part_end}', "
+                "not valid integer values"
+            )
+    else:
+        raise RuntimeError(
+            f"Unknown mocked response retry range definition '{string_definition}', "
+            "range definition should consist of one integer (e.g. '0'), or a integer range (e.g. '1-2')'."
+        )
+
+
+def _mocked_response_from_raw(
+    raw_response_model_range: str, raw_response_model: RawResponseModel
+) -> MockedResponse:
+    range_start, range_end = _parse_mocked_response_range(raw_response_model_range)
+    if raw_response_model.Return:
+        payload = raw_response_model.Return.model_dump()
+        return MockedResponseReturn(range_start=range_start, range_end=range_end, payload=payload)
+    throw_definition = raw_response_model.Throw
+    return MockedResponseThrow(
+        range_start=range_start,
+        range_end=range_end,
+        error=throw_definition.Error,
+        cause=throw_definition.Cause,
+    )
+
+
+def _mocked_responses_from_raw(
+    mocked_response_name: str, raw_mock_config: RawMockConfig
+) -> list[MockedResponse]:
+    raw_response_models: Optional[dict[str, RawResponseModel]] = (
+        raw_mock_config.MockedResponses.get(mocked_response_name)
+    )
+    if not raw_response_models:
+        raise RuntimeError(
+            f"No definitions for mocked response '{mocked_response_name}' in the mock configuration file."
+        )
+    mocked_responses: list[MockedResponse] = list()
+    for raw_response_model_range, raw_response_model in raw_response_models.items():
+        mocked_response: MockedResponse = _mocked_response_from_raw(
+            raw_response_model_range=raw_response_model_range, raw_response_model=raw_response_model
+        )
+        mocked_responses.append(mocked_response)
+    return mocked_responses
+
+
+def _state_mocked_responses_from_raw(
+    state_name: str, mocked_response_name: str, raw_mock_config: RawMockConfig
+) -> StateMockedResponses:
+    mocked_responses = _mocked_responses_from_raw(
+        mocked_response_name=mocked_response_name, raw_mock_config=raw_mock_config
+    )
+    return StateMockedResponses(
+        state_name=state_name,
+        mocked_response_name=mocked_response_name,
+        mocked_responses=mocked_responses,
+    )
+
+
+def _mock_test_case_from_raw(
+    state_machine_name: str, test_case_name: str, raw_mock_config: RawMockConfig
+) -> MockTestCase:
+    state_machine = raw_mock_config.StateMachines.get(state_machine_name)
+    if not state_machine:
+        raise RuntimeError(
+            f"No definitions for state machine '{state_machine_name}' in the mock configuration file."
+        )
+    test_case: RawTestCase = state_machine.TestCases.get(test_case_name)
+    if not test_case:
+        raise RuntimeError(
+            f"No definitions for test case '{test_case_name}' and "
+            f"state machine '{state_machine_name}' in the mock configuration file."
+        )
+    state_mocked_responses_list: list[StateMockedResponses] = list()
+    for state_name, mocked_response_name in test_case.root.items():
+        state_mocked_responses = _state_mocked_responses_from_raw(
+            state_name=state_name,
+            mocked_response_name=mocked_response_name,
+            raw_mock_config=raw_mock_config,
+        )
+        state_mocked_responses_list.append(state_mocked_responses)
+    return MockTestCase(
+        state_machine_name=state_machine_name,
+        test_case_name=test_case_name,
+        state_mocked_responses_list=state_mocked_responses_list,
+    )
+
+
+def load_mock_test_case_for(state_machine_name: str, test_case_name: str) -> Optional[MockTestCase]:
+    raw_mock_config: Optional[RawMockConfig] = _load_sfn_raw_mock_config()
+    if raw_mock_config is None:
+        return None
+    mock_test_case: MockTestCase = _mock_test_case_from_raw(
+        state_machine_name=state_machine_name,
+        test_case_name=test_case_name,
+        raw_mock_config=raw_mock_config,
+    )
+    return mock_test_case

localstack_core-4.3.1.dev65/localstack-core/localstack/services/stepfunctions/mocking/mock_config_file.py

@@ -0,0 +1,150 @@
+import logging
+import os
+from functools import lru_cache
+from typing import Dict, Final, Optional
+
+from pydantic import BaseModel, RootModel, model_validator
+
+from localstack import config
+
+LOG = logging.getLogger(__name__)
+
+_RETURN_KEY: Final[str] = "Return"
+_THROW_KEY: Final[str] = "Throw"
+
+
+class RawReturnResponse(BaseModel):
+    """
+    Represents a return response.
+    Accepts any fields.
+    """
+
+    model_config = {"extra": "allow", "frozen": True}
+
+
+class RawThrowResponse(BaseModel):
+    """
+    Represents an error response.
+    Both 'Error' and 'Cause' are required.
+    """
+
+    model_config = {"frozen": True}
+
+    Error: str
+    Cause: str
+
+
+class RawResponseModel(BaseModel):
+    """
+    A response step must include exactly one of:
+      - 'Return': a ReturnResponse object.
+      - 'Throw': a ThrowResponse object.
+    """
+
+    model_config = {"frozen": True}
+
+    Return: Optional[RawReturnResponse] = None
+    Throw: Optional[RawThrowResponse] = None
+
+    @model_validator(mode="before")
+    def validate_response(cls, data: dict) -> dict:
+        if _RETURN_KEY in data and _THROW_KEY in data:
+            raise ValueError(f"Response cannot contain both '{_RETURN_KEY}' and '{_THROW_KEY}'")
+        if _RETURN_KEY not in data and _THROW_KEY not in data:
+            raise ValueError(f"Response must contain one of '{_RETURN_KEY}' or '{_THROW_KEY}'")
+        return data
+
+
+class RawTestCase(RootModel[Dict[str, str]]):
+    """
+    Represents an individual test case.
+    The keys are state names (e.g., 'LambdaState', 'SQSState')
+    and the values are the names of the mocked response configurations.
+    """
+
+    model_config = {"frozen": True}
+
+
+class RawStateMachine(BaseModel):
+    """
+    Represents a state machine configuration containing multiple test cases.
+    """
+
+    model_config = {"frozen": True}
+
+    TestCases: Dict[str, RawTestCase]
+
+
+class RawMockConfig(BaseModel):
+    """
+    The root configuration that contains:
+      - StateMachines: mapping state machine names to their configuration.
+      - MockedResponses: mapping response configuration names to response steps.
+          Each response step is keyed (e.g. "0", "1-2") and maps to a ResponseModel.
+    """
+
+    model_config = {"frozen": True}
+
+    StateMachines: Dict[str, RawStateMachine]
+    MockedResponses: Dict[str, Dict[str, RawResponseModel]]
+
+
+@lru_cache(maxsize=1)
+def _read_sfn_raw_mock_config(file_path: str, modified_epoch: int) -> Optional[RawMockConfig]:  # noqa
+    """
+    Load and cache the Step Functions mock configuration from a JSON file.
+
+    This function is memoized using `functools.lru_cache` to avoid re-reading the file
+    from disk unless it has changed. The `modified_epoch` parameter is used solely to
+    trigger cache invalidation when the file is updated. If either the file path or the
+    modified timestamp changes, the cached result is discarded and the file is reloaded.
+
+    Parameters:
+        file_path (str):
+            The absolute path to the JSON configuration file.
+
+        modified_epoch (int):
+            The last modified time of the file, in epoch seconds. This value is used
+            as part of the cache key to ensure the cache is refreshed when the file is updated.
+
+    Returns:
+        Optional[dict]:
+            The parsed configuration as a dictionary if the file is successfully loaded,
+            or `None` if an error occurs during reading or parsing.
+
+    Notes:
+        - The `modified_epoch` argument is not used inside the function logic, but is
+          necessary to ensure cache correctness via `lru_cache`.
+        - Logging is used to capture warnings if file access or parsing fails.
+    """
+    try:
+        with open(file_path, "r") as df:
+            mock_config_str = df.read()
+        mock_config: RawMockConfig = RawMockConfig.model_validate_json(mock_config_str)
+        return mock_config
+    except Exception as ex:
+        LOG.warning(
+            "Unable to load step functions mock configuration file at '%s' due to %s",
+            file_path,
+            ex,
+        )
+        return None
+
+
+def _load_sfn_raw_mock_config() -> Optional[RawMockConfig]:
+    configuration_file_path = config.SFN_MOCK_CONFIG
+    if not configuration_file_path:
+        return None
+
+    try:
+        modified_time = int(os.path.getmtime(configuration_file_path))
+    except Exception as ex:
+        LOG.warning(
+            "Unable to access the step functions mock configuration file at '%s' due to %s",
+            configuration_file_path,
+            ex,
+        )
+        return None
+
+    mock_config = _read_sfn_raw_mock_config(configuration_file_path, modified_time)
+    return mock_config

{localstack_core-4.3.1.dev63 → localstack_core-4.3.1.dev65}/localstack-core/localstack/services/stepfunctions/provider.py

@@ -150,6 +150,10 @@ from localstack.services.stepfunctions.backend.store import SFNStore, sfn_stores
 from localstack.services.stepfunctions.backend.test_state.execution import (
     TestStateExecution,
 )
+from localstack.services.stepfunctions.mocking.mock_config import (
+    MockTestCase,
+    load_mock_test_case_for,
+)
 from localstack.services.stepfunctions.stepfunctions_utils import (
     assert_pagination_parameters_valid,
     get_next_page_token_from_arn,
@@ -180,7 +184,7 @@ class StepFunctionsProvider(StepfunctionsApi, ServiceLifecycleHook):
         visitor.visit(sfn_stores)
 
     _STATE_MACHINE_ARN_REGEX: Final[re.Pattern] = re.compile(
-        rf"{ARN_PARTITION_REGEX}:states:[a-z0-9-]+:[0-9]{{12}}:stateMachine:[a-zA-Z0-9-_.]+(:\d+)?(:[a-zA-Z0-9-_.]+)*$"
+        rf"{ARN_PARTITION_REGEX}:states:[a-z0-9-]+:[0-9]{{12}}:stateMachine:[a-zA-Z0-9-_.]+(:\d+)?(:[a-zA-Z0-9-_.]+)*(?:#[a-zA-Z0-9-_]+)?$"
     )
 
     _STATE_MACHINE_EXECUTION_ARN_REGEX: Final[re.Pattern] = re.compile(
@@ -779,6 +783,12 @@ class StepFunctionsProvider(StepfunctionsApi, ServiceLifecycleHook):
     ) -> StartExecutionOutput:
         self._validate_state_machine_arn(state_machine_arn)
 
+        state_machine_arn_parts = state_machine_arn.split("#")
+        state_machine_arn = state_machine_arn_parts[0]
+        mock_test_case_name = (
+            state_machine_arn_parts[1] if len(state_machine_arn_parts) == 2 else None
+        )
+
         store = self.get_store(context=context)
 
         alias: Optional[Alias] = store.aliases.get(state_machine_arn)
@@ -832,6 +842,18 @@ class StepFunctionsProvider(StepfunctionsApi, ServiceLifecycleHook):
                 configuration=state_machine_clone.cloud_watch_logging_configuration,
             )
 
+        mock_test_case: Optional[MockTestCase] = None
+        if mock_test_case_name is not None:
+            state_machine_name = state_machine_clone.name
+            mock_test_case = load_mock_test_case_for(
+                state_machine_name=state_machine_name, test_case_name=mock_test_case_name
+            )
+            if mock_test_case is None:
+                raise InvalidName(
+                    f"Invalid mock test case name '{mock_test_case_name}' "
+                    f"for state machine '{state_machine_name}'"
+                )
+
         execution = Execution(
             name=exec_name,
             sm_type=state_machine_clone.sm_type,
@@ -846,6 +868,7 @@ class StepFunctionsProvider(StepfunctionsApi, ServiceLifecycleHook):
             input_data=input_data,
             trace_header=trace_header,
             activity_store=self.get_store(context).activities,
+            mock_test_case=mock_test_case,
         )
 
         store.executions[exec_arn] = execution