How to install the µTest++ Testing Framework

As an xpm package, the the most convenient way to integrate the µTest++ Testing Framework into a project is to add it as a dependency via xpm.

However, as any source code library, this project can also be integrated into another project in the traditional manner, either by copying the relevant files into the target project, or by linking the entire project as a Git submodule.

xpm packages (xPacks) refresher

xpm packages, abbreviated as xPacks, are general-purpose, language-neutral software packages. They use 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 source and binary packages.

For more details, please see the previous explanation in the Getting Started page.

Automated install

Alongside the source files, this project also includes a package.json file containing the metadata that identifies it as an xpm/npm package, enabling direct installation from GitHub or from the npmjs.com registry as @micro-os-plus/micro-test-plus.

Prerequisites

The only requirement for an automated install is a recent xpm, which is a portable Node.js command line application that complements npm with several extra features specific to C/C++ projects.

To install xpm, follow the instructions in the xpm install page.

If already installed, it is always a good idea to update it to the latest version with:

npm install --location=global xpm@latest

tip

Although not mandated by xpm, it is also a good idea to upgrade npm to the latest version, and node to a reasonably recent version (currently npm requires a node >=18.17.0).

Local installs

One of the xPack design goals is to allow each project to choose the exact versions of the libraries it requires.

Similarly to npm being able to install specific versions of the JavaScript tools into each project, xpm was also designed to be able to install specific versions of the required libraries locally into each project.

Therefore, similarly to the way npm installs the JavaScript packages into node_modules, xpm installs the libraries into xpacks. Here there will be separate folders with the installed packages, for example xpacks/@micro-os-plus/micro-test-plus.

Initialise the project

Upon initial use, ensure that a package.json file is present in the project root folder.

This can be achieved by running xpm init in the desired project folder (substitute my-project accordingly):

cd my-project
xpm init

Under the hood

The main purpose of xpm init is to create a package.json file, if not already present.

In addition to name & version, the minimal package.json must include a property named xpacks, even empty. This property is mandatory to identify the package as an xpm package.

Install via xpm

The next step is to install the micro-test-plus package into the project.

The command to install the latest available version of micro-test-plus is:

xpm install @micro-os-plus/micro-test-plus@latest --verbose

To install a specific version, specify it explicitly:

xpm install @micro-os-plus/micro-test-plus@3.2.2 --verbose

Installation details

The above xpm install command will do the following:

• identify the desired version of @micro-os-plus/micro-test-plus, download it into a cache and unpack it into a versioned folder in the user's global xPacks store (if not already there); check the output of the xpm install command for the actual folder used on your platform;
• create a local symbolic link like xpacks/@micro-os-plus/micro-test-plus pointing to the versioned folder in the user's global xPacks store
• add @micro-os-plus/micro-test-plus to package.json as a dependency; this associates a specific version of the µTest++ Testing Framework with the current project (details below).

tip

The install location can be configured using the XPACKS_STORE_FOLDER environment variable; for more details please check the xpm folders page.

Reproducibility and dependencies

To ensure reproducibility, it is essential for each project to always use the exact desired versions of the required libraries, regardless of the libraries installed in the system.

To achieve this goal, xpm records all locally installed packages as dependencies in the project package.json file.

The result looks like this:

  "xpack": {
  "minimumXpmRequired": "0.20.7",
  "dependencies": {
    "@micro-os-plus/micro-test-plus": {
      "specifier": "3.2.2",
      "local": "link",
      "platforms": "all"
    }
  },
  "devDependencies": {},
  "properties": {},
  "actions": {},
  "buildConfigurations": {}
}

If the package.json is saved in the revision system, the above definition acts as a hard reference to the specific version of the µTest++ Testing Framework.

After cloning the project into a different location, the command xpm install can be used to install all dependencies.

This is particularly useful for CI/CD environments.

Install folder hierarchy

After following the links, the result is a structure like this:

% tree -l
.
├── LICENSE
├── package.json
└── xpacks
    └── @micro-os-plus
        └── micro-test-plus
            ├── CHANGELOG.md
            ├── CMakeLists.txt
            ├── LICENSE
            ├── LICENSE-Boost
            ├── README.md
            ├── include
            │   └── micro-os-plus
            │       ├── detail.h
            │       ├── inlines.h
            │       ├── literals.h
            │       ├── math.h
            │       ├── micro-test-plus.h
            │       ├── reflection.h
            │       ├── test-reporter-inlines.h
            │       ├── test-reporter.h
            │       ├── test-runner.h
            │       ├── test-suite.h
            │       └── type-traits.h
            ├── meson.build
            ├── package.json
            └── src
                ├── micro-test-plus.cpp
                ├── test-reporter.cpp
                ├── test-runner.cpp
                └── test-suite.cpp

