micro-test-plus 3.2.0
µTest++, a lightweight testing framework for embedded platforms
Loading...
Searching...
No Matches
Integration Guide

GitHub package.json version GitHub tag (latest by date) npm (scoped)

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

However, things can be further automated and the most convenient way is to add it as a dependency to the project via xpm.

Install with xpm/npm

Along with the source files, this project also includes a package.json file with the metadata that allows it to be identified as an xpm/npm package so that it can be directly installed from GitHub or from the npmjs.com registry as @micro-os-plus/micro-test-plus.

Prerequisites

A recent xpm, which is a portable Node.js command line application that complements npm with several extra features specific to C/C++ projects.

It is recommended to install/update to the latest version with:

npm install --global xpm@latest

For details please follow the instructions in the xPack install page.

Warning
Be sure xpm is not installed with administrative rights.

xpm

This project can be installed as a package from the npmjs.com registry with:

cd my-project
xpm init # Unless a package.json is already present
xpm install @micro-os-plus/micro-test-plus@latest

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

% tree -l
.
├── LICENSE
├── package.json
└── xpacks
└── @micro-os-plus
└── micro-test-plus -> /Users/ilg/Library/xPacks/@micro-os-plus/micro-test-plus/3.1.1
├── 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

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.

Add as a Git submodule

Besides manually copying the relevant files to the target project, which will later require extra maintenance efforts to keep the project up to date, a more convenient 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

Project repository

The project uses Git and is hosted on GitHub as https://github.com/micro-os-plus/micro-test-plus-xpack.git.

Branches

Apart from the unused master branch, there are two active branches:

  • xpack, with the latest stable version (default)
  • xpack-development, with the current development version

All development is done in the xpack-development branch, and contributions via Pull Requests should be directed to this branch.

When new releases are published, the xpack-development branch is merged into the xpack branch.

Build & integration info

The project is written in C++, and the tests are expected to be written in C++ too, but the tested code can also be written in plain C.

The source code was compiled natively with GCC and LLVM/clang and cross compiled on embedded Arm and RISC-V targets, and is expected to be warnings free.

To run on embedded platforms, the test framework requires a minimum of support from the system, like writing to the output stream. Any such environments are acceptable, but for standalone tests the most common solution is to use Arm semihosting.

To ease the integration of this library into user projects, there are already made CMake and meson configuration files (see below).

For other build systems, consider the following details:

Include folders

The following folders should be passed to the compiler during the build:

  • include

The header files to be included in user projects are:

Source files

The source files to be added to user projects are:

Preprocessor definitions

There are several preprocessor definitions used to configure the build:

  • MICRO_OS_PLUS_INCLUDE_CONFIG_H - to include <micro-os-plus/config.h>
  • MICRO_OS_PLUS_TRACE - to include the trace calls
  • MICRO_TEST_PLUS_TRACE - to enable some tracing messages

Compiler options

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

  • -std=c++20 or higher for C++ sources

Dependencies

The library has the following dependencies:

  • none

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_lists_dependency,
]
)

Status

Note
The micro-test-plus library is fully functional, and it is used to test several projects in the µOS++ framework.

The project is CI tested 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.