ctest: Usage, Options & Common CI Errors
ctest runs the tests registered by CMake and reports pass/fail with timing.
ctest executes the tests a CMake project declared with add_test/enable_testing. The CI essentials are running from the build dir, --output-on-failure to actually see failures, and remembering ctest does not build first.
What it does
ctest is the testing tool bundled with CMake. It discovers tests registered in the build (via add_test() and enable_testing()), runs them, applies filters and parallelism, and reports results - optionally submitting to CDash.
Common usage
ctest --test-dir build --output-on-failure
ctest -j8 --output-on-failure # parallel
ctest -R '^unit_' --test-dir build # filter by name regex
ctest --rerun-failed --output-on-failure
ctest -T Test --no-compress-output # produce XML for CIOptions
| Flag | What it does |
|---|---|
| --output-on-failure | Print test stdout/stderr when it fails |
| -j <N> / --parallel <N> | Run N tests concurrently |
| -R <regex> / -E <regex> | Include / exclude tests by name |
| --rerun-failed | Only re-run previously failed tests |
| --test-dir <dir> | Point ctest at the build directory |
| -T Test | Dashboard mode (emits XML results) |
Common errors in CI
"No tests were found!!!" - you ran ctest outside the build dir, the project never called enable_testing()/add_test(), or you filtered them all out with -R. ctest does NOT build - run cmake --build first or tests reference stale binaries. Without --output-on-failure a failing test shows only "Failed" with no log, which is useless in CI - always pass it. Use -j to parallelize but watch for tests that share fixtures/ports and need RESOURCE_LOCK.