.. _dune_add_test:

dune_add_test
=============

.. cmake_function:: dune_add_test

   .. cmake_brief::

      Adds a test to the Dune testing suite!

   .. cmake_param:: NAME
      :single:

      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.

   .. cmake_param:: SOURCES
      :multi:

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

      You *must* specify either :code:`SOURCES` or :code:`TARGET`.

   .. cmake_param:: TARGET
      :single:

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

      You *must* specify either :code:`SOURCES` or :code:`TARGET`.

   .. cmake_param:: COMPILE_DEFINITIONS
      :multi:
      :argname: def

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

   .. cmake_param:: COMPILE_FLAGS
      :multi:
      :argname: flag

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

   .. cmake_param:: LINK_LIBRARIES
      :multi:
      :argname: lib

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

   .. cmake_param:: EXPECT_COMPILE_FAIL
      :option:

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

   .. cmake_param:: EXPECT_FAIL
      :option:

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

   .. cmake_param:: CMD_ARGS
      :multi:
      :argname: arg

      Command line arguments that should be passed to this test.

   .. cmake_param:: MPI_RANKS
      :multi:
      :argname: 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
      :ref:`DUNE_MAX_TEST_CORES` will be ignored. Tests with a
      processor number :code:`n` higher than one will have the suffix
      :code:`-mpi-n` appended to their name. You need to specify the
      TIMEOUT option when specifying the MPI_RANKS option.

   .. cmake_param:: CMAKE_GUARD
      :multi:
      :argname: condition

      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 :code:`dune_add_test` with an :code:`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.

   .. cmake_param:: COMMAND
      :multi:
      :argname: cmd

      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.

   .. cmake_param:: COMPILE_ONLY
      :option:

      Set if the given test should only be compiled during :code:`make build_tests`,
      but not run during :code:`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.

   .. cmake_param:: TIMEOUT
      :single:

      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.

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

