From cef22753c410b940016e779cf7a625d678b24136 Mon Sep 17 00:00:00 2001
From: Alex Overchenko <alex.overchenko@axonim.by>
Date: Sun, 27 Nov 2022 14:20:03 +0300
Subject: [PATCH] Adding param tests documentation. Describe TEST_CASE logic.

---
 docs/UnityHelperScriptsGuide.md | 60 +++++++++++++++++++++++++++++++++
 1 file changed, 60 insertions(+)

diff --git a/docs/UnityHelperScriptsGuide.md b/docs/UnityHelperScriptsGuide.md
index b430c41..c31baa4 100644
--- a/docs/UnityHelperScriptsGuide.md
+++ b/docs/UnityHelperScriptsGuide.md
@@ -179,6 +179,66 @@ This option specifies the pattern for matching acceptable source file extensions
 By default it will accept cpp, cc, C, c, and ino files.
 If you need a different combination of files to search, update this from the default `'(?:cpp|cc|ino|C|c)'`.
 
+##### `:use_param_tests`
+
+This option enables parameterized test usage.
+That tests accepts arguments from `TEST_CASE` and `TEST_RANGE` macros,
+that are located above current test definition.
+By default, Unity assumes, that parameterized tests are disabled.
+
+Few usage examples can be found in `/test/tests/test_unity_parameterized.c` file.
+
+You should define `UNITY_SUPPORT_TEST_CASES` macro for tests success compiling,
+if you enable current option.
+
+You can see list of supported macros list in the next section.
+
+#### Parameterized tests provided macros
+
+Unity provides support for few param tests generators, that can be combined
+with each other. You must define test function as usual C function with usual
+C arguments, and test generator will pass what you tell as a list of arguments.
+
+Let's show how all of them works on the following test function definitions:
+
+```C
+/* Place your test generators here, usually one generator per one or few lines */
+void test_demoParamFunction(int a, int b, int c)
+{
+  TEST_ASSERT_GREATER_THAN_INT(a + b, c);
+}
+```
+
+##### `TEST_CASE`
+
+Test case is a basic generator, that can be used for param testing.
+One call of that macro will generate only one call for test function.
+It can be used with different args, such as numbers, enums, strings,
+global variables, another preprocessor defines.
+
+If we use replace comment before test function with the following code:
+
+```C
+TEST_CASE(1, 2, 5)
+TEST_CASE(3, 7, 20)
+```
+
+script will generate 2 test calls:
+
+```C
+test_demoParamFunction(1, 2, 5);
+test_demoParamFunction(3, 7, 20);
+```
+
+That calls will be wrapped with `setUp`, `tearDown` and other
+usual Unity calls, as an independent unit tests.
+The following output can be generated after test executable startup:
+
+```Log
+tests/test_unity_parameterized.c:9:test_demoParamFunction(1, 2, 5):PASS
+tests/test_unity_parameterized.c:9:test_demoParamFunction(3, 7, 20):PASS
+```
+
 ### `unity_test_summary.rb`
 
 A Unity test file contains one or more test case functions.