1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
|
<a id="top"></a>
# Supplying main() yourself
**Contents**<br>
[Run the tests from your own main](#run-the-tests-from-your-own-main)<br>
[Options of your own](#options-of-your-own)<br>
[Version detection](#version-detection)<br>
The easiest way to use Catch3 is its own `main`: link against
`Catch3::Catch3WithMain` (the [CMake target](cmake-integration.md#cmake-targets))
or the `catch3-with-main` pkg-config file. To write your own `main`, link
against `Catch3::Catch3` and hand the command line to the
[Catch3 runner](progmasoft-runner.md#top).
The runner starts the same binary again for its worker processes, with the
same `main`. Whatever `main` does before and after `run`, it also does in
every worker. That is usually what global set-up needs; when only the
runner's own process should do something, check whether the environment
variable `CATCH3_WORKER` is set, which it is only in workers.
## Run the tests from your own main
```cpp
#include <Progmasoft/Catch3/Session.hpp>
int main( int argc, char* argv[] ) {
// your setup ...
int result = Catch::Session().run( argc, argv );
// your clean-up...
return result;
}
```
`run` returns the [exit code](progmasoft-runner.md#exit-codes). A binary that
needs no `Catch::Session` may call `Progmasoft::Catch3::RunTests`, from
`<Progmasoft/Catch3/Runner.hpp>`, with the arguments as a
`std::vector<std::string>`.
_If you only want to run some set up before tests are run, it might be
simpler to use [event listeners](event-listeners.md#top) instead._
## Options of your own
Catch2's `Session::cli()` and `Session::configData()` went with Catch2's
runner. Take your own options out of the command line before passing the
rest on; the runner treats an option it does not know as an error.
```cpp
int main( int argc, char* argv[] ) {
int height = 0;
std::vector<char const*> arguments;
for ( int i = 0; i < argc; ++i ) {
std::string const argument = argv[i];
if ( argument.rfind( "--height=", 0 ) == 0 ) {
height = std::atoi( argument.c_str() + 9 );
} else {
arguments.push_back( argv[i] );
}
}
return Catch::Session().run( static_cast<int>( arguments.size() ),
arguments.data() );
}
```
Workers are started with the runner's own options. A value the tests need
in every worker belongs in the environment, which workers inherit.
## Version detection
Catch2 provides a triplet of macros providing the header's version,
* `CATCH_VERSION_MAJOR`
* `CATCH_VERSION_MINOR`
* `CATCH_VERSION_PATCH`
these macros expand into a single number, that corresponds to the appropriate
part of the version. As an example, given single header version v2.3.4,
the macros would expand into `2`, `3`, and `4` respectively. The version of
the Catch3 runner is `Progmasoft::Catch3::kVersion` in
`<Progmasoft/Catch3/Version.hpp>`, and `--version` prints it.
---
[Home](Readme.md#top)
|