How to Create Unit Tests with GTest – ROS 2 Jazzy

This tutorial introduces unit testing in ROS 2 using GTest (GoogleTest), Google’s C++ testing framework. We’ll explore how to write and run tests for ROS 2 nodes, ensuring your robotic software functions correctly at the component level.

By the end, you’ll be equipped to implement comprehensive unit tests, enhancing the reliability and maintainability of your ROS 2 projects.

Prerequisites

You can find all the code here on GitHub.

Why Use GTest

Imagine you’re building a complex robot using ROS 2, with multiple C++ nodes working together to control its behavior. Every time you update your code, install a new version of ROS 2, or upgrade any dependencies, something could break without you realizing it. This is where GTest comes in handy.

GTest is like a safety net for your robot’s C++ code. It automatically checks that everything still works correctly after you make changes. For example, if you update your navigation code or install a new version of a sensor driver, GTest can quickly verify that your nodes are still publishing the right messages at the right times. This helps you catch problems early – before your robot starts behaving unexpectedly in the real world.

Create the Unit Test

Let’s write a basic unit test for our ROS 2 C++ publisher node. The test code we will write sets up a testing environment for a ROS 2 publisher node, making sure it can properly start up and shut down. 

The first test checks if the node is created with the right name and is publishing on the correct topic. The second test verifies that the node actually publishes messages with the correct “Hello World!” format we expect.

Open a terminal window and move to your workspace:

cd ~/ros2_ws/
colcon build && source ~/.bashrc
cd ~/ros2_ws/src/ros2_fundamentals_examples/

Create a new folder:

mkdir -p test/gtest

Create the test file test/gtest/test_publisher.cpp:

/**
 * @file test_publisher.cpp
 * @brief Unit tests for the ROS 2 minimal publisher node.
 *
 * These tests verify the functionality of a minimal ROS 2 publisher including
 * node creation, message formatting, and publishing behavior.
 *
 * @author Addison Sears-Collins
 * @date November 6, 2024
 */

#include <gtest/gtest.h>
#include <memory>
#include "rclcpp/rclcpp.hpp"
#include "std_msgs/msg/string.hpp"
#include "../../src/cpp_minimal_publisher.cpp"

/**
 * @class TestMinimalPublisher
 * @brief Test fixture for the MinimalCppPublisher tests
 *
 * This fixture handles the setup and teardown of ROS 2 infrastructure
 * needed for each test case.
 */
class TestMinimalPublisher : public ::testing::Test 
{
protected:
    void SetUp() override 
    {
        rclcpp::init(0, nullptr);
        node = std::make_shared<MinimalCppPublisher>();
    }

    void TearDown() override 
    {
        node.reset();
        rclcpp::shutdown();
    }

    std::shared_ptr<MinimalCppPublisher> node;
};

/**
 * @test TestNodeCreation
 * @brief Verify the publisher node is created correctly
 *
 * Tests:
 * - Node name is set correctly
 * - Publisher exists on the correct topic
 * - Message type is correct
 */
TEST_F(TestMinimalPublisher, TestNodeCreation) 
{
    // Verify the node name is set correctly
    EXPECT_EQ(node->get_name(), "minimal_cpp_publisher");

    // Get all publisher endpoints
    auto pub_endpoints = node->get_publishers_info_by_topic("/cpp_example_topic");
    
    // Verify we have exactly one publisher on the topic
    EXPECT_EQ(pub_endpoints.size(), 1u);
    
    // Verify the topic name and message type
    EXPECT_EQ(pub_endpoints[0].topic_name, "/cpp_example_topic");
    EXPECT_EQ(pub_endpoints[0].topic_type, "std_msgs/msg/String");
}

/**
 * @test TestMessageContent
 * @brief Verify the published message content is correct
 *
 * Creates a subscription to capture published messages and verifies
 * the message format matches expectations.
 */
TEST_F(TestMinimalPublisher, TestMessageContent) 
{
    // Create a subscription to capture the published message
    std::shared_ptr<std_msgs::msg::String> received_msg;
    auto subscription = node->create_subscription<std_msgs::msg::String>(
        "/cpp_example_topic", 10,
        [&received_msg](const std_msgs::msg::String::SharedPtr msg) {
            received_msg = std::make_shared<std_msgs::msg::String>(*msg);
        });

    // Trigger the timer callback
    node->timerCallback();

    // Spin until we receive the message or timeout
    rclcpp::spin_some(node);
    
    // Verify the message format
    ASSERT_NE(received_msg, nullptr);
    EXPECT_EQ(received_msg->data, "Hello World! 0");
}

/**
 * @brief Main function to run all tests
 */
int main(int argc, char** argv) 
{
    testing::InitGoogleTest(&argc, argv);
    return RUN_ALL_TESTS();
}

Edit the C++ Publisher

Open cpp_minimal_publisher.cpp.

We need to wrap the main function in the TESTING_EXCLUDE_MAIN condition so it won’t be included during testing. Here’s how to modify it:

#ifndef TESTING_EXCLUDE_MAIN
int main(int argc, char * argv[])
{
  // Initialize ROS 2.
  rclcpp::init(argc, argv);

  // Create an instance of the MinimalCppPublisher node and keep it running.
  auto minimal_cpp_publisher_node = std::make_shared<MinimalCppPublisher>();
  rclcpp::spin(minimal_cpp_publisher_node);

  // Shutdown ROS 2 upon node termination.
  rclcpp::shutdown();

  // End of program.
  return 0;
}
#endif

By adding the #ifndef TESTING_EXCLUDE_MAIN and #endif, this main function will only be compiled when we’re not running tests. When we include this file in our test file (where we defined TESTING_EXCLUDE_MAIN), this main function will be skipped.

Edit CMakeLists.txt

Update CMakeLists.txt. Find the if(BUILD_TESTING) block and replace it with:

if(BUILD_TESTING)
  # Find required test packages
  find_package(ament_lint_auto REQUIRED)
  find_package(ament_cmake_pytest REQUIRED)
  find_package(ament_cmake_gtest REQUIRED)
  
  # Python tests
  ament_add_pytest_test(minimal_publisher_test test/pytest/test_publisher.py
    TIMEOUT 60
  )
  
  # C++ tests
  ament_add_gtest(cpp_minimal_publisher_test
    test/gtest/test_publisher.cpp
  )
  
  # Add dependencies for the C++ test executable
  ament_target_dependencies(cpp_minimal_publisher_test
    ${dependencies}
  )
  
  # Optional: Enable other linting tools
  #set(ament_cmake_copyright_FOUND TRUE)
  #set(ament_cmake_cpplint_FOUND TRUE)
  #ament_lint_auto_find_test_dependencies()
endif()

Edit package.xml

We need to add this to the package.xml so that our tests are discoverable to cmake:

<test_depend>ament_cmake_gtest</test_depend>

Save the file, and close it.

Build and Run

Build and run the tests:

cd ~/ros2_ws
colcon build --packages-select ros2_fundamentals_examples
source ~/.bashrc
colcon test --packages-select ros2_fundamentals_examples

To see detailed test results, type:

colcon test --packages-select ros2_fundamentals_examples --event-handlers console_direct+
1-tests-passed

When we run the tests using colcon test, it first runs the Python tests which all pass (“3 passed in 0.37s”). Then it runs our two C++ GTest tests: one checking the node name and publisher setup, and another checking the message content. Both C++ tests pass as shown by the output “[  PASSED  ] 2 tests” and “100% tests passed, 0 tests failed out of 2”, indicating that our publisher node is working exactly as intended.

To check test results:

colcon test-result --all

To see which test cases failed (if any):

colcon test-result --all --verbose

That’s it. Keep building!

How to Create Unit Tests with Pytest – ROS 2 Jazzy

Imagine you’re building a complex robot using ROS 2, the latest version of the Robot Operating System. Your robot is made up of many different parts, each controlled by a piece of software. Now, how do you make sure all these pieces work correctly? That’s where unit testing comes in.

Unit testing is like doing a health check-up for each part of your robot’s software. It’s a way to automatically test small pieces of your code to make sure they’re doing exactly what they’re supposed to do. 

Unit tests are essential tools in robotics software development for two key reasons:

  • Early Bug Detection: Automate the testing of code to ensure that changes or updates don’t introduce bugs.
  • Improved Code Design: Writing testable code leads to cleaner, more modular software.

In this tutorial, I’ll show you how to use a tool called Pytest to write and run these unit tests. With Pytest, you can write tests for individual parts of your code, such as functions and classes, to make sure each part behaves as expected.

Pytest is designed primarily for Python code, so it’s commonly used for testing Python-based ROS 2 packages. For C++ code in ROS 2, other testing frameworks, like GTest, are typically used instead.

Prerequisites

You can find all the code here on GitHub.

Create a Unit Test 

Let’s write a basic unit test for our ROS 2 publisher node. This test will verify three key things: 

  1. that our node is created correctly
  2. that its message counter works properly
  3. that it formats messages as expected. 

We’ll create a Python test file that uses Pytest to run these checks automatically.

Open a terminal window, and move to your workspace.

cd ~/ros2_ws/
colcon build && source ~/.bashrc
cd ~/ros2_ws/src/ros2_fundamentals_examples/
mkdir -p test/pytest

Create a test file test/pytest/test_publisher.py:

#!/usr/bin/env python3
"""
Test suite for the ROS2 minimal publisher node.

This script contains unit tests for verifying the functionality of a minimal ROS2 publisher.
It tests the node creation, message counter increment, and message content formatting.

Subscription Topics:
    None

Publishing Topics:
    /py_example_topic (std_msgs/String): Example messages with incrementing counter

:author: Addison Sears-Collins
:date: November 6, 2024
"""

import pytest
import rclpy
from std_msgs.msg import String
from ros2_fundamentals_examples.py_minimal_publisher import MinimalPyPublisher


def test_publisher_creation():
    """
    Test if the publisher node is created correctly.

    This test verifies:
    1. The node name is set correctly
    2. The publisher object exists
    3. The topic name is correct

    :raises: AssertionError if any of the checks fail
    """
    # Initialize ROS2 communication
    rclpy.init()
    try:
        # Create an instance of our publisher node
        node = MinimalPyPublisher()

        # Test 1: Verify the node has the expected name
        assert node.get_name() == 'minimal_py_publisher'

        # Test 2: Verify the publisher exists and has the correct topic name
        assert hasattr(node, 'publisher_1')
        assert node.publisher_1.topic_name == '/py_example_topic'
    finally:
        # Clean up ROS2 communication
        rclpy.shutdown()


def test_message_counter():
    """
    Test if the message counter increments correctly.

    This test verifies that the counter (node.i) increases by 1 after
    each timer callback execution.

    :raises: AssertionError if the counter doesn't increment properly
    """
    rclpy.init()
    try:
        node = MinimalPyPublisher()
        initial_count = node.i
        node.timer_callback()
        assert node.i == initial_count + 1
    finally:
        rclpy.shutdown()


def test_message_content():
    """
    Test if the message content is formatted correctly.

    This test verifies that the message string is properly formatted
    using an f-string with the current counter value.

    :raises: AssertionError if the message format doesn't match expected output
    """
    rclpy.init()
    try:
        node = MinimalPyPublisher()
        # Set counter to a known value for testing
        node.i = 5
        msg = String()
        # Using f-string instead of % formatting
        msg.data = f'Hello World: {node.i}'
        assert msg.data == 'Hello World: 5'
    finally:
        rclpy.shutdown()


if __name__ == '__main__':
    pytest.main(['-v'])

Edit CMakeLists.txt

Now open CMakeLists.txt, and replace the if(BUILD_TESTING) block with this code:

if(BUILD_TESTING)
  #find_package(ament_lint_auto REQUIRED)
  find_package(ament_cmake_pytest REQUIRED)
  #set(ament_cmake_copyright_FOUND TRUE)
  #set(ament_cmake_cpplint_FOUND TRUE)
  #ament_lint_auto_find_test_dependencies()

  ament_add_pytest_test(minimal_publisher_test test/pytest/test_publisher.py
   TIMEOUT 60
  )
endif()

Edit the package.xml File

We need to add this to the package.xml so that our tests are discoverable to cmake:

<test_depend>ament_cmake_pytest</test_depend>

Save the file, and close it.

Build and Run

Compile and run the tests.

cd ~/ros2_ws
rosdep install --from-paths src --ignore-src -r -y
colcon build --packages-select ros2_fundamentals_examples
source ~/.bashrc
colcon test --packages-select ros2_fundamentals_examples
1-colcon-test

To get more detail, you could also have done:

colcon test --packages-select ros2_fundamentals_examples --event-handlers console_direct+

When we run our unit tests with this command above (Starting >>> ros2_fundamentals_examples), it first starts by loading our ROS 2 package.

The system then collects and runs our three test cases, shown as the three passing tests in the output (test/pytest/test_publisher.py …). These dots represent successful runs of our three tests – publisher node creation, message counter, and message content.

Your test results should show all tests passed successfully (============================== 3 passed in 0.28s ===============================). 

My final summary shows that our single test suite (1/1 Test #1: minimal_publisher_test) passed successfully in 0.76 seconds, with CMake reporting 100% success rate as no tests failed.

Now once that is finished, check the results:

colcon test-result --all

To see which test cases failed, type:

colcon test-result --all --verbose

That’s it.

Keep building!

How to Save Your ROS 2 Project on GitHub

In this tutorial, I will show you how to store your ROS 2 project in a repository on GitHub.

Follow along with me click by click, keystroke by keystroke.

In case you’re not familiar with GitHub, GitHub is an online platform specifically designed for software development. It offers several key functionalities:

  • Version control: This allows you to track changes made to code over time. Think of it like a time machine for your code, letting you revert to previous versions if necessary.
  • Code storage: GitHub acts as a secure and centralized location to store and manage code projects. Think of it like cloud storage specifically for your code.
  • Collaboration: Teams can work together on projects by sharing code, discussing changes, and merging different contributions seamlessly.
  • Open-source contribution: GitHub is a hub for open-source projects, where developers can publicly share their code, contribute to existing projects, and learn from others.

Prerequisites

  • You have created a ROS 2 package inside a workspace.
  • I have created a ROS 2 workspace that is at this path /home/ubuntu/ros2_ws/.

My package is called ros2_fundamentals_examples and is at this path: /home/ubuntu/ros2_ws/src/ros2_fundamentals_examples/

You can see the complete repository here on GitHub.

Install Git

The first thing you need to do is install Git. Open a new terminal window, and type:

sudo apt-get update
sudo apt-get install git -y

Check the git version you have.

git --version

Configure Git

Configure your git username and email.

git config --global user.name "John Doe"
git config --global user.email "johndoe@example.com"
git config --global init.defaultBranch main

Initialize Git

Move to inside your project folder.

cd  ~/ros2_ws/src/ros2_fundamentals_examples/

Initialize the folder as a Git repository by running:

git init

This command allows you to start tracking changes to the files within that directory.

1-git-init

Add and Commit the Files to Your Local Repository

Add the files in your folder to the repository with the following command:

git add .

Commit your staged files to your local repository with:

git commit -m "Initial commit"

Create the Remote Repository on GitHub

Go to GitHub and log in.

Click on the “+” icon in the upper right corner and select “New repository.”

Name your repository.

Add a description (optional).

Choose whether the repository will be public or private.

Ignore the rest of the options.

Click “Create repository.”

Link the Local Repository to the Remote Repository

After creating your repository on GitHub, you’ll get a URL for that repository that looks like this: “https://github.com/…./ros2_fundamentals.git:. 

Go back to a terminal window, and link your local repository to GitHub with this command:

cd  ~/ros2_ws/src/ros2_fundamentals_examples/
git remote add origin <repository-URL>

Now log in to your GitHub account again.

Creating a Fine-Grained Personal Access Token

A personal access token is like a special key that lets you access your GitHub account from other apps or scripts. It’s more secure than using your password because you can control what the token is allowed to do. 

Here are the official steps, but we will walk through everything together now.

First, verify your email address, if it hasn’t been verified yet.

In the top-right corner of the GitHub page, click on your profile picture.

From the menu, click “Settings.”

In the left sidebar of the settings page, scroll down until you see “Developer settings.”

Click on “Developer settings.”

In the left sidebar, under Personal access tokens, click Fine-grained tokens.

Click Generate new token.

Follow the steps to authenticate your identity on GitHub.

Under Token name, enter a name for the token.

Under Resource owner, select a resource owner. The token will only be able to access resources owned by the selected resource owner.

Under Expiration, select an expiration for the token.

Optionally, under Description, add a note to describe the purpose of the token.

Under Repository access, select which repositories you want the token to access.

If you selected Only select repositories in the previous step, under the Selected repositories dropdown, select the repositories that you want the token to access.  I will select the ros2_fundamentals_examples repository.

Under Permissions, select which permissions to grant the token. Depending on which resource owner and which repository access you specified, there are repository and account permissions. You should choose the minimal permissions necessary for your needs. 

I will grant “Read and write” permissions to all of the resources. If “Read and write” is not available for a particular resource, select “Read-only”.

Click Generate token.

Copy the personal access token that you see, and save it somewhere safe.

Push Code to GitHub

Finally, push your code from your local repository (the folder on your computer) to GitHub (the remote folder) with:

cd  ~/ros2_ws/src/ros2_fundamentals_examples/
git push -u origin main

Enter your GitHub Username.

Then, when it asks for your password, enter the personal access token you created in the previous section.

With this command we have created a two-way connection between your local code and GitHub.

The git push -u origin main command uploads your local code to GitHub while simultaneously setting up a tracking relationship between your local and remote branches. 

The -u (or –set-upstream) flag tells Git to remember this connection, so in the future you can simply use git push or git pull without needing to specify where to push to or pull from. 

origin refers to your GitHub repository, and main is the name of your branch. 

Now if you go back to GitHub, you can see your repository.

Git Command Overview

When you make changes to your code on your computer, and want to get these code changes saved to GitHub, here is how you do it:

git add . 

This command picks up all your new code changes and gets them ready to be saved. It’s like gathering up all your files into a neat pile.

git commit -m "description of changes" 

This command saves these changes on your computer with a message explaining what you did. It’s like putting that pile of files into a labeled folder.

git push 

This command sends all your saved changes to GitHub. Think of it like uploading your folder to the cloud so others can see it and you have a backup.

You’ll repeat these three steps each time you want to update your code on GitHub. 

And if you’re working with other people, you should always download their changes first using git fetch, git status, and then git pull (one command right after the other) before you start working.

git fetch checks GitHub to see what changes exist – it’s like looking at a list of updates available but not downloading them yet. It tells you what’s different between your code and GitHub’s code.

git status shows you exactly what’s different between your local code and the code on GitHub after you’ve fetched. It’s like comparing your version with GitHub’s version to see what’s changed.

git pull actually downloads those changes from GitHub to your computer, bringing your local code up to date. It’s like clicking “download” on those updates you found with fetch and status.

These three commands help you safely check for and get any updates before you start working, which helps avoid conflicts with other people’s code changes.

Remove the Need to Use a Username and Password

If you want to not have to use a username and password every time you run “git push”, you can use SSH keys. This page has the official instructions on how to do that.

Here is the process…

Generate an SSH key pair (if you don’t already have one) by running:

ssh-keygen -t ed25519 -C "your_email@example.com"

When you get prompted for a password or saving location, just keep pressing Enter, which will accept the default.

Start the ssh-agent in the background.

eval "$(ssh-agent -s)"

Add your SSH private key to the ssh-agent:

ssh-add ~/.ssh/id_ed25519

Add the SSH public key to your Git server.

cat ~/.ssh/id_ed25519.pub

Copy the entire result to your clipboard by highlighting everything and copying it.

Go to your GitHub account “Settings” by clicking your profile icon in the upper right of the website.

Look for “SSH and GPG keys”.

Add a New SSH key.

Paste the copied key as an “Authentication Key”. Also add a title (you can make it whatever you want).

Click Add SSH key.

Go back to the main page of your repository on GitHub.

Find the SSH URL by clicking the green button labeled “Code”.

Copy the SSH URL that is in there.

Switch your repository’s remote URL to SSH by going to your Ubuntu Linux terminal window, and moving to the directory of your repository.

cd <path to your your local repository>

For example:

cd  ~/ros2_ws/src/ros2_fundamentals_examples/
git remote set-url origin git@github.com:username/repository.git

To confirm everything is setup properly, type:

git pull

If you get asked about the authenticity of the host, just type yes and press Enter.

That’s it.

Using SSH keys is a more secure and convenient method for machines where you regularly push changes, as it doesn’t require entering your credentials after the initial setup.

Keep building!