From bc524d70253a4ab2fe40c3ca3e5666e267c0a4d1 Mon Sep 17 00:00:00 2001 From: Lexi Winter Date: Sun, 29 Jun 2025 19:25:29 +0100 Subject: import catch2 3.8.1 --- docs/faq.md | 113 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 113 insertions(+) create mode 100644 docs/faq.md (limited to 'docs/faq.md') diff --git a/docs/faq.md b/docs/faq.md new file mode 100644 index 0000000..80923d2 --- /dev/null +++ b/docs/faq.md @@ -0,0 +1,113 @@ + +# Frequently Asked Questions (FAQ) + +**Contents**
+[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)
+[How do I clean up global state between running different tests?](#how-do-i-clean-up-global-state-between-running-different-tests)
+[Why cannot I derive from the built-in reporters?](#why-cannot-i-derive-from-the-built-in-reporters)
+[What is Catch2's ABI stability policy?](#what-is-catch2s-abi-stability-policy)
+[What is Catch2's API stability policy?](#what-is-catch2s-api-stability-policy)
+[Does Catch2 support running tests in parallel?](#does-catch2-support-running-tests-in-parallel)
+[Can I compile Catch2 into a dynamic library?](#can-i-compile-catch2-into-a-dynamic-library)
+[What repeatability guarantees does Catch2 provide?](#what-repeatability-guarantees-does-catch2-provide)
+[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)
+ + +## How do I run global setup/teardown only if tests will be run? + +Write a custom [event listener](event-listeners.md#top) and place the +global setup/teardown code into the `testRun*` events. + + +## How do I clean up global state between running different tests? + +Write a custom [event listener](event-listeners.md#top) and place the +cleanup code into either `testCase*` or `testCasePartial*` events, +depending on how often the cleanup needs to happen. + + +## Why cannot I derive from the built-in reporters? + +They are not made to be overridden, in that we do not attempt to maintain +a consistent internal state if a member function is overridden, and by +forbidding users from using them as a base class, we can refactor them +as needed later. + + +## What is Catch2's ABI stability policy? + +Catch2 provides no ABI stability guarantees whatsoever. Catch2 provides +rich C++ interface, and trying to freeze its ABI would take a lot of +pointless work. + +Catch2 is not designed to be distributed as dynamic library, and you +should really be able to compile everything with the same compiler binary. + + +## What is Catch2's API stability policy? + +Catch2 follows [semver](https://semver.org/) to the best of our ability. +This means that we will not knowingly make backwards-incompatible changes +without incrementing the major version number. + + +## Does Catch2 support running tests in parallel? + +Not natively, no. We see running tests in parallel as the job of an +external test runner, that can also run them in separate processes, +support test execution timeouts and so on. + +However, Catch2 provides some tools that make the job of external test +runners easier. [See the relevant section in our page on best +practices](usage-tips.md#parallel-tests). + + +## Can I compile Catch2 into a dynamic library? + +Yes, Catch2 supports the [standard CMake `BUILD_SHARED_LIBS` +option](https://cmake.org/cmake/help/latest/variable/BUILD_SHARED_LIBS.html). +However, the dynamic library support is provided as-is. Catch2 does not +provide API export annotations, and so you can only use it as a dynamic +library on platforms that default to public visibility, or with tooling +support to force export Catch2's API. + + +## What repeatability guarantees does Catch2 provide? + +There are two places where it is meaningful to talk about Catch2's +repeatability guarantees without taking into account user-provided +code. First one is in the test case shuffling, and the second one is +the output from random generators. + +Test case shuffling is repeatable across different platforms since v2.12.0, +and it is also generally repeatable across versions, but we might break +it from time to time. E.g. we broke repeatability with previous versions +in v2.13.4 so that test cases with similar names are shuffled better. + +Since Catch2 3.5.0 the random generators use custom distributions, +that should be repeatable across different platforms, with few caveats. +For details see the section on random generators in the [Generator +documentation](generators.md#random-number-generators-details). + +Before this version, random generators relied on distributions from +platform's stdlib. We thus can provide no extra guarantee on top of the +ones given by your platform. **Important: ``'s distributions +are not specified to be repeatable across different platforms.** + + +## My build cannot find `catch2/catch_user_config.hpp`, how can I fix it? + +`catch2/catch_user_config.hpp` is a generated header that contains user +compile time configuration. It is generated by CMake/Meson/Bazel during +build. If you are not using either of these, your three options are to + +1) Build Catch2 separately using build tool that will generate the header +2) Use the amalgamated files to build Catch2 +3) Use CMake to configure a build. This will generate the header and you + can copy it into your own checkout of Catch2. + + + +--- + +[Home](Readme.md#top) -- cgit v1.2.3