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 throughdebug_launch_file – If set to
True
, instructros2 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 isFalse
.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
See also
- 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 classrclpy.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)
pairstime_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
See also