Add test for scoping of current launch file/dir context locals

Signed-off-by: Christophe Bedard <[email protected]>

Author: christophebedard

launch/test/launch/actions/launch/included/launch_file_dir.launch.py

@@ -0,0 +1,33 @@
+# Copyright 2025 Open Source Robotics Foundation, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from launch import LaunchContext
+from launch import LaunchDescription
+from launch.actions import OpaqueFunction
+from launch.actions import SetEnvironmentVariable
+from launch.substitutions import ThisLaunchFile
+from launch.substitutions import ThisLaunchFileDir
+
+
+def set_local(context: LaunchContext) -> None:
+    context.extend_locals({'included_local': 'context_local_value'})
+
+
+def generate_launch_description():
+    """Fixture for tests."""
+    return LaunchDescription([
+        SetEnvironmentVariable('Included_ThisLaunchFile', ThisLaunchFile()),
+        OpaqueFunction(function=set_local),
+        SetEnvironmentVariable('Included_ThisLaunchFileDir', ThisLaunchFileDir()),
+    ])

launch/test/launch/actions/launch/parent_launch_file_dir.launch.py

@@ -0,0 +1,38 @@
+# Copyright 2025 Open Source Robotics Foundation, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import os
+
+from launch import LaunchDescription
+from launch.actions import IncludeLaunchDescription
+from launch.actions import SetEnvironmentVariable
+from launch.substitutions import ThisLaunchFile
+from launch.substitutions import ThisLaunchFileDir
+
+
+def generate_launch_description():
+    """Fixture for tests."""
+    return LaunchDescription([
+        SetEnvironmentVariable('Before_ThisLaunchFile', ThisLaunchFile()),
+        SetEnvironmentVariable('Before_ThisLaunchFileDir', ThisLaunchFileDir()),
+        IncludeLaunchDescription(
+            os.path.join(
+                os.path.dirname(os.path.abspath(__file__)),
+                'included',
+                'launch_file_dir.launch.py',
+            ),
+        ),
+        SetEnvironmentVariable('After_ThisLaunchFile', ThisLaunchFile()),
+        SetEnvironmentVariable('After_ThisLaunchFileDir', ThisLaunchFileDir()),
+    ])

launch/test/launch/actions/test_include_launch_description.py

@@ -14,6 +14,7 @@
 
 """Tests for the IncludeLaunchDescription action class."""
 
+import os
 from pathlib import Path
 
 from launch import LaunchContext
@@ -22,9 +23,13 @@
 from launch import LaunchService
 from launch.actions import DeclareLaunchArgument
 from launch.actions import IncludeLaunchDescription
+from launch.actions import OpaqueFunction
 from launch.actions import ResetLaunchConfigurations
+from launch.actions import SetEnvironmentVariable
 from launch.actions import SetLaunchConfiguration
 from launch.launch_description_sources import PythonLaunchDescriptionSource
+from launch.substitutions import ThisLaunchFile
+from launch.substitutions import ThisLaunchFileDir
 from launch.utilities import perform_substitutions
 
 import pytest
@@ -87,6 +92,53 @@ def test_include_launch_description_launch_file_location():
     assert action2.get_asyncio_future() is None
 
 
+def test_include_launch_description_launch_file_dir_location_scoped():
+    """Test that the launch file name & dir locals are scoped to the included launch file."""
+    # Rely on the test launch files to set environment variables with
+    # ThisLaunchFile()/ThisLaunchFileDir() to make testing easier
+    parent_dir = os.path.join(os.path.dirname(os.path.abspath(__file__)), 'launch')
+    parent_launch_file = os.path.join(parent_dir, 'parent_launch_file_dir.launch.py')
+    included_dir = os.path.join(parent_dir, 'included')
+    included_launch_file = os.path.join(included_dir, 'launch_file_dir.launch.py')
+
+    # The current launch file/dir context locals should be scoped to the included launch file
+    ld = LaunchDescription([IncludeLaunchDescription(parent_launch_file)])
+    ls = LaunchService()
+    ls.include_launch_description(ld)
+    assert 0 == ls.run()
+    lc = ls.context
+    assert lc.environment.get('Before_ThisLaunchFile') == parent_launch_file
+    assert lc.environment.get('Before_ThisLaunchFileDir') == parent_dir
+    assert lc.environment.get('Included_ThisLaunchFile') == included_launch_file
+    assert lc.environment.get('Included_ThisLaunchFileDir') == included_dir
+    assert lc.environment.get('After_ThisLaunchFile') == parent_launch_file
+    assert lc.environment.get('After_ThisLaunchFileDir') == parent_dir
+
+    # The launch file/dir context locals should be completely removed after the first included
+    # (parent) launch file, because at that point we're in a launch script and not a launch file,
+    # and therefore these substitutions should raise an error
+    ld2 = LaunchDescription([
+        IncludeLaunchDescription(parent_launch_file),
+        SetEnvironmentVariable('Outside_ThisLaunchFile', ThisLaunchFile()),
+        SetEnvironmentVariable('Outside_ThisLaunchFileDir', ThisLaunchFileDir()),
+    ])
+    ls2 = LaunchService()
+    ls2.include_launch_description(ld2)
+    assert 1 == ls2.run()
+
+    # The non-launch file/dir context locals should not be scoped to the included launch file
+    def assert_unscoped_context_local(context: LaunchContext):
+        assert context.locals.included_local == 'context_local_value'
+
+    ld3 = LaunchDescription([
+        IncludeLaunchDescription(parent_launch_file),
+        OpaqueFunction(function=assert_unscoped_context_local),
+    ])
+    ls3 = LaunchService()
+    ls3.include_launch_description(ld3)
+    assert 0 == ls3.run()
+
+
 def test_include_launch_description_launch_arguments():
     """Test the interactions between declared launch arguments and IncludeLaunchDescription."""
     # test that arguments are set when given, even if they are not declared