couchbase 4.2.1 → 4.2.3

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

@@ -1,46 +1,212 @@
 <a id="top"></a>
 # Reporters
 
-Catch has a modular reporting system and comes bundled with a handful of useful reporters built in.
-You can also write your own reporters.
+Reporters are a customization point for most of Catch2's output, e.g.
+formatting and writing out [assertions (whether passing or failing),
+sections, test cases, benchmarks, and so on](reporter-events.md#top).
+
+Catch2 comes with a bunch of reporters by default (currently 8), and
+you can also write your own reporter. Because multiple reporters can
+be active at the same time, your own reporters do not even have to handle
+all reporter event, just the ones you are interested in, e.g. benchmarks.
+
 
 ## Using different reporters
 
-The reporter to use can easily be controlled from the command line.
-To specify a reporter use [`-r` or `--reporter`](command-line.md#choosing-a-reporter-to-use), followed by the name of the reporter, e.g.:
+You can see which reporters are available by running the test binary
+with `--list-reporters`. You can then pick one of them with the [`-r`,
+`--reporter` option](command-line.md#choosing-a-reporter-to-use), followed
+by the name of the desired reporter, like so:
+
+```
+--reporter xml
+```
+
+You can also select multiple reporters to be used at the same time.
+In that case you should read the [section on using multiple
+reporters](#multiple-reporters) to avoid any surprises from doing so.
+
 
+<a id="multiple-reporters"></a>
+## Using multiple reporters
+
+> Support for having multiple parallel reporters was [introduced](https://github.com/catchorg/Catch2/pull/2183) in Catch2 3.0.1
+
+Catch2 supports using multiple reporters at the same time while having
+them write into different destinations. The two main uses of this are
+
+* having both human-friendly and machine-parseable (e.g. in JUnit format)
+  output from one run of binary
+* having "partial" reporters that are highly specialized, e.g. having one
+  reporter that writes out benchmark results as markdown tables and does
+  nothing else, while also having standard testing output separately
+
+Specifying multiple reporter looks like this:
 ```
--r xml
+--reporter JUnit::out=result-junit.xml --reporter console::out=-::colour-mode=ansi
 ```
 
-If you don't specify a reporter then the console reporter is used by default.
-There are four reporters built in to the single include:
+This tells Catch2 to use two reporters, `JUnit` reporter that writes
+its machine-readable XML output to file `result-junit.xml`, and the
+`console` reporter that writes its user-friendly output to stdout and
+uses ANSI colour codes for colouring the output.
 
-* `console` writes as lines of text, formatted to a typical terminal width, with colours if a capable terminal is detected.
-* `compact` similar to `console` but optimised for minimal output - each entry on one line
-* `junit` writes xml that corresponds to Ant's [junitreport](http://help.catchsoftware.com/display/ET/JUnit+Format) target. Useful for build systems that understand Junit.
-Because of the way the junit format is structured the run must complete before anything is written. 
-* `xml` writes an xml format tailored to Catch. Unlike `junit` this is a streaming format so results are delivered progressively.
+Using multiple reporters (or one reporter and one-or-more [event
+listeners](event-listener.md#top)) can have surprisingly complex semantics
+when using customization points provided to reporters by Catch2, namely
+capturing stdout/stderr from test cases.
 
-There are a few additional reporters, for specific build systems, in the Catch repository (in `include\reporters`) which you can `#include` in your project if you would like to make use of them.
-Do this in one source file - the same one you have `CATCH_CONFIG_MAIN` or `CATCH_CONFIG_RUNNER`.
+As long as at least one reporter (or listener) asks Catch2 to capture
+stdout/stderr, captured stdout and stderr will be available to all
+reporters and listeners.
 
-* `teamcity` writes the native, streaming, format that [TeamCity](https://www.jetbrains.com/teamcity/) understands. 
-Use this when building as part of a TeamCity build to see results as they happen ([code example](../examples/207-Rpt-TeamCityReporter.cpp)).
-* `tap` writes in the TAP ([Test Anything Protocol](https://en.wikipedia.org/wiki/Test_Anything_Protocol)) format.
-* `automake` writes in a format that correspond to [automake  .trs](https://www.gnu.org/software/automake/manual/html_node/Log-files-generation-and-test-results-recording.html) files
-* `sonarqube` writes the [SonarQube Generic Test Data](https://docs.sonarqube.org/latest/analysis/generic-test/) XML format.
+Because this might be surprising to the users, if at least one active
+_reporter_ is non-capturing, then Catch2 tries to roughly emulate
+non-capturing behaviour by printing out the captured stdout/stderr
+just before `testCasePartialEnded` event is sent out to the active
+reporters and listeners. This means that stdout/stderr is no longer
+printed out from tests as it is being written, but instead it is written
+out in batch after each runthrough of a test case is finished.
 
-You see what reporters are available from the command line by running with `--list-reporters`.
 
-By default all these reports are written to stdout, but can be redirected to a file with [`-o` or `--out`](command-line.md#sending-output-to-a-file)
 
 ## Writing your own reporter
 
-You can write your own custom reporter and register it with Catch.
-At time of writing the interface is subject to some changes so is not, yet, documented here.
-If you are determined you shouldn't have too much trouble working it out from the existing implementations -
-but do keep in mind upcoming changes (these will be minor, simplifying, changes such as not needing to forward calls to the base class).
+You can also write your own custom reporter and tell Catch2 to use it.
+When writing your reporter, you have two options:
+
+* Derive from `Catch::ReporterBase`. When doing this, you will have
+  to provide handling for all [reporter events](reporter-events.md#top).
+* Derive from one of the provided [utility reporter bases in
+  Catch2](#utility-reporter-bases).
+
+Generally we recommend doing the latter, as it is less work.
+
+Apart from overriding handling of the individual reporter events, reporters
+have access to some extra customization points, described below.
+
+
+### Utility reporter bases
+
+Catch2 currently provides two utility reporter bases:
+
+* `Catch::StreamingReporterBase`
+* `Catch::CumulativeReporterBase`
+
+`StreamingReporterBase` is useful for reporters that can format and write
+out the events as they come in. It provides (usually empty) implementation
+for all reporter events, and if you let it handle the relevant events,
+it also handles storing information about active test run and test case.
+
+`CumulativeReporterBase` is a base for reporters that need to see the whole
+test run, before they can start writing the output, such as the JUnit
+and SonarQube reporters. This post-facto approach requires the assertions
+to be stringified when it is finished, so that the assertion can be written
+out later. Because the stringification can be expensive, and not all
+cumulative reporters need the assertions, this base provides customization
+point to change whether the assertions are saved or not, separate for
+passing and failing assertions.
+
+
+_Generally we recommend that if you override a member function from either
+of the bases, you call into the base's implementation first. This is not
+necessarily in all cases, but it is safer and easier._
+
+
+Writing your own reporter then looks like this:
+
+```cpp
+#include <catch2/reporters/catch_reporter_streaming_base.hpp>
+#include <catch2/catch_test_case_info.hpp>
+#include <catch2/reporters/catch_reporter_registrars.hpp>
+
+#include <iostream>
+
+class PartialReporter : public Catch::StreamingReporterBase {
+public:
+    using StreamingReporterBase::StreamingReporterBase;
+
+    static std::string getDescription() {
+        return "Reporter for testing TestCasePartialStarting/Ended events";
+    }
+
+    void testCasePartialStarting(Catch::TestCaseInfo const& testInfo,
+                                 uint64_t partNumber) override {
+        std::cout << "TestCaseStartingPartial: " << testInfo.name << '#' << partNumber << '\n';
+    }
+
+    void testCasePartialEnded(Catch::TestCaseStats const& testCaseStats,
+                              uint64_t partNumber) override {
+        std::cout << "TestCasePartialEnded: " << testCaseStats.testInfo->name << '#' << partNumber << '\n';
+    }
+};
+
+
+CATCH_REGISTER_REPORTER("partial", PartialReporter)
+```
+
+This create a simple reporter that responds to `testCasePartial*` events,
+and calls itself "partial" reporter, so it can be invoked with
+`--reporter partial` command line flag.
+
+
+### `ReporterPreferences`
+
+Each reporter instance contains instance of `ReporterPreferences`, a type
+that holds flags for the behaviour of Catch2 when this reporter run.
+Currently there are two customization options:
+
+* `shouldRedirectStdOut` - whether the reporter wants to handle
+   writes to stdout/stderr from user code, or not. This is useful for
+   reporters that output machine-parseable output, e.g. the JUnit
+   reporter, or the XML reporter.
+* `shouldReportAllAssertions` - whether the reporter wants to handle
+  `assertionEnded` events for passing assertions as well as failing
+   assertions. Usually reporters do not report successful assertions
+   and don't need them for their output, but sometimes the desired output
+   format includes passing assertions even without the `-s` flag.
+
+
+### Per-reporter configuration
+
+> Per-reporter configuration was introduced in Catch2 3.0.1
+
+Catch2 supports some configuration to happen per reporter. The configuration
+options fall into one of two categories:
+
+* Catch2-recognized options
+* Reporter-specific options
+
+The former is a small set of universal options that Catch2 handles for
+the reporters, e.g. output file or console colour mode. The latter are
+options that the reporters have to handle themselves, but the keys and
+values can be arbitrary strings, as long as they don't contain `::`. This
+allows writing reporters that can be significantly customized at runtime.
+
+Reporter-specific options always have to be prefixed with "X" (large
+letter X).
+
+
+### Other expected functionality of a reporter
+
+When writing a custom reporter, there are few more things that you should
+keep in mind. These are not important for correctness, but they are
+important for the reporter to work _nicely_.
+
+* Catch2 provides a simple verbosity option for users. There are three
+  verbosity levels, "quiet", "normal", and "high", and if it makes sense
+  for reporter's output format, it should respond to these by changing
+  what, and how much, it writes out.
+
+* Catch2 operates with an rng-seed. Knowing what seed a test run had
+  is important if you want to replicate it, so your reporter should
+  report the rng-seed, if at all possible given the target output format.
+
+* Catch2 also operates with test filters, or test specs. If a filter
+  is present, you should also report the filter, if at all possible given
+  the target output format.
+
+
 
 ---
 

package/deps/couchbase-cxx-client/third_party/catch2/docs/skipping-passing-failing.md

@@ -0,0 +1,129 @@
+<a id="top"></a>
+# Explicitly skipping, passing, and failing tests at runtime
+
+## Skipping Test Cases at Runtime
+
+> [Introduced](https://github.com/catchorg/Catch2/pull/2360) in Catch2 3.3.0.
+
+In some situations it may not be possible to meaningfully execute a test case,
+for example when the system under test is missing certain hardware capabilities.
+If the required conditions can only be determined at runtime, it often
+doesn't make sense to consider such a test case as either passed or failed,
+because it simply can not run at all.
+
+To properly express such scenarios, Catch2 provides a way to explicitly
+_skip_ test cases, using the `SKIP` macro:
+
+```
+SKIP( [streamable expression] )
+```
+
+Example usage:
+
+```c++
+TEST_CASE("copy files between drives") {
+    if(getNumberOfHardDrives() < 2) {
+        SKIP("at least two hard drives required");
+    }
+    // ...
+}
+```
+
+This test case is then reported as _skipped_ instead of _passed_ or _failed_.
+
+The `SKIP` macro behaves similarly to an explicit [`FAIL`](#passing-and-failing-test-cases),
+in that it is the last expression that will be executed:
+
+```c++
+TEST_CASE("my test") {
+    printf("foo");
+    SKIP();
+    printf("bar"); // not printed
+}
+```
+
+However a failed assertion _before_ a `SKIP` still causes the entire
+test case to fail:
+
+```c++
+TEST_CASE("failing test") {
+    CHECK(1 == 2);
+    SKIP();
+}
+```
+
+### Interaction with Sections and Generators
+
+Sections, nested sections as well as specific outputs from [generators](generators.md#top)
+can all be individually skipped, with the rest executing as usual:
+
+```c++
+TEST_CASE("complex test case") {
+  int value = GENERATE(2, 4, 6);
+  SECTION("a") {
+    SECTION("a1") { CHECK(value < 8); }
+    SECTION("a2") {
+      if (value == 4) {
+        SKIP();
+      }
+      CHECK(value % 2 == 0);
+    }
+  }
+}
+```
+
+This test case will report 5 passing assertions; one for each of the three
+values in section `a1`, and then two in section `a2`, from values 2 and 4.
+
+Note that as soon as one section is skipped, the entire test case will
+be reported as _skipped_ (unless there is a failing assertion, in which
+case the test is handled as _failed_ instead).
+
+Note that if all test cases in a run are skipped, Catch2 returns a non-zero
+exit code, same as it does if no test cases have run. This behaviour can
+be overridden using the [--allow-running-no-tests](command-line.md#no-tests-override)
+flag.
+
+
+## Passing and failing test cases
+
+Test cases can also be explicitly passed or failed, without the use of
+assertions, and with a specific message. This can be useful to handle
+complex preconditions/postconditions and give useful error messages
+when they fail.
+
+* `SUCCEED( [streamable expression] )`
+
+`SUCCEED` is morally equivalent with `INFO( [streamable expression] ); REQUIRE( true );`.
+Note that it does not stop further test execution, so it cannot be used
+to guard failing assertions from being executed.
+
+_In practice, `SUCCEED` is usually used as a test placeholder, to avoid
+[failing a test case due to missing assertions](command-line.md#warnings)._
+
+```cpp
+TEST_CASE( "SUCCEED showcase" ) {
+    int I = 1;
+    SUCCEED( "I is " << I );
+    // ... execution continues here ...
+}
+```
+
+* `FAIL( [streamable expression] )`
+
+`FAIL` is morally equivalent with `INFO( [streamable expression] ); REQUIRE( false );`.
+
+_In practice, `FAIL` is usually used to stop executing test that is currently
+known to be broken, but has to be fixed later._
+
+```cpp
+TEST_CASE( "FAIL showcase" ) {
+    FAIL( "This test case causes segfault, which breaks CI." );
+    // ... this will not be executed ...
+}
+```
+
+
+---
+
+[Home](Readme.md#top)

package/deps/couchbase-cxx-client/third_party/catch2/docs/test-cases-and-sections.md

@@ -15,9 +15,18 @@ Instead Catch provides a powerful mechanism for nesting test case sections withi
 Test cases and sections are very easy to use in practice:
 
 * **TEST_CASE(** _test name_ \[, _tags_ \] **)**
-* **SECTION(** _section name_ **)**
+* **SECTION(** _section name_, \[, _section description_ \] **)**
 
-_test name_ and _section name_ are free form, quoted, strings. The optional _tags_ argument is a quoted string containing one or more tags enclosed in square brackets. Tags are discussed below. Test names must be unique within the Catch executable.
+
+_test name_ and _section name_ are free form, quoted, strings.
+The optional _tags_ argument is a quoted string containing one or more
+tags enclosed in square brackets, and are discussed below.
+_section description_ can be used to provide long form description
+of a section while keeping the _section name_ short for use with the
+[`-c` command line parameter](command-line.md#specify-the-section-to-run).
+
+**The combination of test names and tags must be unique within the Catch2
+executable.**
 
 For examples see the [Tutorial](tutorial.md#top)
 
@@ -36,13 +45,21 @@ The tag expression, ```"[widget]"``` selects A, B & D. ```"[gadget]"``` selects
 
 For more detail on command line selection see [the command line docs](command-line.md#specifying-which-tests-to-run)
 
-Tag names are not case sensitive and can contain any ASCII characters. This means that tags `[tag with spaces]` and `[I said "good day"]` are both allowed tags and can be filtered on. Escapes are not supported however and `[\]]` is not a valid tag.
+Tag names are not case sensitive and can contain any ASCII characters.
+This means that tags `[tag with spaces]` and `[I said "good day"]`
+are both allowed tags and can be filtered on. However, escapes are not
+supported however and `[\]]` is not a valid tag.
+
+The same tag can be specified multiple times for a single test case,
+but only one of the instances of identical tags will be kept. Which one
+is kept is functionally random.
+
 
 ### Special Tags
 
 All tag names beginning with non-alphanumeric characters are reserved by Catch. Catch defines a number of "special" tags, which have meaning to the test runner itself. These special tags all begin with a symbol character. Following is a list of currently defined special tags and their meanings.
 
-* `[!hide]` or `[.]` - causes test cases to be skipped from the default list (i.e. when no test cases have been explicitly selected through tag expressions or name wildcards). The hide tag is often combined with another, user, tag (for example `[.][integration]` - so all integration tests are excluded from the default run but can be run by passing `[integration]` on the command line). As a short-cut you can combine these by simply prefixing your user tag with a `.` - e.g. `[.integration]`. Because the hide tag has evolved to have several forms, all forms are added as tags if you use one of them.
+* `[.]` - causes test cases to be skipped from the default list (i.e. when no test cases have been explicitly selected through tag expressions or name wildcards). The hide tag is often combined with another, user, tag (for example `[.][integration]` - so all integration tests are excluded from the default run but can be run by passing `[integration]` on the command line). As a short-cut you can combine these by simply prefixing your user tag with a `.` - e.g. `[.integration]`.
 
 * `[!throws]` - lets Catch know that this test is likely to throw an exception even if successful. This causes the test to be excluded when running with `-e` or `--nothrow`.
 
@@ -52,11 +69,13 @@ All tag names beginning with non-alphanumeric characters are reserved by Catch.
 
 * `[!nonportable]` - Indicates that behaviour may vary between platforms or compilers.
 
-* `[#<filename>]` - running with `-#` or `--filenames-as-tags` causes Catch to add the filename, prefixed with `#` (and with any extension stripped), as a tag to all contained tests, e.g. tests in testfile.cpp would all be tagged `[#testfile]`.
+* `[#<filename>]` - these tags are added to test cases when you run Catch2
+                    with [`-#` or `--filenames-as-tags`](command-line.md#filenames-as-tags).
 
 * `[@<alias>]` - tag aliases all begin with `@` (see below).
 
-* `[!benchmark]` - this test case is actually a benchmark. This is an experimental feature, and currently has no documentation. If you want to try it out, look at `projects/SelfTest/Benchmark.tests.cpp` for details.
+* `[!benchmark]` - this test case is actually a benchmark. Currently this only serves to hide the test case by default, to avoid the execution time costs.
+
 
 ## Tag aliases
 
@@ -82,15 +101,65 @@ This macro maps onto ```TEST_CASE``` and works in the same way, except that the
 * **WHEN(** _something_ **)**
 * **THEN(** _something_ **)**
 
-These macros map onto ```SECTION```s except that the section names are the _something_s prefixed by "given: ", "when: " or "then: " respectively.
+These macros map onto ```SECTION```s except that the section names are the _something_ texts prefixed by
+"given: ", "when: " or "then: " respectively. These macros also map onto the AAA or A<sup>3</sup> test pattern
+(standing either for [Assemble-Activate-Assert](http://wiki.c2.com/?AssembleActivateAssert) or
+[Arrange-Act-Assert](http://wiki.c2.com/?ArrangeActAssert)), and in this context, the macros provide both code
+documentation and reporting of these parts of a test case without the need for extra comments or code to do so.
+
+Semantically, a `GIVEN` clause may have multiple _independent_ `WHEN` clauses within it. This allows a test
+to have, e.g., one set of "given" objects and multiple subtests using those objects in various ways in each
+of the `WHEN` clauses without repeating the initialisation from the `GIVEN` clause. When there are _dependent_
+clauses -- such as a second `WHEN` clause that should only happen _after_ the previous `WHEN` clause has been
+executed and validated -- there are additional macros starting with `AND_`:
 
 * **AND_GIVEN(** _something_ **)**
 * **AND_WHEN(** _something_ **)**
 * **AND_THEN(** _something_ **)**
 
-Similar to ```GIVEN```, ```WHEN``` and ```THEN``` except that the prefixes start with "and ". These are used to chain ```GIVEN```s, ```WHEN```s and ```THEN```s together.
+These are used to chain ```GIVEN```s, ```WHEN```s and ```THEN```s together. The `AND_*` clause is placed
+_inside_ the clause on which it depends. There can be multiple _independent_ clauses that are all _dependent_
+on a single outer clause.
+```cpp
+SCENARIO( "vector can be sized and resized" ) {
+    GIVEN( "An empty vector" ) {
+        auto v = std::vector<std::string>{};
+
+        // Validate assumption of the GIVEN clause
+        THEN( "The size and capacity start at 0" ) {
+            REQUIRE( v.size() == 0 );
+            REQUIRE( v.capacity() == 0 );
+        }
+
+        // Validate one use case for the GIVEN object
+        WHEN( "push_back() is called" ) {
+            v.push_back("hullo");
 
-> `AND_GIVEN` was [introduced](https://github.com/catchorg/Catch2/issues/1360) in Catch 2.4.0.
+            THEN( "The size changes" ) {
+                REQUIRE( v.size() == 1 );
+                REQUIRE( v.capacity() >= 1 );
+            }
+        }
+    }
+}
+```
+
+This code will result in two runs through the scenario:
+```
+Scenario : vector can be sized and resized
+  Given  : An empty vector
+  Then   : The size and capacity start at 0
+
+Scenario : vector can be sized and resized
+  Given  : An empty vector
+  When   : push_back() is called
+  Then   : The size changes
+```
+
+See also [runnable example on godbolt](https://godbolt.org/z/eY5a64r99),
+with a more complicated (and failing) example.
+
+> `AND_GIVEN` was [introduced](https://github.com/catchorg/Catch2/issues/1360) in Catch2 2.4.0.
 
 When any of these macros are used the console reporter recognises them and formats the test case header such that the Givens, Whens and Thens are aligned to aid readability.
 
@@ -100,11 +169,15 @@ Other than the additional prefixes and the formatting in the console reporter th
 
 In addition to `TEST_CASE`s, Catch2 also supports test cases parametrised
 by types, in the form of `TEMPLATE_TEST_CASE`,
-`TEMPLATE_PRODUCT_TEST_CASE` and `TEMPLATE_LIST_TEST_CASE`.
+`TEMPLATE_PRODUCT_TEST_CASE` and `TEMPLATE_LIST_TEST_CASE`. These macros
+are defined in the `catch_template_test_macros.hpp` header, so compiling
+the code examples below also requires
+`#include <catch2/catch_template_test_macros.hpp>`.
+
 
 * **TEMPLATE_TEST_CASE(** _test name_ , _tags_,  _type1_, _type2_, ..., _typen_ **)**
 
-> [Introduced](https://github.com/catchorg/Catch2/issues/1437) in Catch 2.5.0.
+> [Introduced](https://github.com/catchorg/Catch2/issues/1437) in Catch2 2.5.0.
 
 _test name_ and _tag_ are exactly the same as they are in `TEST_CASE`,
 with the difference that the tag string must be provided (however, it
@@ -156,7 +229,7 @@ TEMPLATE_TEST_CASE( "vectors can be sized and resized", "[vector][template]", in
 
 * **TEMPLATE_PRODUCT_TEST_CASE(** _test name_ , _tags_, (_template-type1_, _template-type2_, ..., _template-typen_), (_template-arg1_, _template-arg2_, ..., _template-argm_) **)**
 
-> [Introduced](https://github.com/catchorg/Catch2/issues/1468) in Catch 2.6.0.
+> [Introduced](https://github.com/catchorg/Catch2/issues/1468) in Catch2 2.6.0.
 
 _template-type1_ through _template-typen_ is list of template template
 types which should be combined with each of _template-arg1_ through
@@ -195,13 +268,9 @@ TEMPLATE_PRODUCT_TEST_CASE("Product with differing arities", "[template][product
 }
 ```
 
-_While there is an upper limit on the number of types you can specify
-in single `TEMPLATE_TEST_CASE` or `TEMPLATE_PRODUCT_TEST_CASE`, the limit
-is very high and should not be encountered in practice._
-
 * **TEMPLATE_LIST_TEST_CASE(** _test name_, _tags_, _type list_ **)**
 
-> [Introduced](https://github.com/catchorg/Catch2/issues/1627) in Catch 2.9.0.
+> [Introduced](https://github.com/catchorg/Catch2/issues/1627) in Catch2 2.9.0.
 
 _type list_ is a generic list of types on which test case should be instantiated.
 List can be `std::tuple`, `boost::mpl::list`, `boost::mp11::mp_list` or anything with
@@ -221,12 +290,14 @@ TEMPLATE_LIST_TEST_CASE("Template test case with test types specified inside std
 
 ## Signature based parametrised test cases
 
-> [Introduced](https://github.com/catchorg/Catch2/issues/1609) in Catch 2.8.0.
+> [Introduced](https://github.com/catchorg/Catch2/issues/1609) in Catch2 2.8.0.
 
 In addition to [type parametrised test cases](#type-parametrised-test-cases) Catch2 also supports
 signature base parametrised test cases, in form of `TEMPLATE_TEST_CASE_SIG` and `TEMPLATE_PRODUCT_TEST_CASE_SIG`.
 These test cases have similar syntax like [type parametrised test cases](#type-parametrised-test-cases), with one
-additional positional argument which specifies the signature.
+additional positional argument which specifies the signature. These macros are defined in the
+`catch_template_test_macros.hpp` header, so compiling the code examples below also requires
+`#include <catch2/catch_template_test_macros.hpp>`.
 
 ### Signature
 Signature has some strict rules for these tests cases to work properly:
@@ -243,7 +314,7 @@ Currently Catch2 support up to 11 template parameters in signature
 
 * **TEMPLATE_TEST_CASE_SIG(** _test name_ , _tags_,  _signature_, _type1_, _type2_, ..., _typen_ **)**
 
-Inside `TEMPLATE_TEST_CASE_SIG` test case you can use the names of template parameters as defined in _signature_. 
+Inside `TEMPLATE_TEST_CASE_SIG` test case you can use the names of template parameters as defined in _signature_.
 
 ```cpp
 TEMPLATE_TEST_CASE_SIG("TemplateTestSig: arrays can be created from NTTP arguments", "[vector][template][nttp]",

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

@@ -3,7 +3,7 @@
 
 ## Defining test fixtures
 
-Although Catch allows you to group tests together as sections within a test case, it can still be convenient, sometimes, to group them using a more traditional test fixture. Catch fully supports this too. You define the test fixture as a simple structure:
+Although Catch allows you to group tests together as [sections within a test case](test-cases-and-sections.md), it can still be convenient, sometimes, to group them using a more traditional test fixture. Catch fully supports this too. You define the test fixture as a simple structure:
 
 ```c++
 class UniqueTestsFixture {
@@ -59,7 +59,10 @@ struct Template_Fixture {
     T m_a;
 };
 
-TEMPLATE_TEST_CASE_METHOD(Template_Fixture,"A TEMPLATE_TEST_CASE_METHOD based test run that succeeds", "[class][template]", int, float, double) {
+TEMPLATE_TEST_CASE_METHOD(Template_Fixture,
+                          "A TEMPLATE_TEST_CASE_METHOD based test run that succeeds",
+                          "[class][template]",
+                          int, float, double) {
     REQUIRE( Template_Fixture<TestType>::m_a == 1 );
 }
 
@@ -77,7 +80,11 @@ struct Foo_class {
     }
 };
 
-TEMPLATE_PRODUCT_TEST_CASE_METHOD(Template_Template_Fixture, "A TEMPLATE_PRODUCT_TEST_CASE_METHOD based test succeeds", "[class][template]", (Foo_class, std::vector), int) {
+TEMPLATE_PRODUCT_TEST_CASE_METHOD(Template_Template_Fixture,
+                                  "A TEMPLATE_PRODUCT_TEST_CASE_METHOD based test succeeds",
+                                  "[class][template]",
+                                  (Foo_class, std::vector),
+                                  int) {
     REQUIRE( Template_Template_Fixture<TestType>::m_a.size() == 0 );
 }
 ```
@@ -88,7 +95,7 @@ the limit is very high and should not be encountered in practice._
 
 ## Signature-based parametrised test fixtures
 
-> [Introduced](https://github.com/catchorg/Catch2/issues/1609) in Catch 2.8.0.
+> [Introduced](https://github.com/catchorg/Catch2/issues/1609) in Catch2 2.8.0.
 
 Catch2 also provides `TEMPLATE_TEST_CASE_METHOD_SIG` and `TEMPLATE_PRODUCT_TEST_CASE_METHOD_SIG` to support
 fixtures using non-type template parameters. These test cases work similar to `TEMPLATE_TEST_CASE_METHOD` and `TEMPLATE_PRODUCT_TEST_CASE_METHOD`,
@@ -101,7 +108,12 @@ struct Nttp_Fixture{
     int value = V;
 };
 
-TEMPLATE_TEST_CASE_METHOD_SIG(Nttp_Fixture, "A TEMPLATE_TEST_CASE_METHOD_SIG based test run that succeeds", "[class][template][nttp]",((int V), V), 1, 3, 6) {
+TEMPLATE_TEST_CASE_METHOD_SIG(
+    Nttp_Fixture,
+    "A TEMPLATE_TEST_CASE_METHOD_SIG based test run that succeeds",
+    "[class][template][nttp]",
+    ((int V), V),
+    1, 3, 6) {
     REQUIRE(Nttp_Fixture<V>::value > 0);
 }
 
@@ -117,8 +129,13 @@ struct Template_Foo_2 {
     size_t size() { return V; }
 };
 
-TEMPLATE_PRODUCT_TEST_CASE_METHOD_SIG(Template_Fixture_2, "A TEMPLATE_PRODUCT_TEST_CASE_METHOD_SIG based test run that succeeds", "[class][template][product][nttp]", ((typename T, size_t S), T, S),(std::array, Template_Foo_2), ((int,2), (float,6)))
-{
+TEMPLATE_PRODUCT_TEST_CASE_METHOD_SIG(
+    Template_Fixture_2,
+    "A TEMPLATE_PRODUCT_TEST_CASE_METHOD_SIG based test run that succeeds",
+    "[class][template][product][nttp]",
+    ((typename T, size_t S), T, S),
+    (std::array, Template_Foo_2),
+    ((int,2), (float,6))) {
     REQUIRE(Template_Fixture_2<TestType>{}.m_a.size() >= 2);
 }
 ```
@@ -132,8 +149,10 @@ only difference is the source of types. This allows you to reuse the template ty
 Example:
 ```cpp
 using MyTypes = std::tuple<int, char, double>;
-TEMPLATE_LIST_TEST_CASE_METHOD(Template_Fixture, "Template test case method with test types specified inside std::tuple", "[class][template][list]", MyTypes)
-{
+TEMPLATE_LIST_TEST_CASE_METHOD(Template_Fixture,
+                               "Template test case method with test types specified inside std::tuple",
+                               "[class][template][list]",
+                               MyTypes) {
     REQUIRE( Template_Fixture<TestType>::m_a == 1 );
 }
 ```