couchbase 4.2.2 → 4.2.4

package/deps/couchbase-cxx-client/third_party/catch2/docs/tostring.md

@@ -64,14 +64,14 @@ namespace Catch {
 By default all exceptions deriving from `std::exception` will be translated to strings by calling the `what()` method. For exception types that do not derive from `std::exception` - or if `what()` does not return a suitable string - use `CATCH_TRANSLATE_EXCEPTION`. This defines a function that takes your exception type, by reference, and returns a string. It can appear anywhere in the code - it doesn't have to be in the same translation unit. For example:
 
 ```cpp
-CATCH_TRANSLATE_EXCEPTION( MyType& ex ) {
+CATCH_TRANSLATE_EXCEPTION( MyType const& ex ) {
     return ex.message();
 }
 ```
 
 ## Enums
 
-> Introduced in Catch 2.8.0.
+> Introduced in Catch2 2.8.0.
 
 Enums that already have a `<<` overload for `std::ostream` will convert to strings as expected.
 If you only need to convert enums to strings for test reporting purposes you can provide a `StringMaker` specialisations as any other type.
@@ -110,7 +110,7 @@ TEST_CASE() {
 
 ## Floating point precision
 
-> [Introduced](https://github.com/catchorg/Catch2/issues/1614) in Catch 2.8.0.
+> [Introduced](https://github.com/catchorg/Catch2/issues/1614) in Catch2 2.8.0.
 
 Catch provides a built-in `StringMaker` specialization for both `float`
 and `double`. By default, it uses what we think is a reasonable precision,

package/deps/couchbase-cxx-client/third_party/catch2/docs/tutorial.md

@@ -3,32 +3,21 @@
 
 **Contents**<br>
 [Getting Catch2](#getting-catch2)<br>
-[Where to put it?](#where-to-put-it)<br>
 [Writing tests](#writing-tests)<br>
 [Test cases and sections](#test-cases-and-sections)<br>
-[BDD-Style](#bdd-style)<br>
-[Scaling up](#scaling-up)<br>
-[Type parametrised test cases](#type-parametrised-test-cases)<br>
+[BDD style testing](#bdd-style-testing)<br>
+[Data and Type driven tests](#data-and-type-driven-tests)<br>
 [Next steps](#next-steps)<br>
 
-## Getting Catch2
-
-The simplest way to get Catch2 is to download the latest [single header version](https://raw.githubusercontent.com/catchorg/Catch2/v2.x/single_include/catch2/catch.hpp). The single header is generated by merging a set of individual headers but it is still just normal source code in a header file.
-
-Alternative ways of getting Catch2 include using your system package
-manager, or installing it using [its CMake package](cmake-integration.md#installing-catch2-from-git-repository).
-
-The full source for Catch2, including test projects, documentation, and other things, is hosted on GitHub. [http://catch-lib.net](http://catch-lib.net) will redirect you there.
-
-
-## Where to put it?
 
-Catch2 is header only. All you need to do is drop the file somewhere reachable from your project - either in some central location you can set your header search path to find, or directly into your project tree itself! This is a particularly good option for other Open-Source projects that want to use Catch for their test suite. See [this blog entry for more on that](https://levelofindirection.com/blog/unit-testing-in-cpp-and-objective-c-just-got-ridiculously-easier-still.html).
+## Getting Catch2
 
-The rest of this tutorial will assume that the Catch2 single-include header (or the include folder) is available unqualified - but you may need to prefix it with a folder name if necessary.
+Ideally you should be using Catch2 through its [CMake integration](cmake-integration.md#top).
+Catch2 also provides pkg-config files and two file (header + cpp)
+distribution, but this documentation will assume you are using CMake. If
+you are using the two file distribution instead, remember to replace
+the included header with `catch_amalgamated.hpp`.
 
-_If you have installed Catch2 from system package manager, or CMake
-package, you need to include the header as `#include <catch2/catch.hpp>`_
 
 ## Writing tests
 
@@ -40,11 +29,8 @@ unsigned int Factorial( unsigned int number ) {
 }
 ```
 
-To keep things simple we'll put everything in a single file (<a href="#scaling-up">see later for more on how to structure your test files</a>).
-
 ```c++
-#define CATCH_CONFIG_MAIN  // This tells Catch to provide a main() - only do this in one cpp file
-#include "catch.hpp"
+#include <catch2/catch_test_macros.hpp>
 
 unsigned int Factorial( unsigned int number ) {
     return number <= 1 ? number : Factorial(number-1)*number;
@@ -60,13 +46,10 @@ TEST_CASE( "Factorials are computed", "[factorial]" ) {
 
 This will compile to a complete executable which responds to [command line arguments](command-line.md#top). If you just run it with no arguments it will execute all test cases (in this case there is just one), report any failures, report a summary of how many tests passed and failed and return the number of failed tests (useful for if you just want a yes/ no answer to: "did it work").
 
-If you run this as written it will pass. Everything is good. Right?
-Well, there is still a bug here. In fact the first version of this tutorial I posted here genuinely had the bug in! So it's not completely contrived (thanks to Daryle Walker (```@CTMacUser```) for pointing this out).
-
-What is the bug? Well what is the factorial of zero?
-[The factorial of zero is one](http://mathforum.org/library/drmath/view/57128.html) - which is just one of those things you have to know (and remember!).
-
-Let's add that to the test case:
+Anyway, as the tests above as written will pass, but there is a bug.
+The problem is that `Factorial(0)` should return 1 (due to [its
+definition](https://en.wikipedia.org/wiki/Factorial#Factorial_of_zero)).
+Let's add that as an assertion to the test case:
 
 ```c++
 TEST_CASE( "Factorials are computed", "[factorial]" ) {
@@ -78,7 +61,8 @@ TEST_CASE( "Factorials are computed", "[factorial]" ) {
 }
 ```
 
-Now we get a failure - something like:
+After another compile & run cycle, we will see a test failure. The output
+will look something like:
 
 ```
 Example.cpp:9: FAILED:
@@ -87,37 +71,51 @@ with expansion:
   0 == 1
 ```
 
-Note that we get the actual return value of Factorial(0) printed for us (0) - even though we used a natural expression with the == operator. That lets us immediately see what the problem is.
-
-Let's change the factorial function to:
+Note that the output contains both the original expression,
+`REQUIRE( Factorial(0) == 1 )` and the actual value returned by the call
+to the `Factorial` function: `0`.
 
+We can fix this bug by slightly modifying the `Factorial` function to:
 ```c++
 unsigned int Factorial( unsigned int number ) {
   return number > 1 ? Factorial(number-1)*number : 1;
 }
 ```
 
-Now all the tests pass.
-
-Of course there are still more issues to deal with. For example we'll hit problems when the return value starts to exceed the range of an unsigned int. With factorials that can happen quite quickly. You might want to add tests for such cases and decide how to handle them. We'll stop short of doing that here.
 
 ### What did we do here?
 
-Although this was a simple test it's been enough to demonstrate a few things about how Catch is used. Let's take a moment to consider those before we move on.
+Although this was a simple test it's been enough to demonstrate a few
+things about how Catch2 is used. Let's take a moment to consider those
+before we move on.
 
-1. All we did was ```#define``` one identifier and ```#include``` one header and we got everything - even an implementation of ```main()``` that will [respond to command line arguments](command-line.md#top). You can only use that ```#define``` in one implementation file, for (hopefully) obvious reasons. Once you have more than one file with unit tests in you'll just ```#include "catch.hpp"``` and go. Usually it's a good idea to have a dedicated implementation file that just has ```#define CATCH_CONFIG_MAIN``` and ```#include "catch.hpp"```. You can also provide your own implementation of main and drive Catch yourself (see [Supplying-your-own-main()](own-main.md#top)).
-2. We introduce test cases with the ```TEST_CASE``` macro. This macro takes one or two arguments - a free form test name and, optionally, one or more tags (for more see <a href="#test-cases-and-sections">Test cases and Sections</a>). The test name must be unique. You can run sets of tests by specifying a wildcarded test name or a tag expression. See the [command line docs](command-line.md#top) for more information on running tests.
-3. The name and tags arguments are just strings. We haven't had to declare a function or method - or explicitly register the test case anywhere. Behind the scenes a function with a generated name is defined for you, and automatically registered using static registry classes. By abstracting the function name away we can name our tests without the constraints of identifier names.
-4. We write our individual test assertions using the ```REQUIRE``` macro. Rather than a separate macro for each type of condition we express the condition naturally using C/C++ syntax. Behind the scenes a simple set of expression templates captures the left-hand-side and right-hand-side of the expression so we can display the values in our test report. As we'll see later there _are_ other assertion macros - but because of this technique the number of them is drastically reduced.
+* We introduce test cases with the `TEST_CASE` macro. This macro takes
+  one or two string arguments - a free form test name and, optionally,
+  one or more tags (for more see [Test cases and Sections](#test-cases-and-sections)).
+* The test automatically self-registers with the test runner, and user
+  does not have do anything more to ensure that it is picked up by the test
+  framework. _Note that you can run specific test, or set of tests,
+  through the [command line](command-line.md#top)._
+* The individual test assertions are written using the `REQUIRE` macro.
+  It accepts a boolean expression, and uses expression templates to
+  internally decompose it, so that it can be individually stringified
+  on test failure.
+
+On the last point, note that there are more testing macros available,
+because not all useful checks can be expressed as a simple boolean
+expression. As an example, checking that an expression throws an exception
+is done with the `REQUIRE_THROWS` macro. More on that later.
 
-<a id="test-cases-and-sections"></a>
-## Test cases and sections
 
-Most test frameworks have a class-based fixture mechanism. That is, test cases map to methods on a class and common setup and teardown can be performed in ```setup()``` and ```teardown()``` methods (or constructor/ destructor in languages, like C++, that support deterministic destruction).
+## Test cases and sections
 
-While Catch fully supports this way of working there are a few problems with the approach. In particular the way your code must be split up, and the blunt granularity of it, may cause problems. You can only have one setup/ teardown pair across a set of methods, but sometimes you want slightly different setup in each method, or you may even want several levels of setup (a concept which we will clarify later on in this tutorial). It was <a href="http://jamesnewkirk.typepad.com/posts/2007/09/why-you-should-.html">problems like these</a> that led James Newkirk, who led the team that built NUnit, to start again from scratch and <a href="http://jamesnewkirk.typepad.com/posts/2007/09/announcing-xuni.html">build xUnit</a>).
+Like most test frameworks, Catch2 supports a class-based fixture mechanism,
+where individual tests are methods on class and setup/teardown can be
+done in constructor/destructor of the type.
 
-Catch takes a different approach (to both NUnit and xUnit) that is a more natural fit for C++ and the C family of languages. This is best explained through an example ([code](../examples/100-Fix-Section.cpp)):
+However, their use in Catch2 is rare, because idiomatic Catch2 tests
+instead use _sections_ to share setup and teardown code between test code.
+This is best explained through an example ([code](../examples/100-Fix-Section.cpp)):
 
 ```c++
 TEST_CASE( "vectors can be sized and resized", "[vector]" ) {
@@ -154,125 +152,75 @@ TEST_CASE( "vectors can be sized and resized", "[vector]" ) {
 }
 ```
 
-For each ```SECTION``` the ```TEST_CASE``` is executed from the start - so as we enter each section we know that size is 5 and capacity is at least 5. We enforced those requirements with the ```REQUIRE```s at the top level so we can be confident in them.
-This works because the ```SECTION``` macro contains an if statement that calls back into Catch to see if the section should be executed. One leaf section is executed on each run through a ```TEST_CASE```. The other sections are skipped. Next time through the next section is executed, and so on until no new sections are encountered.
+For each `SECTION` the `TEST_CASE` is executed from the start. This means
+that each section is entered with a freshly constructed vector `v`, that
+we know has size 5 and capacity at least 5, because the two assertions
+are also checked before the section is entered. Each run through a test
+case will execute one, and only one, leaf section.
 
-So far so good - this is already an improvement on the setup/teardown approach because now we see our setup code inline and use the stack.
+Section can also be nested, in which case the parent section can be
+entered multiple times, once for each leaf section. Nested sections are
+most useful when you have multiple tests that share part of the set up.
+To continue on the vector example above, you could add a check that
+`std::vector::reserve` does not remove unused excess capacity, like this:
 
-The power of sections really shows, however, when we need to execute a sequence of checked operations. Continuing the vector example, we might want to verify that attempting to reserve a capacity smaller than the current capacity of the vector changes nothing. We can do that, naturally, like so:
-
-```c++
+```cpp
     SECTION( "reserving bigger changes capacity but not size" ) {
         v.reserve( 10 );
 
         REQUIRE( v.size() == 5 );
         REQUIRE( v.capacity() >= 10 );
-
-        SECTION( "reserving smaller again does not change capacity" ) {
+        SECTION( "reserving down unused capacity does not change capacity" ) {
             v.reserve( 7 );
-
+            REQUIRE( v.size() == 5 );
             REQUIRE( v.capacity() >= 10 );
         }
     }
 ```
 
-Sections can be nested to an arbitrary depth (limited only by your stack size). Each leaf section (i.e. a section that contains no nested sections) will be executed exactly once, on a separate path of execution from any other leaf section (so no leaf section can interfere with another). A failure in a parent section will prevent nested sections from running - but then that's the idea.
-
-## BDD-Style
-
-If you name your test cases and sections appropriately you can achieve a BDD-style specification structure. This became such a useful way of working that first class support has been added to Catch. Scenarios can be specified using ```SCENARIO```, ```GIVEN```, ```WHEN``` and ```THEN``` macros, which map on to ```TEST_CASE```s and ```SECTION```s, respectively. For more details see [Test cases and sections](test-cases-and-sections.md#top).
-
-The vector example can be adjusted to use these macros like so ([example code](../examples/120-Bdd-ScenarioGivenWhenThen.cpp)):
-
-```c++
-SCENARIO( "vectors can be sized and resized", "[vector]" ) {
-
-    GIVEN( "A vector with some items" ) {
-        std::vector<int> v( 5 );
-
-        REQUIRE( v.size() == 5 );
-        REQUIRE( v.capacity() >= 5 );
-
-        WHEN( "the size is increased" ) {
-            v.resize( 10 );
-
-            THEN( "the size and capacity change" ) {
-                REQUIRE( v.size() == 10 );
-                REQUIRE( v.capacity() >= 10 );
-            }
-        }
-        WHEN( "the size is reduced" ) {
-            v.resize( 0 );
-
-            THEN( "the size changes but not capacity" ) {
-                REQUIRE( v.size() == 0 );
-                REQUIRE( v.capacity() >= 5 );
-            }
-        }
-        WHEN( "more capacity is reserved" ) {
-            v.reserve( 10 );
-
-            THEN( "the capacity changes but not the size" ) {
-                REQUIRE( v.size() == 5 );
-                REQUIRE( v.capacity() >= 10 );
-            }
-        }
-        WHEN( "less capacity is reserved" ) {
-            v.reserve( 0 );
-
-            THEN( "neither size nor capacity are changed" ) {
-                REQUIRE( v.size() == 5 );
-                REQUIRE( v.capacity() >= 5 );
-            }
-        }
-    }
-}
-```
-
-Conveniently, these tests will be reported as follows when run:
-
-```
-Scenario: vectors can be sized and resized
-     Given: A vector with some items
-      When: more capacity is reserved
-      Then: the capacity changes but not the size
-```
-
-<a id="scaling-up"></a>
-## Scaling up
+Another way to look at sections is that they are a way to define a tree
+of paths through the test. Each section represents a node, and the final
+tree is walked in depth-first manner, with each path only visiting only
+one leaf node.
 
-To keep the tutorial simple we put all our code in a single file. This is fine to get started - and makes jumping into Catch even quicker and easier. As you write more real-world tests, though, this is not really the best approach.
+There is no practical limit on nesting sections, as long as your compiler
+can handle them, but keep in mind that overly nested sections can become
+unreadable. From experience, having section nest more than 3 levels is
+usually very hard to follow and not worth the removed duplication.
 
-The requirement is that the following block of code ([or equivalent](own-main.md#top)):
-
-```c++
-#define CATCH_CONFIG_MAIN
-#include "catch.hpp"
-```
 
-appears in _exactly one_ source file. Use as many additional cpp files (or whatever you call your implementation files) as you need for your tests, partitioned however makes most sense for your way of working. Each additional file need only ```#include "catch.hpp"``` - do not repeat the ```#define```!
+## BDD style testing
 
-In fact it is usually a good idea to put the block with the ```#define``` [in its own source file](slow-compiles.md#top) (code example [main](../examples/020-TestCase-1.cpp), [tests](../examples/020-TestCase-2.cpp)).
+Catch2 also provides some basic support for BDD-style testing. There are
+macro aliases for `TEST_CASE` and `SECTIONS` that you can use so that
+the resulting tests read as BDD spec. `SCENARIO` acts as a `TEST_CASE`
+with "Scenario: " name prefix. Then there are `GIVEN`, `WHEN`, `THEN`
+(and their variants with `AND_` prefix), which act as a `SECTION`,
+similarly prefixed with the macro name.
 
-Do not write your tests in header files!
+For more details on the macros look at the [test cases and
+sections](test-cases-and-sections.md#top) part of the reference docs,
+or at the [vector example done with BDD macros](../examples/120-Bdd-ScenarioGivenWhenThen.cpp).
 
 
-## Type parametrised test cases
+## Data and Type driven tests
 
-Test cases in Catch2 can be also parametrised by type, via the
-`TEMPLATE_TEST_CASE` and `TEMPLATE_PRODUCT_TEST_CASE` macros,
-which behave in the same way the `TEST_CASE` macro, but are run for
-every type or type combination.
+Test cases in Catch2 can also be driven by types, input data, or both
+at the same time.
 
-For more details, see our documentation on [test cases and
-sections](test-cases-and-sections.md#type-parametrised-test-cases).
+For more details look into the Catch2 reference, either at the
+[type parametrized test cases](test-cases-and-sections.md#type-parametrised-test-cases),
+or [data generators](generators.md#top).
 
 
 ## Next steps
 
-This has been a brief introduction to get you up and running with Catch, and to point out some of the key differences between Catch and other frameworks you may already be familiar with. This will get you going quite far already and you are now in a position to dive in and write some tests.
+This page is a brief introduction to get you up and running with Catch2,
+and to show the basic features of Catch2. The features mentioned here
+can get you quite far, but there are many more. However, you can read
+about these as you go, in the ever-growing [reference section](Readme.md#top)
+of the documentation.
 
-Of course there is more to learn - most of which you should be able to page-fault in as you go. Please see the ever-growing [Reference section](Readme.md#top) for what's available.
 
 ---
 

package/deps/couchbase-cxx-client/third_party/catch2/docs/usage-tips.md

@@ -0,0 +1,100 @@
+<a id="top"></a>
+# Best practices and other tips on using Catch2
+
+## Running tests
+
+Your tests should be run in a manner roughly equivalent with:
+
+```
+./tests --order rand --warn NoAssertions
+```
+
+Notice that all the tests are run in a large batch, their relative order
+is randomized, and that you ask Catch2 to fail test whose leaf-path
+does not contain an assertion.
+
+The reason I recommend running all your tests in the same process is that
+this exposes your tests to interference from their runs. This can be both
+positive interference, where the changes in global state from previous
+test allow later tests to pass, but also negative interference, where
+changes in global state from previous test causes later tests to fail.
+
+In my experience, interference, especially destructive interference,
+usually comes from errors in the code under test, rather than the tests
+themselves. This means that by allowing interference to happen, our tests
+can find these issues. Obviously, to shake out interference coming from
+different orderings of tests, the test order also need to be shuffled
+between runs.
+
+However, running all tests in a single batch eventually becomes impractical
+as they will take too long to run, and you will want to run your tests
+in parallel.
+
+
+<a id="parallel-tests"></a>
+## Running tests in parallel
+
+There are multiple ways of running tests in parallel, with various level
+of structure. If you are using CMake and CTest, then we provide a helper
+function [`catch_discover_tests`](cmake-integration.md#automatic-test-registration)
+that registers each Catch2 `TEST_CASE` as a single CTest test, which
+is then run in a separate process. This is an easy way to set up parallel
+tests if you are already using CMake & CTest to run your tests, but you
+will lose the advantage of running tests in batches.
+
+
+Catch2 also supports [splitting tests in a binary into multiple
+shards](command-line.md#test-sharding). This can be used by any test
+runner to run batches of tests in parallel. Do note that when selecting
+on the number of shards, you should have more shards than there are cores,
+to avoid issues with long-running tests getting accidentally grouped in
+the same shard, and causing long-tailed execution time.
+
+**Note that naively composing sharding and random ordering of tests will break.**
+
+Invoking Catch2 test executable like this
+
+```text
+./tests --order rand --shard-index 0 --shard-count 3
+./tests --order rand --shard-index 1 --shard-count 3
+./tests --order rand --shard-index 2 --shard-count 3
+```
+
+does not guarantee covering all tests inside the executable, because
+each invocation will have its own random seed, thus it will have its own
+random order of tests and thus the partitioning of tests into shards will
+be different as well.
+
+To do this properly, you need the individual shards to share the random
+seed, e.g.
+```text
+./tests --order rand --shard-index 0 --shard-count 3 --rng-seed 0xBEEF
+./tests --order rand --shard-index 1 --shard-count 3 --rng-seed 0xBEEF
+./tests --order rand --shard-index 2 --shard-count 3 --rng-seed 0xBEEF
+```
+
+Catch2 actually provides a helper to automatically register multiple shards
+as CTest tests, with shared random seed that changes each CTest invocation.
+For details look at the documentation of
+[`CatchShardTests.cmake` CMake script](cmake-integration.md#catchshardtestscmake).
+
+
+## Organizing tests into binaries
+
+Both overly large and overly small test binaries can cause issues. Overly
+large test binaries have to be recompiled and relinked often, and the
+link times are usually also long. Overly small test binaries in turn pay
+significant overhead from linking against Catch2 more often per compiled
+test case, and also make it hard/impossible to run tests in batches.
+
+Because there is no hard and fast rule for the right size of a test binary,
+I recommend having 1:1 correspondence between libraries in project and test
+binaries. (At least if it is possible, in some cases it is not.) Having
+a test binary for each library in project keeps related tests together,
+and makes tests easy to navigate by reflecting the project's organizational
+structure.
+
+
+---
+
+[Home](Readme.md#top)

package/deps/couchbase-cxx-client/third_party/catch2/docs/why-catch.md

@@ -6,40 +6,53 @@ including (but not limited to),
 [Google Test](http://code.google.com/p/googletest/),
 [Boost.Test](http://www.boost.org/doc/libs/1_49_0/libs/test/doc/html/index.html),
 [CppUnit](http://sourceforge.net/apps/mediawiki/cppunit/index.php?title=Main_Page),
-[Cute](http://www.cute-test.com),
+[Cute](http://www.cute-test.com), and
 [many, many more](http://en.wikipedia.org/wiki/List_of_unit_testing_frameworks#C.2B.2B).
 
-So what does Catch bring to the party that differentiates it from these? Apart from a Catchy name, of course.
+So what does Catch2 bring to the party that differentiates it from these? Apart from the catchy name, of course.
+
 
 ## Key Features
 
-* Quick and Really easy to get started. Just download catch.hpp, `#include` it and you're away.
-* No external dependencies. As long as you can compile C++11 and have a C++ standard library available.
+* Quick and easy to get started. Just download two files, add them into your project and you're away.
+* No external dependencies. As long as you can compile C++14 and have the C++ standard library available.
 * Write test cases as, self-registering, functions (or methods, if you prefer).
 * Divide test cases into sections, each of which is run in isolation (eliminates the need for fixtures).
 * Use BDD-style Given-When-Then sections as well as traditional unit test cases.
 * Only one core assertion macro for comparisons. Standard C/C++ operators are used for the comparison - yet the full expression is decomposed and lhs and rhs values are logged.
 * Tests are named using free-form strings - no more couching names in legal identifiers.
 
+
 ## Other core features
 
 * Tests can be tagged for easily running ad-hoc groups of tests.
-* Failures can (optionally) break into the debugger on Windows and Mac.
+* Failures can (optionally) break into the debugger on common platforms.
 * Output is through modular reporter objects. Basic textual and XML reporters are included. Custom reporters can easily be added.
 * JUnit xml output is supported for integration with third-party tools, such as CI servers.
 * A default main() function is provided, but you can supply your own for complete control (e.g. integration into your own test runner GUI).
 * A command line parser is provided and can still be used if you choose to provided your own main() function.
-* Catch can test itself.
 * Alternative assertion macro(s) report failures but don't abort the test case
-* Floating point tolerance comparisons are built in using an expressive Approx() syntax.
+* Good set of facilities for floating point comparisons (`Catch::Approx` and full set of matchers)
 * Internal and friendly macros are isolated so name clashes can be managed
-* Matchers
+* Data generators (data driven test support)
+* Hamcrest-style Matchers for testing complex properties
+* Microbenchmarking support
+
 
-## Who else is using Catch?
+## Who else is using Catch2?
 
-See the list of [open source projects using Catch](opensource-users.md#top).
+A whole lot of people. According to the 2021 JetBrains C++ ecosystem survey,
+about 11% of C++ programmers use Catch2 for unit testing, making it the
+second most popular unit testing framework.
+
+You can also take a look at the (incomplete) list of [open source projects](opensource-users.md#top)
+or the (very incomplete) list of [commercial users of Catch2](commercial-users.md#top)
+for some idea on who else also uses Catch2.
+
+---
 
-See the [tutorial](tutorial.md#top) to get more of a taste of using Catch in practice 
+See the [tutorial](tutorial.md#top) to get more of a taste of using
+Catch2 in practice.
 
 ---
 

package/deps/couchbase-cxx-client/third_party/catch2/examples/010-TestCase.cpp

@@ -1,11 +1,8 @@
 // 010-TestCase.cpp
+// And write tests in the same file:
+#include <catch2/catch_test_macros.hpp>
 
-// Let Catch provide main():
-#define CATCH_CONFIG_MAIN
-
-#include <catch2/catch.hpp>
-
-int Factorial( int number ) {
+static int Factorial( int number ) {
    return number <= 1 ? number : Factorial( number - 1 ) * number;  // fail
 // return number <= 1 ? 1      : Factorial( number - 1 ) * number;  // pass
 }
@@ -22,7 +19,7 @@ TEST_CASE( "Factorials of 1 and higher are computed (pass)", "[single-file]" ) {
 }
 
 // Compile & run:
-// - g++ -std=c++11 -Wall -I$(CATCH_SINGLE_INCLUDE) -o 010-TestCase 010-TestCase.cpp && 010-TestCase --success
+// - g++ -std=c++14 -Wall -I$(CATCH_SINGLE_INCLUDE) -o 010-TestCase 010-TestCase.cpp && 010-TestCase --success
 // - cl -EHsc -I%CATCH_SINGLE_INCLUDE% 010-TestCase.cpp && 010-TestCase --success
 
 // Expected compact output (all assertions):

package/deps/couchbase-cxx-client/third_party/catch2/examples/020-TestCase-1.cpp

@@ -1,12 +1,6 @@
 // 020-TestCase-1.cpp
 
-// In a Catch project with multiple files, dedicate one file to compile the
-// source code of Catch itself and reuse the resulting object file for linking.
-
-// Let Catch provide main():
-#define CATCH_CONFIG_MAIN
-
-#include <catch2/catch.hpp>
+#include <catch2/catch_test_macros.hpp>
 
 TEST_CASE( "1: All test cases reside in other .cpp files (empty)", "[multi-file:1]" ) {
 }
@@ -16,8 +10,8 @@ TEST_CASE( "1: All test cases reside in other .cpp files (empty)", "[multi-file:
 // Here just to show there are two source files via option --list-tests.
 
 // Compile & run:
-// - g++ -std=c++11 -Wall -I$(CATCH_SINGLE_INCLUDE) -c 020-TestCase-1.cpp
-// - g++ -std=c++11 -Wall -I$(CATCH_SINGLE_INCLUDE) -o 020-TestCase TestCase-1.o 020-TestCase-2.cpp && 020-TestCase --success
+// - g++ -std=c++14 -Wall -I$(CATCH_SINGLE_INCLUDE) -c 020-TestCase-1.cpp
+// - g++ -std=c++14 -Wall -I$(CATCH_SINGLE_INCLUDE) -o 020-TestCase TestCase-1.o 020-TestCase-2.cpp && 020-TestCase --success
 //
 // - cl -EHsc -I%CATCH_SINGLE_INCLUDE% -c 020-TestCase-1.cpp
 // - cl -EHsc -I%CATCH_SINGLE_INCLUDE% -Fe020-TestCase.exe 020-TestCase-1.obj 020-TestCase-2.cpp && 020-TestCase --success

package/deps/couchbase-cxx-client/third_party/catch2/examples/020-TestCase-2.cpp

@@ -2,9 +2,9 @@
 
 // main() provided by Catch in file 020-TestCase-1.cpp.
 
-#include <catch2/catch.hpp>
+#include <catch2/catch_test_macros.hpp>
 
-int Factorial( int number ) {
+static int Factorial( int number ) {
    return number <= 1 ? number : Factorial( number - 1 ) * number;  // fail
 // return number <= 1 ? 1      : Factorial( number - 1 ) * number;  // pass
 }

package/deps/couchbase-cxx-client/third_party/catch2/examples/030-Asn-Require-Check.cpp

@@ -8,11 +8,11 @@
 // - REQUIRE_FALSE() stops at first failure.
 // - CHECK_FALSE() continues after failure.
 
-// main() provided in 000-CatchMain.cpp
+// main() provided by linkage to Catch2WithMain
 
-#include <catch2/catch.hpp>
+#include <catch2/catch_test_macros.hpp>
 
-std::string one() {
+static std::string one() {
     return "1";
 }
 
@@ -53,8 +53,8 @@ TEST_CASE( "Assert that something is false (continue after failure)", "[check-fa
 }
 
 // Compile & run:
-// - g++ -std=c++11 -Wall -I$(CATCH_SINGLE_INCLUDE) -o 030-Asn-Require-Check 030-Asn-Require-Check.cpp 000-CatchMain.o && 030-Asn-Require-Check --success
-// - cl -EHsc -I%CATCH_SINGLE_INCLUDE% 030-Asn-Require-Check.cpp 000-CatchMain.obj && 030-Asn-Require-Check --success
+// - g++ -std=c++14 -Wall -I$(CATCH_SINGLE_INCLUDE) -o 030-Asn-Require-Check 030-Asn-Require-Check.cpp && 030-Asn-Require-Check --success
+// - cl -EHsc -I%CATCH_SINGLE_INCLUDE% 030-Asn-Require-Check.cpp && 030-Asn-Require-Check --success
 
 // Expected compact output (all assertions):
 //

package/deps/couchbase-cxx-client/third_party/catch2/examples/100-Fix-Section.cpp

@@ -4,9 +4,10 @@
 // - Sections (this file)
 // - Traditional class-based fixtures
 
-// main() provided in 000-CatchMain.cpp
+// main() provided by linkage to Catch2WithMain
 
-#include <catch2/catch.hpp>
+#include <catch2/catch_test_macros.hpp>
+#include <vector>
 
 TEST_CASE( "vectors can be sized and resized", "[vector]" ) {
 
@@ -44,8 +45,8 @@ TEST_CASE( "vectors can be sized and resized", "[vector]" ) {
 }
 
 // Compile & run:
-// - g++ -std=c++11 -Wall -I$(CATCH_SINGLE_INCLUDE) -o 100-Fix-Section 100-Fix-Section.cpp 000-CatchMain.o && 100-Fix-Section --success
-// - cl -EHsc -I%CATCH_SINGLE_INCLUDE% 100-Fix-Section.cpp 000-CatchMain.obj && 100-Fix-Section --success
+// - g++ -std=c++14 -Wall -I$(CATCH_SINGLE_INCLUDE) -o 100-Fix-Section 100-Fix-Section.cpp && 100-Fix-Section --success
+// - cl -EHsc -I%CATCH_SINGLE_INCLUDE% 100-Fix-Section.cpp && 100-Fix-Section --success
 
 // Expected compact output (all assertions):
 //