Getting Started with the µTest++ Testing Framework
The site has a separate guide for each audience:
- the Integration Guide;
- the User's Guide;
- the Contributor's Guide;
- the Maintainer's Guide.
Overview
The µTest++ Testing Framework project (micro test plus plus) is a macro-free modern C++ library offering a testing framework characterised by a small memory footprint, primarily intended for executing unit tests on embedded platforms in a reproducible manner. Test results are reported in TAP (Test Anything Protocol) format, enabling simple integration with standard TAP-aware tooling.
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, the term embedded refers to bare-metal systems, excluding embedded Linux, which requires a different approach to development.
The open-source µTest++ Testing Framework project is available
on GitHub under the repository name
micro-os-plus/micro-test-plus-xpack.
Additionally, the content is published on the npmjs.com repository as
@micro-os-plus/micro-test-plus,
making it accessible for integration into projects as an
xpm dependency.
Features and benefits
The main attributes of the µTest++ Testing Framework are as follows. Its model, with test suites, test cases, and results reported in TAP (Test Anything Protocol) format, follows node-tap; the function comparators were inspired by Boost UT.
- Results reported in TAP format, enabling simple integration with standard TAP-aware tooling, with a human-readable reporter available on request.
- Test suites, and test cases that may be nested, created with a
t.test()andt.expect()mechanism modelled on node-tap. - Parametrised tests, with
test_each(), which runs a test case for each value of a list, a range, or a tuple. - Support for expectations, requirements, and exceptions.
- Custom types and custom comparators, reported with their operands as the built-in ones.
- Selection of the suites and of the test cases by name, and listing of the test cases, from the command line.
- Builds without exceptions, common on embedded targets, where a failed requirement aborts the test execution.
- Automatic registration of test suites: each test suite can be defined as a static global object in its own source file, and registration with the test runner is performed automatically via the C++ static constructors mechanism, eliminating the need for any explicit registration calls.
- Macro-free implementation, while retaining the ability to report the file name and line number for failed tests.
- Written in modern C++20, improving code readability and maintainability.
- Designed for testing both C and C++ projects (the tests themselves are written in C++20).
Key distinctions from Boost UT include:
- Reduced memory footprint, owing to its independence from the C++ stream library — particularly beneficial on embedded platforms with constrained memory resources.
- A slightly simplified API.
Install
The source code library can be installed either automatically via xpm or manually. Manual installation can be performed by copying the necessary files directly into the target project or by linking the entire project as a Git submodule.
Detailed instructions for installing the µTest++ Testing Framework are available in the Integration Guide.
What are xpm packages? (xPacks)
xpm packages, also known as xPacks, are language-neutral software packages, used in C and C++ projects.
Why xpm packages, and not another package format?
In practice, xpm packages are simple. They automate frequent tasks of software development, such as installing the dependencies, and make the builds reproducible.
xpm packages are managed by xpm (the xPack Project Manager), a utility that complements the npm CLI, the widely used JavaScript package manager, by introducing language-neutral features.
The xPack Framework does not define a new package format; it
adopts the standard npm package format, which comprises
a collection of files and folders, with a package.json
file containing the metadata.
xpm can install packages from the same repositories as npm, public or private.
Packages, which are typically regular archives or git repositories, are extracted into distinct folders within the project.
Based on their contents, xpm packages fall into two categories:
- Source xpm packages: these contain source libraries;
- Binary xpm packages: these typically consist of executables, often platform-specific binary tools.
Source xpm packages are standard npm packages that incorporate library source files, usually written in C/C++, although they are not restricted to any particular programming language.
Binary xpm packages are also standard npm packages but have
minimal contents, generally limited to a package.json file.
Since these packages provide executables for multiple platforms —
many of which can be considerably large — it is impractical to
include all binaries within the npm package itself. Instead, the
package.json file includes references (URLs) to platform-specific
binary archives (e.g., .tar.gz for Unix or .zip for Windows).
These archives, along with the package metadata, are extracted.
Additionally, links or forwarders to the executables are created
within a .bin folder, thereby eliminating the need to add multiple
folders to the system PATH.
For more information, see the xpm Concepts page.
Status
The µTest++ Testing Framework project is stable, and can be used in production environments.
Where to go next
The documentation of the library has the following parts:
- the Integration Guide: how to install the library and add it to a build;
- the User's Guide: how to write and run tests, with the options and the reports;
- the API reference: the classes, the functions, and the concepts of the library.
Testing
The library is subject to continuous integration (CI) testing with every push using GitHub Actions. The tests run on Ubuntu, macOS, and Windows.
Testing is conducted on both 32-bit and 64-bit bare-metal platforms, including a selection of Arm Cortex-M, Cortex-A and RISC-V, running using QEMU.
The native tests run with the GCC and LLVM/clang compilers.
A workflow that runs the tests on all the supported platforms and
configurations can be triggered manually in the GitHub Actions interface, the
Eun all tests workflow.
In the upstream project repository, the workflow can also be triggered manually with:
xpm run trigger-workflow-test-all -C ~/Work/micro-os-plus/micro-test-plus-xpack.git/tests
(this requires curl and the GITHUB_API_DISPATCH_TOKEN environment
variable to be set.)
Release schedule
The project employs a continuous release strategy, with updates published as development progresses, rather than following a fixed release schedule.
Releases
The list of releases is available on the Releases page.
Change log
The release notes and the change log are in the
CHANGELOG.md
file of the repository.
Support and feedback
Use GitHub Discussions for support and feedback.
For more information, see the Help Centre page.
Compatibility notices
The changes that affect existing code, with the old and new names, are listed in reverse chronological order on the Compatibility notices page.
Licence
Unless explicitly stated otherwise, the original content is distributed under the terms of the MIT License, with all rights reserved by Liviu Ionescu.
Portions of the codebase derived from Boost UT are distributed under the terms of the Boost Software License, Version 1.0.
Credits
Grateful acknowledgement is extended to:
- Claude Code – for its assistance with code review, refactoring, and improving the documentation.
- node-tap – for demonstrating that testing frameworks need not be overly complex, and for inspiring the initial versions of this project.
- Boost UT – for demonstrating that, in C++, file names and line numbers can be obtained without resorting to C macros, and for contributing significant portions of the codebase.
- Doxygen – for the API documentation tools.
- doxygen2docusaurus – for converting the Doxygen output into the Docusaurus API reference pages.
Thanks to Shields IO for the badges and SVG REPO for the SVG icons.
Support the project
If you find this project useful, you can support it in the following ways: