ROS2 easy-test

A Python test framework for ROS2 allowing for:

• simple and expressive assertions based on message and service interactions (black box testing)
• easy integration of existing nodes and launch files
• testing of nodes implemented in any programming language (C++, Python, ...)
• works with and without tools like colcon test and pytest
• is minimalistic and has very few dependencies
• is typed and documented
• is tested, used in practice, and maintained

Installation

Just run:

pip install ros2-easy-test

Examples

The following two examples show off the usage of the Python decorators @with_single_node and @with_launch_file, which provide the core functionality of this package. To get a better understanding of their inner workings, please have a look at their implementation here. Besides the simple examples here, you can embed everything in unittest.TestCase as well. To check out how, have a look at the provided test in tests/demo/ for some advanced examples.

Testing a Node

Simple settings where a single node shall be tested can use the decorator @with_single_node as in the following example.

from ros2_easy_test import ROS2TestEnvironment, with_launch_file, with_single_node
from my_nodes import Talker
from std_msgs.msg import String

@with_single_node(Talker, watch_topics={"/chatter": String})
def test_simple_publisher(env: ROS2TestEnvironment) -> None:
    response: String = env.assert_message_published("/chatter", timeout=5)
    assert response.data == "Hello World: 0"

It is also possible to specify custom QoSProfiles for the ROS2TestEnvironment to use when subscribing or publishing on the specified topics. See tests/demo/latching_topic_test.py for an example. If no profile is specified, the default QoSProfile(history=QoSHistoryPolicy.KEEP_ALL) is used.

You can optionally provide more parameters to the test setting, i.e., additionally pass parameters={"some.thing": 30.2} to the decorator. The argument of the test function receiving the ROS2TestEnvironment must be named env.

Testing a Launch File

For more complex scenarios involving multiple nodes using a launch file (both nodes and launch file being implemented in any language supported by ROS2), the @with_launch_file decorator can be used.

@with_launch_file(
    "example_launch_file.yaml",
    watch_topics={"/some/interesting/response": ColorRGBA},
)
def test_simple_update_launch_file(env: ROS2TestEnvironment) -> None:
    env.publish("/topic/for/node_input", ColorRGBA(r=0.5, g=0.2, b=0.9, a=1.0))
    response_color = env.assert_message_published("/some/interesting/response")
    assert response_color.r == 0.5

You can also pass the literal launch file contents as a str instead of a path like "example_launch_file.yaml". The argument of the test function receiving the ROS2TestEnvironment must be named env.

Note that, however, this method is much slower than the one above. One reason for this is the requirement of a fixed warm-up time for the nodes to be started. This is because the test environment has to wait for the nodes to be ready before it can start listening for messages.

Usage

How you can interact with the node(s)

Using ROS2TestEnvironment, you can call:

• publish(topic: str, message: RosMessage) -> None
• listen_for_messages(topic: str, time_span: float) -> List[RosMessage]
• clear_messages(topic: str) -> None to forget all messages that have been received so far.
• call_service(name: str, request: Request, timeout_availability: Optional[float], timeout_call: Optional[float]) -> Response

Note that ROS2TestEnvironment is a rclpy.node.Node and thus has all the methods of a ROS2 node. So feel free to call offer a service with env.create_service(), interface with an action using ActionClient(env, DoTheThing, 'maker'), etc., to cover more specific use cases. Extend as you please!

In addition, nothing stops you from using any other means of interacting with ROS2 that would work otherwise.

What you can test (recommended way of obtaining messages)

Using ROS2TestEnvironment, you can assert:

• assert_message_published(topic: str, timeout: Optional[float]) -> RosMessage
• assert_no_message_published(topic: str, timeout: Optional[float]) -> None
• assert_messages_published(topic: str, number: int, ...) -> List[RosMessage]

Generally, you can always test that no exceptions are thrown, e.g., when nodes are initialized (see limitations below).

Combining with other tools

Some hints:

• If you want to use pytest markers like @pytest.mark.skipif(...), add that above (=before) the @with_single_node(...)/@with_launch_file(...) decorator and it will work just fine.
• Similarly, you can seamlessly use other tools which annotate test functions, like hypothesis or pytest fixtures. Generally, you have to be mindful of the order of the decorators here. The ROS2TestEnvironment is always added as a keyword argument called env to the test function. See tests/demo/ for a few examples.

Limitations, Design, and Other Projects

See the documentation on that.

Contributing

You can install the development dependencies with pip install -e ".[dev]". After this, you will have access to the configured formatters black . and ruff check ..

You can run the test with simply pytest. Coverage reports and timings will be printed on the command line, and a fresh line-by-line coverage report is in htmlcov/index.html.

Building the documentation is simple, too:

# Install the required dependencies
pip install -e ".[doc]"

# Build the documentation
cd doc
make html
# open build/html/index.html in you browser

# You can also run a small webserver to serve the static files with
cd build/html
python -m http.server

Changelog

See Releases.

License

See LICENSE.

Initially developed by Felix Divo at Sailing Team Darmstadt e. V., a student group devoted to robotic sailing based in Darmstadt, Germany. Thanks to Simon Kohaut for his kind and nuanced feedback.