repository·rolling·Indexed 41 days ago
https://github.com/ros2/launchA system for orchestrating the execution of multiple processes in ROS 2. It includes tools for managing complex systems and integration testing via launch_pytest and launch_testing, as well as support for defining launch descriptions using XML (launch_xml) and YAML (launch_yaml).
The launch_testing framework distinguishes between two types of tests:
Active Tests: Any class inheriting from unittest.TestCase that is not decorated with @launch_testing.post_shutdown_test. These run concurrently with the launched processes and are used to interact with running nodes (e.g., checking stdout in real-time).
Post-Shutdown Tests: Any class inheriting from unittest.TestCase decorated with @launch_testing.post_shutdown_test. These run after the launched processes have been shut down. They are used to verify exit codes, final stdout/stderr, or side-effects created by the processes.
The framework automatically injects two objects into your test cases to allow access to process information:
self.proc_info: A ProcInfoHandler object used to access exit codes and manage process shutdown.self.proc_output: An IoHandler object used to access stdout and stderr.Both objects provide dictionary-like access to process information and methods to wait for specific events.
The launch framework provides extension points that allow external Python packages to add new functionality to the core categories. To extend the framework, your custom classes must follow these inheritance requirements:
launch.Action.launch.Event.launch.Substitution.launch.LaunchDescriptionEntity.Event handlers allow you to react to specific lifecycle events within a launch session. To create a custom event handler, you must inherit from the launch.EventHandler base class and implement two required methods:
matches(event): Receives the event as input. It must return True if the handler should react to this specific event, or False otherwise.handle(event, launch_context): Receives the event and the current launch_context. This method can perform side effects and optionally returns a list of launch.LaunchDescriptionEntity objects. If returned, these entities are visited by the launch service depth-first.Note that event handlers are not LaunchDescriptionEntity objects themselves, but they are 'visited' by the launch service during event processing.
The core of the launch framework is built around LaunchDescriptionEntity objects. These entities capture the user's intent for how a system should be launched and how the system should react to asynchronous events.
Key components include:
launch.LaunchDescriptionEntity: The base class for all entities that are "launched". They implement a visit method (called during execution) and describe methods (called during introspection).launch.LaunchDescription: The root entity that encapsulates a list of launch.Action objects. It serves as the starting point for the launch process.launch.Action: A type of entity that performs side effects (like running a process) or yields other actions. Actions can be introspected without being executed.launch.Substitution: Values embedded within descriptions that are only evaluated at runtime (e.g., fetching an environment variable or a launch configuration).The behavior of your test depends on whether it is a standard function, a coroutine, a generator, or an async generator. Use the shutdown argument to control when the test runs relative to the launch service lifecycle.
shutdown=True: Runs only after the launch service has shut down.Generators allow you to split a test into two phases: a concurrent phase and a post-shutdown phase.
yield runs concurrently with the launch service.yield runs after the launch service has shut down.shutdown argument to the decorator when using generators.# Standard function (concurrent)
@pytest.mark.launch(fixture=my_ld_fixture)
def normal_test_case():
pass
# Standard function (after shutdown)
@pytest.mark.launch(fixture=my_ld_fixture, shutdown=True)
def shutdown_test_case():
pass
# Generator (concurrent phase -> yield -> post-shutdown phase)
@pytest.mark.launch(fixture=my_ld_fixture)
def generator_test_case():
assert True # Runs while service is active
yield
assert True # Runs after service shuts downAttributes in the YAML tree can themselves be entities or lists of entities.
get_attr with data_type=List[Entity] or by accessing the attribute name directly as a property..children property. This returns a list of launch_xml.Entity objects wrapping each child.# Accessing a list of entities (e.g., an 'env' list)
env = e.get_attr('env', data_type=List[Entity])
len(env) == 2
env[0].get_attr('name') == 'a'
# Accessing children directly
# Returns a list of Entity objects wrapping the children
child_entities = e.childrenA @launch_pytest.fixture must return a launch.LaunchDescription object or a sequence where the first item is a launch.LaunchDescription.
You can include launch_pytest.actions.ReadyToTest() in your LaunchDescription to signal exactly when the launch service is ready and the active tests should begin. If you do not add this action, one will be automatically appended to the end of your description.
launch_pytest fixtures support module, class, or function scopes (default is function).
function scope: A new launch service is started and shut down for every single test case.module scope: The launch service is started once for the entire module, and all test cases run concurrently with that same service.Best Practices:
module scope fixtures with class or function scope fixtures in the same file.module.launch_pytest fixture.@launch_pytest.fixture
def launch_description(hello_world_proc):
"""Launch a simple process to print 'hello_world'."""
return launch.LaunchDescription([
hello_world_proc,
# Tell launch when to start the test
# If no ReadyToTest action is added, one will be appended automatically.
launch_pytest.actions.ReadyToTest()
])
@pytest.mark.launch(fixture=launch_description)
def test_case():
passTo integrate launch tests into a ROS 2 package using CMake:
launch_testing_ament_cmake to your package.xml dependencies.CMakeLists.txt, use find_package and add_launch_test.Basic usage:
find_package(launch_testing_ament_cmake)
add_launch_test(test/name_of_test.test.py)Passing arguments via CMake:
add_launch_test(
test/test_with_args.test.py
ARGS "arg1:=foo"
)The launch.LaunchService is a long-running activity that manages the event loop, dispatches events to handlers, and executes actions.
To use a LaunchService in a typical application, follow these steps:
LaunchDescription (programmatically or via a markup file).LaunchService.LaunchDescription in the service.SIGINT) that calls shutdown() on the service.Note: You can include launch descriptions asynchronously from other threads (e.g., from a REST or ROS service) while the launch service is already running.
To use launch_pytest for integration testing, create a pytest file that defines a @launch_pytest.fixture returning a launch.LaunchDescription. Mark your test cases with @pytest.mark.launch(fixture=<fixture_name>) to associate them with that launch description.
Run your tests using the standard pytest module command:
python3 -m pytest <path_to_test_file>python3 -m pytest test/launch_pytest/examples/pytest_hello_world.py