DuneTestMacros
---------------

Tools for integrating tests into the DUNE build system.

.. cmake:command:: dune_declare_test_label

  Declare labels for :cmake:command:`dune_add_test()`.

  .. code-block:: cmake

    dune_declare_test_label(LABELS <labels...>)

  ``LABELS``
    Names of labels to declare. Label names must be non-empty and may contain
    only alphanumeric characters plus ``-`` and ``_`` so they remain easy to
    use in ``ctest -L`` regular expressions.

  Labels are normally declared on demand by :cmake:command:`dune_add_test()`.
  Call this command explicitly if you want ``build_<label>_tests`` targets to
  exist even when no test with that label is added in the current configuration.
  The label ``quick`` is always predeclared.

.. cmake:command:: dune_add_test

  Add a test to the DUNE testing suite.

  .. code-block:: cmake

    dune_add_test(
      [NAME <name>]
      [SOURCES <sources...>]
      [TARGET <target>]
      [COMPILE_DEFINITIONS <def>...]
      [COMPILE_FLAGS <flag>...]
      [LINK_LIBRARIES <lib>...]
      [EXPECT_COMPILE_FAIL]
      [EXPECT_FAIL]
      [CMD_ARGS <arg>...]
      [MPI_RANKS <ranks>...]
      [CMAKE_GUARD <condition>...]
      [COMMAND <cmd>...]
      [COMPILE_ONLY]
      [TIMEOUT <seconds>]
      [WORKING_DIRECTORY <dir>]
      [LABELS <labels...>]
    )

  ``NAME``
    Name of the test. If omitted, the name is deduced from the single source
    file or the given target.

  ``SOURCES``
    Source files used to build the test executable. You must provide either
    ``SOURCES`` or ``TARGET``.

  ``TARGET``
    Existing executable target to use for the test. You must provide either
    ``SOURCES`` or ``TARGET``.

  ``COMPILE_DEFINITIONS``
    Extra compile definitions to add when :cmake:command:`dune_add_test()`
    creates the executable itself.

  ``COMPILE_FLAGS``
    Extra non-definition compile flags to add when
    :cmake:command:`dune_add_test()` creates the executable itself.

  ``LINK_LIBRARIES``
    Extra libraries to link when :cmake:command:`dune_add_test()` creates the
    executable itself.

  ``EXPECT_COMPILE_FAIL``
    Expect the test target to fail during compilation.

  ``EXPECT_FAIL``
    Expect the test to compile but fail at run time.

  ``CMD_ARGS``
    Additional command line arguments passed to the test command.

  ``MPI_RANKS``
    Numbers of MPI ranks with which the test should run. One ctest test is
    created for each rank count. Values larger than
    :cmake:variable:`DUNE_MAX_TEST_CORES` are ignored. When this option is
    used, ``TIMEOUT`` must also be specified.

  ``CMAKE_GUARD``
    Conditions evaluated by CMake before adding the test. Use this instead of
    guarding the call with a plain ``if()`` when you want the test summary to
    report the case as skipped.

  ``COMMAND``
    Exact command line to execute for the test. If ``CMD_ARGS`` is also given,
    those arguments are appended to the command.

  ``COMPILE_ONLY``
    Compile the test during ``make build_tests`` but do not run it during
    ``make test``.

  ``TIMEOUT``
    Timeout in seconds. This overrides the default ctest timeout for the test.

  ``WORKING_DIRECTORY``
    Working directory used when executing the test. By default this is the
    build directory corresponding to the current source directory.

  ``LABELS``
    Labels attached to the test. They also control creation of
    ``build_<label>_tests`` targets. Use :cmake:command:`dune_declare_test_label()`
    when you want such targets to exist unconditionally.

  You may either create the executable yourself with
  :cmake:command:`add_executable()` and pass it through ``TARGET``, or let
  :cmake:command:`dune_add_test()` create the executable from ``SOURCES``.

.. cmake:variable:: DUNE_MAX_TEST_CORES

  Upper bound for the number of processors a single test may use. The default
  is 2 when MPI is found and 1 otherwise.

.. cmake:variable:: DUNE_BUILD_TESTS_ON_MAKE_ALL

  If enabled, build all tests during ``make all``. Otherwise tests are built
  through the ``build_tests`` target. This option does not apply to immutable
  targets such as imported or aliased targets.

.. cmake:variable:: PYTHON_TEST

  Marker used by :cmake:command:`dune_python_add_test()` to identify python
  tests. It disables the check for the existence of the target file.