Getting Started with the µTest++ Testing Framework
To address the specific needs of different audiences, this site features separate User's Guide, Contributor's Guide and Maintainer's Guide pages. This way, each group can easily find the information and resources most relevant to them.
Overview
The µTest++ Testing Framework project (micro test plus plus) is a C++ source code library that provides a testing framework with a small memory footprint, designed mainly for running unit tests on embedded platforms in a reproducible way.
What are reproducible operations?
To be reproducible, an operation must remain stable over time and across different environments. In other words, if the same operation is repeated after some time, possibly on a different machine or platform, the resulting behaviour must be functionally equivalent.
In this context, embedded refers exclusively to bare-metal systems, not embedded Linux, which necessitates a different approach for building Linux user-space applications.
The open-source µTest++ Testing Framework project is hosted on GitHub as
micro-os-plus/micro-test-plus-xpack.
As an npm/xpm package, the content is also published as
@micro-os-plus/micro-test-plus
on the npmjs.com repository
and can be integrated into projects as an xpm
dependency.
What are xpm packages? (xPacks)
xpm packages, abbreviated as xPacks, are versatile, language-neutral software packages. They have been successfully utilised in C/C++ projects.
What the heck are xpm packages (xPacks)? Please, do not introduce another package format!
Although the initial appearance may seem complex, utilising xpm packages is, in fact, straightforward. The design rationale is to automate frequent operations that occur during software development, such as the installation of dependencies, and to ensure reproducibility.
These packages are managed by xpm (the xPack Project Manager), a programme that complements the npm CLI (the popular JavaScript package manager), with new language-neutral features.
The xPacks Framework does NOT introduce a new package format; instead,
it uses the same format as npm packages, which is a collection of
files/folders and a package.json file with the package metadata.
xpm can install packages from the same repositories as npm, whether public or private.
The packages (usually regular archives, but also git repositories), are extracted into separate folders within the project.
Based on the content, there are two types of xpm packages:
- packages with source libraries (source xpm packages)
- packages with executables, usually platform-specific binary tools (binary xpm packages)
Source xpm packages are regular npm packages that include library source files, typically in C/C++, though there are no language restrictions.
Binary xpm packages are also regular npm packages, but with minimal
content, typically just the package.json file. Since these packages
provide executables for multiple platforms, some of which are quite
large, it is not practical to include all binaries within the npm
package itself. Instead, the package.json file contains references
(URLs) to platform-specific binary archives (e.g., .tar.gz for Unix or
.zip for Windows).
These archives are also expanded along with the package metadata.
Links/forwarders to
these executables are created in a .bin folder,
eliminating the need to add multiple folders to the PATH.
In summary, xpm packages can enhance and automate the installation process for source libraries and tools.
In summary, xpm packages can streamline and automate the installation process for source libraries and tools. Further details are available on the xpm Concepts page.
Features
The main characteristics of the µTest++ Testing Framework, essentially inherited from Boost UT, are:
- Designed to test both C and C++ projects.
- Modern C++20 code (which also raised the bar to C++20 for the entire µOS++ project).
- Macro-free (while preserving the nice feature of reporting the file name and line number for failed tests).
- Expectations, assumptions, exceptions.
- Test cases, test suites.
- Automatic test suites registration.
As major differentiators from Boost UT:
- Reduced memory footprint, as there are no dependencies on the standard C++ stream library.
- A slightly simplified API.
Benefits
- Versatility in testing both C and C++ projects: Provides a streamlined testing process for projects containing both languages.
- Utilisation of contemporary C++20 features for optimal performance: Enhances readability and maintainability of the code.
- Reduced complexity and improved clarity without macros: Simplifies the testing process.
- Comprehensive testing capabilities: Covers various scenarios efficiently.
- Structured approach to organising and executing tests: Facilitates easier management and scalability of test scenarios.
- Simplified test suite management with automated registration: Requires reduced manual intervention and improves efficiency.
- Enhanced performance on embedded platforms with limited memory: Optimises resource utilisation and performance.
Install
The source code library can be installed automatically with xpm or manually, either by copying the relevant files into the target project, or by linking the entire project as a Git submodule.
The details for installing the µTest++ Testing Framework can be found in the Install Guide.
Status
The µTest++ Testing Framework project is fully functional, stable, and suitable for use in production environments.
Testing
The library is CI tested on every push via GitHub Actions, on Ubuntu, macOS, and Windows.
The tests run on 32 and 64-bit bare-metal platforms (Arm Cortex-M0, Cortex-M3, Cortex-M4F, Cortex-M7F, Cortex-A15, Cortex-A72, RISC-V RV32IMAC, RV64IMAFDC), and natively, with GCC and LLVM/clang.
Release schedule
There are no scheduled releases; the project adheres to a continuous release approach, with updates deployed as development progresses.
Releases
The list of releases is available in the Releases pages.
Change log
The release and change log is available in the repository
CHANGELOG.md file.
Support & feedback
The quick advice for getting support and providing feedback is to use the GitHub Discussions.
For additional information, please refer to the Help Centre page.
Compatibility notices
According to SemVer rules:
Major version X (X.y.z | X > 0) MUST be incremented if any backwards incompatible changes are introduced to the public API.
The breaking changes introduced by each major release, in reverse chronological order, are:
v3.x (2022-04-03)
Major rework, with full set of comparators, exceptions, function templates for test cases and class templates for test suites.
v2.3.x (2022-02-19)
Deprecate run_test_case(func, name) in favour of
run_test_case(name, func), to prepare for variadic templates.
v2.x (2021-03-01)
The C++ namespace was renamed from os to micro_os_plus.
v1.x (2021-02-04)
The initial code (inspired in its simplicity by node-tap) was extracted from the mono-repo µOS++ project.
License
Unless otherwise stated, the original content is released under the terms of the MIT License, with all rights reserved by Liviu Ionescu.
The code from Boost UT is released under the terms of the Boost Version 1.0 Software License.
Credits
Many thanks to:
- Node tap - for the great example showing that testing frameworks do not need to be very complicated and for the inspiration in writing the initial versions
- Boost UT - for showing that in C++ getting the file name and line number is possible without the ugly C macros and for major parts of the code
- Doxygen - for the site generator
- doxygen-awesome-css - for the nice Doxygen theme
- SVG REPO - for the SVG icons
Thanks to Shields IO for the badges.
Enjoyed Using This Project? Let Us Know!
If you enjoyed using this project, please let us know! Here are some ways you can show your support:
