catkin test – Test Packages

The test verb is used to test one or more packages in a catkin workspace. Like most verbs, test is context-aware and can be executed from within any directory contained by an initialized workspace. Specific workspaces can also be built from arbitrary working directories with the --workspace option.

Basic Usage

Before running tests for packages in the workspace, they have to be built with catkin build. Then, to run the tests, use the following:

$ catkin test

Under the hood, this invokes the make targets run_tests or test, depending on the package. catkin packages all define the run_tests target which aggregates all types of tests and runs them together. For cmake packages that do not use catkin, the test target is invoked. This target is usually populated by cmake when the enable_testing() command is used in the CMakeLists.txt. If it does not exist, a warning is printed.

To run a catkin test for a specific catkin package, from a directory within that package:

$ catkin test --this

Advanced Options

To manually specify a different make target, use --test-target:

$ catkin test --test-target gtest

It is also possible to use --catkin-test-target to change the target only for catkin packages.

Normally, the tests are run in parallel, similar to the build jobs of catkin build. To avoid building packages in parallel or to reduce the amount of parallel jobs, use -p:

$ catkin test -p 1

Sometimes, it can be helpful to see the output of tests while they are still running. This can be achieved using --interleave-output.

Full Command-Line Interface

usage: catkin test [-h] [--workspace WORKSPACE] [--profile PROFILE] [--this]
                   [--continue-on-failure] [-p PACKAGE_JOBS] [-t TARGET]
                   [--catkin-test-target TARGET] [--make-args ARG [ARG ...]]
                   [--verbose] [--interleave-output] [--summarize]
                   [--no-status] [--limit-status-rate LIMIT_STATUS_RATE]
                   [--no-notify]
                   [PKGNAME ...]

Test one or more packages in a catkin workspace. This invokes `make run_tests`
or `make test` for either all or the specified packages in a catkin workspace.

optional arguments:
  -h, --help            show this help message and exit
  --workspace WORKSPACE, -w WORKSPACE
                        The path to the catkin_tools workspace or a directory
                        contained within it (default: ".")
  --profile PROFILE     The name of a config profile to use (default: active
                        profile)

Packages:
  Control which packages get tested.

  PKGNAME               Workspace packages to test. If no packages are given,
                        then all the packages are tested.
  --this                Test the package containing the current working
                        directory.
  --continue-on-failure, -c
                        Continue testing packages even if the tests for other
                        requested packages fail.

Config:
  Parameters for the underlying build system.

  -p PACKAGE_JOBS, --parallel-packages PACKAGE_JOBS
                        Maximum number of packages allowed to be built in
                        parallel (default is cpu count)
  -t TARGET, --test-target TARGET
                        Make target to run for tests (default is "run_tests"
                        for catkin and "test" for cmake)
  --catkin-test-target TARGET
                        Make target to run for tests for catkin packages,
                        overwrites --test-target (default is "run_tests")
  --make-args ARG [ARG ...]
                        Arbitrary arguments which are passed to make. It
                        collects all of following arguments until a "--" is
                        read.

Interface:
  The behavior of the command-line interface.

  --verbose, -v         Print output from commands in ordered blocks once the
                        command finishes.
  --interleave-output, -i
                        Prevents ordering of command output when multiple
                        commands are running at the same time.
  --summarize, --summary, -s
                        Adds a summary to the end of the log
  --no-status           Suppresses status line, useful in situations where
                        carriage return is not properly supported.
  --limit-status-rate LIMIT_STATUS_RATE, --status-rate LIMIT_STATUS_RATE
                        Limit the update rate of the status bar to this
                        frequency. Zero means unlimited. Must be positive,
                        default is 10 Hz.
  --no-notify           Suppresses system pop-up notification.