Skip to content

Commit

Permalink
Merge pull request #4 from bxparks/develop
Browse files Browse the repository at this point in the history
v0.3.0: implement all remaining macros from ArduinoUnit
  • Loading branch information
bxparks authored Mar 19, 2018
2 parents 609eb0e + ffe1782 commit b042c64
Show file tree
Hide file tree
Showing 13 changed files with 691 additions and 67 deletions.
3 changes: 3 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,8 @@
# Changelog

* v0.3.0 (2018-03-19)
* Implement all remaining macros from ArduinoUnit:
assertTestXxx(), checkTestXxx(), externTest(), externTesting().
* v0.2.0 (2018-03-16)
* TestRunner can time out long running tests. Default time out is 10
seconds, but is configurable using TestRunner::setTimeout().
Expand Down
93 changes: 66 additions & 27 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# AUnit - Unit Testing Framework for Arduino Platforms

Version: v0.3.0 (2018-03-19)

## Summary

**AUnit** (rhymes with "JUnit") is a unit testing framework based
Expand All @@ -16,8 +18,9 @@ AUnit was created to solve 2 problems with ArduinoUnit:
[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), and
[ArduinoUni#55](https://github.com/mmurdoch/arduinounit/issues/55)).
[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)).

In contrast:
* AUnit consumes as much as 66% *less* flash memory than ArduinoUnit on the
Expand All @@ -31,11 +34,16 @@ convert to AUnit:
* `#include <ArduinoUnit.h>` -> `#include <AUnit.h>`
* `Test::run()` -> `aunit::TestRunner::run()`

Almost all of the frequently used macros are compatible between ArduinoUnit and
Essentially all of the various macros are compatible between ArduinoUnit and
AUnit:
* `test()`
* `testing()`
* `assertXxx()`
* Meta Assertions
* `checkTestXxx()`
* `assertTestXxx()`
* `externTest()`
* `externTesting()`

AUnit supports exclude and include filters:
* `TestRunner::exclude()`
Expand All @@ -48,15 +56,19 @@ Here are the features which have not been ported over from ArduinoUnit:
* ArduinoUnit supports multiple `*` wildcards in its `exclude()` and `include()`
methods. AUnit supports only a single `*` wildcard and it must occur at the
end if present.
* Various "Meta Assertions" from ArduinoUnit (i.e. `checkTestXxx()` and
`assertTestXxx()`) have not been implemented.

### Added Features

Here are some features in AUnit, not available in 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.
can prevent `testing()` test cases from running forever. The following
methods and macros are available in AUnit to support this feature:
* `Test::expire()`
* `assertTestExpire()`
* `assertTestNotExpire()`
* `checkTestExpire()`
* `checkTestNotExpire()`
* AUnit works on the ESP8266 platform.

### Beta Status
Expand All @@ -67,14 +79,16 @@ it currently in "beta stage" until more users have tested it.

## Installation

The library is available in the Arduino IDE Library Manager. Search for "unit
test" or "AUnit", select "AUnit", then click the "Install" button.
The latest stable release is available in the Arduino IDE Library Manager.
Search for "unit test" or "AUnit", select "AUnit", then click the "Install"
button.

