Merge pull request #25 from bxparks/develop

0.5.0 - support verbose messages with AUnitVerbose.h

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+* 0.5.0 (2018-04-25)
+    * Support verbose assertion messages using AUnitVerbose.h. Fixes #8.
+    * Better assertion messages for assertTrue() and assertFalse(). Fixes #17.
+    * Print duration of test runner at the end. Fixes #18.
+    * Extract meta assertion tests to tests/AUnitMetaTest, so that core
+      tests/AUnitTest can fit inside an Arduino Micro.
 * 0.4.2 (2018-04-10)
     * Fix FSM for excluded tests so that they bypass setup() and teardown().
 * 0.4.1 (2018-04-06)

README.md

@@ -3,7 +3,7 @@
 A unit testing framework for Arduino platforms inspired by ArduinoUnit and
 Google Test.
 
-Version: 0.4.2 (2018-04-10)
+Version: 0.5.0 (2018-04-25)
 
 ## Summary
 
@@ -20,10 +20,9 @@ AUnit was created to solve 3 problems with ArduinoUnit:
   Arduino UNO, Nano) as explained in
   [ArduinoUnit#70](https://github.com/mmurdoch/arduinounit/issues/70).
 * ArduinoUnit does not compile on the ESP8266 platform (see
-  [ArduinoUni#68](https://github.com/mmurdoch/arduinounit/issues/68),
-  [ArduinoUni#57](https://github.com/mmurdoch/arduinounit/pull/57),
-  [ArduinoUni#55](https://github.com/mmurdoch/arduinounit/issues/55),
-  [ArduinoUni#54](https://github.com/mmurdoch/arduinounit/issues/54)).
+  [ArduinoUnit#68](https://github.com/mmurdoch/arduinounit/issues/68),
+  [ArduinoUnit#55](https://github.com/mmurdoch/arduinounit/issues/55),
+  [ArduinoUnit#54](https://github.com/mmurdoch/arduinounit/issues/54)).
 * ArduinoUnit does not provide an easy way to create tests using fixtures,
   equivalent to the `TEST_F()` macro in Google Test.
 
@@ -72,29 +71,33 @@ Here are the features which have not been ported over from ArduinoUnit:
 
 Here are the features in AUnit which are not available in ArduinoUnit:
 
-* The `TestRunner` supports a configurable timeout parameter which
-  can prevent `testing()` test cases from running forever. The following
-  methods and macros are available in AUnit to support this feature:
+* Configurable timeout parameter to prevent `testing()` test cases from
+  running forever:
     * `TestRunner::setTimeout(seconds)`
     * `Test::expire()`
     * `assertTestExpire()`
     * `assertTestNotExpire()`
     * `checkTestExpire()`
     * `checkTestNotExpire()`
-* AUnit adds support for test fixtures using the "F" variations of existing
-  macros:
+* Test fixtures using the "F" variations of existing macros:
     * `testF()`
     * `testingF()`
     * `assertTestXxxF()`
     * `checkTestXxxF()`
     * `externTestF()`
     * `externTestingF()`
-* AUnit supports the `teardown()` method to clean up test fixtures after
-  the `setup()` method.
-* AUnit is tested on the AVR (8-bit), Teensy ARM (32-bit) , and ESP8266 (32-bit)
-  Arduino platforms.
-* Test filters (`TestRunner::include()` and `TestRunner::exclude()`) support the
-  same 2 arguments versions corresponding to `testF()` and `testingF()`
+* `teardown()` method, mirroring the `setup()`
+    * `teardown()`
+* Tested on the following Arduino platforms:
+    * AVR (8-bit)
+    * Teensy ARM (32-bit)
+    * ESP8266 (32-bit)
+* Test filters support the 2 arguments versions:
+    * `TestRunner::include(testClass, name)` - matching `testF()`
+    * `TestRunner::exclude(testClass, name)` - matching `testingF()`
+* Terse and verbose modes:
+    * `#include <AUnit.h>` - terse messages uses less flash memory
+    * `#include <AUnitVerbose.h>` - verbose messages uses more flash
 
 ### Beta Status
 
@@ -137,8 +140,11 @@ The `examples/` directory has a number of examples:
 
 In the `tests/` directory:
 
-* `AUnitTest` - the unit test for `AUnit` itself has a large number of examples
+* `AUnitTest` - the unit test for core `AUnit` functions,
+* `AUnitMetaTest` - the unit test for meta assertions and `extern*()` macros
 * `FilterTest` - manual tests for `include()` and `exclude()` filters
+* `SetupAndTeardownTest` - tests to verify that `setup()` and `teardown()` are
+  called properly by the finite state machine
 
 ### Header and Namespace
 
@@ -162,6 +168,22 @@ Similar to ArduinoUnit, many of the "functions" in this framework (e.g.
 in the global namespace, so it is usually not necessary to import the entire
 `aunit` namespace.
 
+### Verbose Mode
+
+By default, AUnit generates terse assertion messages by leaving out
+the string arguments of the various `assertXxx()` macros. If you would like
+to get the same verbose output as ArduinoUnit, use the following header
+instead:
+
+```
+#include <AUnitVerbose.h>
+```
+
+The flash memory consumption on an 8-bit AVR may go up by 20-25% for medium to
+large tests. On Teensy ARM or ESP8266, the increased memory size probably does
+not matter too much because these microcontrollers have far more flash and
+static memory.
+
 ### Defining the Tests
 
 The usage of **AUnit** is basically identical to **ArduinoUnit**. The following
@@ -177,8 +199,8 @@ subclass derived from the base class indicated above. The `test()` and `testF()`
 macros place the code body into the `TestOnce::once()` method. The `testing()`
 and `testingF()` macros place the code body into the `TestAgain::again()`
 method. The name of the subclass is a concatenation of the string `"test_"` and
-the `name` (for `test()` and `testing()`) the `classname` and the `name` (for
-`testF()` and `testing()`).
+the `name` for `test()` and `testing()`, or the concatenation of
+`classname` + `"_"` + `name` for `testF()` and `testing()`.
 
 The argument to these macros are the name of the test case, and is used to
 generate a name for the subclass. (The name is available within the test code
@@ -844,6 +866,31 @@ The error message (if enabled, which is the default) is:
 Assertion failed: (3) == (4), file AUnitTest.ino, line 134.
 ```
 
+Asserts with `bool` values produce customized messages, printing "true" or
+"false" instead of using the Print class default conversion to `int`:
+```
+assertEquals(true, false);
+
+Assertion failed: (true) == (false), file AUnitTest.ino, line 134.
+```
+
+Similarly, the `assertTrue()` and `assertFalse()` macros provide more customized
+messages:
+```
+bool ok = false;
+assertTrue(ok);
+
+Assertion failed: (false) is true, file AUnitTest.ino, line 134.
+```
+
+and
+```
+bool ok = true;
+assertFalse(ok);
+
+Assertion failed: (true) is false, file AUnitTest.ino, line 134.
+```
+
 ***ArduinoUnit Compatibility***:
 _ArduinoUnit captures the arguments of the `assertEqual()` macro
 and prints:_
@@ -854,7 +901,29 @@ Assertion failed: (expected=3) == (counter=4), file AUnitTest.ino, line 134.
 
 _Each capture of the parameter string consumes flash memory space. If the unit
 test has numerous `assertXxx()` statements, the flash memory cost is expensive.
-AUnit omits the parameters to reduce flash memory space by about 33%_
+AUnit omits the parameters to reduce flash memory space by about 33%._
+
+_The messages for asserts with bool values are customized for better clarity
+(partially to compensate for the lack of capture of the string of the actual
+arguments, and are different from ArduinoUnit._
+
+#### Verbose Mode
+
+If you use the verbose header:
+```
+#include <AUnitVerbose.h>
+```
+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.
+```
+
+***ArduinoUnit Compatibility***:
+_The verbose mode produces the same messages as ArduinoUnit, at the cost of
+increased flash memory usage._
 
 ### Test Summary
 
@@ -878,6 +947,7 @@ At the end of the test run, the `TestRunner` prints out the summary
 of all test cases, like this:
 
 ```
+TestRunner duration: 0.05 seconds.
 TestRunner summary: 12 passed, 0 failed, 2 skipped, 1 timed out, out of 15 test(s).
 ```
 
@@ -1009,9 +1079,12 @@ delayed failure) slightly easier to implement.
 
 ## Benchmarks
 
-AUnit consumes as much as 65% less flash memory than ArduinoUnit on an AVR
+AUnit consumes as much as 65% less flash memory than ArduinoUnit 2.2 on an AVR
 platform (e.g. Arduino UNO, Nano), and 30% less flash on the Teensy-ARM platform
-(e.g. Teensy LC ). Here are the resource consumption (flash and static) numbers
+(e.g. Teensy LC ). (ArduinoUnit 2.3 reduces the flash memory by 30% or so, which
+means that AUnit can still consume significantly less flash memory.)
+
+Here are the resource consumption (flash and static) numbers
 from
 [AceButtonTest](https://github.com/bxparks/AceButton/tree/develop/tests/AceButtonTest)
 containing 26 test cases using 331 `assertXxx()`
@@ -1051,17 +1124,18 @@ This library was developed and tested using:
 * [Teensyduino 1.41](https://www.pjrc.com/teensy/td_download.html)
 * [ESP8266 Arduino Core 2.4.1](https://arduino-esp8266.readthedocs.io/en/2.4.1/)
 
-I used MacOS 10.13.3 for most of my development.
+I used MacOS 10.13.3 and Ubuntu 17.10 for most of my development.
 
 The library has been verified to work on the following hardware:
 
 * Arduino Nano clone (16 MHz ATmega328P)
 * Arduino UNO R3 clone (16 MHz ATmega328P)
 * Arduino Pro Mini clone (16 MHz ATmega328P)
+* Arduino Pro Micro clone (16 MHz ATmega32U4)
 * Teensy LC (48 MHz ARM Cortex-M0+)
 * Teensy 3.2 (72 MHz ARM Cortex-M4)
-* NodeMCU 1.0 clone (ESP-12E module, 80MHz ESP8266)
-* ESP-01 (ESP-01 module, 80MHz ESP8266)
+* NodeMCU 1.0 clone (ESP-12E module, 80 MHz ESP8266)
+* ESP-01 (ESP-01 module, 80 MHz ESP8266)
 
 ## License
 

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         = 0.4.1
+PROJECT_NUMBER         = 0.5.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

@@ -0,0 +1,131 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<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.13"/>
+<meta name="viewport" content="width=device-width, initial-scale=1"/>
+<title>AUnit: /home/brian/dev/AUnit/src/AUnitVerbose.h File Reference</title>
+<link href="tabs.css" rel="stylesheet" type="text/css"/>
+<script type="text/javascript" src="jquery.js"></script>
+<script type="text/javascript" src="dynsections.js"></script>
+<link href="search/search.css" rel="stylesheet" type="text/css"/>
+<script type="text/javascript" src="search/searchdata.js"></script>
+<script type="text/javascript" src="search/search.js"></script>
+<link href="doxygen.css" rel="stylesheet" type="text/css" />
+</head>
+<body>
+<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
+<div id="titlearea">
+<table cellspacing="0" cellpadding="0">
+ <tbody>
+ <tr style="height: 56px;">
+  <td id="projectalign" style="padding-left: 0.5em;">
+   <div id="projectname">AUnit
+   &#160;<span id="projectnumber">0.5.0</span>
+   </div>
+   <div id="projectbrief">Unit testing framework for Arduino platforms inspired by ArduinoUnit and Google Test.</div>
+  </td>
+ </tr>
+ </tbody>
+</table>
+</div>
+<!-- end header part -->
+<!-- Generated by Doxygen 1.8.13 -->
+<script type="text/javascript">
+var searchBox = new SearchBox("searchBox", "search",false,'Search');
+</script>
+<script type="text/javascript" src="menudata.js"></script>
+<script type="text/javascript" src="menu.js"></script>
+<script type="text/javascript">
+$(function() {
+  initMenu('',true,false,'search.php','Search');
+  $(document).ready(function() { init_search(); });
+});
+</script>
+<div id="main-nav"></div>
+<!-- window showing the filter options -->
+<div id="MSearchSelectWindow"
+     onmouseover="return searchBox.OnSearchSelectShow()"
+     onmouseout="return searchBox.OnSearchSelectHide()"
+     onkeydown="return searchBox.OnSearchSelectKey(event)">
+</div>
+
+<!-- iframe showing the search results (closed by default) -->
+<div id="MSearchResultsWindow">
+<iframe src="javascript:void(0)" frameborder="0" 
+        name="MSearchResults" id="MSearchResults">
+</iframe>
+</div>
+
+<div id="nav-path" class="navpath">
+  <ul>
+<li class="navelem"><a class="el" href="dir_68267d1309a1af8e8297ef4c3efbcdba.html">src</a></li>  </ul>
+</div>
+</div><!-- top -->
+<div class="header">
+  <div class="summary">
+<a href="#define-members">Macros</a>  </div>
+  <div class="headertitle">
+<div class="title">AUnitVerbose.h File Reference</div>  </div>
+</div><!--header-->
+<div class="contents">
+
+<p>Same as <a class="el" href="AUnit_8h_source.html">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;aunit/Verbosity.h&quot;</code><br />
+<code>#include &quot;aunit/Compare.h&quot;</code><br />
+<code>#include &quot;aunit/Printer.h&quot;</code><br />
+<code>#include &quot;aunit/Test.h&quot;</code><br />
+<code>#include &quot;aunit/Assertion.h&quot;</code><br />
+<code>#include &quot;aunit/MetaAssertion.h&quot;</code><br />
+<code>#include &quot;aunit/TestOnce.h&quot;</code><br />
+<code>#include &quot;aunit/TestAgain.h&quot;</code><br />
+<code>#include &quot;aunit/TestRunner.h&quot;</code><br />
+<code>#include &quot;<a class="el" href="AssertVerboseMacros_8h_source.html">aunit/AssertVerboseMacros.h</a>&quot;</code><br />
+<code>#include &quot;<a class="el" href="MetaAssertMacros_8h_source.html">aunit/MetaAssertMacros.h</a>&quot;</code><br />
+<code>#include &quot;<a class="el" href="TestMacros_8h_source.html">aunit/TestMacros.h</a>&quot;</code><br />
+</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_2dev_2AUnit_2src_2AUnitVerbose_8h" alt=""/></div>
+<map name="_2home_2brian_2dev_2AUnit_2src_2AUnitVerbose_8h" id="_2home_2brian_2dev_2AUnit_2src_2AUnitVerbose_8h">
+<area shape="rect" id="node2" href="Verbosity_8h_source.html" title="aunit/Verbosity.h" alt="" coords="316,468,436,495"/>
+<area shape="rect" id="node4" href="Compare_8h_source.html" title="aunit/Compare.h" alt="" coords="44,95,163,121"/>
+<area shape="rect" id="node6" href="Printer_8h_source.html" title="aunit/Printer.h" alt="" coords="239,319,342,345"/>
+<area shape="rect" id="node7" href="Test_8h_source.html" title="aunit/Test.h" alt="" coords="389,393,480,420"/>
+<area shape="rect" id="node9" href="Assertion_8h_source.html" title="aunit/Assertion.h" alt="" coords="366,319,486,345"/>
+<area shape="rect" id="node12" href="MetaAssertion_8h_source.html" title="aunit/MetaAssertion.h" alt="" coords="340,244,489,271"/>
+<area shape="rect" id="node13" href="TestOnce_8h_source.html" title="aunit/TestOnce.h" alt="" coords="721,169,844,196"/>
+<area shape="rect" id="node14" href="TestAgain_8h_source.html" title="aunit/TestAgain.h" alt="" coords="415,169,539,196"/>
+<area shape="rect" id="node15" href="TestRunner_8h_source.html" title="aunit/TestRunner.h" alt="" coords="561,319,694,345"/>
+<area shape="rect" id="node16" href="AssertVerboseMacros_8h.html" title="Verbose versions of the macros in AssertMacros.h. " alt="" coords="546,95,741,121"/>
+<area shape="rect" id="node17" href="MetaAssertMacros_8h.html" title="Various assertTestXxx(), checkTestXxx(), assertTestXxxF() and checkTestXxxF() macros are defined in t..." alt="" coords="766,95,940,121"/>
+<area shape="rect" id="node18" href="TestMacros_8h.html" title="Various macros (test(), testF(), testing(), testingF(), externTest(), externTestF(), externTesting(), externTestingF()) are defined in this header. " alt="" coords="964,95,1099,121"/>
+<area shape="rect" id="node8" href="FCString_8h_source.html" title="FCString.h" alt="" coords="689,468,774,495"/>
+<area shape="rect" id="node10" href="Flash_8h.html" title="Flash strings (using F() macro) on the ESP8266 platform cannot be placed in an inline context..." alt="" coords="952,393,1018,420"/>
+</map>
+</div>
+</div>
+<p><a href="AUnitVerbose_8h_source.html">Go to the source code of this file.</a></p>
+<table class="memberdecls">
+<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;000500</td></tr>
+<tr class="separator:a87cbb10969eff63f8ae66afc4e9457eb"><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_source.html">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.13
+</small></address>
+</body>
+</html>

docs/html/AUnitVerbose_8h__incl.map

@@ -0,0 +1,16 @@
+<map id="/home/brian/dev/AUnit/src/AUnitVerbose.h" name="/home/brian/dev/AUnit/src/AUnitVerbose.h">
+<area shape="rect" id="node2" href="$Verbosity_8h_source.html" title="aunit/Verbosity.h" alt="" coords="316,468,436,495"/>
+<area shape="rect" id="node4" href="$Compare_8h_source.html" title="aunit/Compare.h" alt="" coords="44,95,163,121"/>
+<area shape="rect" id="node6" href="$Printer_8h_source.html" title="aunit/Printer.h" alt="" coords="239,319,342,345"/>
+<area shape="rect" id="node7" href="$Test_8h_source.html" title="aunit/Test.h" alt="" coords="389,393,480,420"/>
+<area shape="rect" id="node9" href="$Assertion_8h_source.html" title="aunit/Assertion.h" alt="" coords="366,319,486,345"/>
+<area shape="rect" id="node12" href="$MetaAssertion_8h_source.html" title="aunit/MetaAssertion.h" alt="" coords="340,244,489,271"/>
+<area shape="rect" id="node13" href="$TestOnce_8h_source.html" title="aunit/TestOnce.h" alt="" coords="721,169,844,196"/>
+<area shape="rect" id="node14" href="$TestAgain_8h_source.html" title="aunit/TestAgain.h" alt="" coords="415,169,539,196"/>
+<area shape="rect" id="node15" href="$TestRunner_8h_source.html" title="aunit/TestRunner.h" alt="" coords="561,319,694,345"/>
+<area shape="rect" id="node16" href="$AssertVerboseMacros_8h.html" title="Verbose versions of the macros in AssertMacros.h. " alt="" coords="546,95,741,121"/>
+<area shape="rect" id="node17" href="$MetaAssertMacros_8h.html" title="Various assertTestXxx(), checkTestXxx(), assertTestXxxF() and checkTestXxxF() macros are defined in t..." alt="" coords="766,95,940,121"/>
+<area shape="rect" id="node18" href="$TestMacros_8h.html" title="Various macros (test(), testF(), testing(), testingF(), externTest(), externTestF(), externTesting(), externTestingF()) are defined in this header. " alt="" coords="964,95,1099,121"/>
+<area shape="rect" id="node8" href="$FCString_8h_source.html" title="FCString.h" alt="" coords="689,468,774,495"/>
+<area shape="rect" id="node10" href="$Flash_8h.html" title="Flash strings (using F() macro) on the ESP8266 platform cannot be placed in an inline context..." alt="" coords="952,393,1018,420"/>
+</map>

docs/html/AUnitVerbose_8h__incl.md5

@@ -0,0 +1 @@
+dd1d0ed32d54834939a1889af843be14