7 directories, 24 files

Uninstall

The xpm packages do not use any form of system installer; instead they are distributed as portable archives; therefore they do not require to run any uninstaller; simply removing the links and possibly the user's global xPacks store folder and the user xPack cache folder is enough.

To remove the links created by xpm in the current project, go to the project folder:

cd my-project

and ask xpm to uninstall the package:

xpm uninstall @micro-os-plus/micro-test-plus --verbose

To completely remove the package from the user's global xPacks store:

xpm uninstall --global @micro-os-plus/micro-test-plus --verbose

Clean-ups

For a thorough clean-up, please note that xpm uses only two folders:

Windows

• %APPDATA%\Roaming\xPacks
• %APPDATA%\Local\Caches\xPacks

macOS

• ${HOME}/Library/xPacks
• ${HOME}/Library/Caches/xPacks

GNU/Linux

• ${HOME}/.local/xPacks
• ${HOME}/.cache/xPacks

They can be removed at any time and space reclaimed; xpm will recreate them on new installs.

However, projects linking to the user's global xPacks store will fail with broken paths.

Install via npm

The package can also be installed with npm or related, but the features specific to C/C++ projects will not be available; therefore, at least for consistency reasons, it is recommended to use xpm.

Manual install

Copy files

The traditional way of using source libraries is to simply copy them into the user project.

The obvious advantage is simplicity, but the downside is that the library becomes part of the project, and any improvements or bug fixes must be manually copied to the project.

Add as a Git submodule

Another common solution is to link the entire project as a Git submodule, for example below an xpacks folder:

cd my-project
git init # Unless already a Git project
mkdir -p xpacks

git submodule add https://github.com/micro-os-plus/micro-test-plus-xpack.git \
  xpacks/@micro-os-plus/micro-test-plus

Build & Integration Information

This project is implemented in C++, and it is expected that tests will also be written in C++, although the code under test may be written in standard C.

The source code has been compiled natively using GCC and LLVM/clang, and cross-compiled for embedded Arm and RISC-V targets, ensuring that it is free from warnings.

For execution on embedded platforms, the test framework requires only minimal system support, such as the ability to write to an output stream. Any environment providing this capability is suitable; however, for standalone tests, the most common approach is to employ Arm semihosting.

To simplify integration into user projects, pre-configured CMake and meson build files are provided (see below).

For alternative build systems, please consult the information provided below.

Include Folders

The following folder should be specified to the compiler during the build process:

• include

The primary header file to include in user projects is:

#include <micro-os-plus/micro-test-plus.h>

Source Files

The following source files should be incorporated into user projects:

• src/micro-test-plus.cpp
• src/test-reporter.cpp
• src/test-runner.cpp
• src/test-suite.cpp

Preprocessor Definitions

The build can be configured using the following preprocessor definitions:

• MICRO_OS_PLUS_INCLUDE_CONFIG_H – to include <micro-os-plus/config.h>
• MICRO_OS_PLUS_TRACE – to enable trace calls
• MICRO_OS_PLUS_TRACE_MICRO_TEST_PLUS – to activate specific tracing messages

Compiler Options

The following options must be supplied to the compiler and linker:

• -std=c++20 or later for C++ source files

Dependencies

This library does not have any external dependencies.

CMake

To integrate the micro-test-plus library into a CMake application, add the folder where this project is located to the build:

add_subdirectory("xpacks/@micro-os-plus/micro-test-plus")

The result is an interface library that can be added as an application dependency with:

target_link_libraries(your-target PRIVATE

  micro-os-plus::micro-test-plus
)

Meson Build

To integrate the micro-test-plus library into a meson application, add the folder where this project is located to the build:

subdir('xpacks/@micro-os-plus/micro-test-plus')

The result is a dependency object that can be added to an application with:

exe = executable(
  your-target,
  link_with: [
    # Nothing, not static.
  ],
  dependencies: [
    micro_os_plus_micro_test_plus_dependency,
  ]
)

Status

The micro-test-plus library is fully operational and is employed to test multiple projects within the µOS++ framework.

Testing

The library undergoes continuous integration (CI) testing with every push using GitHub Actions. This ensures compatibility and stability across Ubuntu, macOS, and Windows operating systems.

The tests are conducted on both 32-bit and 64-bit bare-metal platforms, including Arm Cortex-M0, Cortex-M3, Cortex-M4F, Cortex-M7F, Cortex-A15, Cortex-A72, RISC-V RV32IMAC, and RV64IMAFDC. Additionally, native testing is performed using GCC and LLVM/clang compilers, ensuring thorough validation across various environments.