From 732e4b06db8779bf8bb586a71769256362b42821 Mon Sep 17 00:00:00 2001
From: Jozef Grajciar <jozef.grajciar@gmail.com>
Date: Wed, 24 Apr 2019 17:04:13 +0200
Subject: [PATCH] docs for signature based parametrised test cases

---
 docs/test-cases-and-sections.md | 51 +++++++++++++++++++++++++++++++++
 docs/test-fixtures.md           | 27 +++++++++++++++++
 2 files changed, 78 insertions(+)

diff --git a/docs/test-cases-and-sections.md b/docs/test-cases-and-sections.md
index 62a805f4..8a494b5c 100644
--- a/docs/test-cases-and-sections.md
+++ b/docs/test-cases-and-sections.md
@@ -6,6 +6,7 @@
 [Tag aliases](#tag-aliases)<br>
 [BDD-style test cases](#bdd-style-test-cases)<br>
 [Type parametrised test cases](#type-parametrised-test-cases)<br>
+[Signature based parametrised test cases](#signature-based-parametrised-test-cases)<br>
 
 While Catch fully supports the traditional, xUnit, style of class-based fixtures containing test case methods this is not the preferred style.
 
@@ -191,6 +192,56 @@ _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._
 
+
+## Signature based parametrised test cases
+
+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.
+
+### Signature
+Signature has some strict rules for these tests cases to work properly:
+* signature with multiple template parameters e.g. `typename T, size_t S` must have this format in test case declaration
+  `((typename T, size_t S), T, S)`
+* signature with variadic template arguments e.g. `typename T, size_t S, typename...Ts` must have this format in test case declaration
+  `((typename T, size_t S, typename...Ts), T, S, Ts...)`
+* signature with single non type template parameter e.g. `int V` must have this format in test case declaration `((int V), V)`
+* signature with single type template parameter e.g. `typename T` should not be used as it is in fact `TEMPLATE_TEST_CASE`
+
+Currently Catch2 support up to 11 template parameters in signature
+
+### Examples
+
+* **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_. 
+
+```cpp
+TEMPLATE_TEST_CASE_SIG("TemplateTestSig: arrays can be created from NTTP arguments", "[vector][template][nttp]",
+  ((typename T, int V), T, V), (int,5), (float,4), (std::string,15), ((std::tuple<int, float>), 6)) {
+
+    std::array<T, V> v;
+    REQUIRE(v.size() > 1);
+}
+```
+
+* **TEMPLATE_PRODUCT_TEST_CASE_SIG(** _test name_ , _tags_, _signature_, (_template-type1_, _template-type2_, ..., _template-typen_), (_template-arg1_, _template-arg2_, ..., _template-argm_) **)**
+
+```cpp
+
+template<typename T, size_t S>
+struct Bar {
+    size_t size() { return S; }
+};
+
+TEMPLATE_PRODUCT_TEST_CASE_SIG("A Template product test case with array signature", "[template][product][nttp]", ((typename T, size_t S), T, S), (std::array, Bar), ((int, 9), (float, 42))) {
+    TestType x;
+    REQUIRE(x.size() > 0);
+}
+```
+
+
 ---
 
 [Home](Readme.md#top)
diff --git a/docs/test-fixtures.md b/docs/test-fixtures.md
index 6b29ce68..5a2d4df5 100644
--- a/docs/test-fixtures.md
+++ b/docs/test-fixtures.md
@@ -84,6 +84,33 @@ _While there is an upper limit on the number of types you can specify
 in single `TEMPLATE_TEST_CASE_METHOD` or `TEMPLATE_PRODUCT_TEST_CASE_METHOD`,
 the limit is very high and should not be encountered in practice._
 
+
+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`,
+with additional positional argument for [signature](test-cases-and-sections.md#signature-based-parametrised-test-cases).
+
+Example:
+```cpp
+template <int V>
+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) {
+    REQUIRE(Nttp_Fixture<V>::value > 0);
+}
+
+template< typename T, size_t V>
+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)))
+{
+    REQUIRE(Template_Fixture_2<TestType>{}.m_a.size() >= 2);
+}
+```
+
 ---
 
 [Home](Readme.md#top)