1<a id="top"></a>
2# CI and other odd pieces
3
4**Contents**<br>
5[Continuous Integration systems](#continuous-integration-systems)<br>
6[Other reporters](#other-reporters)<br>
7[Low-level tools](#low-level-tools)<br>
8[CMake](#cmake)<br>
9
10This page talks about how Catch integrates with Continuous Integration
11Build 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.
12
13## Continuous Integration systems
14
15Probably 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).
16
17Two 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.
18
19### XML Reporter
20```-r xml```
21
22The XML Reporter writes in an XML format that is specific to Catch.
23
24The 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.
25
26The 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.
27
28### JUnit Reporter
29```-r junit```
30
31The JUnit Reporter writes in an XML format that mimics the JUnit ANT schema.
32
33The 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.
34
35The 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.
36
37## Other reporters
38Other reporters are not part of the single-header distribution and need
39to be downloaded and included separately. All reporters are stored in
40`single_include` directory in the git repository, and are named
41`catch_reporter_*.hpp`. For example, to use the TeamCity reporter you
42need to download `single_include/catch_reporter_teamcity.hpp` and include
43it after Catch itself.
44
45```cpp
46#define CATCH_CONFIG_MAIN
47#include "catch.hpp"
48#include "catch_reporter_teamcity.hpp"
49```
50
51### TeamCity Reporter
52```-r teamcity```
53
54The TeamCity Reporter writes TeamCity service messages to stdout. In order to be able to use this reporter an additional header must also be included.
55
56Being 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).
57
58### Automake Reporter
59```-r automake```
60
61The 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`.
62
63### TAP (Test Anything Protocol) Reporter
64```-r tap```
65
66Because 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.
67
68## Low-level tools
69
70### Precompiled headers (PCHs)
71
72Catch offers prototypal support for being included in precompiled headers, but because of its single-header nature it does need some actions by the user:
73* The precompiled header needs to define `CATCH_CONFIG_ALL_PARTS`
74* The implementation file needs to
75  * undefine `TWOBLUECUBES_SINGLE_INCLUDE_CATCH_HPP_INCLUDED`
76  * define `CATCH_CONFIG_IMPL_ONLY`
77  * define `CATCH_CONFIG_MAIN` or `CATCH_CONFIG_RUNNER`
78  * include "catch.hpp" again
79
80
81### CodeCoverage module (GCOV, LCOV...)
82
83If 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
84
85
86### pkg-config
87
88Catch2 provides a rudimentary pkg-config integration, by registering itself
89under the name `catch2`. This means that after Catch2 is installed, you
90can use `pkg-config` to get its include path: `pkg-config --cflags catch2`.
91
92### gdb and lldb scripts
93
94Catch2's `contrib` folder also contains two simple debugger scripts,
95`gdbinit` for `gdb` and `lldbinit` for `lldb`. If loaded into their
96respective debugger, these will tell it to step over Catch2's internals
97when stepping through code.
98
99
100## CMake
101
102[As it has been getting kinda long, the documentation of Catch2's
103integration with CMake has been moved to its own page.](cmake-integration.md#top)
104
105
106---
107
108[Home](Readme.md#top)
109