1  <a id="top"></a>
  2  # Frequently Asked Questions (FAQ)
  3  
  4  **Contents**<br>
  5  [How do I run global setup/teardown only if tests will be run?](#how-do-i-run-global-setupteardown-only-if-tests-will-be-run)<br>
  6  [How do I clean up global state between running different tests?](#how-do-i-clean-up-global-state-between-running-different-tests)<br>
  7  [Why cannot I derive from the built-in reporters?](#why-cannot-i-derive-from-the-built-in-reporters)<br>
  8  [What is Catch2's ABI stability policy?](#what-is-catch2s-abi-stability-policy)<br>
  9  [What is Catch2's API stability policy?](#what-is-catch2s-api-stability-policy)<br>
 10  [Does Catch2 support running tests in parallel?](#does-catch2-support-running-tests-in-parallel)<br>
 11  [Can I compile Catch2 into a dynamic library?](#can-i-compile-catch2-into-a-dynamic-library)<br>
 12  [What repeatability guarantees does Catch2 provide?](#what-repeatability-guarantees-does-catch2-provide)<br>
 13  [My build cannot find `catch2/catch_user_config.hpp`, how can I fix it?](#my-build-cannot-find-catch2catch_user_confighpp-how-can-i-fix-it)<br>
 14  
 15  
 16  ## How do I run global setup/teardown only if tests will be run?
 17  
 18  Write a custom [event listener](event-listeners.md#top) and place the
 19  global setup/teardown code into the `testRun*` events.
 20  
 21  
 22  ## How do I clean up global state between running different tests?
 23  
 24  Write a custom [event listener](event-listeners.md#top) and place the
 25  cleanup code into either `testCase*` or `testCasePartial*` events,
 26  depending on how often the cleanup needs to happen.
 27  
 28  
 29  ## Why cannot I derive from the built-in reporters?
 30  
 31  They are not made to be overridden, in that we do not attempt to maintain
 32  a consistent internal state if a member function is overridden, and by
 33  forbidding users from using them as a base class, we can refactor them
 34  as needed later.
 35  
 36  
 37  ## What is Catch2's ABI stability policy?
 38  
 39  Catch2 provides no ABI stability guarantees whatsoever. Catch2 provides
 40  rich C++ interface, and trying to freeze its ABI would take a lot of
 41  pointless work.
 42  
 43  Catch2 is not designed to be distributed as dynamic library, and you
 44  should really be able to compile everything with the same compiler binary.
 45  
 46  
 47  ## What is Catch2's API stability policy?
 48  
 49  Catch2 follows [semver](https://semver.org/) to the best of our ability.
 50  This means that we will not knowingly make backwards-incompatible changes
 51  without incrementing the major version number.
 52  
 53  
 54  ## Does Catch2 support running tests in parallel?
 55  
 56  Not natively, no. We see running tests in parallel as the job of an
 57  external test runner, that can also run them in separate processes,
 58  support test execution timeouts and so on.
 59  
 60  However, Catch2 provides some tools that make the job of external test
 61  runners easier. [See the relevant section in our page on best
 62  practices](usage-tips.md#parallel-tests).
 63  
 64  
 65  ## Can I compile Catch2 into a dynamic library?
 66  
 67  Yes, Catch2 supports the [standard CMake `BUILD_SHARED_LIBS`
 68  option](https://cmake.org/cmake/help/latest/variable/BUILD_SHARED_LIBS.html).
 69  However, the dynamic library support is provided as-is. Catch2 does not
 70  provide API export annotations, and so you can only use it as a dynamic
 71  library on platforms that default to public visibility, or with tooling
 72  support to force export Catch2's API.
 73  
 74  
 75  ## What repeatability guarantees does Catch2 provide?
 76  
 77  There are two places where it is meaningful to talk about Catch2's
 78  repeatability guarantees without taking into account user-provided
 79  code. First one is in the test case shuffling, and the second one is
 80  the output from random generators.
 81  
 82  Test case shuffling is repeatable across different platforms since v2.12.0,
 83  and it is also generally repeatable across versions, but we might break
 84  it from time to time. E.g. we broke repeatability with previous versions
 85  in v2.13.4 so that test cases with similar names are shuffled better.
 86  
 87  Since Catch2 3.5.0 the random generators use custom distributions,
 88  that should be repeatable across different platforms, with few caveats.
 89  For details see the section on random generators in the [Generator
 90  documentation](generators.md#random-number-generators-details).
 91  
 92  Before this version, random generators relied on distributions from
 93  platform's stdlib. We thus can provide no extra guarantee on top of the
 94  ones given by your platform. **Important: `<random>`'s distributions
 95  are not specified to be repeatable across different platforms.**
 96  
 97  
 98  ## My build cannot find `catch2/catch_user_config.hpp`, how can I fix it?
 99  
100  `catch2/catch_user_config.hpp` is a generated header that contains user
101  compile time configuration. It is generated by CMake/Meson/Bazel during
102  build. If you are not using either of these, your three options are to
103  
104  1) Build Catch2 separately using build tool that will generate the header
105  2) Use the amalgamated files to build Catch2
106  3) Use CMake to configure a build. This will generate the header and you
107     can copy it into your own checkout of Catch2.
108  
109  
110  
111  ---
112  
113  [Home](Readme.md#top)