ctest --output-on-failure: Run CMake Tests in CI
ctest runs the tests that CMake registered with add_test/enable_testing, and --output-on-failure prints the log of any test that fails.
ctest is the test driver that ships with CMake. In CI the essential flags are --output-on-failure (so a failure shows its output) and -j (so tests run in parallel).
What it does
ctest discovers the tests recorded in the build directory (CTestTestfile.cmake) and runs them, reporting pass/fail. By default it hides passing output; --output-on-failure prints the captured output of any failing test.
Common usage
ctest --test-dir build --output-on-failure -j 4
ctest --test-dir build -R "unit_.*"
ctest --test-dir build --rerun-failed --output-on-failureOptions
| Flag | What it does |
|---|---|
| --output-on-failure | Print a test's output when it fails |
| -j <N> / --parallel <N> | Run up to N tests concurrently |
| --test-dir <dir> | Build directory to run tests from (CTest 3.20+) |
| -R <regex> | Run only tests whose name matches the regex |
| -E <regex> | Exclude tests matching the regex |
| --rerun-failed | Run only tests that failed the previous run |
| --output-junit <file> | Write JUnit XML for CI test reporting |
In CI
Combine --output-on-failure -j $(nproc) so failures are diagnosable and the suite runs in parallel. Use --output-junit (CTest 3.21+) to surface results in the CI test UI. Run from --test-dir build rather than cd-ing so the step is a single line.
Common errors in CI
"No tests were found!!!" means enable_testing()/add_test() was never called, tests were not built, or --test-dir points at the wrong directory. "Cannot find file: .../CTestTestfile.cmake" means the build dir was not configured. A test marked "Failed" with no output is why you add --output-on-failure. "Errors while running CTest" with exit code non-zero is the signal your CI job should fail on.