Merge pull request #78 from bxparks/develop

merge v1.6.0 into master

Author: bxparks

CHANGELOG.md

@@ -1,6 +1,33 @@
 # Changelog
 
 * Unreleased
+* 1.6.0 (2021-11-02)
+    * Add `TestRunner::includesub(word)` and `TestRunner::excludesub(word)`
+      which includes or excludes tests based on the substring match on the
+      `word`.
+    * Call `excludeAll()` if the first filtering request is an `include()` or
+      `includesub()`.
+        * Otherwise, the first include request does not do anything.
+    * Add command line flags and arguments when compiled under EpoxyDuino.
+      See [Command Line Flags and
+      Arguments](README.md#CommandLineFlagsAndArguments) in the README.md for
+      full details. Fixes
+      [Issue#76](https://github.com/bxparks/AUnit/issues/76).
+        * `--include pattern,...`
+            * Calls `TestRunner::include(pattern)` on each `pattern` in the
+              comma-separated list.
+        * `--exclude pattern,...`
+            * Calls `TestRunner::exclude(pattern)` on each `pattern` in the
+              comma-separated list.
+        * `--includesub substring,...`
+            * Calls `TestRunner::includesub(substring)` on each `substring` in
+              the comma-separated list.
+        * `--excludesub substring,...`
+            * Calls `TestRunner::excludesub(substring)` on each `substring` in
+              the comma-separated list.
+        * `substring ...`
+            * Any remaining **space**-separated list of words are processed
+              using `TestRunner::includesub(substring)`.
 * 1.5.5 (2021-05-03)
     * Prevent accidental inclusion of `HardwareSerial` class (via the `Serial`
       global variable). Remove reference to `SERIAL_PORT_MONITOR` from

README.md

@@ -2,11 +2,6 @@
 
 [![AUnit Tests](https://github.com/bxparks/AUnit/actions/workflows/aunit_tests.yml/badge.svg)](https://github.com/bxparks/AUnit/actions/workflows/aunit_tests.yml)
 
-**New**: [GitHub Discussions](https://github.com/bxparks/AUnit/discussions)
-for this project is now active! Let's use that for general support questions,
-and reserve the [GitHub Issues](https://github.com/bxparks/AUnit/issues)
-section for bugs and feature requests.
-
 A unit testing framework for Arduino platforms inspired by by
 [ArduinoUnit](https://github.com/mmurdoch/arduinounit) and [Google
 Test](https://github.com/google/googletest/). The unit tests usually run on the
@@ -16,7 +11,7 @@ natively on Linux or MacOS using the
 [EpoxyDuino](https://github.com/bxparks/EpoxyDuino) companion project.
 
 AUnit is almost a drop-in replacement of ArduinoUnit with some advantages. AUnit
-supports timeouts and test fixtures. It somtimes consumes 50% less flash memory
+supports timeouts and test fixtures. It sometimes consumes 50% less flash memory
 on the AVR platform, and it has been tested to work on the AVR, SAMD21, STM32,
 ESP8266, ESP32 and Teensy platforms. Another companion project
 [AUniter](https://github.com/bxparks/AUniter) project provides command line
@@ -25,7 +20,7 @@ instead of having to go through the Arduino IDE. Both the AUniter and
 EpoxyDuino tools can be used in a continuous integration system like Jenkins,
 or with [GitHub Actions](https://github.com/features/actions).
 
-**Version**: 1.5.5 (2021-05-03)
+**Version**: 1.6 (2021-11-02)
 
 **Changelog**: [CHANGELOG.md](CHANGELOG.md)
 
@@ -57,7 +52,7 @@ or with [GitHub Actions](https://github.com/features/actions).
     * [Unconditional Termination](#UnconditionalTermination)
     * [Overridable Methods](#OverridableMethods)
     * [Running the Tests](#RunningTests)
-    * [Filering Test Cases](#FilteringTestCases)
+    * [Filtering Test Cases](#FilteringTestCases)
     * [Output Printer](#OutputPrinter)
     * [Controlling Verbosity](#ControllingVerbosity)
     * [Line Number Mismatch](#LineNumberMismatch)
@@ -71,11 +66,12 @@ or with [GitHub Actions](https://github.com/features/actions).
 * [Command Line Tools](#CommandLineTools)
     * [AUniter](#AUniter)
     * [EpoxyDuino](#EpoxyDuino)
+    * [Command Line Flags and Arguments](#CommandLineFlagsAndArguments)
 * [Continuous Integration](#ContinuousIntegration)
     * [Arduino IDE/CLI + Cloud](#IdePlusCloud)
     * [Arduino IDE/CLI + Jenkins](#IdePlusJenkins)
     * [EpoxyDuino + Jenkins](#EpoxyDuinoPlusJenkins)
-    * [EpoxyDuino + Cloud (Recommmended)](#EpoxyDuinoPlusCloud)
+    * [EpoxyDuino + Cloud (Recommended)](#EpoxyDuinoPlusCloud)
 * [Tips](#Tips)
     * [Debugging Assertions in Fixtures](#DebuggingFixtures)
     * [Class Hierarchy](#ClassHierarchy)
@@ -652,7 +648,7 @@ test(nullPointer) {
 }
 ```
 
-prints the following:
+This will print the following:
 
 ```
 Assertion failed: (aa=0x3FFFFF58) == (nullptr=0x0), file AUnitTest.ino, line 348.
@@ -710,7 +706,7 @@ errors. Google Test provides
   `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:
+AUnit offers only the equivalent of `ASSERT_NEAR()` function:
 
 * `assertNear(a, b, error)`
 * `assertNotNear(a, b, error)`
@@ -761,7 +757,7 @@ The following boolean asserts are also available:
 
 When the unit tests become more complex, using test fixtures will allow you to
 place common data objects and methods into a class that can be shared among
-multiple test cases. This concept matches very closely to the the test fixtures
+multiple test cases. This concept matches very closely to the test fixtures
 in
 [Google Test](https://github.com/google/googletest/blob/master/googletest/docs/Primer.md).
 
@@ -1056,32 +1052,45 @@ only a single test case, then returns._
 <a name="FilteringTestCases"></a>
 ### Filtering Test Cases
 
-We can `exclude()` or `include()` test cases using a pattern match:
-
-* `TestRunner::exclude(pattern)`
-* `TestRunner::exclude(testClass, pattern)`
-* `TestRunner::include(pattern)`
-* `TestRunner::include(testClass, pattern)`
+Six filtering methods are available on the `TestRunner` class:
+* `TestRunner::include(pattern)` - prefix match
+* `TestRunner::include(testClass, pattern)` - prefix match
+* `TestRunner::exclude(pattern)` - prefix match
+* `TestRunner::exclude(testClass, pattern)` - prefix match
+* `TestRunner::includesub(substring)` - substring match (v1.6)
+* `TestRunner::excludesub(substring)` - substring match (v1.6)
 
-These methods are called from the global `setup()` method:
+These methods are called from the global `setup()` method, for example:
 
 ```C++
 void setup() {
-  TestRunner::exclude("*");
   TestRunner::include("looping*");
   TestRunner::exclude("CustomTestAgain", "*");
   TestRunner::include("CustomTestAgain", "test*");
+  TestRunner::include("CustomTestAgain", "test*");
+  TestRunner::includesub("net");
+  TestRunner::excludesub("net");
   ...
 }
 ```
 
-Excluded tests bypass their `setup()` and `teardown()` methods and terminate
-immidiately. For the purposes of reporting, however, excluded tests are
-counted as "skipped".
+Excluded tests bypass their `Test::setup()` and `Test::teardown()` methods and
+terminate immediately. For the purposes of reporting, excluded tests are counted
+as "skipped".
 
 The 2-argument versions of `include()` and `exclude()` correspond to the
 2 arguments of `testF()` and `testingF()`.
 
+The filtering methods are also available as command line flags and arguments
+(`--include`, `--exclude`, `--includesub` `--excludesub`) if the test
+program is compiled using EpoxyDuino under a Unix-like environment. See
+the [EpoxyDuino](#EpoxyDuino) section below.
+
+**Implicit Exclude All**: If the *first* filtering request is an "include" (i.e.
+`include(pattern)`, `include(testClass, pattern)`, `includesub(substring)`),
+all tests are excluded by default initially, instead of being included by
+default. Otherwise, the first "include" statement would have no effect.
+
 ***ArduinoUnit Compatibility***:
 _The equivalent versions in ArduinoUnit are `Test::exclude()` and
 `Test::include()` The matching algorithm in AUnit is not as powerful as the one
@@ -1398,7 +1407,7 @@ or
 ## Command Line Tools
 
 Each unit test is an independent `*.ino` program. You can run it using your
-Ardunio IDE. But there are 2 command line tools that can be used to run them.
+Arduino IDE. But there are 2 command line tools that can be used to run them.
 
 <a name="AUniter"></a>
 ### AUniter
@@ -1490,6 +1499,65 @@ EpoxyDuino, the test program will terminate at the end through the
 will call `exit(0)`. If there are any failing tests (i.e. failed or timed out),
 it will call `exit(1)`.
 
+<a name="CommandLineFlagsAndArguments"></a>
+### Command Line Flags and Arguments
+
+(Added in v1.6)
+
+The standard Arduino environment does not provide command line arguments, since
+a microcontroller does not normally provide a command line environment. However,
+if the AUnit test program is compiled under EpoxyDuino, the standard Unix
+command line parameters (`argc` and `argv`)  become available through the
+`extern int epoxy_argc` and `extern const char* const* epoxy_argv` global
+variables. These allow the `TestRunner` class to provide command line flags and
+arguments as follows:
+
+```bash
+$ ./test.out --help
+Usage: ./test.out [--help] [--include pattern,...] [--exclude pattern,...]
+   [--includesub substring,...] [--excludesub substring,...]
+   [--] [substring ...]
+```
+
+Example, the following runs all tests with substring "net" or "led" in its
+name, and skips all others:
+
+```bash
+$ ./test.out net led
+```
+
+Flags:
+
+* `--include pattern,...`
+    * Comma-separated list of patterns to pass to the
+      `TestRunner::include(pattern)` method
+* `--exclude pattern,...`
+    * Comma-separated list of patterns to pass to the
+      `TestRunner::exclude(pattern)` method
+* `--includesub substring,...`
+    * Comma-separated list of substrings to pass to the
+      `TestRunner::includesub(substring)` method
+* `--excludesub substring,...`
+    * Comma-separated list of substrings to pass to the
+      `TestRunner::excludesub(substring)` method
+
+Arguments:
+
+* Any **Space**-separated list of words after the optional flags are passed to
+  the `TestRunner::includesub(substring)` method.
+
+The command line flags and arguments are processed *after* any hardcoded calls
+to `TestRunner::include()` and `TestRunner::exclude()` methods in the global
+`setup()` method.
+
+The flags and command line arguments are processed *in order* of appearance
+on the command line.
+
+Similar to the hardcoded calls to `TestRunner::include()` and
+`TestRunner::exclude()`, if the first command line flag is an `--include` or
+`--includesub`, then all tests are *excluded* by default initially. Otherwise,
+the first include flag would have no effect.
+
 <a name="ContinuousIntegration"></a>
 ## Continuous Integration
 
@@ -1542,7 +1610,7 @@ Although I think it's theoretically possible, I have never actually verified
 that this can be done.
 
 <a name="IdePlusJenkins"></a>
-### Arduion IDE/CLI + Jenkins
+### Arduino IDE/CLI + Jenkins
 
 This setup is described in [Continuous Integration with
 Jenkins](https://github.com/bxparks/AUniter/tree/develop/jenkins), and it worked
@@ -1835,15 +1903,15 @@ I will occasionally test on the following hardware as a sanity check:
 
 The following boards are **not** supported:
 
-* megaAVR (e.g. Nano Every) using ArduinoCore-megaavr
-  (https://github.com/arduino/ArduinoCore-megaavr/)
-* SAMD21 boards (e.g. MKRZero) using ArduinoCore-samd
-  (https://github.com/arduino/ArduinoCore-samd) starting with
-  `arduino:samd` version >= 1.8.10
-* Raspberry Pi Pico (RP2040) using Arduino-Pico
-  (https://github.com/earlephilhower/arduino-pico)
-* Any other platform using the ArduinoCore-API
-  (https://github.com/arduino/ArduinoCore-api)
+* Any platform using the ArduinoCore-API
+  (https://github.com/arduino/ArduinoCore-api), such as:
+    * megaAVR (e.g. Nano Every) using ArduinoCore-megaavr
+      (https://github.com/arduino/ArduinoCore-megaavr/)
+    * SAMD21 boards (e.g. MKRZero) using ArduinoCore-samd
+      (https://github.com/arduino/ArduinoCore-samd) starting with
+      `arduino:samd` version >= 1.8.10
+    * Raspberry Pi Pico (RP2040) using Arduino-Pico
+      (https://github.com/earlephilhower/arduino-pico)
 
 <a name="ToolChain"></a>
 ### Tool Chain
@@ -1855,15 +1923,18 @@ This library was validated using:
 * [Arduino SAMD Boards 1.8.9](https://github.com/arduino/ArduinoCore-samd)
 * [SparkFun AVR Boards 1.1.13](https://github.com/sparkfun/Arduino_Boards)
 * [SparkFun SAMD Boards 1.8.1](https://github.com/sparkfun/Arduino_Boards)
-* [STM32duino 1.9.0](https://github.com/stm32duino/Arduino_Core_STM32)
+* [STM32duino 2.0.0](https://github.com/stm32duino/Arduino_Core_STM32)
 * [ESP8266 Arduino 2.7.4](https://github.com/esp8266/Arduino)
 * [ESP32 Arduino 1.0.6](https://github.com/espressif/arduino-esp32)
-* [Teensyduino 1.53](https://www.pjrc.com/teensy/td_download.html)
+* [Teensyduino 1.54](https://www.pjrc.com/teensy/td_download.html)
 
 This library is *not* compatible with:
-* [Arduino SAMD Boards >=1.8.10](https://github.com/arduino/ArduinoCore-samd)
-* [Arduino megaAVR](https://github.com/arduino/ArduinoCore-megaavr/)
-* [MegaCoreX](https://github.com/MCUdude/MegaCoreX)
+
+* Any platform using the
+  [ArduinoCore-API](https://github.com/arduino/ArduinoCore-api), for example:
+    * [Arduino SAMD Boards >=1.8.10](https://github.com/arduino/ArduinoCore-samd)
+    * [Arduino megaAVR](https://github.com/arduino/ArduinoCore-megaavr/)
+    * [MegaCoreX](https://github.com/MCUdude/MegaCoreX)
 
 (See [Issue #56](https://github.com/bxparks/AUnit/issues/56)
 and [Issue #66](https://github.com/bxparks/AUnit/issues/66)).
@@ -1874,7 +1945,8 @@ not tested it extensively.
 <a name="OperatingSystem"></a>
 ### Operating System
 
-I used MacOS 10.13.3, Ubuntu 18.04, and Ubuntu 20.04 for most of my development.
+I use Ubuntu 20.04 for the vast majority of my development. I expect that the
+library will work fine under MacOS and Windows, but I have not tested them.
 
 <a name="License"></a>
 ## License
@@ -1884,18 +1956,14 @@ I used MacOS 10.13.3, Ubuntu 18.04, and Ubuntu 20.04 for most of my development.
 <a name="FeedbackAndSupport"></a>
 ## Feedback and Support
 
-If you find this library useful, consider starring this project on GitHub. The
-stars will let me prioritize the more popular libraries over the less popular
-ones.
-
-If you have any questions, comments and other support questions about how to
-use this library, please use the
-[GitHub Discussions](https://github.com/bxparks/AUnit/discussions)
-for this project. If you have bug reports or feature requests, please file a
-ticket in [GitHub Issues](https://github.com/bxparks/AUnit/issues).
-I'd love to hear about how this software and its documentation can be improved.
-I can't promise that I will incorporate everything, but I will give your ideas
-serious consideration.
+If you have any questions, comments, or feature requests for this library,
+please use the [GitHub
+Discussions](https://github.com/bxparks/AUnit/discussions) for this project. If
+you have bug reports, please file a ticket in [GitHub
+Issues](https://github.com/bxparks/AUnit/issues). Feature requests should go
+into Discussions first because they often have alternative solutions which are
+useful to remain visible, instead of disappearing from the default view of the
+Issue tracker after the ticket is closed.
 
 Please refrain from emailing me directly unless the content is sensitive. The
 problem with email is that I cannot reference the email conversation when other

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.5.5
+PROJECT_NUMBER         = 1.6.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

@@ -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.5.5</span>
+   &#160;<span id="projectnumber">1.6.0</span>
    </div>
    <div id="projectbrief">Unit testing framework for Arduino platforms inspired by ArduinoUnit and Google Test.</div>
   </td>
@@ -120,10 +120,10 @@
 <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;10505</td></tr>
+#define&#160;</td><td class="memItemRight" valign="bottom"><b>AUNIT_VERSION</b>&#160;&#160;&#160;10600</td></tr>
 <tr class="separator:a87cbb10969eff63f8ae66afc4e9457eb"><td class="memSeparator" colspan="2">&#160;</td></tr>
 <tr class="memitem:a70ade1487f0d9d7172f24897cd0f2dd5"><td class="memItemLeft" align="right" valign="top"><a id="a70ade1487f0d9d7172f24897cd0f2dd5"></a>
-#define&#160;</td><td class="memItemRight" valign="bottom"><b>AUNIT_VERSION_STRING</b>&#160;&#160;&#160;&quot;1.5.5&quot;</td></tr>
+#define&#160;</td><td class="memItemRight" valign="bottom"><b>AUNIT_VERSION_STRING</b>&#160;&#160;&#160;&quot;1.6.0&quot;</td></tr>
 <tr class="separator:a70ade1487f0d9d7172f24897cd0f2dd5"><td class="memSeparator" colspan="2">&#160;</td></tr>
 </table>
 <a name="details" id="details"></a><h2 class="groupheader">Detailed Description</h2>

docs/html/AUnitVerbose_8h_source.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.5.5</span>
+   &#160;<span id="projectnumber">1.6.0</span>
    </div>
    <div id="projectbrief">Unit testing framework for Arduino platforms inspired by ArduinoUnit and Google Test.</div>
   </td>
@@ -124,8 +124,8 @@
 <div class="line"><a name="l00061"></a><span class="lineno">   61</span>&#160;<span class="preprocessor">#include &quot;<a class="code" href="TestMacros_8h.html">aunit/TestMacros.h</a>&quot;</span></div>
 <div class="line"><a name="l00062"></a><span class="lineno">   62</span>&#160; </div>
 <div class="line"><a name="l00063"></a><span class="lineno">   63</span>&#160;<span class="comment">// Version format: xxyyzz == &quot;xx.yy.zz&quot;</span></div>
-<div class="line"><a name="l00064"></a><span class="lineno">   64</span>&#160;<span class="preprocessor">#define AUNIT_VERSION 10505</span></div>
-<div class="line"><a name="l00065"></a><span class="lineno">   65</span>&#160;<span class="preprocessor">#define AUNIT_VERSION_STRING &quot;1.5.5&quot;</span></div>
+<div class="line"><a name="l00064"></a><span class="lineno">   64</span>&#160;<span class="preprocessor">#define AUNIT_VERSION 10600</span></div>
+<div class="line"><a name="l00065"></a><span class="lineno">   65</span>&#160;<span class="preprocessor">#define AUNIT_VERSION_STRING &quot;1.6.0&quot;</span></div>
 <div class="line"><a name="l00066"></a><span class="lineno">   66</span>&#160; </div>
 <div class="line"><a name="l00067"></a><span class="lineno">   67</span>&#160;<span class="preprocessor">#endif</span></div>
 </div><!-- fragment --></div><!-- contents -->