# CMake Testing

**`enable_testing()` activates testing support. `add_test(NAME name COMMAND cmd)` registers a test that CMake/CTest will run**. Tests are commands; their exit code determines pass (0) or fail (non-zero).

Basic setup:

```cmake
cmake_minimum_required(VERSION 3.20)
project(MyApp)

enable_testing()

add_executable(test_app test.cpp)
add_test(NAME MyTest COMMAND test_app)
```

Running tests:

```bash
cmake --build . --target test
# or
ctest
ctest -V            # verbose: show output
ctest -R pattern    # run matching tests
ctest -j 4          # run 4 tests in parallel
```

Multiple tests:

```cmake
enable_testing()

add_executable(test_math test_math.cpp)
add_test(NAME MathTest COMMAND test_math)

add_executable(test_string test_string.cpp)
add_test(NAME StringTest COMMAND test_string)
```

Test with framework (example: Google Test / gtest):

```cmake
find_package(GTest REQUIRED)

add_executable(test_app test.cpp)
target_link_libraries(test_app PRIVATE GTest::gtest GTest::gtest_main)
add_test(NAME GoogleTests COMMAND test_app)
```

Test properties:

```cmake
add_test(NAME MyTest COMMAND test_app)
set_tests_properties(MyTest PROPERTIES
  TIMEOUT 10          # timeout after 10 seconds
  DEPENDS OtherTest   # run after OtherTest
  LABELS unit         # label for filtering
)

ctest -L unit        # run tests labeled "unit"
```

Working directory:

```cmake
add_test(NAME FileTest COMMAND test_app
  WORKING_DIRECTORY ${CMAKE_BINARY_DIR}/test_data)
```

Conditional tests:

```cmake
if(BUILD_TESTING)
  enable_testing()
  add_executable(test_app test.cpp)
  add_test(NAME MyTest COMMAND test_app)
endif()
```

Then build with:

```bash
cmake -DBUILD_TESTING=ON ..
```

Tests typically live in a `tests/` or `test/` subdirectory:

```cmake
# CMakeLists.txt
add_subdirectory(tests)

# tests/CMakeLists.txt
enable_testing()
add_executable(test_unit unit.cpp)
add_test(NAME UnitTests COMMAND test_unit)
```

Testing is essential for catching regressions. Enable it early and run tests frequently. CMake integrates with CTest (test runner) and CPack (installer), so test results can be submitted to a dashboard.