Merge pull request #71 from bxparks/develop

merge v1.5.4 into master

Author: bxparks

CHANGELOG.md

@@ -1,14 +1,18 @@
 # Changelog
 
 * Unreleased
+* 1.5.4 (2021-03-02)
+    * Implement `assertNoFatalFailure(statement)` macro to prevent continued
+      execution if `statement` contains assertion failures. Fixes
+      [Issue #11](https://github.com/bxparks/AUnit/issues/11).
 * 1.5.3 (2021-02-23)
     * I botched the 1.5.2 release. Try again as 1.5.3.
 * 1.5.2 (2021-02-23)
     * Convert `examples/AUnitPlatformIO/src/AUnitPlatformIO.ino` from
       a symlink to a regular file. The Arduino Library Manager apparently does
       not allow symlinks (see
       https://github.com/arduino/Arduino/wiki/Library-Manager-FAQ). So when I
-      created the symlink at v1.3 on 2019-06-05, the Library Manager stopped
+      created the symlink at v1.3.1 on 2019-07-31, the Library Manager stopped
       updating the library for almost 2 years, until I removed the symlink at
       v1.5.2.
     * No functional change in this release.

README.md

@@ -20,7 +20,7 @@ instead of having to go through the Arduino IDE. Both the AUniter and
 EpoxyDuino tools can be used in a continuous integration system like Jenkins,
 or with [GitHub Actions](https://github.com/features/actions).
 
-**Version**: 1.5.3 (2021-02-23)
+**Version**: 1.5.4 (2021-03-02)
 
 **Changelog**: [CHANGELOG.md](CHANGELOG.md)
 
@@ -862,57 +862,46 @@ method only. The statement after the `assertCustomStuff()` will continue to
 execute.
 
 In other words, in the following example, if the `assertCustomStuff()` fails,
-then `doStuff()` inside `testF()` will execute:
+then `assertMoreStuff()` inside `testF()` will execute:
 
 ```C++
 class CustomTestOnce: public TestOnce {
   protected:
-    // optional
-    void setup() override {
-      TestOnce::setup();
-      ...setup code...
-    }
-
-    // optional
-    void teardown() override {
-      ...teardown code...
-      TestOnce::teardown();
-    }
-
     void assertCustomStuff() {
       assertEqual(sharedValue, 3);
 
-      // This will not execute if the assertEqual() failed.
+      // This will not execute if the assertEqual() above fails.
       assertLess(...);
     }
 
+    void assertMoreStuff() {
+      assertEqual(...);
+    }
+
     int sharedValue;
 };
 
-testF(CustomTestOnce, calculate) {
+// DON'T DO THIS
+testF(CustomTestOnce, dontDoThis) {
   assertCustomStuff();
 
-  // This will execute even if assertCustomStuff() failed.
-  doStuff();
-
-  // This will immediately exit this method if assertCustomStuff() failed.
-  assertTrue(true);
+  // This will execute even if assertCustomStuff() fails.
+  assertMoreStuff();
+}
 
-  // This will NOT execute if assertCustomStuff() failed.
-  doMoreStuff();
+// DO THIS INSTEAD
+testF(CustomTestOnce, doThis) {
+  assertNoFatalFailure(assertCustomStuff());
+  assertNoFatalFailure(assertMoreStuff());
 }
 ```
 
-AUnit tries to mitigate this problem by having every `assertXxx()` macro
-perform a check to see if a previous assert statement raise an error condition
-for the test. If so, then the assert macro immediately exits. In the code above,
-`doMoreStuff()` will not execute, because the `assertNotEqual()` will immidately
-exit upon detecting the failure of `assertCustomStuff()`.
-
-Google Test has a
-[ASSERT_NO_FATAL_FAILURE( statement)](https://github.com/google/googletest/blob/master/googletest/docs/AdvancedGuide.md)
-macro that can guard against this possibility. AUnit does not have that macro,
-but we get the equivalent effect by doing a `assertTrue(true)` shown above.
+The solution is to use the `assertNoFatalFailure(statement)` macro which checks
+whether the inner `statement` returned with a fatal assertion. If so, then it
+returns immediately, preventing execution from continuing to the code that
+follows. This macro is modeled after the
+[ASSERT_NO_FATAL_FAILURE(statement)](https://github.com/google/googletest/blob/master/docs/advanced.md)
+macro in Google Test that provides the same functionality.
 
 <a name="MetaAssertions"></a>
 ### Meta Assertions

docs/doxygen.cfg

@@ -38,7 +38,7 @@ PROJECT_NAME           = "AUnit"
 # could be handy for archiving the generated documentation or if some version
 # control system is used.
 
-PROJECT_NUMBER         = 1.5.3
+PROJECT_NUMBER         = 1.5.4
 
 # Using the PROJECT_BRIEF tag one can provide an optional one line description
 # for a project that appears at the top of each page and should give viewer a

docs/html/AUnitVerbose_8h.html

@@ -22,7 +22,7 @@
  <tr style="height: 56px;">
   <td id="projectalign" style="padding-left: 0.5em;">
    <div id="projectname">AUnit
-   &#160;<span id="projectnumber">1.5.3</span>
+   &#160;<span id="projectnumber">1.5.4</span>
    </div>
    <div id="projectbrief">Unit testing framework for Arduino platforms inspired by ArduinoUnit and Google Test.</div>
   </td>
@@ -120,10 +120,10 @@
 <tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="define-members"></a>
 Macros</h2></td></tr>
 <tr class="memitem:a87cbb10969eff63f8ae66afc4e9457eb"><td class="memItemLeft" align="right" valign="top"><a id="a87cbb10969eff63f8ae66afc4e9457eb"></a>
-#define&#160;</td><td class="memItemRight" valign="bottom"><b>AUNIT_VERSION</b>&#160;&#160;&#160;10503</td></tr>
+#define&#160;</td><td class="memItemRight" valign="bottom"><b>AUNIT_VERSION</b>&#160;&#160;&#160;10504</td></tr>
 <tr class="separator:a87cbb10969eff63f8ae66afc4e9457eb"><td class="memSeparator" colspan="2">&#160;</td></tr>
 <tr class="memitem:a70ade1487f0d9d7172f24897cd0f2dd5"><td class="memItemLeft" align="right" valign="top"><a id="a70ade1487f0d9d7172f24897cd0f2dd5"></a>
-#define&#160;</td><td class="memItemRight" valign="bottom"><b>AUNIT_VERSION_STRING</b>&#160;&#160;&#160;&quot;1.5.3&quot;</td></tr>
+#define&#160;</td><td class="memItemRight" valign="bottom"><b>AUNIT_VERSION_STRING</b>&#160;&#160;&#160;&quot;1.5.4&quot;</td></tr>
 <tr class="separator:a70ade1487f0d9d7172f24897cd0f2dd5"><td class="memSeparator" colspan="2">&#160;</td></tr>
 </table>
 <a name="details" id="details"></a><h2 class="groupheader">Detailed Description</h2>

docs/html/AUnitVerbose_8h_source.html

@@ -22,7 +22,7 @@
  <tr style="height: 56px;">
   <td id="projectalign" style="padding-left: 0.5em;">
    <div id="projectname">AUnit
-   &#160;<span id="projectnumber">1.5.3</span>
+   &#160;<span id="projectnumber">1.5.4</span>
    </div>
    <div id="projectbrief">Unit testing framework for Arduino platforms inspired by ArduinoUnit and Google Test.</div>
   </td>
@@ -122,8 +122,8 @@
 <div class="line"><a name="l00059"></a><span class="lineno">   59</span>&#160;<span class="preprocessor">#include &quot;<a class="code" href="TestMacros_8h.html">aunit/TestMacros.h</a>&quot;</span></div>
 <div class="line"><a name="l00060"></a><span class="lineno">   60</span>&#160; </div>
 <div class="line"><a name="l00061"></a><span class="lineno">   61</span>&#160;<span class="comment">// Version format: xxyyzz == &quot;xx.yy.zz&quot;</span></div>
-<div class="line"><a name="l00062"></a><span class="lineno">   62</span>&#160;<span class="preprocessor">#define AUNIT_VERSION 10503</span></div>
-<div class="line"><a name="l00063"></a><span class="lineno">   63</span>&#160;<span class="preprocessor">#define AUNIT_VERSION_STRING &quot;1.5.3&quot;</span></div>
+<div class="line"><a name="l00062"></a><span class="lineno">   62</span>&#160;<span class="preprocessor">#define AUNIT_VERSION 10504</span></div>
+<div class="line"><a name="l00063"></a><span class="lineno">   63</span>&#160;<span class="preprocessor">#define AUNIT_VERSION_STRING &quot;1.5.4&quot;</span></div>
 <div class="line"><a name="l00064"></a><span class="lineno">   64</span>&#160; </div>
 <div class="line"><a name="l00065"></a><span class="lineno">   65</span>&#160;<span class="preprocessor">#endif</span></div>
 </div><!-- fragment --></div><!-- contents -->

docs/html/AUnit_8h.html

@@ -22,7 +22,7 @@
  <tr style="height: 56px;">
   <td id="projectalign" style="padding-left: 0.5em;">
    <div id="projectname">AUnit
-   &#160;<span id="projectnumber">1.5.3</span>
+   &#160;<span id="projectnumber">1.5.4</span>
    </div>
    <div id="projectbrief">Unit testing framework for Arduino platforms inspired by ArduinoUnit and Google Test.</div>
   </td>
@@ -120,10 +120,10 @@
 <tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="define-members"></a>
 Macros</h2></td></tr>
 <tr class="memitem:a87cbb10969eff63f8ae66afc4e9457eb"><td class="memItemLeft" align="right" valign="top"><a id="a87cbb10969eff63f8ae66afc4e9457eb"></a>
-#define&#160;</td><td class="memItemRight" valign="bottom"><b>AUNIT_VERSION</b>&#160;&#160;&#160;10503</td></tr>
+#define&#160;</td><td class="memItemRight" valign="bottom"><b>AUNIT_VERSION</b>&#160;&#160;&#160;10504</td></tr>
 <tr class="separator:a87cbb10969eff63f8ae66afc4e9457eb"><td class="memSeparator" colspan="2">&#160;</td></tr>
 <tr class="memitem:a70ade1487f0d9d7172f24897cd0f2dd5"><td class="memItemLeft" align="right" valign="top"><a id="a70ade1487f0d9d7172f24897cd0f2dd5"></a>
-#define&#160;</td><td class="memItemRight" valign="bottom"><b>AUNIT_VERSION_STRING</b>&#160;&#160;&#160;&quot;1.5.3&quot;</td></tr>
+#define&#160;</td><td class="memItemRight" valign="bottom"><b>AUNIT_VERSION_STRING</b>&#160;&#160;&#160;&quot;1.5.4&quot;</td></tr>
 <tr class="separator:a70ade1487f0d9d7172f24897cd0f2dd5"><td class="memSeparator" colspan="2">&#160;</td></tr>
 </table>
 <a name="details" id="details"></a><h2 class="groupheader">Detailed Description</h2>

docs/html/AUnit_8h_source.html

@@ -22,7 +22,7 @@
  <tr style="height: 56px;">
   <td id="projectalign" style="padding-left: 0.5em;">
    <div id="projectname">AUnit
-   &#160;<span id="projectnumber">1.5.3</span>
+   &#160;<span id="projectnumber">1.5.4</span>
    </div>
    <div id="projectbrief">Unit testing framework for Arduino platforms inspired by ArduinoUnit and Google Test.</div>
   </td>
@@ -122,8 +122,8 @@
 <div class="line"><a name="l00069"></a><span class="lineno">   69</span>&#160;<span class="preprocessor">#include &quot;<a class="code" href="TestMacros_8h.html">aunit/TestMacros.h</a>&quot;</span></div>
 <div class="line"><a name="l00070"></a><span class="lineno">   70</span>&#160; </div>
 <div class="line"><a name="l00071"></a><span class="lineno">   71</span>&#160;<span class="comment">// Version format: xxyyzz == &quot;xx.yy.zz&quot;</span></div>
-<div class="line"><a name="l00072"></a><span class="lineno">   72</span>&#160;<span class="preprocessor">#define AUNIT_VERSION 10503</span></div>
-<div class="line"><a name="l00073"></a><span class="lineno">   73</span>&#160;<span class="preprocessor">#define AUNIT_VERSION_STRING &quot;1.5.3&quot;</span></div>
+<div class="line"><a name="l00072"></a><span class="lineno">   72</span>&#160;<span class="preprocessor">#define AUNIT_VERSION 10504</span></div>
+<div class="line"><a name="l00073"></a><span class="lineno">   73</span>&#160;<span class="preprocessor">#define AUNIT_VERSION_STRING &quot;1.5.4&quot;</span></div>
 <div class="line"><a name="l00074"></a><span class="lineno">   74</span>&#160; </div>
 <div class="line"><a name="l00075"></a><span class="lineno">   75</span>&#160;<span class="preprocessor">#endif</span></div>
 </div><!-- fragment --></div><!-- contents -->

docs/html/AssertMacros_8h.html

@@ -22,7 +22,7 @@
  <tr style="height: 56px;">
   <td id="projectalign" style="padding-left: 0.5em;">
    <div id="projectname">AUnit
-   &#160;<span id="projectnumber">1.5.3</span>
+   &#160;<span id="projectnumber">1.5.4</span>
    </div>
    <div id="projectbrief">Unit testing framework for Arduino platforms inspired by ArduinoUnit and Google Test.</div>
   </td>
@@ -139,6 +139,9 @@
 <tr class="memitem:a780f10370d41f109377629af76c84f78"><td class="memItemLeft" align="right" valign="top">#define&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="AssertMacros_8h.html#a780f10370d41f109377629af76c84f78">assertNotNear</a>(arg1,  arg2,  error)</td></tr>
 <tr class="memdesc:a780f10370d41f109377629af76c84f78"><td class="mdescLeft">&#160;</td><td class="mdescRight">Assert that arg1 and arg2 are NOT within error of each other.  <a href="AssertMacros_8h.html#a780f10370d41f109377629af76c84f78">More...</a><br /></td></tr>
 <tr class="separator:a780f10370d41f109377629af76c84f78"><td class="memSeparator" colspan="2">&#160;</td></tr>
+<tr class="memitem:a9d2a603b6fbf3bcee3ce0a74c77c06b3"><td class="memItemLeft" align="right" valign="top">#define&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="AssertMacros_8h.html#a9d2a603b6fbf3bcee3ce0a74c77c06b3">assertNoFatalFailure</a>(statement)</td></tr>
+<tr class="memdesc:a9d2a603b6fbf3bcee3ce0a74c77c06b3"><td class="mdescLeft">&#160;</td><td class="mdescRight">Assert that the inner 'statement' returns with no fatal assertions.  <a href="AssertMacros_8h.html#a9d2a603b6fbf3bcee3ce0a74c77c06b3">More...</a><br /></td></tr>
+<tr class="separator:a9d2a603b6fbf3bcee3ce0a74c77c06b3"><td class="memSeparator" colspan="2">&#160;</td></tr>
 </table>
 <a name="details" id="details"></a><h2 class="groupheader">Detailed Description</h2>
 <div class="textblock"><p>Various assertion macros (assertXxx()) are defined in this header. These macros can be used only in a subclass of TestOnce or TestAgain, which is true for all tests created by <a class="el" href="TestMacros_8h.html#a152fb8fe682506b1b08ddda59abce668" title="Macro to define a test that will be run only once.">test()</a>, <a class="el" href="TestMacros_8h.html#a1f7b0603fa6951be1f019586eafc6e6b" title="Macro to define a test that will run repeatly upon each iteration of the global loop() method,...">testing()</a>, <a class="el" href="TestMacros_8h.html#a4f2798c22904efe9442ce65eb6932a9c" title="Create a test that is derived from a custom TestOnce class.">testF()</a> and <a class="el" href="TestMacros_8h.html#a648c8cb704b9d942b36d8c4646645c2c" title="Create a test that is derived from a custom TestAgain class.">testingF()</a>. </p>
@@ -222,6 +225,33 @@ <h2 class="memtitle"><span class="permalink"><a href="#ab37dc3ab85b61bad53032bde
 
 <p class="definition">Definition at line <a class="el" href="AssertMacros_8h_source.html#l00090">90</a> of file <a class="el" href="AssertMacros_8h_source.html">AssertMacros.h</a>.</p>
 
+</div>
+</div>
+<a id="a9d2a603b6fbf3bcee3ce0a74c77c06b3"></a>
+<h2 class="memtitle"><span class="permalink"><a href="#a9d2a603b6fbf3bcee3ce0a74c77c06b3">&#9670;&nbsp;</a></span>assertNoFatalFailure</h2>
+
+<div class="memitem">
+<div class="memproto">
+      <table class="memname">
+        <tr>
+          <td class="memname">#define assertNoFatalFailure</td>
+          <td>(</td>
+          <td class="paramtype">&#160;</td>
+          <td class="paramname">statement</td><td>)</td>
+          <td></td>
+        </tr>
+      </table>
+</div><div class="memdoc">
+<b>Value:</b><div class="fragment"><div class="line">  <span class="keywordflow">do</span> { \</div>
+<div class="line">  statement; \</div>
+<div class="line">  if (isDone()) return; \</div>
+<div class="line">} while (false)</div>
+</div><!-- fragment -->
+<p>Assert that the inner 'statement' returns with no fatal assertions. </p>
+<p>This is required because AUnit does not use exceptions, so we have to check the assertion state after calling an inner function. This macro is similar to the <code>ASSERT_NO_FATAL_FAILURE(statement)</code> in GoogleTest. </p>
+
+<p class="definition">Definition at line <a class="el" href="AssertMacros_8h_source.html#l00109">109</a> of file <a class="el" href="AssertMacros_8h_source.html">AssertMacros.h</a>.</p>
+
 </div>
 </div>
 <a id="a780f10370d41f109377629af76c84f78"></a>

docs/html/AssertMacros_8h_source.html

@@ -22,7 +22,7 @@
  <tr style="height: 56px;">
   <td id="projectalign" style="padding-left: 0.5em;">
    <div id="projectname">AUnit
-   &#160;<span id="projectnumber">1.5.3</span>
+   &#160;<span id="projectnumber">1.5.4</span>
    </div>
    <div id="projectbrief">Unit testing framework for Arduino platforms inspired by ArduinoUnit and Google Test.</div>
   </td>
@@ -151,7 +151,12 @@
 <div class="line"><a name="l00100"></a><span class="lineno">  100</span>&#160;<span class="preprocessor">    return;\</span></div>
 <div class="line"><a name="l00101"></a><span class="lineno">  101</span>&#160;<span class="preprocessor">} while (false)</span></div>
 <div class="line"><a name="l00102"></a><span class="lineno">  102</span>&#160; </div>
-<div class="line"><a name="l00103"></a><span class="lineno">  103</span>&#160;<span class="preprocessor">#endif</span></div>
+<div class="line"><a name="l00109"></a><span class="lineno"><a class="line" href="AssertMacros_8h.html#a9d2a603b6fbf3bcee3ce0a74c77c06b3">  109</a></span>&#160;<span class="preprocessor">#define assertNoFatalFailure(statement) do { \</span></div>
+<div class="line"><a name="l00110"></a><span class="lineno">  110</span>&#160;<span class="preprocessor">  statement; \</span></div>
+<div class="line"><a name="l00111"></a><span class="lineno">  111</span>&#160;<span class="preprocessor">  if (isDone()) return; \</span></div>
+<div class="line"><a name="l00112"></a><span class="lineno">  112</span>&#160;<span class="preprocessor">} while (false)</span></div>
+<div class="line"><a name="l00113"></a><span class="lineno">  113</span>&#160; </div>
+<div class="line"><a name="l00114"></a><span class="lineno">  114</span>&#160;<span class="preprocessor">#endif</span></div>
 </div><!-- fragment --></div><!-- contents -->
 <!-- start footer part -->
 <hr class="footer"/><address class="footer"><small>