|
3 | 3 | A unit testing framework for Arduino platforms inspired by ArduinoUnit and |
4 | 4 | Google Test. |
5 | 5 |
|
6 | | -Version: 0.5.0 (2018-04-25) |
| 6 | +Version: 0.5.1 (2018-05-01) |
7 | 7 |
|
8 | 8 | ## Summary |
9 | 9 |
|
@@ -86,24 +86,32 @@ Here are the features in AUnit which are not available in ArduinoUnit: |
86 | 86 | * `checkTestXxxF()` |
87 | 87 | * `externTestF()` |
88 | 88 | * `externTestingF()` |
| 89 | +* Status setters |
| 90 | + * `passNow()` |
| 91 | + * `failNow()` |
| 92 | + * `skipNow()` |
| 93 | + * `expireNow()` |
89 | 94 | * `teardown()` method, mirroring the `setup()` |
90 | 95 | * `teardown()` |
91 | 96 | * Tested on the following Arduino platforms: |
92 | 97 | * AVR (8-bit) |
93 | 98 | * Teensy ARM (32-bit) |
94 | 99 | * ESP8266 (32-bit) |
| 100 | + * ESP32 (32-bit) |
95 | 101 | * Test filters support the 2 arguments versions: |
96 | 102 | * `TestRunner::include(testClass, name)` - matching `testF()` |
97 | 103 | * `TestRunner::exclude(testClass, name)` - matching `testingF()` |
98 | 104 | * Terse and verbose modes: |
99 | 105 | * `#include <AUnit.h>` - terse messages uses less flash memory |
100 | 106 | * `#include <AUnitVerbose.h>` - verbose messages uses more flash |
101 | 107 |
|
| 108 | +Every feature of AUnit is unit tested using AUnit itself. |
| 109 | + |
102 | 110 | ### Beta Status |
103 | 111 |
|
104 | | -Although this library has been extensively tested by me, and I converted my |
105 | | -[AceButton](https://github.com/bxparks/AceButton) library to use it, I consider |
106 | | -it currently in "beta stage" until more users have tested it. |
| 112 | +Although this library has been extensively tested by me, and two of my Arduino |
| 113 | +libraries (AceButton and AceSegment, see Examples below) now use it, I consider |
| 114 | +it currently in "beta stage" until more users have tested it. |
107 | 115 |
|
108 | 116 | ## Installation |
109 | 117 |
|
@@ -146,6 +154,20 @@ In the `tests/` directory: |
146 | 154 | * `SetupAndTeardownTest` - tests to verify that `setup()` and `teardown()` are |
147 | 155 | called properly by the finite state machine |
148 | 156 |
|
| 157 | +Perhaps the best way to see AUnit in action through real life examples. I |
| 158 | +currently have 2 Arduino project using AUnit extensively: |
| 159 | + |
| 160 | +* [AceButton](https://github.com/bxparks/AceButton) |
| 161 | +* [AceSegment](https://github.com/bxparks/AceSegment) |
| 162 | + |
| 163 | +Look under the `tests` directory in each project. |
| 164 | + |
| 165 | +The tests for AceButton were originally created using ArduinoUnit 2.2, and I |
| 166 | +have kept those tests backwards compatible. They do not use the new features of |
| 167 | +AUnit. |
| 168 | + |
| 169 | +The tests for AceSegment demonstrate the full power of AUnit better. |
| 170 | + |
149 | 171 | ### Header and Namespace |
150 | 172 |
|
151 | 173 | To prevent name clashes with other libraries and code, all classes in the AUnit |
@@ -180,8 +202,8 @@ instead: |
180 | 202 | ``` |
181 | 203 |
|
182 | 204 | The flash memory consumption on an 8-bit AVR may go up by 20-25% for medium to |
183 | | -large tests. On Teensy ARM or ESP8266, the increased memory size probably does |
184 | | -not matter too much because these microcontrollers have far more flash and |
| 205 | +large tests. On Teensy ARM, ESP8266 or ESP32, the increased memory size probably |
| 206 | +does not matter too much because these microcontrollers have far more flash and |
185 | 207 | static memory. |
186 | 208 |
|
187 | 209 | ### Defining the Tests |
@@ -229,9 +251,9 @@ testing(looping_test) { |
229 | 251 | if (...) { |
230 | 252 | pass(); |
231 | 253 | } else if (...) { |
232 | | - fail(); |
| 254 | + failNow(); |
233 | 255 | } else { |
234 | | - skip(); |
| 256 | + skipNow(); |
235 | 257 | } |
236 | 258 | } |
237 | 259 |
|
@@ -399,8 +421,8 @@ will produce a compiler error: |
399 | 421 | unsigned short ushortValue = 5; |
400 | 422 | assertEqual(5U, ushortValue); |
401 | 423 | ``` |
402 | | -But on Teensy-ARM and ESP8266, a 16-bit (short) can be promoted to a 32-bit |
403 | | -(int) without loss of precision, so the above will compile just fine. For |
| 424 | +But on Teensy-ARM, ESP8266, and ESP32, a 16-bit (short) can be promoted to a |
| 425 | +32-bit (int) without loss of precision, so the above will compile just fine. For |
404 | 426 | portability, the following should be used on all platforms: |
405 | 427 | ``` |
406 | 428 | unsigned short ushortValue = 5; |
@@ -644,17 +666,39 @@ assertTestXxx() meta assertion macros._ |
644 | 666 |
|
645 | 667 | ### Status Indicator Methods |
646 | 668 |
|
647 | | -These methods can be used inside a `test()` or `testing()` macro |
648 | | -to indicate whether the test has passed or failed (or reached some other |
649 | | -status reason). |
| 669 | +The following macros can be used inside the body of `test()` or `testing()` |
| 670 | +macro to indicate whether the test has passed or failed (or reached some other |
| 671 | +status). Each macro prints a short message, and returns immediately from the |
| 672 | +test, much like an `assertXxx()` macro that fails. |
| 673 | + |
| 674 | +* `passNow()` [*] |
| 675 | +* `failNow()` [*] |
| 676 | +* `skipNow()` [*] |
| 677 | +* `expireNow()` [*] |
| 678 | + |
| 679 | +The message looks like: |
| 680 | +``` |
| 681 | +Status timed out, file AUnitTest.ino, line 381. |
| 682 | +Status failed, file AUnitTest.ino, line 378. |
| 683 | +Status failed, file AUnitTest.ino, line 378. |
| 684 | +Status skipped, file AUnitTest.ino, line 380. |
| 685 | +``` |
| 686 | + |
| 687 | +The above methods are recommended over the following methods on the `Test` class |
| 688 | +because the `xxxNow()` versions print the file and line number of the statement. |
| 689 | +The methods on `Test` are completely silent which makes debugging difficult. |
650 | 690 |
|
651 | 691 | * `pass()` - test passed |
652 | 692 | * `fail()` - test failed |
653 | 693 | * `skip()` - test skipped |
654 | 694 | * `expire()` - test timed out [*] |
655 | 695 |
|
656 | | -***ArduinoUnit Compatibility***: _The method(s) marked by [*] are only |
657 | | -available in AUnit._ |
| 696 | +***ArduinoUnit Compatibility***: _ |
| 697 | +_The method(s) marked by [*] are only available in AUnit. For most cases, |
| 698 | +the failNow(), skipNow() and expireNow() methods are recommended over the |
| 699 | +methods from ArduinoUnit which have been carried over for compatibility and for |
| 700 | +internal use. In a testing() loop test, the pass() method may be more useful |
| 701 | +than the passNow() macro._ |
658 | 702 |
|
659 | 703 | ### Overridable Methods |
660 | 704 |
|
@@ -1000,7 +1044,7 @@ Collection of useful tidbits. |
1000 | 1044 |
|
1001 | 1045 | ### Debugging Assertions in Fixtures |
1002 | 1046 |
|
1003 | | -When using test fixtures with the `testF()` and testingF()` macros, it's often |
| 1047 | +When using test fixtures with the `testF()` and `testingF()` macros, it's often |
1004 | 1048 | useful to create helper assertions, such as the `assertCustomStuff()` below. |
1005 | 1049 | Debugging such assertion statements can be tricky. I've found that turning on |
1006 | 1050 | messages for successful assertions (with a |
@@ -1123,18 +1167,23 @@ This library was developed and tested using: |
1123 | 1167 | * [Arduino IDE 1.8.5](https://www.arduino.cc/en/Main/Software) |
1124 | 1168 | * [Teensyduino 1.41](https://www.pjrc.com/teensy/td_download.html) |
1125 | 1169 | * [ESP8266 Arduino Core 2.4.1](https://arduino-esp8266.readthedocs.io/en/2.4.1/) |
| 1170 | +* [arduino-esp32](https://github.com/espressif/arduino-esp32) |
1126 | 1171 |
|
1127 | 1172 | I used MacOS 10.13.3 and Ubuntu 17.10 for most of my development. |
1128 | 1173 |
|
1129 | | -The library has been verified to work on the following hardware: |
| 1174 | +The library is tested on the following hardware before each release: |
1130 | 1175 |
|
1131 | 1176 | * Arduino Nano clone (16 MHz ATmega328P) |
1132 | | -* Arduino UNO R3 clone (16 MHz ATmega328P) |
1133 | | -* Arduino Pro Mini clone (16 MHz ATmega328P) |
1134 | 1177 | * Arduino Pro Micro clone (16 MHz ATmega32U4) |
1135 | | -* Teensy LC (48 MHz ARM Cortex-M0+) |
1136 | 1178 | * Teensy 3.2 (72 MHz ARM Cortex-M4) |
1137 | 1179 | * NodeMCU 1.0 clone (ESP-12E module, 80 MHz ESP8266) |
| 1180 | +* ESP32 dev board (ESP-WROOM-32 module, 240 MHz dual core Tensilica LX6) |
| 1181 | + |
| 1182 | +I will occasionally test on the following hardware as a sanity check: |
| 1183 | + |
| 1184 | +* Arduino UNO R3 clone (16 MHz ATmega328P) |
| 1185 | +* Arduino Pro Mini clone (16 MHz ATmega328P) |
| 1186 | +* Teensy LC (48 MHz ARM Cortex-M0+) |
1138 | 1187 | * ESP-01 (ESP-01 module, 80 MHz ESP8266) |
1139 | 1188 |
|
1140 | 1189 | ## License |
|
0 commit comments