You're reading the documentation for a version of ROS 2 that has reached its EOL (end-of-life), and is no longer officially supported. If you want up-to-date information, please have a look at Iron.

Writing Basic Tests with Python

Starting point: we’ll assume you have a basic ament_python package set up already and you want to add some tests to it.

If you are using ament_cmake_python, refer to the the ament_cmake_python docs for how to make tests dicoverable. The test contents and invocation with colcon remain the same.

Package Setup

Your must a test dependency on pytest within the call to setup(...):


Test Files and Folders

Your test code needs to go in a folder named tests in the root of your package.

Any file that contains tests that you want to run must have the pattern where FOO can be replaced with anything.

Example package layout:


Test Contents

You can now write tests to your heart’s content. There are plenty of resources on pytest, but in short, you can write functions with the test_ prefix and include whatever assert statements you’d like.

def test_math():
    assert 2 + 2 == 5   # This should fail for most mathematical systems

Special Commands

Beyond the standard colcon testing commands you can also specify arguments to the pytest framework from the command line with the --pytest-args flag. For example, you can specify the name of the function to run with

colcon test --packages-select <name-of-pkg> --pytest-args -k name_of_the_test_function