Decorators

This module contains the decorators to be applied to test functions.

Warning

If the node crashes due to an exception in service callback, a test calling the service will deadlock indefinitely. In that case, exiting with Ctrl + C will probably print the exception from the node.

ros2_easy_test.decorators.with_launch_file(launch_file: Path | str, *, launch_arguments: Dict[str, Any] | None = None, debug_launch_file: bool = False, warmup_time: float = 2, time_limit: float | None = 60, shutdown_timeout=2, acceptable_return_codes: set[int] | None = {0, 130}, **kwargs) Callable[[Callable[[...], _TestReturnType]], Callable[[...], _TestReturnType]]

Marks a test case that shall be wrapped by a ROS2 context and be given an environment to interact.

Note

Your test function must accept the environment as a keyword-parameter called env, e.g. def my_test(env: ROS2TestEnvironment): ....

Parameters:
  • launch_file – Either: 1) The path to the launch file to start for the test. 2) The literal launch file (must contain a newline to be detected as such).

  • launch_arguments – The launch_arguments as key:=value pairs which will be passed through

  • debug_launch_file – If set to True, instruct ros2 launch to be more verbose and run in debug mode. It only affects the output on failing tests. However, it might also cause sudden failures, therefore the default is False.

  • warmup_time – The time to sleep while letting the ROS2 system spin up. Must be zero or larger. Strange bugs will occur when this value is set too low: No messages can be exchanged, independently of how long the test waits. The default should suffice on most computers, it is rather conservative and higher numbers will slow down each test case even more.

  • time_limit – The time in seconds to give the test case to complete. This only applies to the test function, not the node setup etc. If it takes longer than this, the test will fail. Set to None to disable the timeout.

  • shutdown_timeout – The time to give a node for a successful shutdown. If it takes longer than this, the test will fail. It applies individually to both shutting down the environment and the launch process.

  • acceptable_return_codes – Acceptable return codes for the launch process. By default, both SUCCESS (0) and the result code of SIGINT (130) are acceptable. Empty list accepts all codes.

  • kwargs – Passed to the ros2_easy_test.env.ROS2TestEnvironment

ros2_easy_test.decorators.with_single_node(node_class: Type[Node], *, parameters: Dict[str, Any] | None = None, time_limit: float | None = 60, shutdown_timeout=2, **kwargs) Callable[[Callable[[...], _TestReturnType]], Callable[[...], _TestReturnType]]

Marks a test case that shall be wrapped by a ROS2 context and be given an environment to interact.

This function is not fundamentally restricted to one node, but more are simply not implemented as of now. See with_launch_file() for more complex scenarios.

Note

Your test function must accept the environment as a keyword-parameter called env, e.g. def test(env: ROS2TestEnvironment).

Note

Make sure that the initializer of node_class passes along any keyword arguments to the super class rclpy.node.Node. To do this, have the __init__ of your node accept **kwargs as the last argument and call the super class constructor with these, e.g. super().__init__("node name", **kwargs).

Parameters:
  • node_class – Class of the node to instantiate. Assumed to accept no extra parameters besides any keyword arguments that are passed along to rclpy.node.Node.

  • parameters – The parameters to be set for the node as ("key", value) pairs

  • time_limit – The time in seconds to give the test case to complete. This only applies to the test function, not the node setup etc. If it takes longer than this, the test will fail. Set to None to disable the timeout.

  • shutdown_timeout – The time to give a node for a successful shutdown. If it takes longer than this, the test will fail.

  • kwargs – Passed to the ros2_easy_test.env.ROS2TestEnvironment