Merge pull request #94 from bxparks/develop

merge 1.7.0 into master

.github/workflows/aunit_tests.yml

@@ -5,10 +5,10 @@ on: [push]
 jobs:
   build:
 
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
 
     - name: Setup
       run: |

CHANGELOG.md

@@ -1,6 +1,16 @@
 # Changelog
 
 * Unreleased
+* 1.7.0 (2022-12-08)
+    * **Potentially Breaking** Change format of assertion failure message from:
+        * "Assertion failed: (expected=3) == (counter=4), file AUnitTest.ino,
+          line 134.", to
+        * "AUnitTest.ino:134: Assertion failed: (expected=3) == (counter=4)."
+        * This format is compatible with various Linux/MacOS/Unix command line
+          tools, in particular, the `vim` editor.
+        * When used with EpoxyDuino, this message format allows the `vim` editor
+          to jump directly to the file and line where the assertion failure
+          occurred.
 * 1.6.1 (2022-02-02)
     * Upgrade tool chain.
         * Arduino IDE from 1.8.13 to 1.8.19

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.6.1 (2022-02-02)
+**Version**: 1.7.0 (2022-12-08)
 
 **Changelog**: [CHANGELOG.md](CHANGELOG.md)
 
@@ -40,6 +40,7 @@ or with [GitHub Actions](https://github.com/features/actions).
     * [Defining the Tests](#DefiningTests)
     * [Generated Class and Instance Names](#GeneratedClass)
     * [Binary Assertions](#BinaryAssertions)
+        * [Assertion Message Format](#AssertionMessageFormat)
         * [Supported Parameter Types](#SupportedParameterTypes)
         * [Parameter Types Must Match](#ParameterTypesMustMatch)
         * [Pointer Comparisons](#PointerComparisons)
@@ -501,6 +502,35 @@ are available. These are essentially identical to ArduinoUnit:
 * `assertLessOrEqual(a, b)`
 * `assertMoreOrEqual(a, b)`
 
+<a name="AssertionMessageFormat"></a>
+#### Assertion Message Format
+
+When the assertion passes, nothing is printed by default. This can be controlled
+by the `TestRunner::setVerbosity()` method. See [Controlling
+Verbosity](#ControllingVerbosity).
+
+When the assertion fails, an error message of the following format is printed:
+
+```
+SampleTest.ino:10: Assertion failed: (2) == (1)
+```
+
+The format of the assertion failure messages was changed in v1.7 to the
+following:
+```
+{filName}:{lineNumber}: Assertion failed: {expression}
+```
+
+This format is a widely used in many other programs, for example, the C compiler
+`gcc`, the C++ compiler `g++`, the Python 3 interpreter `python3`, `grep`, and
+the GNU Make program `make`. In particular, the
+[quickfix](https://vimhelp.org/quickfix.txt.html) feature in the `vim` text
+editor can parse this error format and jump directly to the `fileName` and
+`lineNumber` indicated by the error message. See the instructions in
+[EpoxyDuino](https://github.com/bxparks/EpoxyDuino) to see how to run unit tests
+on a Linux or MacOS machine inside the `vim` editor so that the editor jumps
+directly to the files and line numbers where the assertion failure occurred.
+
 <a name="SupportedParameterTypes"></a>
 #### Supported Parameter Types
 
@@ -527,7 +557,7 @@ following 18 combinations for their parameter types:
 * `(const __FlashStringHelper*, const String&)`
 * `(const __FlashStringHelper*, const __FlashStringHelper*)`
 
-The `assertEqual()` and `assertNotEqual()` support arbitary pointer types
+The `assertEqual()` and `assertNotEqual()` support arbitrary pointer types
 through implicit casts to `const void*`:
 
 * `(const void*, const void*)` (since v1.4)
@@ -643,7 +673,7 @@ test(voidPointer) {
 
 This test will fail with the following error message:
 ```
-Assertion failed: (aa=0x3FFFFF38) == (bb=0x3FFFFF30), file AUnitTest.ino, line 338.
+AUnitTest.ino:338: Assertion failed: (aa=0x3FFFFF38) == (bb=0x3FFFFF30).
 Test voidPointer failed.
 ```
 
@@ -659,7 +689,7 @@ test(nullPointer) {
 This will print the following:
 
 ```
-Assertion failed: (aa=0x3FFFFF58) == (nullptr=0x0), file AUnitTest.ino, line 348.
+AUnitTest.ino:348: Assertion failed: (aa=0x3FFFFF58) == (nullptr=0x0).
 Test nullPointer failed.
 ```
 
@@ -721,8 +751,8 @@ AUnit offers only the equivalent of `ASSERT_NEAR()` function:
 
 Upon failure, the error messages will look something like:
 ```
-Assertion failed: |(1.00) - (1.10)| > (0.20), file AUnitTest.ino, line 517.
-Assertion failed: |(4.00) - (1.10)| <= (0.20), file AUnitTest.ino, line 527.
+AUnitTest.ino:517: Assertion failed: |(1.00) - (1.10)| > (0.20).
+AUnitTest.ino:527: Assertion failed: |(4.00) - (1.10)| <= (0.20).
 ```
 
 Unlike Google Test where `ASSERT_NEAR()` supports only the `double` type, both
@@ -944,10 +974,10 @@ and returns a `bool`. The execution continues even if `false`.
 The `assertTestXxx()` methods stops the unit test if the status check
 returns `false`, and prints assertion messages that look like this:
 ```
-Assertion passed: Test slow_pass is done, file AUnitTest.ino, line 366.
-Assertion passed: Test slow_pass is not failed, file AUnitTest.ino, line 372.
-Assertion passed: Test slow_skip is skipped, file AUnitTest.ino, line 448.
-Assertion passed: Test slow_skip is not timed out, file AUnitTest.ino, line 451.
+AUnitTest.ino:366: Assertion passed: Test slow_pass is done.
+AUnitTest.ino:372: Assertion passed: Test slow_pass is not failed.
+AUnitTest.ino:448: Assertion passed: Test slow_skip is skipped.
+AUnitTest.ino:451: Assertion passed: Test slow_skip is not timed out.
 ```
 (The human readable version of being `expired` will always be `timed out` or
 `not timed out` on the `Serial` output.)
@@ -966,8 +996,7 @@ available in AUnit. Also, the assertion messages are different. ArduinoUnit
 reuses the format used by the `assertXxx()` macros, so prints something like
 the following:_
 ```
-Assertion passed: (test_slow_skip_instance.state=2) >= (Test::DONE_SKIP=2), file
-AUnitTest.ino, line 439.
+AUnitTest.ino:439: Assertion passed: (test_slow_skip_instance.state=2) >= (Test::DONE_SKIP=2).
 ```
 
 _AUnit has a separate message handler to print a customized message for the
@@ -988,10 +1017,10 @@ fails.
 
 The messages look like:
 ```
-Status passed, file AUnitTest.ino, line 360.
-Status failed, file AUnitTest.ino, line 378.
-Status skipped, file AUnitTest.ino, line 380.
-Status timed out, file AUnitTest.ino, line 391.
+AUnitTest.ino:360: Status passed.
+AUnitTest.ino:378: Status failed.
+AUnitTest.ino:380: Status skipped.
+AUnitTest.ino:391: Status timed out.
 ```
 
 The following methods on the `Test` class also set the `status` of the test, but
@@ -1242,15 +1271,15 @@ assertEquals(expected, counter);
 
 The error message (if enabled, which is the default) is:
 ```
-Assertion failed: (3) == (4), file AUnitTest.ino, line 134.
+AUnitTest.ino:134: Assertion failed: (3) == (4).
 ```
 
 Asserts with `bool` values produce customized messages, printing "true" or
 "false" instead of using the Print class default conversion to `int`:
 ```C++
 assertEquals(true, false);
 
-Assertion failed: (true) == (false), file AUnitTest.ino, line 134.
+AUnitTest.ino:134: Assertion failed: (true) == (false).
 ```
 
 Similarly, the `assertTrue()` and `assertFalse()` macros provide more customized
@@ -1259,23 +1288,23 @@ messages:
 bool ok = false;
 assertTrue(ok);
 
-Assertion failed: (false) is true, file AUnitTest.ino, line 134.
+AUnitTest.ino:134: Assertion failed: (false) is true.
 ```
 
 and
 ```C++
 bool ok = true;
 assertFalse(ok);
 
-Assertion failed: (true) is false, file AUnitTest.ino, line 134.
+AUnitTest.ino:134: Assertion failed: (true) is false.
 ```
 
 ***ArduinoUnit Compatibility***:
 _ArduinoUnit captures the arguments of the `assertEqual()` macro
 and prints:_
 
 ```
-Assertion failed: (expected=3) == (counter=4), file AUnitTest.ino, line 134.
+AUnitTest.ino:134: Assertion failed: (expected=3) == (counter=4).
 ```
 
 _Each capture of the parameter string consumes flash memory space. If the unit
@@ -1297,13 +1326,20 @@ the assertion message will contain the string fragments of the arguments
 passed into the `assertXxx()` macros, like this:
 
 ```
-Assertion failed: (expected=3) == (counter=4), file AUnitTest.ino, line 134.
-Assertion failed: (ok=false) is true, file AUnitTest.ino, line 134.
+AUnitTest.ino:134: Assertion failed: (expected=3) == (counter=4).
+AUnitTest.ino:134: Assertion failed: (ok=false) is true.
+```
+
+instead of:
+
+```
+AUnitTest.ino:134: Assertion failed: (3) == (4).
+AUnitTest.ino:134: Assertion failed: (false) is true.
 ```
 
 ***ArduinoUnit Compatibility***:
-_The verbose mode produces the same messages as ArduinoUnit, at the cost of
-increased flash memory usage._
+_As of v1.7, the assertion message format is compatible with the vim editor
+and other Linux/MacOS/Unix tools, and no longer compatible with ArduinoUnit
 
 <a name="TestCaseSummary"></a>
 #### Test Case Summary

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.6.1
+PROJECT_NUMBER         = 1.7.0
 
 # 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

@@ -3,7 +3,7 @@
 <head>
 <meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
 <meta http-equiv="X-UA-Compatible" content="IE=9"/>
-<meta name="generator" content="Doxygen 1.8.17"/>
+<meta name="generator" content="Doxygen 1.9.1"/>
 <meta name="viewport" content="width=device-width, initial-scale=1"/>
 <title>AUnit: /home/brian/src/AUnit/src/AUnitVerbose.h File Reference</title>
 <link href="tabs.css" rel="stylesheet" type="text/css"/>
@@ -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.6.0</span>
+   &#160;<span id="projectnumber">1.7.0</span>
    </div>
    <div id="projectbrief">Unit testing framework for Arduino platforms inspired by ArduinoUnit and Google Test.</div>
   </td>
@@ -31,10 +31,10 @@
 </table>
 </div>
 <!-- end header part -->
-<!-- Generated by Doxygen 1.8.17 -->
+<!-- Generated by Doxygen 1.9.1 -->
 <script type="text/javascript">
 /* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
-var searchBox = new SearchBox("searchBox", "search",false,'Search');
+var searchBox = new SearchBox("searchBox", "search",false,'Search','.html');
 /* @license-end */
 </script>
 <script type="text/javascript" src="menudata.js"></script>
@@ -73,6 +73,9 @@
 <div class="title">AUnitVerbose.h File Reference</div>  </div>
 </div><!--header-->
 <div class="contents">
+
+<p>Same as <a class="el" href="AUnit_8h.html" title="Same as AUnitVerbose.h except that the terse versions of the various assertXxx() macros are provided.">AUnit.h</a> except that the verbose versions of the various assertXxx() macros are provided.  
+<a href="#details">More...</a></p>
 <div class="textblock"><code>#include &quot;<a class="el" href="print64_8h_source.html">aunit/print64.h</a>&quot;</code><br />
 <code>#include &quot;aunit/Verbosity.h&quot;</code><br />
 <code>#include &quot;<a class="el" href="Compare_8h_source.html">aunit/Compare.h</a>&quot;</code><br />
@@ -89,27 +92,27 @@
 </div><div class="textblock"><div class="dynheader">
 Include dependency graph for AUnitVerbose.h:</div>
 <div class="dyncontent">
-<div class="center"><img src="AUnitVerbose_8h__incl.png" border="0" usemap="#_2home_2brian_2src_2AUnit_2src_2AUnitVerbose_8h" alt=""/></div>
-<map name="_2home_2brian_2src_2AUnit_2src_2AUnitVerbose_8h" id="_2home_2brian_2src_2AUnit_2src_2AUnitVerbose_8h">
-<area shape="rect" title=" " alt="" coords="436,5,599,47"/>
-<area shape="rect" href="print64_8h.html" title=" " alt="" coords="5,95,123,121"/>
+<div class="center"><img src="AUnitVerbose_8h__incl.png" border="0" usemap="#a_2home_2brian_2src_2AUnit_2src_2AUnitVerbose_8h" alt=""/></div>
+<map name="a_2home_2brian_2src_2AUnit_2src_2AUnitVerbose_8h" id="a_2home_2brian_2src_2AUnit_2src_2AUnitVerbose_8h">
+<area shape="rect" title="Same as AUnit.h except that the verbose versions of the various assertXxx() macros are provided." alt="" coords="436,5,599,47"/>
+<area shape="rect" href="print64_8h.html" title="Helper routines to print &#39;long long&#39; and &#39;unsigned long long&#39; because the Print::print() methods in P..." alt="" coords="5,95,123,121"/>
 <area shape="rect" href="Verbosity_8h_source.html" title=" " alt="" coords="512,468,643,495"/>
-<area shape="rect" href="Compare_8h.html" title=" " alt="" coords="197,244,328,271"/>
+<area shape="rect" href="Compare_8h.html" title="This file provides overloaded compareXxx(a, b) functions which are used by the various assertXxx(a,..." alt="" coords="197,244,328,271"/>
 <area shape="rect" href="Printer_8h_source.html" title=" " alt="" coords="390,319,503,345"/>
 <area shape="rect" href="Test_8h_source.html" title=" " alt="" coords="563,393,661,420"/>
 <area shape="rect" href="Assertion_8h_source.html" title=" " alt="" coords="579,319,711,345"/>
 <area shape="rect" href="MetaAssertion_8h_source.html" title=" " alt="" coords="555,244,720,271"/>
 <area shape="rect" href="TestOnce_8h_source.html" title=" " alt="" coords="765,169,896,196"/>
 <area shape="rect" href="TestAgain_8h_source.html" title=" " alt="" coords="921,169,1055,196"/>
 <area shape="rect" href="TestRunner_8h_source.html" title=" " alt="" coords="555,95,698,121"/>
-<area shape="rect" href="AssertVerboseMacros_8h.html" title=" " alt="" coords="824,95,1035,121"/>
-<area shape="rect" href="MetaAssertMacros_8h.html" title=" " alt="" coords="997,244,1189,271"/>
-<area shape="rect" href="TestMacros_8h.html" title=" " alt="" coords="1131,95,1275,121"/>
+<area shape="rect" href="AssertVerboseMacros_8h.html" title="Verbose versions of the macros in AssertMacros.h." alt="" coords="824,95,1035,121"/>
+<area shape="rect" href="MetaAssertMacros_8h.html" title="Various assertTestXxx(), checkTestXxx(), assertTestXxxF() and checkTestXxxF() macros are defined in t..." alt="" coords="997,244,1189,271"/>
+<area shape="rect" href="TestMacros_8h.html" title="Various macros (test(), testF(), testing(), testingF(), externTest(), externTestF(),..." alt="" coords="1131,95,1275,121"/>
 <area shape="rect" title=" " alt="" coords="225,543,300,569"/>
 <area shape="rect" title=" " alt="" coords="8,169,72,196"/>
 <area shape="rect" title=" " alt="" coords="778,543,849,569"/>
 <area shape="rect" href="FCString_8h_source.html" title=" " alt="" coords="769,468,858,495"/>
-<area shape="rect" href="Flash_8h.html" title=" " alt="" coords="1059,393,1128,420"/>
+<area shape="rect" href="Flash_8h.html" title="Various macros to smooth over the differences among the various platforms with regards to their suppo..." alt="" coords="1059,393,1128,420"/>
 <area shape="rect" title=" " alt="" coords="1030,468,1157,495"/>
 <area shape="rect" title=" " alt="" coords="657,169,741,196"/>
 </map>
@@ -120,22 +123,21 @@
 <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;10600</td></tr>
+#define&#160;</td><td class="memItemRight" valign="bottom"><b>AUNIT_VERSION</b>&#160;&#160;&#160;10700</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.6.0&quot;</td></tr>
+#define&#160;</td><td class="memItemRight" valign="bottom"><b>AUNIT_VERSION_STRING</b>&#160;&#160;&#160;&quot;1.7.0&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>
-<div class="textblock"><p>Same as <a class="el" href="AUnit_8h.html">AUnit.h</a> except that the verbose versions of the various assertXxx() macros are provided. These capture the strings of the actual arguments in the assert macros and print more verbose and helpful messages in the same format used by ArduinoUnit. The cost is 20-25% increase in flash memory to hold those strings for medium to large unit tests. </p>
+<div class="textblock"><p>Same as <a class="el" href="AUnit_8h.html" title="Same as AUnitVerbose.h except that the terse versions of the various assertXxx() macros are provided.">AUnit.h</a> except that the verbose versions of the various assertXxx() macros are provided. </p>
+<p>These capture the strings of the actual arguments in the assert macros and print more verbose and helpful messages in the same format used by ArduinoUnit. The cost is 20-25% increase in flash memory to hold those strings for medium to large unit tests. </p>
 
 <p class="definition">Definition in file <a class="el" href="AUnitVerbose_8h_source.html">AUnitVerbose.h</a>.</p>
 </div></div><!-- contents -->
 <!-- start footer part -->
 <hr class="footer"/><address class="footer"><small>
-Generated by &#160;<a href="http://www.doxygen.org/index.html">
-<img class="footer" src="doxygen.png" alt="doxygen"/>
-</a> 1.8.17
+Generated by&#160;<a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.1
 </small></address>
 </body>
 </html>