###################
cmake_test/add_test
###################

.. module:: cmake_test/add_test


.. function:: ct_add_test(**kwargs)


   .. note:: This is a macro, and so does not introduce a new scope.

   Defines a unit test for the CMakeTest framework.
   
   Unit testing in CMakeTest works by `include()`ing each unit test, determining which ones
   need to be ran, and then executing them sequentially in-process. This macro defines which functions
   are to be interpretted as actual unit tests.
   
   A variable named :code:`CMAKETEST_TEST` will be set in the
   calling scope that holds the test function ID. Use this variable
   to define the CMake function holding the section code. Ex:
   
   .. code-block:: cmake
   
      ct_add_test(NAME [=[Any test name here]=])
      function(${CMAKETEST_TEST})
          message(STATUS "This code will run in a test")
      endfunction()
   
   
   Additionally, the NAME parameter will be populated as by set() with the
   generated section function name. This is for backwards-compatibility
   purposes. Ex:
   
   .. code-block:: cmake
   
      ct_add_test(NAME this_test)
      function(${this_test})
          message(STATUS "This code will run in a test")
      endfunction()
   
   This behavior is considered deprecated, use the first form
   for new tests.
   
   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.
   
   
   **Keyword Arguments**
   
   :keyword NAME: Required argument specifying the name variable of the section.
                  Will set a variable with specified name containing the generated function ID to use.
   :type NAME: pointer
   :keyword EXPECTFAIL: 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.
   :type EXPECTFAIL: option
   :keyword PRINT_LENGTH: Optional argument specifying the desired print length of pass/fail output lines.
   :type PRINT_LENGTH: int