RclexTesting (RclexTesting (Experimental) v0.12.13)

A Phoenix.LiveViewTest-style testing library for ROS2 applications built with rclex.

Provides a high-level scenario DSL for expressing robot behaviour as executable test specifications without manually managing nodes, publishers, subscriptions, or assertion loops.

Usage

defmodule RobotTest do
  use ExUnit.Case
  use RclexTesting

  scenario "robot starts mission" do
    watch "/robot/state", MyPkg.Msg.RobotState
    publish "/mission/start", MyPkg.Msg.MissionStart.new(id: 42)
    expect "/robot/state", &(&1.state == :running)
  end
end

Options

Every DSL function that creates or uses an rclex entity accepts an optional trailing keyword list. :timeout is consumed by the DSL; every other option is forwarded verbatim to the underlying Rclex call — :qos, :namespace, :introspection, action :options and callbacks, and so on.

watch "/scan", LaserScan, qos: Rclex.QoS.profile_sensor_data()
expect "/scan", &(&1.ranges != []), timeout: 10_000

:namespace identifies the scenario node, not a topic prefix. Set it once with scenario/3 and every DSL call in the block inherits it:

scenario "namespaced robot", namespace: "/robot1" do
  publish "/mission/start", %MissionStart{id: 42}
end

DSL

The scenario DSL is organized into the following modules:

• RclexTesting.DSL.Topics - publish, observe, and assert topic messages.
• RclexTesting.DSL.Services - mock services and assert service requests.
• RclexTesting.DSL.Actions - mock action servers and assert goals, feedback, and results.
• RclexTesting.DSL.Events - describe and assert workflows across message, service, and action streams.
• RclexTesting.DSL.Graph - assert the live ROS graph topology.
• RclexTesting.DSL.Time - control and inspect simulated ROS time.

use RclexTesting imports every DSL module, scenario declarations, and RclexTesting.Matchers.