Merge pull request #36 from bxparks/develop

1.1 - add assertNear() for approximate floating point comparison

Author: bxparks

CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+* 1.1 (2018-07-23)
+    * Add assertNear() and assertNotNear() for floating and integral types.
+      Fixes #35.
+    * Moved deliberately failing tests into FailingTest.ino and add passing
+      tests to AUniter/Jenkins.
 * 1.0.1 (2018-06-27)
     * Move AUniter tools into separate project and integrate with
       a Jenkins continuous integration service running locally.

README.md

@@ -6,10 +6,12 @@ or emulator. It is almost a drop-in replacement of ArduinoUnit with some
 advantages. AUnit supports timeouts and test fixtures. It somtimes consume 50%
 less flash memory on the AVR platform, and it has been tested to work on the
 AVR, ESP8266, ESP32 and Teensy platforms. The sister AUniter project provides
-command line tools to verify, upload and validate the unit tests. AUniter tools
-can be used in a continuous integration systems like Jenkins.
+command line tools to verify, upload and validate the unit tests. The AUniter
+tools can be used in a continuous integration system like Jenkins.
 
-Version: 1.0.1 (2018-06-27)
+Version: 1.1 (2018-07-23)
+
+[![AUniter Jenkins Badge](https://us-central1-xparks2015.cloudfunctions.net/badge?project=AUnit)](https://github.com/bxparks/AUniter)
 
 ## Summary
 
@@ -94,6 +96,9 @@ Here are the features in AUnit which are not available in ArduinoUnit 2.2:
 * Case-insensitive string comparisons:
     * `assertStringCaseEqual()`
     * `assertStringCaseNotEqual()`
+* Approximate comparisons:
+    * `assertNear()`
+    * `asssertNotNear()`
 * Test fixtures using the "F" variations of existing macros:
     * `testF()`
     * `testingF()`
@@ -357,13 +362,6 @@ are available. These are essentially identical to ArduinoUnit:
 * `assertLessOrEqual(a, b)`
 * `assertMoreOrEqual(a, b)`
 
-Two additional macros provide case-insensitive string comparisons
-(analogous to `ASSERT_STRCASEEQ()` and `ASSERT_STRCASENE()` in
-Google Test):
-
-* `assertStringCaseEqual()`
-* `assertStringCaseNotEqual()`
-
 #### Supported Parameter Types
 
 The 6 core assert macros (assertEqual, assertNotEqual, assertLess, assertMore,
@@ -477,6 +475,75 @@ difficult to remember (and sometimes difficult to understand). The best way to
 avoid these compiler errors is to make sure that the assertion parameter types
 are identical, potentially using explicit casting.
 
+### Case Insensitive String Comparisons
+
+Two macros provide case-insensitive string comparisons (analogous to
+`ASSERT_STRCASEEQ()` and `ASSERT_STRCASENE()` in Google Test):
+
+* `assertStringCaseEqual(a, b)`
+* `assertStringCaseNotEqual(a, b)`
+
+The supported types for `(a, b)` are all 9 combinations of Arduino string types:
+
+* `(const char *, const char *)`
+* `(const char *, const String&)`
+* `(const char *, const __FlashStringHelper*)`
+* `(const String&, const char*)`
+* `(const String&, const String&)`
+* `(const String&, const __FlashStringHelper*)`
+* `(const __FlashStringHelper*, const char*)`
+* `(const __FlashStringHelper*, const String&)`
+* `(const __FlashStringHelper*, const __FlashStringHelper*)`
+
+***ArduinoUnit Compatibility***: _Not available in ArduinoUnit._
+
+### Approximate Comparisons
+
+Floating point values are difficult to compare because of internal rounding
+errors. Google Test provides
+[two types of macros to handle floating points](https://github.com/google/googletest/blob/master/googletest/docs/advanced.md#floating-point-comparison):
+* `ASSERT_FLOAT_EQ(a, b)`, `ASSERT_DOUBLE_EQ(a, b)` - determine if the
+  floating point numbers are within 4
+  [Units in the Last Place (ULPs)](https://randomascii.wordpress.com/2012/02/25/comparing-floating-point-numbers-2012-edition/)
+* `ASSERT_NEAR(a, b, error)` - determine if the absolute distance between
+  `a` and `b` is within the given `error`
+
+Since floating point operations are relatively rare in Arduino programming,
+AUnit offers only the equilvalent of `ASSERT_NEAR()` function:
+
+* `assertNear(a, b, error)`
+* `assertNotNear(a, b, error)`
+
+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.
+```
+
+Unlike Google Test where `ASSERT_NEAR()` supports only the `double` type, both
+`assertNear()` and `assertNotNear()` support integral types as well. The full
+list of supported types is:
+
+* `int`
+* `unsigned int`
+* `long`
+* `unsigned long`
+* `double`
+
+Other primitive types (e.g. `char` or `float`) will be automatically converted
+to one of these supported types by the compiler.
+
+Note that the `abs()` of 2 values of a signed integer type can be larger than
+the maximum value that can be represented by the given signed type. Since signed
+integer overflow is an
+[undefined behavior](https://stackoverflow.com/questions/16188263/is-signed-integer-overflow-still-undefined-behavior-in-c)
+in C and C++11, I cannot predict what the compiler will do in that case.
+Unsigned types should not have this problem because the distance between two
+values of an unsigned type should always fit inside the given unsigned type.
+Technically, a similar problem exists for the floating point types (which are
+naturally signed), but it is unlikely that you are dealing with floating point
+values so close to the maximum values.
+
 ### Boolean Assertions
 
 The following boolean asserts are also available:
@@ -1083,7 +1150,7 @@ framework, but let me know if you truly need a timeout of greater than 4m15s).
 
 ***ArduinoUnit Compatibility***: _Only available in AUnit._
 
-## Commandline Tools and Continous Integration
+## Commandline Tools and Continuous Integration
 
 ### AUniter
 
@@ -1205,6 +1272,15 @@ allows those assertion statements to have access to the internal states of the
 `Test` instance, which makes certain functions (like the early return upon
 delayed failure) slightly easier to implement.
 
+### Comparing Pointers
+
+Currently the `assertEqual()` and other `assertXxx()` methods do not support
+comparing arbitrary pointers (i.e. `(void*)`. This could change if 
+[Issue #34](https://github.com/bxparks/AUnit/issues/34) is
+resolved. In the meantime, a workaround is to cast the pointer to a `uintptr_t`
+integer type from `#include <stdint.h>` and then calling `assertEqual()` on the
+integer type.
+
 ## Benchmarks
 
 AUnit consumes as much as 65% less flash memory than ArduinoUnit 2.2 on an AVR

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.0.0
+PROJECT_NUMBER         = 1.1
 
 # 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.0.0</span>
+   &#160;<span id="projectnumber">1.1</span>
    </div>
    <div id="projectbrief">Unit testing framework for Arduino platforms inspired by ArduinoUnit and Google Test.</div>
   </td>
@@ -112,7 +112,7 @@
 <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;010000</td></tr>
+#define&#160;</td><td class="memItemRight" valign="bottom"><b>AUNIT_VERSION</b>&#160;&#160;&#160;010100</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>