diff --git a/Modules/FindCxxTest.cmake b/Modules/FindCxxTest.cmake index a0d0e6e496..37f1e7adc6 100644 --- a/Modules/FindCxxTest.cmake +++ b/Modules/FindCxxTest.cmake @@ -5,123 +5,163 @@ FindCxxTest ----------- -Find CxxTest unit testing framework. - -Find the `CxxTest`_ suite and declare a helper macro for creating -unit tests and integrating them with CTest. +Finds `CxxTest`_, a C++ unit testing framework suite, and provides a helper +command to create test runners and integrate them with CTest. .. _`CxxTest`: https://github.com/CxxTest/cxxtest -Input Variables -^^^^^^^^^^^^^^^ - -``CXXTEST_USE_PYTHON`` - .. deprecated:: 1.3 - - Only used in the case both Python & Perl - are detected on the system to control - which CxxTest code generator is used. - Valid only for CxxTest version 3. - - In older versions of this Find Module, - this variable controlled if the Python test - generator was used instead of the Perl one, - regardless of which scripting language the - user had installed. - -``CXXTEST_TESTGEN_ARGS`` - .. versionadded:: 2.8.3 - - Specify a list of options to pass to the CxxTest code - generator. If not defined, ``--error-printer`` is passed. - Result Variables ^^^^^^^^^^^^^^^^ +This module defines the following variables: + ``CXXTEST_FOUND`` - True if the CxxTest framework was found + Boolean indicating whether the CxxTest framework is found. ``CXXTEST_INCLUDE_DIRS`` - Where to find the CxxTest include directory - -``CXXTEST_PERL_TESTGEN_EXECUTABLE`` - The perl-based test generator - -``CXXTEST_PYTHON_TESTGEN_EXECUTABLE`` - The python-based test generator + Include directories containing headers needed to use CxxTest. ``CXXTEST_TESTGEN_EXECUTABLE`` - .. versionadded:: 2.8.3 - - The test generator that is actually used (chosen using user preferences - and interpreters found in the system) + The path to the found CxxTest test generator script (Perl- or Python-based), + selected based on the found interpreter or user-specified preference. ``CXXTEST_TESTGEN_INTERPRETER`` - .. versionadded:: 2.8.3 + The path to the found Perl or Python interpreter used to run the test + generator script, if needed (e.g., on platforms where script shebang lines are + not supported). - The full path to the Perl or Python executable on the system, on - platforms where the script cannot be executed using its shebang line. - - -Module Commands +Cache Variables ^^^^^^^^^^^^^^^ +The following cache variables may also be set: + +``CXXTEST_PERL_TESTGEN_EXECUTABLE`` + The path to the Perl-based CxxTest test generator script. + +``CXXTEST_PYTHON_TESTGEN_EXECUTABLE`` + The path to the Python-based CxxTest test generator script. + +Hints +^^^^^ + +This module accepts the following variables before calling +``find_package(CxxTest)``: + +``CXXTEST_TESTGEN_ARGS`` + This variable can be set to specify a semicolon-separated list of command-line + options to pass to the CxxTest code generator. If not set, the default value + is ``--error-printer``. + +Commands +^^^^^^^^ + +This module provides the following command if CxxTest is found: + .. command:: cxxtest_add_test - Create a CxxTest runner and adds it to the CTest testing suite: + Creates a CxxTest runner and adds it to the CTest testing suite: .. code-block:: cmake - CXXTEST_ADD_TEST( - ...) + cxxtest_add_test( ...) Parameters: - ``test_name`` - The name of the test + ```` + The name of the test executable target to be created and registered as a + test in the CTest suite. - ``gen_source_file`` - The generated source filename to be generated by CxxTest + ```` + The name of the source file to be generated by the CxxTest code generator. + This must be a relative path. It is interpreted relative to the + current binary directory (:variable:`CMAKE_CURRENT_BINARY_DIR`). - ``input_files_to_testgen`` - The list of header files containing the CxxTest::TestSuite's - to be included in this runner + ```` + A list of header files containing test suite classes derived from the C++ + class ``CxxTest::TestSuite``, to be included in the test runner. These must + be given as absolute paths. -Example Usage -^^^^^^^^^^^^^ +Deprecated Variables +^^^^^^^^^^^^^^^^^^^^ -The following example, if CxxTest is found, will: +The following variables are deprecated and provided for backward compatibility: -* Invoke the testgen executable to autogenerate foo_test.cc in the - binary tree from "foo_test.h" in the current source directory. -* Create an executable and test called unittest_foo. +``CXXTEST_USE_PYTHON`` + .. deprecated:: 2.8.3 + In earlier versions of CMake, this hint variable was used to force the use + of the Python-based test generator instead of the Perl one, regardless of + which scripting language was installed. It is now only considered when both + Perl and Python interpreters are found. + + A boolean hint variable that, when set to true, prefers the Python code + generator over the Perl one if both interpreters are found. This variable is + only relevant when using CxxTest version 3. + +Examples +^^^^^^^^ + +The following example demonstrates how CxxTest can be used in CMake with this +module. If CxxTest is found: + +* Additional interface :ref:`imported target ` is created + manually in the project to encapsulate the CxxTest usage requirements and + link it to specified tests. Such target is useful, for example, when dealing + with multiple tests. + +* Test generator is invoked to create ``foo_test.cc`` in the current binary + directory from the input header ``foo_test.h`` located in the current source + directory. + +* An executable named ``unit_test_foo`` is built and registered as a test in + CTest. .. code-block:: cmake + :caption: ``CMakeLists.txt`` find_package(CxxTest) - if(CXXTEST_FOUND) - include_directories(${CXXTEST_INCLUDE_DIR}) - enable_testing() - CXXTEST_ADD_TEST(unittest_foo foo_test.cc - ${CMAKE_CURRENT_SOURCE_DIR}/foo_test.h) - target_link_libraries(unittest_foo foo) # as needed + + # Create interface imported target: + if(CXXTEST_FOUND AND NOT TARGET CxxTest::CxxTest) + add_library(CxxTest::CxxTest INTERFACE IMPORTED) + set_target_properties( + CxxTest::CxxTest + PROPERTIES INTERFACE_INCLUDE_DIRECTORIES "${CXXTEST_INCLUDE_DIRS}" + ) endif() -``foo_test.h`` contains: + # Add test: + if(CXXTEST_FOUND) + enable_testing() + + cxxtest_add_test( + unit_test_foo + foo_test.cc + ${CMAKE_CURRENT_SOURCE_DIR}/foo_test.h + ) + + target_link_libraries( + unit_test_foo + PRIVATE + CxxTest::CxxTest + # Link any project targets as needed, if test depends on them: + foo + ) + endif() .. code-block:: c++ + :caption: ``foo_test.h`` #include + class MyTestSuite : public CxxTest::TestSuite { public: - void testAddition( void ) - { - TS_ASSERT( 1 + 1 > 1 ); - TS_ASSERT_EQUALS( 1 + 1, 2 ); - } + void testAddition(void) + { + TS_ASSERT(1 + 1 > 1); + TS_ASSERT_EQUALS(1 + 1, 2); + } }; - #]=======================================================================] # Version 1.4 (11/18/10) (CMake 2.8.4) @@ -150,7 +190,7 @@ The following example, if CxxTest is found, will: # Cleaned up and added more documentation #============================================================= -# CXXTEST_ADD_TEST (public macro) +# cxxtest_add_test (public macro) #============================================================= macro(CXXTEST_ADD_TEST _cxxtest_testname _cxxtest_outfname) set(_cxxtest_real_outfname ${CMAKE_CURRENT_BINARY_DIR}/${_cxxtest_outfname})