#Testing CMake Modules & Scripts

The testing module includes a “mini” framework for testing your CMake modules and scripts. It is built on top of CTest.

#Getting Started

The following guide illustrates how you can get started. It is by no means a comprehensive guide on how to write tests, but rather just a starting point.

#Directory Structure

Create an appropriate directory in which your tests should reside. For instance, this can be located in the root of your project. You can name it “tests”, or whatever makes the most sense for you. The important part is to isolate tests from the remaining of your project’s CMake logic.

The following example is a possible directory and files structure, that you can use.

/tests
    /unit
        /assets
            build_assets_test.cmake
    CMakeLists.txt    
CMakeLists.txt

#Define Test Suite

In your /tests/CMakeLists.txt, define the test suite(s) for your project.

# ...in your /tests/CMakeLists.txt

enable_testing()

project(my_package_tests LANGUAGES NONE)

include("rsp/testing")

# Define the test suites for this project
define_test_suite("unit" DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/unit")

#Define Test Case

To define a new test case, invoke the define_test_case() function. This should be done in each test file (e.g. in the /tests/unit/assets/build_assets_tests.cmake from the above shown example directory and files structure).

# ... in your test file

include("rsp/testing")

define_test_case(
    "Build Assets Test"
    LABELS "assets;build"
)

# ... remaining not shown ...

#Define Test(s)

Once your test-case has been defined, you can define the tests. To do so, you need to define the function that must be invoked when the test-case is executed. This is done by the define_test() function.

# ... in your test file

# ... previous not shown ...

define_test("can build assets" "can_build_assets")
function(can_build_assets)
    
    # ... testing logic not shown ...
    
    assert_truthy(assets_built MESSAGE "Assets could bot be built...")
endfunction()

define_test("fails if assets not ready" "fails_when_not_ready" EXPECT_FAILURE)
function(fails_when_not_ready)

    # ... testing logic not shown ...

    assert_truthy(false MESSAGE "Assets should not be built when not ready...")
endfunction()

# ... etc

#Build & Run

To run the tests, you must first build the project using CMake. After that, use CTests to run the tests.

ctest --output-on-failure --parallel --test-dir <your-build-directory>/tests

#Caveats

Due to the nature of how tests are defined (via ctest), and how this “mini” testing framework has been designed, you might be required to rebuild your CMake, whenever changes are made to the various “define” functions’ parameters. This can, for instance, be when you rename a test function.

Throughout the remain of this documentation, if a “define” function requires rebuilding before changes take effect, then it will be highlighted via a warning, similar to the one shown below: