[Documentation] [TitleIndex] [WordIndex

Writing rostest files

Test nodes

In order to create a rostest, you first need to write some test nodes. Test nodes are nodes that also execute unit tests. To date, we have used both the C++ gtest framework and the Python unittest framework within rostest. Nodes written with gtest are 100% compatible with rostest; Python unittests require an extra wrapper.

File format

rostest files are 100% compatible with roslaunch. These files generally have a .test or .launch file extension.

It's highly recommended that you embed tests within your roslaunch files in order to verify that they are functioning properly. The difference between rostest and roslaunch is that rostest also processes <test> tags within your XML file. These <test> tags specify test nodes to run.

<test> tag

Please see <test> tag reference

Add rostests in CMakeLists.txt

You can easily add a rostest to your CMake build using the rosbuild_add_rostest(test_file) command (documentation) in your CMakeLists.txt file.

Using the ROS-specific cmake build commands is highly recommended as it enables you to do useful test commands such as testing all packages that depend on your package.

This is how you might want to set up the test in your CMakeLists.txt (assuming that your test is using gtest):

# add the test executable, keep it from being built by "make all"
rosbuild_add_executable(test_mynode EXCLUDE_FROM_ALL src/test/test_mynode.cpp)

# Link test_mynode against gtest and add a dependency to the "test" target
rosbuild_add_gtest_build_flags(test_mynode)

# Make sure rostest launches test/mynode.test during "make test"
rosbuild_add_rostest(test/mynode.test)

Running your rostest with 'make test'

If you run make test on the command line now, the test binary will get compiled and the rostest file 'test/mytest.test' will be launched by rostest.

With gtest

You can easily add a rostest to your CMake build using the add_rostest_gtest(target_name test_file source_file+) function in your CMakeLists.txt file.

Using the ROS-specific cmake build commands is highly recommended as it enables you to do useful test commands such as testing all packages that depend on your package.

This is how you might want to set up the test in your CMakeLists.txt (assuming that your test is using gtest):

find_package(rostest REQUIRED)

# create a gtest executable with target name "test_mynode"
# which is not built by "make all" but only by "make tests"
# add one/multiple source files to the executable target
# register the rostest launch file "test/mynode.test"
add_rostest_gtest(tests_mynode test/mynode.test src/test/test_mynode.cpp [more cpp files])

# you will likely need to link other libraries to your test executable
target_link_libraries(tests_mynode [libraries to depend on, e.g. ${catkin_LIBRARIES}])

You should also wrap all testing stuff in a conditional block:

if(CATKIN_ENABLE_TESTING)
  find_package(rostest REQUIRED)
  add_rostest_gtest(tests_mynode test/mynode.test src/test/test_mynode.cpp [more cpp files])
  target_link_libraries(tests_mynode ${catkin_LIBRARIES})
endif()

Also see the comment from Dirk Thomas in rostest - Minimum Working Example for a better CMakeLists.txt snippet.

With unittest

To use a test mytest.test with a <test> attribute calling a Python script, your CmakeLists.txt file should contain:

if(CATKIN_ENABLE_TESTING)
  find_package(rostest REQUIRED)
  add_rostest(test/mytest.test)
endif()

Also you can add rostests that accept arguments and you can define dependencies between a rostest and any other target:

if(CATKIN_ENABLE_TESTING)
  find_package(rostest REQUIRED)
  add_rostest(test/my_first_test.test ARGS myarg1:=true myarg2:=false)

  catkin_download_test_data(
    ${PROJECT_NAME}_saloon.bag
    http://downloads.foo.com/bags/saloon.bag
    DESTINATION ${CATKIN_DEVEL_PREFIX}/${CATKIN_PACKAGE_SHARE_DESTINATION}/test
    MD5 01603ce158575da859b8afff5b676bf9)
  add_rostest(test/my_second_test.test DEPENDENCIES ${PROJECT_NAME}_saloon.bag)
endif()

Running your rostest with 'make run_tests'

If you run make run_tests on the command line in the build folder now, the test binary will get compiled and the rostest file 'test/mytest.test' will be launched by rostest.

Example rostest files

Here is a very simple rostest file, which you'll note is compatible with the roslaunch format:

<launch>
  <node pkg="mypkg" type="mynode" name="mynode" />
  <test test-name="test_mynode" pkg="mypkg" type="test_mynode" />
</launch>

This launch file will start mynode and then run the test_mynode test node.

Here's another rostest file that uses rostest to initialize the parameter server:

<launch>
  <param name="string"  value="mystring" />
  <test test-name="test_string_params" pkg="somepackage" type="test_string_param.py" />
</launch>

2024-03-23 12:57