CMakeUnit

CMakeUnit is a small set of functions and macros useful when testing CMake code. There are three main scenarios how you can use CMakeUnit:

1. TDD the code, functions and macros
2. Run a part of the code in isolation
3. Use assertions in production code

Configuration

There are at least three ways to add CMakeUnit to your project:

1. Add CMakeUnit using FetchContent, add CMakeUnit source folder to CMAKE_MODULE_PATH for your convenience and include CMakeUnit.

    include(FetchContent)
   
    FetchContent_Declare(
        cmakeunit
        GIT_REPOSITORY "https://github.com/tawez/CMakeUnit.git"
        GIT_TAG "ccb7cfdcdcffcf76036f9dc53c83e7a313924e4c"
        UPDATE_DISCONNECTED ON
    )
    FetchContent_MakeAvailable(cmakeunit)
   
    list(PREPEND CMAKE_MODULE_PATH "${cmakeunit_SOURCE_DIR}")
    ...
    include(CMakeUnit)

   • Use git tag or commit hash as GIT_TAG
   • UPDATE_DISCONNECTED ON is optional

2. Add CMakeUnit as a git submodule, add path to CMakeUnit root folder to CMAKE_MODULE_PATH for your convenience and include CMakeUnit.

    list(PREPEND CMAKE_MODULE_PATH "path/to/CMakeUnit")
    ...
    include(CMakeUnit)

3. Add a copy of CMakeUnit.cmake to the folder of your choice, add this folder to CMAKE_MODULE_PATH for your convenience and include CMakeUnit.

    list(PREPEND CMAKE_MODULE_PATH "path/to/folder")
    ...
    include(CMakeUnit)

This is enough to use CMakeUnit assertions in production code wherever needed.

Setup for testing

1. Include CTest
2. Add the location of CMakeUnit module and location of every module you want to test to the CMAKE_MODULE_PATH
3. Add all the tests that you need with add_cmake_test
4. Add test target with add_cmakeunit_target

When done, follow the usual steps to run the test target:

mkdir build
cd build
cmake ..
make <cmakeunit target name>

For complete project setup and test examples, see CMakeUnit-example.

API

• Core functions
• Reporters
• Assertions
• Mocks

Core functions

• add_cmake_test
• add_cmakeunit_target

add_cmake_test

Add a test to be run by ctest. Test will be run with CMAKE_MODULE_PATH set to its current value.

Usage

add_cmake_test(<name> <path>
               [SKIP]
               [WILL_FAIL]
               [OPTIONS args...])

Params

• name Test name
• path Path to test source resolved from the CMAKE_CURRENT_SOURCE_DIR. If path is a folder, CMakeLists.txt is expected to be inside.
• SKIP Skip this test but keep it in test report
• WILL_FAIL Denote this test as expected to fail. Will set test property WILL_FAIL to true.
• OPTIONS Additional test options. This is a convenient way to set up test ENV.

add_cmakeunit_target

Add a custom target that will run ctest to execute registered tests.

Usage

add_cmakeunit_target(<name> [args...])

Params

• name Target name (usually there is no need to pass anything more).
• args Additional target options (all add_custom_target options are accepted).

Reporters

• FATAL
• FAIL

FATAL

Generate a fatal error and abort the current test/code.

Usage

FATAL([text...])

Params

• text Text to display when reporting error.

FAIL

Generate a non-fatal error and allow the current test/code to continue.

Usage

FAIL([text...])

Params

• text Text to display when reporting error.

Assertions

The following assertions come as a pair of variants ASSERT and EXPECT. Upon failure, ASSERT generates fatal error and aborts the execution of the current test/code, while EXPECT generates non-fatal error and allows the current test/code to continue.

NOTE: If not specified, error means fatal error for ASSERT and non-fatal error for EXPECT assertions.

• ASSERT_TRUE / EXPECT_TRUE
• ASSERT_FALSE / EXPECT_FALSE
• ASSERT_DEFINED / EXPECT_DEFINED
• ASSERT_UNDEFINED / EXPECT_UNDEFINED
• ASSERT_STREQ / EXPECT_STREQ
• ASSERT_NOT_STREQ / EXPECT_NOT_STREQ
• ASSERT_MATCH / EXPECT_MATCH
• ASSERT_NOT_MATCH / EXPECT_NOT_MATCH
• ASSERT_EQ / EXPECT_EQ
• ASSERT_NE / EXPECT_NE
• ASSERT_LT / EXPECT_LT
• ASSERT_LE / EXPECT_LE
• ASSERT_GT / EXPECT_GT
• ASSERT_GE / EXPECT_GE
• ASSERT_LIST_LENGTH / EXPECT_LIST_LENGTH
• ASSERT_LIST_EQ / EXPECT_LIST_EQ
• ASSERT_LIST_CONTAINS / EXPECT_LIST_CONTAINS

ASSERT_TRUE / EXPECT_TRUE

Verify if the value is true.

Usage

ASSERT_TRUE(<value>)
EXPECT_TRUE(<value>)

Params

• value Value to test

Reports

• error if the value is not true

ASSERT_FALSE / EXPECT_FALSE

Verify if the value is false.

Usage

ASSERT_FALSE(<value>)
EXPECT_FALSE(<value>)

Params

• value Value to test

Reports

• error if the value is not false

ASSERT_DEFINED / EXPECT_DEFINED

Verify if the variable is defined.

Usage

ASSERT_DEFINED(<variable>)
EXPECT_DEFINED(<variable>)

Params

• variable Variable to test

