From 99199515fddd2e791bffc69839cdfeeaede32536 Mon Sep 17 00:00:00 2001 From: mvandervoord Date: Tue, 17 Mar 2020 15:01:46 -0400 Subject: [PATCH] Update documentation. Add UNITY_PRINT_TEST_CONTEXT (thanks @jlindgren90 !) Replaces PR #473 --- docs/UnityAssertionsReference.md | 69 +++++++++++++++++++------------- docs/UnityConfigurationGuide.md | 26 ++++++++++-- docs/UnityHelperScriptsGuide.md | 14 ++++++- src/unity.c | 7 ++++ src/unity_internals.h | 4 ++ 5 files changed, 87 insertions(+), 33 deletions(-) diff --git a/docs/UnityAssertionsReference.md b/docs/UnityAssertionsReference.md index 2e4e0ff..58ceb6f 100644 --- a/docs/UnityAssertionsReference.md +++ b/docs/UnityAssertionsReference.md @@ -67,18 +67,20 @@ to be well designed code. The convention of assertion parameters generally follows this order: - TEST_ASSERT_X( {modifiers}, {expected}, actual, {size/count} ) +``` +TEST_ASSERT_X( {modifiers}, {expected}, actual, {size/count} ) +``` -The very simplest assertion possible uses only a single "actual" parameter (e.g. +The very simplest assertion possible uses only a single `actual` parameter (e.g. a simple null check). -"Actual" is the value being tested and unlike the other parameters in an -assertion construction is the only parameter present in all assertion variants. -"Modifiers" are masks, ranges, bit flag specifiers, floating point deltas. -"Expected" is your expected value (duh) to compare to an "actual" value; it's -marked as an optional parameter because some assertions only need a single -"actual" parameter (e.g. null check). -"Size/count" refers to string lengths, number of array elements, etc. + - `Actual` is the value being tested and unlike the other parameters in an + assertion construction is the only parameter present in all assertion variants. + - `Modifiers` are masks, ranges, bit flag specifiers, floating point deltas. + - `Expected` is your expected value (duh) to compare to an `actual` value; it's + marked as an optional parameter because some assertions only need a single + `actual` parameter (e.g. null check). + - `Size/count` refers to string lengths, number of array elements, etc. Many of Unity's assertions are clear duplications in that the same data type is handled by several assertions. The differences among these are in how failure @@ -98,11 +100,15 @@ the reference list below and add a string as the final parameter. _Example:_ - TEST_ASSERT_X( {modifiers}, {expected}, actual, {size/count} ) +``` +TEST_ASSERT_X( {modifiers}, {expected}, actual, {size/count} ) +``` becomes messageified like thus... - TEST_ASSERT_X_MESSAGE( {modifiers}, {expected}, actual, {size/count}, message ) +``` +TEST_ASSERT_X_MESSAGE( {modifiers}, {expected}, actual, {size/count}, message ) +``` Notes: - The `_MESSAGE` variants intentionally do not support `printf` style formatting @@ -122,18 +128,21 @@ with the `_MESSAGE`variants of Unity's Asserts in that for pretty much any Unity type assertion you can tack on `_ARRAY` and run assertions on an entire block of memory. +``` TEST_ASSERT_EQUAL_TYPEX_ARRAY( expected, actual, {size/count} ) +``` -"Expected" is an array itself. -"Size/count" is one or two parameters necessary to establish the number of array -elements and perhaps the length of elements within the array. + - `Expected` is an array itself. + - `Size/count` is one or two parameters necessary to establish the number of array + elements and perhaps the length of elements within the array. Notes: -- The `_MESSAGE` variant convention still applies here to array assertions. The -`_MESSAGE` variants of the `_ARRAY` assertions have names ending with -`_ARRAY_MESSAGE`. -- Assertions for handling arrays of floating point values are grouped with float -and double assertions (see immediately following section). + + - The `_MESSAGE` variant convention still applies here to array assertions. The + `_MESSAGE` variants of the `_ARRAY` assertions have names ending with + `_ARRAY_MESSAGE`. + - Assertions for handling arrays of floating point values are grouped with float + and double assertions (see immediately following section). ### TEST_ASSERT_EACH_EQUAL_X Variants @@ -142,19 +151,22 @@ Unity provides a collection of assertions for arrays containing a variety of types which can be compared to a single value as well. These are documented in the Each Equal section below. these are almost on par with the `_MESSAGE` variants of Unity's Asserts in that for pretty much any Unity type assertion you -can inject _EACH_EQUAL and run assertions on an entire block of memory. +can inject `_EACH_EQUAL` and run assertions on an entire block of memory. - TEST_ASSERT_EACH_EQUAL_TYPEX( expected, actual, {size/count} ) +``` +TEST_ASSERT_EACH_EQUAL_TYPEX( expected, actual, {size/count} ) +``` -"Expected" is a single value to compare to. -"Actual" is an array where each element will be compared to the expected value. -"Size/count" is one of two parameters necessary to establish the number of array -elements and perhaps the length of elements within the array. + - `Expected` is a single value to compare to. + - `Actual` is an array where each element will be compared to the expected value. + - `Size/count` is one of two parameters necessary to establish the number of array + elements and perhaps the length of elements within the array. Notes: -- The `_MESSAGE` variant convention still applies here to Each Equal assertions. -- Assertions for handling Each Equal of floating point values are grouped with -float and double assertions (see immediately following section). + + - The `_MESSAGE` variant convention still applies here to Each Equal assertions. + - Assertions for handling Each Equal of floating point values are grouped with + float and double assertions (see immediately following section). ### Configuration @@ -189,6 +201,7 @@ performing logic beyond a simple assertion. That is, in practice, `TEST_FAIL()` will always be found inside a conditional code block. _Examples:_ + - Executing a state machine multiple times that increments a counter your test code then verifies as a final step. - Triggering an exception and verifying it (as in Try / Catch / Throw - see the diff --git a/docs/UnityConfigurationGuide.md b/docs/UnityConfigurationGuide.md index 7633e0d..e96db03 100644 --- a/docs/UnityConfigurationGuide.md +++ b/docs/UnityConfigurationGuide.md @@ -350,7 +350,7 @@ specifying `UNITY_USE_FLUSH_STDOUT`. No other defines are required. ##### `UNITY_OUTPUT_FOR_QT_CREATOR` When managing your own builds, it is often handy to have messages output in a format which is -recognized by your IDE. These are some standard formats which can be supported. If you're using +recognized by your IDE. These are some standard formats which can be supported. If you're using Ceedling to manage your builds, it is better to stick with the standard format (leaving these all undefined) and allow Ceedling to use its own decorators. @@ -392,6 +392,24 @@ _Example:_ #define UNITY_EXCLUDE_DETAILS ``` +##### `UNITY_PRINT_TEST_CONTEXT` + +This option allows you to specify your own function to print additional context +as part of the error message when a test has failed. It can be useful if you +want to output some specific information about the state of the test at the point +of failure, and `UNITY_SET_DETAILS` isn't flexible enough for your needs. + +_Example:_ +```C +#define UNITY_PRINT_TEST_CONTEXT PrintIterationCount + +extern int iteration_count; + +void PrintIterationCount(void) +{ + UnityPrintFormatted("At iteration #%d: ", iteration_count); +} +``` ##### `UNITY_EXCLUDE_SETJMP` @@ -441,12 +459,12 @@ will allow you to specify how Unity will treat these assertions. #### `UNITY_SUPPORT_VARIADIC_MACROS` -This will force Unity to support variadic macros when using its own built-in +This will force Unity to support variadic macros when using its own built-in RUN_TEST macro. This will rarely be necessary. Most often, Unity will automatically detect if the compiler supports variadic macros by checking to see if it's C99+ compatible. In the event that the compiler supports variadic macros, but is primarily -C89 (ANSI), defining this option will allow you to use them. This option is also not -necessary when using Ceedling or the test runner generator script. +C89 (ANSI), defining this option will allow you to use them. This option is also not +necessary when using Ceedling or the test runner generator script. ## Getting Into The Guts diff --git a/docs/UnityHelperScriptsGuide.md b/docs/UnityHelperScriptsGuide.md index da56db2..46c9d74 100644 --- a/docs/UnityHelperScriptsGuide.md +++ b/docs/UnityHelperScriptsGuide.md @@ -48,7 +48,7 @@ ruby generate_test_runner.rb TestFile.c NameOfRunner.c ``` Alternatively, if you include only the test file parameter, the script will copy -the name of the test file and automatically append "_Runner" to the name of the +the name of the test file and automatically append `_Runner` to the name of the generated file. The example immediately below will create TestFile_Runner.c. ```Shell @@ -194,6 +194,18 @@ If you are using CMock, it is very likely that you are already passing an array of plugins to CMock. You can just use the same array here. This script will just ignore the plugins that don't require additional support. +##### `:include_extensions` + +This option specifies the pattern for matching acceptable header file extensions. +By default it will accept hpp, hh, H, and h files. If you need a different combination +of files to search, update this from the default `'(?:hpp|hh|H|h)'`. + +##### `:source_extensions` + +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)'`. + ### `unity_test_summary.rb` diff --git a/src/unity.c b/src/unity.c index aa8074c..90ea672 100644 --- a/src/unity.c +++ b/src/unity.c @@ -566,6 +566,10 @@ static void UnityAddMsgIfSpecified(const char* msg) if (msg) { UnityPrint(UnityStrSpacer); + +#ifdef UNITY_PRINT_TEST_CONTEXT + UNITY_PRINT_TEST_CONTEXT(); +#endif #ifndef UNITY_EXCLUDE_DETAILS if (Unity.CurrentDetail1) { @@ -1760,6 +1764,9 @@ void UnityFail(const char* msg, const UNITY_LINE_TYPE line) { UNITY_OUTPUT_CHAR(':'); +#ifdef UNITY_PRINT_TEST_CONTEXT + UNITY_PRINT_TEST_CONTEXT(); +#endif #ifndef UNITY_EXCLUDE_DETAILS if (Unity.CurrentDetail1) { diff --git a/src/unity_internals.h b/src/unity_internals.h index eda066e..cdf1374 100644 --- a/src/unity_internals.h +++ b/src/unity_internals.h @@ -509,6 +509,10 @@ void UnityDefaultTestRun(UnityTestFunction Func, const char* FuncName, const int #endif #endif +#ifdef UNITY_PRINT_TEST_CONTEXT +void UNITY_PRINT_TEST_CONTEXT(void); +#endif + /*------------------------------------------------------- * Test Output *-------------------------------------------------------*/