AUnit

A unit testing framework for Arduino platforms inspired by by ArduinoUnit and Google Test. AUnit is almost a drop-in replacement of ArduinoUnit (v2.2) with some advantages. AUnit 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. The assertion error messages were updated in v1.7 to provide seamless integration with Unix tools like vim.

Originally, the AUnit tests were designed to run on the embedded controller itself which allows detection of architecture-specific problems. But the uploading, flashing, and execution process is often slow and flaky, causing the iteration cycle to take too much time. It is often more effective to execute the AUnit tests natively on a host machine (running Linux, MacOS, or FreeBSD) using the EpoxyDuino companion project. Once the unit tests are running on the Linux or MacOS host machine, they can be incorporated into a continuous integration system like Jenkins system or a cloud-based system like GitHub Actions.

Version: 1.7.1 (2023-06-15)

Changelog: CHANGELOG.md

Table of Contents

• Summary
  • ArduinoUnit Compatible Features
  • Missing Features
  • Added Features
• Installation
  • Source Code
• Documentation
  • Examples
• Usage
  • Header and Namespace
  • Verbose Mode
  • Defining the Tests
  • Generated Class and Instance Names
  • Binary Assertions
    • Assertion Message Format
    • Supported Parameter Types
    • Parameter Types Must Match
    • Pointer Comparisons
    • Case Insensitive String Comparisons
  • Approximate Comparisons
  • Boolean Assertions
  • Test Fixtures
  • Early Return and Delayed Assertions
  • Meta Assertions
  • Unconditional Termination
  • Overridable Methods
  • Running the Tests
  • Filtering Test Cases
  • Output Printer
  • Controlling Verbosity
  • Line Number Mismatch
  • Test Framework Messages
    • Assertion Message
    • Verbose Mode Message
    • Test Case Summary
    • Test Runner Summary
  • Test Timeout
• GoogleTest Adapter
• Command Line Tools
  • AUniter
  • EpoxyDuino
  • Command Line Flags and Arguments
• Continuous Integration
  • Arduino IDE/CLI + Cloud
  • Arduino IDE/CLI + Jenkins
  • EpoxyDuino + Jenkins
  • EpoxyDuino + Cloud (Recommended)
• Tips
  • Debugging Assertions in Fixtures
  • Class Hierarchy
  • Testing Private Helper Methods
• Benchmarks
  • Memory Benchmark
  • Compared with ArduinoUnit
• System Requirements
  • Hardware
  • Toolchains
  • Operating System
• License
• Feedback and Support
• Authors

<a name="Summary"></a>

Summary

AUnit was created to solve 3 problems with ArduinoUnit 2.2:

• ArduinoUnit consumes too much flash memory on an AVR platform (e.g. Arduino UNO, Nano) as explained in ArduinoUnit#70.
• ArduinoUnit does not compile on the ESP8266 platform (see ArduinoUnit#68, ArduinoUnit#55, ArduinoUnit#54).
• ArduinoUnit does not provide an easy way to create tests using fixtures, equivalent to the TEST_F() macro in Google Test.

In contrast:

• AUnit consumes as much as 65% less flash memory than ArduinoUnit 2.2 on the AVR platform. On Teensy-ARM, the savings can be as much as 30%.
• AUnit has been tested on AVR, Teensy-ARM and ESP8266.
• AUnit implements the testF() and testingF() macros to use fixtures.

The AUniter command line tools can compile the unit tests, upload them to Arduino boards attached to the serial ports of the local machine, and validate the output of the AUnit test runner. In addition, the AUniter script can be integrated into a Jenkins continuous integration service running on the local machine, and the unit tests can be monitored automatically.

Unit tests written using AUnit can often be compiled and executed natively on Linux or MacOS using the EpoxyDuino library. The output on the Serial object is redirected to the stdout of the Unix host. This provides another avenue for implementing continuous builds or integration.

<a name="ArduinoUnitCompatible"></a>

ArduinoUnit Compatible Features

For basic unit tests written using ArduinoUnit 2.2, only two changes are required to convert to AUnit:

• #include <ArduinoUnit.h> -> #include <AUnit.h>
• Test::run() -> aunit::TestRunner::run()

Most of the core macros are compatible between ArduinoUnit and AUnit:

• test()
• testing()
• assertXxx()
• Meta Assertions
  • checkTestXxx()
  • assertTestXxx()
• externTest()
• externTesting()

AUnit also supports exclude and include filters:

• TestRunner::exclude()
• TestRunner::include()

Filters can be accessed through Command Line Flags on desktop machines using EpoxyDuino

The various assertion and test status messages can be enabled or disabled using the Verbosity flags on per test basis:

• enableVerbosity()
• disableVerbosity()

<a name="MissingFeatures"></a>

Missing Features

Here are the features which have not been ported over from ArduinoUnit 2.2:

• 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.

<a name="AddedFeatures"></a>

Added Features

Here are the features in AUnit which are not available in ArduinoUnit 2.2:

• Configurable timeout parameter to prevent testing() test cases from running forever:
  • TestRunner::setTimeout(seconds)
  • Test::expire()
  • assertTestExpire()
  • assertTestNotExpire()
  • checkTestExpire()
  • checkTestNotExpire()
• Case-insensitive string comparisons:
  • assertStringCaseEqual()
  • assertStringCaseNotEqual()
• Approximate comparisons:
  • assertNear()
  • asssertNotNear()
• Supports 64-bit integer
  • assertXxx() support both long long and unsigned long long
• test() and testing() macros support both 1 and 2 arguments
  • test(testName) and test(suiteName, testName)
  • testing(testName) and testing(suiteName, testName)
• Test fixtures using the "F" variations of existing macros:
  • testF()
  • testingF()
  • assertTestXxxF()
  • checkTestXxxF()
  • externTestF()
  • externTestingF()
• Unconditional termination:
  • passTestNow()
  • failTestNow()
  • skipTestNow()
  • expireTestNow()
• teardown() method which mirrors the setup() method:
  • teardown()
• Test filters support 2-arguments, matching testF() and testingF():
  • TestRunner::include(testClass, name)
  • TestRunner::exclude(testClass, name)
• No dynamic allocation of heap memory:
  • The library does not create a String object.
  • It reads from a String if the calling code provides it.
• Terse and verbose modes:
  • #include <AUnit.h> - terse messages use less flash memory
  • #include <AUnitVerbose.h> - verbose messages use more flash memory

Every feature of AUnit is unit tested using AUnit itself.

<a name="Installation"></a>

Installation

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 development version can be installed by cloning the GitHub repository, 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.

<a name="SourceCode"></a>

Source Code

The source files are organized as follows:

• src/AUnit.h - main header file
• src/AUnitVerbose.h - verbose version of main header file
• src/aunit/ - all implementation fi