# FindCxxTest

Finds CxxTest, a C++ unit testing framework suite, and provides a helper command to create test runners and integrate them with CTest.

## Result Variables

This module defines the following variables:

`CXXTEST_FOUND`

  Boolean indicating whether the CxxTest framework is found.

`CXXTEST_INCLUDE_DIRS`

  Include directories containing headers needed to use CxxTest.

`CXXTEST_TESTGEN_EXECUTABLE`

  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`

  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).

## 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:

cxxtest_add_test

  Creates a CxxTest runner and adds it to the CTest testing suite:

      cxxtest_add_test(<test-name> <gen-source-file> <input-files-to-testgen>...)

  Parameters:

  `<test-name>`

    The name of the test executable target to be created and registered as a test in the CTest suite.

  `<gen-source-file>`

    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 (`CMAKE_CURRENT_BINARY_DIR`).

  `<input-files-to-testgen>`

    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.

## Deprecated Variables

The following variables are deprecated and provided for backward compatibility:

`CXXTEST_USE_PYTHON`

  Deprecated since version 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 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.

`CMakeLists.txt`

    find_package(CxxTest)

    # 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()

    # 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()

`foo_test.h`

    #include <cxxtest/TestSuite.h>

    class MyTestSuite : public CxxTest::TestSuite
    {
    public:
      void testAddition(void)
      {
        TS_ASSERT(1 + 1 > 1);
        TS_ASSERT_EQUALS(1 + 1, 2);
      }
    };