ctest Command Reference

Run the test suite registered with CMake by add_test.

ctest runs the tests a CMake project registers via add_test. In CI it is the standard test driver for C/C++ projects built with CMake.

What it does

ctest discovers and runs tests defined in the build directory, reporting pass/fail and timing. It can parallelize, filter by regex or label, repeat to catch flakes, and emit JUnit XML for CI test reporting.

Common flags and usage

--output-on-failure: print test output only when a test fails
-j N / --parallel N: run tests in parallel
-R REGEX / -L LABEL: filter tests by name or label
--test-dir DIR: point at the build directory
--output-junit FILE: emit JUnit XML for CI

Example

shell

- name: Test
  run: ctest --test-dir build --output-on-failure -j"$(nproc)"

In CI

Always pass --output-on-failure so a failing test prints its output instead of a bare summary, which is otherwise the hardest part of debugging a CMake test failure on a runner. Use --output-junit to feed CI test reporters.

Key takeaways

--output-on-failure prints failing-test output, essential for CI debugging.
-j parallelizes the suite; -R and -L filter by name and label.
--output-junit produces XML for CI test reporting.