cmake_test/add_section

cmake_test/add_section.ct_add_section(**kwargs)

Adds a test section, should be called inside of a declared test function directly before declaring the section function.

A variable named CMAKETEST_SECTION will be set in the calling scope that holds the section function ID. Use this variable to define the CMake function holding the section code. Ex:

#This is inside of a declared test function
ct_add_section(NAME this_section)
function(${CMAKETEST_SECTION})
    message(STATUS "This code will run in a test section")
endfunction()

Additionally, the NAME parameter will be populated as by set() with the generated section function name. This is for backwards-compatibility purposes. Ex:

#This is inside of a declared test function
ct_add_section(NAME this_section)
function(${this_section})
    message(STATUS "This code will run in a test section")
endfunction()

This behavior is considered deprecated, use the first form for new sections.

Print length of pass/fail lines can be adjusted with the PRINT_LENGTH option.

Priority for print length is as follows (first most important):

  1. Current execution unit’s PRINT_LENGTH option

  2. Parent’s PRINT_LENGTH option

  3. Length set by ct_set_print_length()

  4. Built-in default of 80.

If a section raises an exception when it is not expected to, it will be marked as a failing section and its subsections will not be executed, due to limitations in how CMake handles failures. However, sibling sections as well as other tests will continue to execute, and the failures will be aggregated and printed after all tests have been ran.

Keyword Arguments

Parameters:

  • NAME (str*) – Required argument specifying the name variable of the section. Will set a variable with specified name containing the generated function ID to use.

  • EXPECTFAIL (option) – Option indicating whether the section is expected to fail or not, if specified will cause test failure when no exceptions were caught and success upon catching any exceptions.

  • PRINT_LENGTH (int) – Optional argument specifying the desired print length of pass/fail output lines.

See also

ct_add_test() for details on EXPECTFAIL.

See also

ct_exec_tests() for details on halting tests on exceptions.

Implementation Details

Upon being executed, this function will check if the section should be executed. If it is not, this function will generate an ID for the section function and sets the variable pointed to by the NAME parameter to it. It will also construct a new CTExecutionUnit instance to represent the section.

If the section is supposed to be executed, this function will call the execute() method of the unit representing this section. Exceptions will be tracked while the function is being executed. After completion of the test, the test status will be output using print_pass_or_fail(). The section’s subsections will then be executed recursively, following this same flow until there are no more subsections.