The library can also be installed by cloning the
[GitHub repository](https://github.com/bxparks/AUnit), then
manually copying over the contents to the `./libraries` directory used
by the Arduino IDE. (The result is a directory named `./libraries/AUnit`.)
See the Preferences menu for the location of the Arduino sketch directory.
The development version can be installed by cloning the
[GitHub repository](https://github.com/bxparks/AUnit), checking out the
`develop` branch, then manually copying over the contents to the `./libraries`
directory used by the Arduino IDE. (The result is a directory named
`./libraries/AUnit`.) See the Preferences menu for the location of the Arduino
sketch directory. The `master` branch contains the stable release.

Using either installation method, you may need to restart the Arduino IDE to
pick up the new library.
Expand Down Expand Up @@ -310,9 +324,7 @@ The following boolean asserts are also available:

### Meta Assertions

***ArduinoUnit Compatibility***: _Not implemented in AUnit._

The following methods from ArduinoUnit are not implemented:
The following methods from ArduinoUnit have also been implemented:

* `checkTestDone(name)`
* `checkTestNotDone(name)`
Expand All @@ -322,6 +334,8 @@ The following methods from ArduinoUnit are not implemented:
* `checkTestNotFail(name)`
* `checkTestSkip(name)`
* `checkTestNotSkip(name)`
* `checkTestExpire(name)` [&ast;]
* `checkTestNotExpire(name)` [&ast;]
* `assertTestDone(name)`
* `assertTestNotDone(name)`
* `assertTestPass(name)`
Expand All @@ -330,14 +344,38 @@ The following methods from ArduinoUnit are not implemented:
* `assertTestNotFail(name)`
* `assertTestSkip(name)`
* `assertTestNotSkip(name)`
* `assertTestExpire(name)` [&ast;]
* `assertTestNotExpire(name)` [&ast;]

The following macros are not implemented because they are only needed
by the Meta Assertions:
The `checkTestXxx()` methods check the status of the test named `name`
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.
```

The following macros define `extern` references to test case objects which live
in other `.cpp` files. These are required for the above meta assertions if the
test cases are defined in another file:

* `externTest()`
* `externTesting()`

***ArduinoUnit Compatibility***: _Not implemented in AUnit._
***ArduinoUnit Compatibility***: _The methods marked by [&ast;] are only
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.
```

_AUnit has a separate message handler to print a customized message for the
assertTestXxx() meta assertion macros._

### Status Indicator Methods

Expand All @@ -348,9 +386,10 @@ status reason).
* `pass()` - test passed
* `fail()` - test failed
* `skip()` - test skipped
* `expire()` - test timed out
* `expire()` - test timed out [&ast;]

***ArduinoUnit Compatibility***: _`expire()` is available only in AUnit._
***ArduinoUnit Compatibility***: _The method(s) marked by [&ast;] are only
available in AUnit._

### Overridable Methods

Expand Down Expand Up @@ -627,11 +666,11 @@ Teensy LC (static) | 8192 | 2980 | 2780 |
Teensy 3.2 (flash) | 262144 | 51236 | 36300 |
Teensy 3.2 (static) | 65536 | 5328 | 5236 |
---------------------------+---------+-------------+-------------|
ESP8266 - ESP-12E (flash) | 1044464 | does not | 267479 |
ESP8266 - ESP-12E (static) | 81920 | compile | 34564 |
ESP8266 - ESP-12E (flash) | 1044464 | does not | 266748 |
ESP8266 - ESP-12E (static) | 81920 | compile | 33128 |
---------------------------+---------+-------------+-------------|
ESP8266 - ESP-01 (flash) | 499696 | does not | 267359 |
ESP8266 - ESP-01 (static) | 47356 | compile | 34564 |
ESP8266 - ESP-01 (flash) | 499696 | does not | 266748 |
ESP8266 - ESP-01 (static) | 47356 | compile | 33128 |
---------------------------+---------+-------------+-------------|
```

Expand All @@ -647,7 +686,7 @@ See [CHANGELOG.md](CHANGELOG.md).
This library was developed and tested using:
* [Arduino IDE 1.8.5](https://www.arduino.cc/en/Main/Software)
* [Teensyduino 1.41](https://www.pjrc.com/teensy/td_download.html)
* [ESP8266 Arduino Core 2.4.0](https://arduino-esp8266.readthedocs.io/en/2.4.0-rc2/)
* [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.

Expand Down
202 changes: 202 additions & 0 deletions examples/meta_asserts/meta_asserts.ino
Original file line number Diff line number Diff line change
@@ -0,0 +1,202 @@
#line 2 "meta_asserts.ino"

// Originally derived from the README.md in
// https://github.com/mmurdoch/arduinounit/ but is now very different.

#define USE_AUNIT 0

#if USE_AUNIT == 1
#include <AUnit.h>
using aunit::TestRunner;
using aunit::Verbosity;
#else
#include <ArduinoUnit.h>
#define assertTestExpire(x)
#define assertTestNotExpire(x)
#define checkTestExpire(x) true
#define checkTestNotExpire(x) true
#endif

testing(slow_pass) { if (millis() > 1000) pass(); }

testing(slow_fail) { if (millis() > 1000) fail(); }

testing(slow_skip) { if (millis() > 1000) skip(); }

#if USE_AUNIT == 1
testing(slow_expire) { if (millis() > 1000) expire(); }
#endif

testing(slow_pass_monitor) {
unsigned long now = millis();
if (now < 1000) {
assertTestNotDone(slow_pass);
assertTrue(checkTestNotDone(slow_pass));

assertTestNotPass(slow_pass);
assertTrue(checkTestNotPass(slow_pass));

assertTestNotFail(slow_pass);
assertTrue(checkTestNotFail(slow_pass));

assertTestNotSkip(slow_pass);
assertTrue(checkTestNotSkip(slow_pass));

assertTestNotExpire(slow_pass);
assertTrue(checkTestNotExpire(slow_pass));
}
if (now > 2000) {
assertTestDone(slow_pass);
assertTrue(checkTestDone(slow_pass));

assertTestPass(slow_pass);
assertTrue(checkTestPass(slow_pass));

assertTestNotFail(slow_pass);
assertTrue(checkTestNotFail(slow_pass));

assertTestNotSkip(slow_pass);
assertTrue(checkTestNotSkip(slow_pass));

assertTestNotExpire(slow_pass);
assertTrue(checkTestNotExpire(slow_pass));

pass();
}
}

testing(slow_fail_monitor) {
unsigned long now = millis();
if (now < 1000) {
assertTestNotDone(slow_fail);
assertTrue(checkTestNotDone(slow_fail));

assertTestNotPass(slow_fail);
assertTrue(checkTestNotPass(slow_fail));

assertTestNotFail(slow_fail);
assertTrue(checkTestNotFail(slow_fail));

assertTestNotSkip(slow_fail);
assertTrue(checkTestNotSkip(slow_fail));

assertTestNotExpire(slow_fail);
assertTrue(checkTestNotExpire(slow_fail));
}
if (now > 2000) {
assertTestDone(slow_fail);
assertTrue(checkTestDone(slow_fail));

assertTestNotPass(slow_fail);
assertTrue(checkTestNotPass(slow_fail));

assertTestFail(slow_fail);
assertTrue(checkTestFail(slow_fail));

assertTestNotSkip(slow_fail);
assertTrue(checkTestNotSkip(slow_fail));

assertTestNotExpire(slow_fail);
assertTrue(checkTestNotExpire(slow_fail));

pass();
}
}

testing(slow_skip_monitor) {
unsigned long now = millis();
if (now < 1000) {
assertTestNotDone(slow_skip);
assertTrue(checkTestNotDone(slow_skip));

assertTestNotPass(slow_skip);
assertTrue(checkTestNotPass(slow_skip));

assertTestNotFail(slow_skip);
assertTrue(checkTestNotFail(slow_skip));

assertTestNotSkip(slow_skip);
assertTrue(checkTestNotSkip(slow_skip));

assertTestNotExpire(slow_skip);
assertTrue(checkTestNotExpire(slow_skip));
}
if (now > 2000) {
assertTestDone(slow_skip);
assertTrue(checkTestDone(slow_skip));

assertTestNotPass(slow_skip);
assertTrue(checkTestNotPass(slow_skip));

assertTestNotFail(slow_skip);
assertTrue(checkTestNotFail(slow_skip));

assertTestSkip(slow_skip);
assertTrue(checkTestSkip(slow_skip));

assertTestNotExpire(slow_skip);
assertTrue(checkTestNotExpire(slow_skip));

pass();
}
}

#if USE_AUNIT == 1
testing(slow_expire_monitor) {
unsigned long now = millis();
if (now < 1000) {
assertTestNotDone(slow_expire);
assertTrue(checkTestNotDone(slow_expire));

assertTestNotPass(slow_expire);
assertTrue(checkTestNotPass(slow_expire));

assertTestNotFail(slow_expire);
assertTrue(checkTestNotFail(slow_expire));

assertTestNotSkip(slow_expire);
assertTrue(checkTestNotSkip(slow_expire));

assertTestNotExpire(slow_expire);
assertTrue(checkTestNotExpire(slow_expire));
}
if (now > 2000) {
assertTestDone(slow_expire);
assertTrue(checkTestDone(slow_expire));

assertTestNotPass(slow_expire);
assertTrue(checkTestNotPass(slow_expire));

assertTestNotFail(slow_expire);
assertTrue(checkTestNotFail(slow_expire));

assertTestNotSkip(slow_expire);
assertTrue(checkTestNotSkip(slow_expire));

assertTestExpire(slow_expire);
assertTrue(checkTestExpire(slow_expire));

pass();
}
}
#endif

void setup() {
Serial.begin(74880); // 74880 is default for some ESP8266 boards
while(!Serial); // for the Arduino Leonardo/Micro only
}

void loop() {
#if USE_AUNIT == 1
// Should get the following summary output:
// TestRunner summary:
// 5 passed, 1 failed, 1 skipped, 1 timed out, out of 8 test(s).
//
//TestRunner::setVerbosity(Verbosity::kAll);
TestRunner::run();
#else
// Should get the following summary output:
// Test summary: 4 passed, 1 failed, and 1 skipped, out of 6 test(s).
Test::run();
#endif
}
Loading

0 comments on commit b042c64

Please sign in to comment.