cmake_test/execution_unit

The execution_unit module houses the class that makes up the core of CMakeTest. It includes cmakepp_lang to define the class and its attrbutes and methods.

Attention

This module is intended for internal use only.

class cmake_test/execution_unit.CTExecutionUnit

CTExecutionUnit represents the basic atomic unit of tests. Units can be either tests or test sections. The unit stores and tracks all state information related to the unit, such as the test ID, its friendly name, the file that contains it, etc.

This class also contains useful instance methods for generating or modifying required information.

An execution unit must be linked to an accompanying function that will be executed when this unit is tested.

Additional Constructors

CTOR(test_id, friendly_name, expect_fail)

Construct an execution unit with the given ID, friendly name, and expectfail status. The ID is the final function containing the user-defined test code. Since ct_add_test and its section counterpart are always called before the test function is defined, the function ${test_id} will not be a valid function until later in the execution. Thus, the type of test_id is defined here as desc.

The friendly_name is the user-defined name passed as the NAME argument to ct_add_test and ct_add_section. This name is both a user-identifiable string denoting the unit, and a pointer to the test_id

Parameters:

test_id (str) – The autogenerated unique ID for the unit, typed as str since it may or may not be defined as a function.
friendly_name (str) – The name given to the test or section by the user
expect_fail (bool) – Whether this unit is expected to fail.

Methods

append_child(key, child)

Add a new subsection to this unit. The key must point to the ID of the subsection and the value must be a dereferenced pointer pointing to the subsection. We take a function pointer for the key because the ID is used to define the section’s function.

Parameters:

key (desc) – Pointer to the ID of the subsection
child (CTExecutionUnit) – Reference to the new subsection.

get_parent_list(ret)

Construct the list of all parents of this unit from the root down to the immediate parent of this unit. The returned list contains pointers to each of the parents, ordered with the root as the last element.

Parameters:: ret (list*) – A return variable that will be set to the constructed list.

to_string(ret)

Get a human-readable representation of this unit.

Parameters:: ret (desc*) –

execute(): Executes the test or section that this unit represents. This function handles printing the pass/failure state as well as executing subsections. However, if this unit has already been executed, this function does nothing.

exec_sections(): Executes all subsections of this unit. If this unit has no subsections, this function does nothing.

print_pass_or_fail(): Determines whether the unit passed or failed and prints it, obeying the section depth, print length, and whether colors are enabled.

is_in_expect_fail_tgt(ret)

Determines whether the unit has a parent that is the target of the EXPECTFAIL invocation. If true and if in the subprocess, then cmake_test/add_section.add_section will create the unit even if no name is set, since it was only discovered in the subprocess.

Parameters:: ret (bool*) –

Attributes

test_id: Stores the unique ID of the unit. This value is autogenerated and is used to name the function this unit is linked to.

friendly_name: The “friendly name” of the execution unit. This is equivalent to the NAME parameter when calling ct_add_test() or ct_add_section(). Dereferencing the value of this field will yield the ID of this unit while in the scope of the unit.

test_file: The full path that points to the file containing this unit’s declaration. This value is propagated down from the root test to all sections and subsections.

expect_fail: A boolean describing whether this unit is intended to fail or not. Directly related to the parameter of the same name in ct_add_test() and ct_add_section().

parent: A reference pointing to the parent execution unit of this unit. This will be empty for the root test and filled for all subsections.

children: A map between IDs and references to unit instances used to represent the subsections of this unit.

print_length = "${CT_PRINT_LENGTH}": The length to use for printing in the context of this unit and any subsections that do not override it. This value can be set by the parameter of the same name in ct_add_test() and ct_add_section(). It can also be set via an overriding cache variable.

print_length_forced = FALSE: Describes whether the print length was forced via the call to ct_add_test() or ct_add_section() that constructed this unit.

execute_sections = FALSE: A boolean describing whether or not this unit should loop over and execute all of its subsections.

section_names_to_ids: A map linking section friendly names to Ids so the id isn’t lost between the first and second invocation passes.

exceptions: A list containing messages representing any exceptions that occurred during the execution of this unit.

has_executed = FALSE: Whether this unit has been executed already or not. Useful for determining whether to re-execute after a failed test is detected.

has_printed = FALSE: Whether the pass/fail status of this unit has been printed yet. This ensures that parent units of a failed unit are not printed multiple times.

section_depth = 0: Stores how many sections deep this execution unit is. This is used to determine how many tabs to place in front of the pass/fail print line.

debug_mode = FALSE: The value CMAKEPP_LANG_DEBUG_MODE should be set to while running this unit, i.e. what the test code itself will see. Should only be propagated from the test itself.