launch_testing

This tool is a framework for launch integration testing. For example:

• The exit codes of all processes are available to the tests.
• Tests can check that all processes shut down normally, or with specific exit codes.
• Tests can fail when a process dies unexpectedly.
• The stdout and stderr of all processes are available to the tests.
• The command-line used to launch the processes are available to the tests.
• Some tests run concurrently with the launch and can interact with the running processes.

Quick start example

Start with the launch_testing example good_proc_launch_test.py.

Run the example by doing:

launch_test test/launch_testing/examples/good_proc_launch_test.py

launch_test will launch the nodes found in the generate_test_description function, run the tests from the TestGoodProcess class, shut down the launched nodes, and then run the tests from the TestProcessOutput class.

The Launch Description

def generate_test_description():

    return launch.LaunchDescription([
        launch.actions.ExecuteProcess(
            cmd=[path_to_process],
        ),

        # Start tests right away - no need to wait for anything in this example.
        # In a more complicated launch description, we might want this action happen
        # once some process starts or once some other event happens
        launch_testing.actions.ReadyToTest()
    ])

The generate_test_description function should return a launch.LaunchDescription object that launches the system to be tested.

The launch description needs to include a ReadyToTest action to signal to the test framework that it’s safe to start the active tests.

In the above example, there is no need to delay the start of the tests so the ReadyToTest action is a peer to the process under test and will signal to the framework that it’s safe to start around the same time the ExecuteProcess action is run.

Active Tests

Any classes that inherit from unittest.TestCase and not decorated with the post_shutdown_test descriptor will be run concurrently with the process under test. These tests are expected to interact with the running processes in some way.

Post-Shutdown Tests

Any classes that inherit from unittest.TestCase that are decorated with the post_shutdown_test descriptor will be run after the launched processes have been shut down. These tests have access to the exit codes and the stdout of all of the launched processes, as well as any data created as a side-effect of running the processes.

Exit Codes and Standard Out

The launch_testing framework automatically adds some member fields to each test case so that the tests can access process output and exit codes.

• self.proc_info - a ProcInfoHandler object
• self.proc_output - an IoHandler object

These objects provide dictionary like access to information about the running processes. They also contain methods that the active tests can use to wait for a process to exit or to wait for specific output.

Assertions

The launch_testing framework automatically records all stdout from the launched processes as well as the exit codes from any processes that are launched. This information is made available to the tests via the proc_info and proc_output object. These objects can be used by one of several assert methods to check the output or exit codes of the process:

launch_testing.asserts.assertInStdout(proc_output, msg, process, cmd_args=None, *, strict_proc_matching=True)

Asserts that a message is found in the stdout of a particular process.

• msg:

  The text to look for in the process standard out

• process:

  Either the process name as a string, or a launch.actions.ExecuteProcess object that was used to start the process. Pass None or an empty string to search all processes.

• cmd_args:

  When looking up processes by process by name, cmd_args can be used to disambiguate multiple processes with the same name.

• strict_proc_matching:

  When looking up a process by name, strict_proc_matching=True will make it an error to match multiple processes. This prevents an assert from accidentally passing if the output came from a different process than the one the user was expecting.

launch_testing.asserts.assertExitCodes(proc_info, allowable_exit_codes=[EXIT_OK], process, cmd_args=None, *, strict_proc_matching=True)

Asserts that the specified processes exited with a particular exit code.

• allowable_exit_codes:

File truncated at 100 lines see the full file

Changelog for package launch_testing

3.4.11 (2026-06-02)

• Correct typos (backport #961) (#963)

  * Correct typos (#961) (cherry picked from commit b51d67a0fb3c572a8255855ac73364ca53ed3691) Co-authored-by: Auguste Lalande <<auguste.lalande@gmail.com>> Co-authored-by: Alejandro Hernandez Cordero <<ahcorde@gmail.com>>

• Contributors: mergify[bot]

3.4.10 (2026-01-12)

3.4.9 (2025-11-07)

3.4.8 (2025-10-17)

3.4.7 (2025-10-06)

3.4.6 (2025-08-06)

3.4.5 (2025-06-23)

3.4.4 (2025-04-02)

• Merge pull request #834 from ros2/mergify/bp/jazzy/pr-833 Fix function params indentation (backport #833)
• Fix function params indentation (#833) (cherry picked from commit 151b024a7cfac06f0d56798cbe87ab180b9ea3ab)
• Contributors: Alejandro Hernández Cordero, Christophe Bedard

3.4.3 (2024-12-18)

3.4.2 (2024-04-16)

• Fix a warning in modern unittest. (#773) Newer versions of unittest no longer store an errors list; instead, they store a result, which then stores an error list. Update the code here to be able to deal with either version.
• Contributors: Chris Lalancette

3.4.1 (2024-03-28)

• Add consider_namespace_packages=False (#766)
• Contributors: Tony Najjar

3.4.0 (2024-02-07)

3.3.0 (2024-01-24)

3.2.1 (2023-12-26)

3.2.0 (2023-10-04)

• to open expected outpout file with an encoding parameter (#717)
• Contributors: Chen Lihui

3.1.0 (2023-09-08)

3.0.1 (2023-09-07)

3.0.0 (2023-08-21)

2.2.1 (2023-07-11)

2.2.0 (2023-06-07)

2.1.0 (2023-04-27)

2.0.1 (2023-04-12)

2.0.0 (2023-04-11)

• Improve type checking (#679)
• Contributors: Hervé Audren

1.4.1 (2023-02-24)

• Fixed typos (#692)
• Contributors: Alejandro Hernández Cordero

1.4.0 (2023-02-14)

• Allow ReadyToTest() usage in event handler (#665)
• Inherit markers from generate_test_description (#670)
• [rolling] Update maintainers - 2022-11-07 (#671)
• Contributors: Audrow Nash, Nikolai Morin, Scott K Logan

File truncated at 100 lines see the full file