dune_add_test¶

Adds a test to the Dune testing suite!

dune_add_test(
    [NAME name]
    [SOURCES source1 [source2 ...]]
    [TARGET target]
    [COMPILE_DEFINITIONS def1 [def2 ...]]
    [COMPILE_FLAGS flag1 [flag2 ...]]
    [LINK_LIBRARIES lib1 [lib2 ...]]
    [EXPECT_COMPILE_FAIL]
    [EXPECT_FAIL]
    [CMD_ARGS arg1 [arg2 ...]]
    [MPI_RANKS ranks1 [ranks2 ...]]
    [CMAKE_GUARD condition1 [condition2 ...]]
    [COMMAND cmd1 [cmd2 ...]]
    [COMPILE_ONLY]
    [TIMEOUT timeout]
    [LABELS label1 [label2 ...]]
)

NAME

The name of the test that should be added. If an executable is also added (by specifying SOURCES), the executable is also named accordingly. If omitted, the name will be deduced from the (single) sources parameter or from the given target. Note that this requires you to take care, that you only use a target or source file for but one such test.

SOURCES

The source files that this test depends on. These are the sources that will be passed to add_executable.

You must specify either SOURCES or TARGET.

TARGET

An executable target which should be used for the test. Use this option over the SOURCES parameter if you want to reuse already added targets.

You must specify either SOURCES or TARGET.

COMPILE_DEFINITIONS

A set of compile definitions to add to the target. Only definitions beyond the application of add_dune_all_flags have to be stated. This is only used, if dune_add_test adds the executable itself.

COMPILE_FLAGS

A set of non-definition compile flags to add to the target. Only flags beyond the application of add_dune_all_flags have to be stated. This is only used, if dune_add_test adds the executable itself.

LINK_LIBRARIES

A list of libraries to link the target to. Only libraries beyond the application of add_dune_all_flags have to be stated. This is only used, if dune_add_test adds the executable itself.

EXPECT_COMPILE_FAIL

If given, the test is expected to not compile successfully!

EXPECT_FAIL

If given, this test is expected to compile, but fail to run.

CMD_ARGS

Command line arguments that should be passed to this test.

MPI_RANKS

The numbers of cores that this test should be executed with. Note that one test (in the ctest sense) is created for each number given here. Any number exceeding the user-specified processor maximum DUNE_MAX_TEST_CORES will be ignored. Tests with a processor number n higher than one will have the suffix -mpi-n appended to their name. You need to specify the TIMEOUT option when specifying the MPI_RANKS option.

CMAKE_GUARD

A number of conditions that CMake should evaluate before adding this test. If one of the conditions fails, the test should be shown as skipped in the test summary. Use this feature instead of guarding the call to dune_add_test with an if clause.

The passed condition can be a complex expression like ( A OR B ) AND ( C OR D ). Mind the spaces around the parentheses.

Example: Write CMAKE_GUARD dune-foo_FOUND if you want your test to only build and run when the dune-foo module is present.

COMMAND

You may specify the COMMAND option to give the exact command line to be executed when running the test. This defaults to the name of the executable added by dune_add_test for this test. Note that if you specify both CMD_ARGS and COMMAND, the given CMD_ARGS will be put behind your COMMAND. If you use this in combination with the MPI_RANKS parameter, the call to mpi will still be wrapped around the given commands.

COMPILE_ONLY

Set if the given test should only be compiled during make build_tests, but not run during make test. This is useful if you compile the same executable twice, but with different compile flags, where you want to assure that it compiles with both sets of flags, but you already know they will produce the same result.

TIMEOUT

If set, the test will time out after the given number of seconds. This supersedes any timeout setting in ctest (see cmake –help-property TIMEOUT). If you specify the MPI_RANKS option, you need to specify a TIMEOUT.

LABELS

A list of labels to add to the test. This has two effects: it sets the LABELS property on the test so ctest -L ${label_regex} can be used to run all tests with certain labels. It also adds any targets created as dependencies to a custom target, so you can build all tests with a particular label by doing make build_${label}_tests without having to build all the other tests as well.

The build_${label}_tests targets are created on-demand the first time a test with that label is added. In some situations it can depend on the values of cmake cache variables whether a test is added, and then it can happen that the build_${target}_tests target exists only sometimes. If your workflow relies on the existance of these targets, even if building them just returns successfully without doing anything, you can ensure they exist by calling dune_declare_test_label unconditionally. The label quick is always predeclared in this way.

The label names must be non-empty, and must only contain alphanumeric characters other than - or _. This restriction is in place to make it easy to construct regular expressions from the label names for ctest -L ${label_regex}.

This function defines the Dune way of adding a test to the testing suite. You may either add the executable yourself through add_executable and pass it to the TARGET option, or you may rely on dune_add_test to do so.