merge iss73

CHANGELOG.md

@@ -33,9 +33,4 @@
 * Use more standard file names (README.md, LICENSE, and CHANGELOG.md)
 * Use less likely to fail version of `while (!Serial) {}` in examples and documentation.
 * Make Test::TestString ArduinoUnitString, and refactor Compare to leverage that code.
-
-
-
-
-
-
+* Add an optional lazy message last argument to every assert.

README.md

@@ -39,6 +39,7 @@ And the following more-is-more features:
 1. Test names and assert strings are stored in flash (not RAM).
    - Test names can optionally be stored in either RAM or flash.
 1. assertions about other tests.
+1. optional message [Since 2.3.1]
 
 ## Getting Started
 
@@ -93,6 +94,27 @@ Test bad failed.
 Test ok passed.
 Test summary: 1 passed, 1 failed, and 0 skipped, out of 2 test(s).
 ```
+# Message
+
+When things go wrong, it is sometimes useful to print additional information.  As of 2.3.2-alpha,
+this is possible with any assertXXX() method by adding an additional third parameter to the assert.  For example,
+```
+test(cases)
+{
+  int x=3;
+  for (int k=0; k<4; ++k) {
+    assertNotEqual(x,k,"case k=" << k);
+  }
+}
+```
+will fail with the message
+```
+Assertion failed: (x=3) != (k=3), file basic.ino, line 20 [case k=3].
+```
+The additional message is only created if the assert actually needs to generate output (usually when it fails).
+It appears in the [] brackets at the end of the assert message.  Notice you can create fairly complex messages
+by chaining things you can print (like `Serial.print()`) between `<<` operators.  This is similar to the C++ ostream insertion operators, if you are familar with that.
+
 # Verbosity
 
 Just how much information is generated on each test is fairly flexible, and designed to address these rules:

examples/message/message.ino

@@ -0,0 +1,35 @@
+#line 2 "basic.ino"
+#include <ArduinoUnit.h>
+
+test(correct)
+{
+  int x=1;
+  // Use F() to store a string in flash, which saves RAM for long strings
+  assertEqual(x,1,F("inconceivable!"));
+}
+
+test(incorrect)
+{
+  int x=1;
+  // Compose a message with A << B << C << ...
+  assertNotEqual(x,1,F("we are saying x != 1, which is false when x=") << x << F(", see?"));
+}
+
+test(cases)
+{
+  int x=3;
+  for (int k=0; k<4; ++k) {
+    assertNotEqual(x,2*k-1,"case k=" << k);
+  }
+}
+
+void setup()
+{
+  Serial.begin(9600);
+  while(!Serial) {} // Portability for Leonardo/Micro
+}
+
+void loop()
+{
+  Test::run();
+}