docs/build-systems.md

   1 # CI and build system integration
   2
   3 Build Systems may refer to low-level tools, like CMake, or larger systems that run on servers, like Jenkins or TeamCity. This page will talk about both.
   4
   5 # Continuous Integration systems
   6
   7 Probably the most important aspect to using Catch with a build server is the use of different reporters. Catch comes bundled with three reporters that should cover the majority of build servers out there - although adding more for better integration with some is always a possibility (currently we also offer TeamCity, TAP and Automake reporters).
   8
   9 Two of these reporters are built in (XML and JUnit) and the third (TeamCity) is included as a separate header. It's possible that the other two may be split out in the future too - as that would make the core of Catch smaller for those that don't need them.
  10
  11 ## XML Reporter
  12 ```-r xml```
  13
  14 The XML Reporter writes in an XML format that is specific to Catch.
  15
  16 The advantage of this format is that it corresponds well to the way Catch works (especially the more unusual features, such as nested sections) and is a fully streaming format - that is it writes output as it goes, without having to store up all its results before it can start writing.
  17
  18 The disadvantage is that, being specific to Catch, no existing build servers understand the format natively. It can be used as input to an XSLT transformation that could convert it to, say, HTML - although this loses the streaming advantage, of course.
  19
  20 ## JUnit Reporter
  21 ```-r junit```
  22
  23 The JUnit Reporter writes in an XML format that mimics the JUnit ANT schema.
  24
  25 The advantage of this format is that the JUnit Ant schema is widely understood by most build servers and so can usually be consumed with no additional work.
  26
  27 The disadvantage is that this schema was designed to correspond to how JUnit works - and there is a significant mismatch with how Catch works. Additionally the format is not streamable (because opening elements hold counts of failed and passing tests as attributes) - so the whole test run must complete before it can be written.
  28
  29 ## Other reporters
  30 Other reporters are not part of the single-header distribution and need to be downloaded and included separately. All reporters are stored in `include/reporters` directory in the git repository, and are named `catch_reporter_*.hpp`. For example, to use the TeamCity reporter you need to download `include/reporters/catch_reporter_teamcity.hpp` and include it after Catch itself.
  31
  32 ```
  33 #define CATCH_CONFIG_MAIN
  34 #include "catch.hpp"
  35 #include "catch_reporter_teamcity.hpp"
  36 ```
  37
  38 ### TeamCity Reporter
  39 ```-r teamcity```
  40
  41 The TeamCity Reporter writes TeamCity service messages to stdout. In order to be able to use this reporter an additional header must also be included.
  42
  43 Being specific to TeamCity this is the best reporter to use with it - but it is completely unsuitable for any other purpose. It is a streaming format (it writes as it goes) - although test results don't appear in the TeamCity interface until the completion of a suite (usually the whole test run).
  44
  45 ### Automake Reporter
  46 ```-r automake```
  47
  48 The Automake Reporter writes out the [meta tags](https://www.gnu.org/software/automake/manual/html_node/Log-files-generation-and-test-results-recording.html#Log-files-generation-and-test-results-recording) expected by automake via `make check`.
  49
  50 ### TAP (Test Anything Protocol) Reporter
  51 ```-r tap```
  52
  53 Because of the incremental nature of Catch's test suites and ability to run specific tests, our implementation of TAP reporter writes out the number of tests in a suite last.
  54
  55 # Low-level tools
  56
  57 ## CMake
  58
  59 In general we recommend "vendoring" Catch's single-include releases inside your own repository. If you do this, the following example shows a minimal CMake project:
  60 ```CMake
  61 cmake_minimum_required(VERSION 3.0)
  62
  63 project(cmake_test)
  64
  65 # Prepare "Catch" library for other executables
  66 set(CATCH_INCLUDE_DIR ${CMAKE_CURRENT_SOURCE_DIR}/catch)
  67 add_library(Catch INTERFACE)
  68 target_include_directories(Catch INTERFACE ${CATCH_INCLUDE_DIR})
  69
  70 # Make test executable
  71 set(TEST_SOURCES ${CMAKE_CURRENT_SOURCE_DIR}/main.cpp)
  72 add_executable(tests ${TEST_SOURCES})
  73 target_link_libraries(tests Catch)
  74 ```
  75 Note that it assumes that the path to the Catch's header is `catch/catch.hpp` from the `CMakeLists.txt` file.
  76
  77
  78 You can also use the following CMake snippet to automatically fetch the entire Catch repository from github and configure it as an external project:
  79 ```CMake
  80 cmake_minimum_required(VERSION 2.8.8)
  81 project(catch_builder CXX)
  82 include(ExternalProject)
  83 find_package(Git REQUIRED)
  84
  85 ExternalProject_Add(
  86     catch
  87     PREFIX ${CMAKE_BINARY_DIR}/catch
  88     GIT_REPOSITORY https://github.com/philsquared/Catch.git
  89     TIMEOUT 10
  90     UPDATE_COMMAND ${GIT_EXECUTABLE} pull
  91     CONFIGURE_COMMAND ""
  92     BUILD_COMMAND ""
  93     INSTALL_COMMAND ""
  94     LOG_DOWNLOAD ON
  95    )
  96
  97 # Expose required variable (CATCH_INCLUDE_DIR) to parent scope
  98 ExternalProject_Get_Property(catch source_dir)
  99 set(CATCH_INCLUDE_DIR ${source_dir}/single_include CACHE INTERNAL "Path to include folder for Catch")
 100 ```
 101
 102 If you put it in, e.g., `${PROJECT_SRC_DIR}/${EXT_PROJECTS_DIR}/catch/`, you can use it in your project by adding the following to your root CMake file:
 103
 104 ```CMake
 105 # Includes Catch in the project:
 106 add_subdirectory(${EXT_PROJECTS_DIR}/catch)
 107 include_directories(${CATCH_INCLUDE_DIR} ${COMMON_INCLUDES})
 108 enable_testing(true)  # Enables unit-testing.
 109 ```
 110
 111 The advantage of this approach is that you can always automatically update Catch to the latest release. The disadvantage is that it means bringing in lot more than you need.
 112
 113
 114 ### Automatic test registration
 115 If you are also using ctest, `contrib/ParseAndAddCatchTests.cmake` is a CMake script that attempts to parse your test files and automatically register all test cases, using tags as labels. This means that these
 116 ```cpp
 117 TEST_CASE("Test1", "[unit]") {
 118     int a = 1;
 119     int b = 2;
 120     REQUIRE(a == b);
 121 }
 122
 123 TEST_CASE("Test2") {
 124     int a = 1;
 125     int b = 2;
 126     REQUIRE(a == b);
 127 }
 128
 129 TEST_CASE("Test3", "[a][b][c]") {
 130     int a = 1;
 131     int b = 2;
 132     REQUIRE(a == b);
 133 }
 134 ```
 135 would be registered as 3 tests, `Test1`, `Test2` and `Test3`, and ctest 4 labels would be created, `a`, `b`, `c` and `unit`.
 136
 137 ### CodeCoverage module (GCOV, LCOV...)
 138
 139 If you are using GCOV tool to get testing coverage of your code, and are not sure how to integrate it with CMake and Catch, there should be an external example over at https://github.com/fkromer/catch_cmake_coverage
 140
 141 ---
 142
 143 [Home](Readme.md)