You're reading the documentation for a development version. For the latest released version, please have a look at Iron.

Running Tests in ROS 2 from the Command Line

Build and run your tests

To compile and run the tests, simply run the test verb from colcon.

colcon test --ctest-args tests [package_selection_args]

(where package_selection_args are optional package selection arguments for colcon to limit which packages are built and run)

Sourcing the workspace before testing should not be necessary. colcon test makes sure that the tests run with the right environment, have access to their dependencies, etc.

Examine Test Results

To see the results, simply run the test-result verb from colcon.

colcon test-result --all

To see the exact test cases which fail, use the --verbose flag:

colcon test-result --all --verbose

Debugging tests with GDB

If a C++ test is failing, GDB can be used directly on the test executable in the build directory. Ensure to build the code in debug mode. Since the previous build type may be cached by CMake, clean the cache and rebuild.

colcon build --cmake-clean-cache --mixin debug

In order for GDB to load debug symbols for any shared libraries called, make sure to source your environment. This configures the value of LD_LIBRARY_PATH.

source install/setup.bash

Finally, run the test directly through GDB. For example:

gdb -ex run ./build/rcl/test/test_logging

If the code is throwing an unhandled exception, you can catch it in GDB before gtest handles it.

gdb ./build/rcl/test/test_logging
catch throw
run