Skip to content

Tests of the Localization

Five test files check the EKF and the IMU sample validator of the Localization chapter without the robot. Each file tests at a different level: the validator's rules alone, the validator and the filter on a clock that the test steps, the whole robot in Gazebo, the launch files, and the publisher of the transform odom → base_footprint. Each test has a page that walks through its code, with a figure of what the test feeds and what it checks.

Which question each test answers

Each question below leads to the page of the test that answers it. The pages go from a single decision of the validator, through the validator and the EKF together, to the simulated robot:

  1. Which IMU samples may reach the EKF?
    • Answer: a sample passes only at a ROS time other than 0, and only with the right frame, finite values, valid variances, a stamp close to the ROS time, and a stamp later than the last valid sample's.
    • Where the test runs: in Python alone. The unit tests call the validator's class directly, without a ROS master.
  2. What does the EKF estimate when the IMU samples are valid, invalid or stop?
    • Answer: the estimate's yaw rate \(\omega_z\) follows the valid IMU samples, ignores the samples that the validator drops, and goes to the wheels' yaw rate when no valid sample arrives, also at the robot's rates. The estimate's forward speed \(v_x\) follows the wheels', also when their speed changes.
    • Where the test runs: the validator and the EKF run as ROS nodes, on a clock that the test steps, without Gazebo.
  3. Does the EKF recover a wrong turn in Gazebo?
    • Answer: yes. With a wheel separation that is 25 % too large in the drive controller, the wheel odometry's turn falls behind the true turn, and the EKF's turn stays within 0.05 rad of the true turn. In the same simulation, the EKF is the only node that publishes the transform odom → base_footprint.
    • Where the test runs: in Gazebo without a window, with the EKF, with DiffBot and with Remo.
  4. Does ekf:=true start the EKF and hand the transform over to the EKF?
    • Answer: the launch files that start the robot or the simulation start the EKF and the validator only with ekf:=true, and then turn the drive controller's transform off. The launch files that start a planner make the planner read the EKF's odometry by default with ekf:=true.
    • Where the test runs: roslaunch's loader reads the launch files. No node starts.
  5. Which node publishes the transform odom → base_footprint without the EKF?
    • Answer: the only publisher is /gazebo, the node that runs the drive controller in the simulation. With the EKF, the test of question 3 checks that the EKF is the only publisher, and the page of this question shows both cases.
    • Where the test runs: in Gazebo without a window, without the EKF, with DiffBot and with Remo.

How the tests run

The five test files are Python tests, written with Python's unittest module: each file defines its tests as methods of a unittest.TestCase class. catkin runs the five files with the workspace's other tests. The packages register them in their CMakeLists.txt with two functions:

  • catkin_add_nosetests(): for the two files without ROS nodes. The test runner nose finds the TestCase classes in the file and runs their tests.
  • add_rostest(): for the three files that start nodes. rostest starts the nodes of the test's .test launch file, then the test file.

catkin's guides Configuring Python nose tests and Configuring rostest explain the two functions. CI runs the same tests on every pull request, as Testing and CI explains.

Run the tests

Run the commands in the dev container, in a shell in which its built Noetic workspace ~/catkin_ws is sourced, as the container's setup leaves it. These commands run every test of the workspace, as CI does, from the workspace's folder:

1
2
3
cd ~/catkin_ws
catkin build --catkin-make-args run_tests
catkin_test_results build

The second line builds the workspace and runs every registered test, the five files included. The third line sums up the result files and fails if any test failed. Run it on Simulation Test explains the two commands.

To run one test file, use its command from the list. Each item names what a passing run prints. The test's page shows the whole output and what the test doesn't show.

  • test_imu_validator.py, IMU Sample Validator: Python's unittest runs the file from its folder.

    1
    2
    roscd diffbot_control/test
    python3 -m unittest -v test_imu_validator
    

    A pass ends with the line OK, after Ran 30 tests.

  • test_ekf_synthetic.py, EKF on a Stepped Clock: rostest runs one scenario for each .test file.

    1
    2
    rostest diffbot_control ekf_synthetic.test
    rostest diffbot_control ekf_synthetic_robot_rates.test
    

    For each command, look for * RESULT: SUCCESS under SUMMARY at the end of the output.

  • test_ekf.py, EKF in Gazebo: rostest starts the simulation of one robot with the EKF.

    1
    2
    rostest diffbot_gazebo sim_ekf_diffbot.test
    rostest diffbot_gazebo sim_ekf_remo.test
    

    For each command, look for * RESULT: SUCCESS under SUMMARY at the end of the output.

  • test_ekf_switch.py, The ekf Switch: Python's unittest runs the file from its folder.

    1
    2
    roscd diffbot_gazebo/test
    python3 -m unittest -v test_ekf_switch
    

    A pass ends with the line OK, after Ran 5 tests.

  • test_odom_tf.py, The Transform's Publisher: rostest starts the simulation of one robot without the EKF and runs all five test nodes of the file, this test among them.

    1
    2
    rostest diffbot_gazebo sim_drive_diffbot.test
    rostest diffbot_gazebo sim_drive_remo.test
    

    For each command, look for * RESULT: SUCCESS under SUMMARY at the end of the output. This result covers all five test nodes of the file.

What the tests don't show

The tests run without the robot. They don't show four things:

Comments

Comments are GitHub Discussions, shown with giscus. Loading them connects to giscus.app (hosted by Vercel, USA) and GitHub (USA); you need a GitHub account to comment.