Forrest logo
tool overview
On this page you find all important commands for the CLI tool ctest. If the command you are looking for is missing please ask our AI.

ctest

CTest is a command line tool that is a part of the CMake build system. It is primarily used for running tests on CMake-built projects. Here are some key points about ctest:

  1. Test Execution: CTest allows you to execute tests defined in your CMake project conveniently from the command line. It can run tests in parallel, making it efficient for large projects with numerous tests.

  2. Test Discovery: It automatically discovers the tests defined in your project, and you can group them using regular expressions or by specifying specific test executable names.

  3. Continuous Integration Integration: CTest is often used in conjunction with Continuous Integration (CI) systems like Jenkins, Travis CI, or GitLab CI. It provides an integration mechanism to run tests as part of the CI build process.

  4. Test Output: CTest captures the output of the tests it executes, including both standard output and standard error. It can generate detailed reports and summaries of the test results, which can be helpful for identifying and fixing issues.

  5. Test Labels: CTest supports labeling tests using user-defined attributes. This feature allows you to categorize tests based on their characteristics or requirements (e.g., performance tests, unit tests, integration tests, etc.). Labels can be used to selectively execute specific groups of tests.

  6. Test Timeouts: CTest allows you to set time limits for individual tests. If a test exceeds the specified time limit, CTest can terminate it and mark it as failed.

  7. Test Coverage: CTest provides support for code coverage analysis. By enabling coverage tracking, you can generate reports that show which parts of your codebase have been tested.

  8. Dashboard Reporting: CTest can upload test results to a centralized dashboard server, such as the CDash web application. This allows for easy monitoring and visualization of test results across multiple projects or platforms.

Note: CTest is primarily used with CMake projects; however, it can also be used independently with custom test suites if the project follows a specific test executable naming convention.

List of commands for ctest:

  • ctest:tldr:0b190 ctest: Run all tests defined in the CMake project, executing 4 jobs at a time in parallel.
    $ ctest -j${4} --output-on-failure
    try on your machine
    explain this command
  • ctest:tldr:25e10 ctest: Run a single test based on its name, or filter on a regular expression.
    $ ctest --output-on-failure -R '^${test_name}$'
    try on your machine
    explain this command
  • ctest:tldr:e74fe ctest: Show a list of available tests.
    $ ctest -N
    try on your machine
    explain this command
tool overview