Reports

• error if the variable is not defined

ASSERT_UNDEFINED / EXPECT_UNDEFINED

Verify if the variable is undefined.

Usage

ASSERT_UNDEFINED(<variable>)
EXPECT_UNDEFINED(<variable>)

Params

• variable Variable to test

Reports

• error if the variable is defined

ASSERT_STREQ / EXPECT_STREQ

Verify if two strings, value and expected, have the same content.

Usage

ASSERT_STREQ(<value> <expected>)
EXPECT_STREQ(<value> <expected>)

Params

• value Value to test
• expected Expected value

Reports

• error if values differ

ASSERT_NOT_STREQ / EXPECT_NOT_STREQ

Verify if two strings, value and expected, have different content.

Usage

ASSERT_NOT_STREQ(<value> <expected>)
EXPECT_NOT_STREQ(<value> <expected>)

Params

• value Value to test
• expected Expected value

Reports

• error if values are equal

ASSERT_MATCH / EXPECT_MATCH

Verify if the value matches the pattern.

Usage

ASSERT_MATCH(<value> <pattern>)
EXPECT_MATCH(<value> <pattern>)

Params

• value Value to test
• pattern Pattern to test value against

Reports

• error if the value does not match the pattern

ASSERT_NOT_MATCH / EXPECT_NOT_MATCH

Verify if the value does not match the pattern.

Usage

ASSERT_NOT_MATCH(<value> <pattern>)
EXPECT_NOT_MATCH(<value> <pattern>)

Params

• value Value to test
• pattern Pattern to test value against

Reports

• error if the value matches the pattern

ASSERT_EQ / EXPECT_EQ

Verify if the value equals to the expected.

Usage

ASSERT_EQ(<value> <expected>)
EXPECT_EQ(<value> <expected>)

Params

• value Value to test
• expected Expected value

Reports

• error if values differ

ASSERT_NE / EXPECT_NE

Verify if the value does not equal to the expected.

Usage

ASSERT_NE(<value> <expected>)
EXPECT_NE(<value> <expected>)

Params

• value Value to test
• expected Expected value

Reports

• error if values are equal

ASSERT_LT / EXPECT_LT

Verify if the value is less than the expected.

Usage

ASSERT_LT(<value> <expected>)
EXPECT_LT(<value> <expected>)

Params

• value Value to test
• expected Expected value

Reports

• error if the value is not less than expected

ASSERT_LE / EXPECT_LE

Verify if the value is less than or equal to the expected.

Usage

ASSERT_LE(<value> <expected>)
EXPECT_LE(<value> <expected>)

Params

• value Value to test
• expected Expected value

Reports

• error if the value is greater than expected

ASSERT_GT / EXPECT_GT

Verify if the value is greater than the expected.

Usage

ASSERT_GT(<value> <expected>)
EXPECT_GT(<value> <expected>)

Params

• value Value to test
• expected Expected value

Reports

• error if the value is not greater than expected

ASSERT_GE / EXPECT_GE

Verify if the value is greater than or equal to the expected.

Usage

ASSERT_GE(<value> <expected>)
EXPECT_GE(<value> <expected>)

Params

• value Value to test
• expected Expected value

Reports

• error if the value is less than expected

ASSERT_LIST_LENGTH / EXPECT_LIST_LENGTH

Verify if the length of the list is in relation to the given expected value.

Usage

ASSERT_LIST_LENGTH(<variable> <relation> <expected>)
EXPECT_LIST_LENGTH(<variable> <relation> <expected>)

Params

• variable List variable to test
• relation One of: EQ, NE, LT, LE, GT, GE
• expected Expected list length

Reports

• error if the list length is not in relation to expected value

ASSERT_LIST_EQ / EXPECT_LIST_EQ

Verify if the value equals to the list made of the given item(s).

Usage

ASSERT_LIST_EQ(<value> [<item>...])
EXPECT_LIST_EQ(<value> [<item>...])

Params

• value Value to test
• item... Expected content of the list

Reports

• error if the value differs from the given list of items

ASSERT_LIST_CONTAINS / EXPECT_LIST_CONTAINS

Verify if the value contains all the given item(s) without any particular order.

Usage

ASSERT_LIST_CONTAINS(<value> [<item>...])
EXPECT_LIST_CONTAINS(<value> [<item>...])

Params

• value Value to test
• item... Expected content of the list

Reports

• error if the value does not contain at least one item

Mocks

• MOCK_FUNCTION
• EXPECT_CALL_TIMES
• EXPECT_CALL_WITH

MOCK_FUNCTION

Define a mock function with the given name.

Usage

MOCK_FUNCTION(<name>)

Params

• name Name of the mock to be created

Reports

• fatal error if mock function for the same name is defined again

EXPECT_CALL_TIMES

Verify if the mock has been called the expected number of times.

Usage

EXPECT_CALL_TIMES(<name> <expected>)

Params

• name Mock function name
• expected Expected number of mock function calls (no less than 0)

Reports

• fatal error if mock function is not defined or if expected is less than 0
• non-fatal error if mock function was not called expected number of times

EXPECT_CALL_WITH

Verify if the nth call of the mock function has been done with the given arguments.

Usage

EXPECT_CALL_WITH(<name> <nth> [<arg>...])

Params

• name Mock function name
• nth Number of the call of the mock function to verify
• arg... List of expected arguments

Reports

• fatal error if mock function is not defined or if nth is less than 1
• non-fatal error if mock function has not been called or if has been called less than nth times or if expected arguments differ to actual