docs/limitations.md

   1 # Known limitations
   2
   3 Catch has some known limitations, that we are not planning to change. Some of these are caused by our desire to support C++98 compilers, some of these are caused by our desire to keep Catch crossplatform, some exist because their priority is seen as low compared to the development effort they would need and some other yet are compiler/runtime bugs.
   4
   5 ## Features
   6 This section outlines some missing features, what is their status and their possible workarounds.
   7
   8 ### Thread safe assertions
   9 Because threading support in standard C++98 is limited (well, non-existent), assertion macros in Catch are not thread safe. This does not mean that you cannot use threads inside Catch's test, but that only single thread can interact with Catch's assertions and other macros.
  10
  11 This means that this is ok
  12 ```cpp
  13     std::vector<std::thread> threads;
  14     std::atomic<int> cnt{ 0 };
  15     for (int i = 0; i < 4; ++i) {
  16         threads.emplace_back([&]() {
  17             ++cnt; ++cnt; ++cnt; ++cnt;
  18         });
  19     }
  20     for (auto& t : threads) { t.join(); }
  21     REQUIRE(cnt == 16);
  22 ```
  23 because only one thread passes the `REQUIRE` macro and this is not
  24 ```cpp
  25     std::vector<std::thread> threads;
  26     std::atomic<int> cnt{ 0 };
  27     for (int i = 0; i < 4; ++i) {
  28         threads.emplace_back([&]() {
  29             ++cnt; ++cnt; ++cnt; ++cnt;
  30             CHECK(cnt == 16);
  31         });
  32     }
  33     for (auto& t : threads) { t.join(); }
  34     REQUIRE(cnt == 16);
  35 ```
  36
  37
  38 _This limitation is highly unlikely to be lifted before Catch 2 is released._
  39
  40 ### Process isolation in a test
  41 Catch does not support running tests in isolated (forked) processes. While this might in the future, the fact that Windows does not support forking and only allows full-on process creation and the desire to keep code as similar as possible across platforms, mean that this is likely to take significant development time, that is not currently available.
  42
  43 ### Running multiple tests in parallel
  44 Catch's test execution is strictly serial. If you find yourself with a test suite that takes too long to run and you want to make it parallel, there are 2 feasible solutions
  45  * You can split your tests into multiple binaries and then run these binaries in parallel.
  46  * You can have Catch list contained test cases and then run the same test binary multiple times in parallel, passing each instance list of test cases it should run.
  47
  48 Both of these solutions have their problems, but should let you wring parallelism out of your test suite.
  49
  50 ## 3rd party bugs
  51 This section outlines known bugs in 3rd party components (this means compilers, standard libraries, standard runtimes).
  52
  53 ### Visual Studio 2017 -- raw string literal in assert fails to compile
  54 There is a known bug in Visual Studio 2017 (VC 15), that causes compilation error when preprocessor attempts to stringize a raw string literal (`#` preprocessor is applied to it). This snippet is sufficient to trigger the compilation error:
  55 ```cpp
  56 #define CATCH_CONFIG_MAIN
  57 #include "catch.hpp"
  58
  59 TEST_CASE("test") {
  60     CHECK(std::string(R"("\)") == "\"\\");
  61 }
  62 ```
  63
  64 Catch provides a workaround, it is possible to disable stringification of original expressions by defining `CATCH_CONFIG_DISABLE_STRINGIFICATION`:
  65 ```cpp
  66 #define CATCH_CONFIG_FAST_COMPILE
  67 #define CATCH_CONFIG_DISABLE_STRINGIFICATION
  68 #include "catch.hpp"
  69
  70 TEST_CASE("test") {
  71     CHECK(std::string(R"("\)") == "\"\\");
  72 }
  73 ```
  74
  75 _Do note that this changes the output somewhat_
  76 ```
  77 catchwork\test1.cpp(6):
  78 PASSED:
  79   CHECK( Disabled by CATCH_CONFIG_DISABLE_STRINGIFICATION )
  80 with expansion:
  81   ""\" == ""\"
  82 ```
  83
  84
  85 ### Visual Studio 2013 -- do-while loop withing range based for fails to compile (C2059)
  86 There is a known bug in Visual Studio 2013 (VC 12), that causes compilation error if range based for is followed by an assertion macro, without enclosing the block in braces. This snippet is sufficient to trigger the error
  87 ```cpp
  88 #define CATCH_CONFIG_MAIN
  89 #include "catch.hpp"
  90
  91 TEST_CASE("Syntax error with VC12") {
  92     for ( auto x : { 1 , 2, 3 } )
  93         REQUIRE( x < 3.14 );
  94 }
  95 ```
  96 An easy workaround is possible, use braces:
  97 ```cpp
  98 #define CATCH_CONFIG_MAIN
  99 #include "catch.hpp"
 100
 101 TEST_CASE("No longer a syntax error with VC12") {
 102     for ( auto x : { 1 , 2, 3 } ) {
 103         REQUIRE( x < 3.14 );
 104     }
 105 }
 106 ```
 107
 108 ### Visual Studio 2003 -- Syntax error caused by improperly expanded `__LINE__` macro
 109 Older version of Visual Studio can have trouble compiling Catch, not expanding the `__LINE__` macro properly when recompiling the test binary. This is caused by Edit and Continue being on.
 110
 111 A workaround is to turn off Edit and Continue when compiling the test binary.
 112
 113 ### Clang/G++ -- skipping leaf sections after an exception
 114 Some versions of `libc++` and `libstdc++` (or their runtimes) have a bug with `std::uncaught_exception()` getting stuck returning `true` after rethrow, even if there are no active exceptions. One such case is this snippet, which skipped the sections "a" and "b", when compiled against `libcxxrt` from master
 115 ```cpp
 116 #define CATCH_CONFIG_MAIN
 117 #include <catch.hpp>
 118
 119 TEST_CASE("a") {
 120     CHECK_THROWS(throw 3);
 121 }
 122
 123 TEST_CASE("b") {
 124     int i = 0;
 125     SECTION("a") { i = 1; }
 126     SECTION("b") { i = 2; }
 127     CHECK(i > 0);
 128 }
 129 ```
 130
 131 If you are seeing a problem like this, i.e. a weird test paths that trigger only under Clang with `libc++`, or only under very specific version of `libstdc++`, it is very likely you are seeing this. The only known workaround is to use a fixed version of your standard library.