From 5b4ffd3c9368fe3d2ab2f0bd4b28825b2d0edddb Mon Sep 17 00:00:00 2001 From: Jozef Grajciar Date: Sun, 25 Nov 2018 14:45:37 +0100 Subject: [PATCH] Docs: added docs for TEMPLATE_PRODUCT_TEST_CASE --- docs/test-cases-and-sections.md | 46 ++++++++++++++++++++++++++++++--- docs/test-fixtures.md | 38 ++++++++++++++++++++++----- docs/tutorial.md | 5 ++-- 3 files changed, 77 insertions(+), 12 deletions(-) diff --git a/docs/test-cases-and-sections.md b/docs/test-cases-and-sections.md index 50de14bf..abd55cd0 100644 --- a/docs/test-cases-and-sections.md +++ b/docs/test-cases-and-sections.md @@ -95,7 +95,8 @@ Other than the additional prefixes and the formatting in the console reporter th ## Type parametrised test cases In addition to `TEST_CASE`s, Catch2 also supports test cases parametrised -by type, in the form of `TEMPLATE_TEST_CASE`. +by types, in the form of `TEMPLATE_TEST_CASE` and +`TEMPLATE_PRODUCT_TEST_CASE`. * **TEMPLATE_TEST_CASE(** _test name_ , _tags_, _type1_, _type2_, ..., _typen_ **)** @@ -147,9 +148,48 @@ 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_) **)** + +_template-type1_ through _template-typen_ is list of template template +types which should be combined with each of _template-arg1_ through + _template-argm_, resulting in _n * m_ test cases. Inside the test case, +the resulting type is available under the name of `TestType`. + +To specify more than 1 type as a single _template-type_ or _template-arg_, +you must enclose the types in an additional set of parentheses, e.g. +`((int, float), (char, double))` specifies 2 template-args, each +consisting of 2 concrete types (`int`, `float` and `char`, `double` +respectively). You can also omit the outer set of parentheses if you +specify only one type as the full set of either the _template-types_, +or the _template-args_. + + +Example: +``` +template< typename T> +struct Foo { + size_t size() { + return 0; + } +}; + +TEMPLATE_PRODUCT_TEST_CASE("A Template product test case", "[template][product]", (std::vector, Foo), (int, float)) { + TestType x; + REQUIRE(x.size() == 0); +} +``` + +You can also have different arities in the _template-arg_ packs: +``` +TEMPLATE_PRODUCT_TEST_CASE("Product with differing arities", "[template][product]", std::tuple, (int, (int, double), (int, double, float))) { + TestType x; + REQUIRE(std::tuple_size::value >= 1); +} +``` + _While there is an upper limit on the number of types you can specify -in single `TEMPLATE_TEST_CASE`, the limit is very high and should not -be encountered in practice._ +in single `TEMPLATE_TEST_CASE` or `TEMPLATE_PRODUCT_TEST_CASE`, the limit +is very high and should not be encountered in practice._ --- diff --git a/docs/test-fixtures.md b/docs/test-fixtures.md index bfdb1b3c..6b29ce68 100644 --- a/docs/test-fixtures.md +++ b/docs/test-fixtures.md @@ -31,16 +31,22 @@ class UniqueTestsFixture { The two test cases here will create uniquely-named derived classes of UniqueTestsFixture and thus can access the `getID()` protected method and `conn` member variables. This ensures that both the test cases are able to create a DBConnection using the same method (DRY principle) and that any ID's created are unique such that the order that tests are executed does not matter. -Catch2 also provides `TEMPLATE_TEST_CASE_METHOD` that can be used together -with templated fixtures to perform tests for multiple different types. -However, unlike `TEST_CASE_METHOD`, `TEMPLATE_TEST_CASE_METHOD` requires -the tag specification to be non-empty, as it is followed by further macros -arguments. +Catch2 also provides `TEMPLATE_TEST_CASE_METHOD` and +`TEMPLATE_PRODUCT_TEST_CASE_METHOD` that can be used together +with templated fixtures and templated template fixtures to perform +tests for multiple different types. Unlike `TEST_CASE_METHOD`, +`TEMPLATE_TEST_CASE_METHOD` and `TEMPLATE_PRODUCT_TEST_CASE_METHOD` do +require the tag specification to be non-empty, as it is followed by +further macro arguments. Also note that, because of limitations of the C++ preprocessor, if you want to specify a type with multiple template parameters, you need to enclose it in parentheses, e.g. `std::map` needs to be passed as `(std::map)`. +In the case of `TEMPLATE_PRODUCT_TEST_CASE_METHOD`, if a member of the +type list should consist of more than single type, it needs to be enclosed +in another pair of parentheses, e.g. `(std::map, std::pair)` and +`((int, float), (char, double))`. Example: ```cpp @@ -54,11 +60,29 @@ struct Template_Fixture { TEMPLATE_TEST_CASE_METHOD(Template_Fixture,"A TEMPLATE_TEST_CASE_METHOD based test run that succeeds", "[class][template]", int, float, double) { REQUIRE( Template_Fixture::m_a == 1 ); } + +template +struct Template_Template_Fixture { + Template_Template_Fixture() {} + + T m_a; +}; + +template +struct Foo_class { + size_t size() { + return 0; + } +}; + +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::m_a.size() == 0 ); +} ``` _While there is an upper limit on the number of types you can specify -in single `TEMPLATE_TEST_CASE`, the limit is very high and should not -be encountered in practice._ +in single `TEMPLATE_TEST_CASE_METHOD` or `TEMPLATE_PRODUCT_TEST_CASE_METHOD`, +the limit is very high and should not be encountered in practice._ --- diff --git a/docs/tutorial.md b/docs/tutorial.md index 247d5d86..7c0f8145 100644 --- a/docs/tutorial.md +++ b/docs/tutorial.md @@ -260,8 +260,9 @@ Do not write your tests in header files! ## Type parametrised test cases Test cases in Catch2 can be also parametrised by type, via the -`TEMPLATE_TEST_CASE` macro, which behaves in the same way the `TEST_CASE` -macro, but is run for every type. +`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. For more details, see our documentation on [test cases and sections](test-cases-and-sections.md#type-parametrised-test-cases).