@micro-os-plus/micro-test-plus 2.1.1

package/CHANGELOG.md

@@ -0,0 +1,145 @@
+# Change & release log
+
+Releases in reverse chronological order.
+
+Please check
+[GitHub](https://github.com/micro-os-plus/micro-test-plus-xpack/issues/)
+and close existing issues and pull requests.
+
+## 2022-02-05
+
+- v2.2.1
+- 473d3f3 package.json: use npmjs.com deps
+- b88b767 CI.yml try to enable qemu-cmake on Windows
+- 518645c package.json: enable cortexm builds on windows
+- e342558 meson create symbolic link at build time
+- 00ff79d cmake revert to .. instead of top symlink
+- 68053a5 package.json: bump build-helper
+- 65918f6 cmake notice that -flto fails on embedded
+- 868c55d meson native with_linux_clang_lto
+- a223600 meson: notice that -flto fails on embedded
+- bb3628a meson always include warnings
+- 1d1e612 meson revert to warning_level = 0
+- cc41eac meson native without -flto
+- d562a5e cmake native add --gc-sections
+ 4bee003 cmake globals -flto for release
+- c2c7972 package.json: bump devices-stm32f4-extras
+- 6139edb meson: disable -flto for clang on linux
+
+## 2022-02-04
+
+- v2.2.0
+- 18219ef package.json: bump deps
+- d30ea7d updates for device-*cortexm
+- 33e2244 cmake: add xpack_display_target_lists
+- 4f7324b package.json: add stm32f4discovery meson
+
+## 2022-02-03
+
+- d64bd80 cmake update qemu-mps2
+- 18955fa cmake update stm32f4discovery
+- e4541e9 cmake update for interface
+
+## 2022-02-02
+
+- e703fa9 .vscode/launch.json: add qemu launchers
+- 3055967 cmake: rework test commands
+
+## 2022-02-01
+
+- 90e894f add meson qemu
+- 6f55a37 package.json: rename dependencies to device-*
+- fde47e6 package.json: move toolchain files to folder
+- 041c252 cmake: rename platform-qemu-mps2-an386
+- 1230c9b cmake: update for device-qemu-cortexm
+- 10304ab rename platform-qemu-mps2-an386
+
+## 2022-01-28
+
+- 829ffbd separate top CMake config for tests
+- 920a928 add top symbolic link
+- 9a5987e sample-test.cpp: static variables
+- 82c83d8 sample-test.cpp: test args
+
+## 2022-01-26
+
+- 15d6fe9 package.json: skip qemu tests on windows
+- v2.1.0
+- rework CMake
+
+## 2022-01-03
+
+- v2.0.5
+
+## 2022-01-02
+
+- CI.yml: remove native-cmake
+- package.json: add meson gcc/clang
+- PLATFORM_STM32F4DISCOVERY_WITHOUT_HAL
+
+## 2022-01-01
+
+- meson.build: add /utf-8 to msvc options
+- [#4] add support for MSVC
+- package.json: use posix paths on windows
+
+## 2021-12-29
+
+- stm32f4discovery test functional
+- add native meson tests
+- package.json: add clang12 test
+- add explicit CMakeLists.txt
+
+## 2021-12-26
+
+- package.json: move devDeps to configs
+- CI.yml: test-native
+- package.json: migrate native to xpack actions
+
+## 2021-03-13
+
+- v2.0.4
+- remove -pedantic-errors, use -Werror only on bare-metal
+
+## 2021-03-10
+
+- v2.0.3
+- bump devDeps
+
+## 2021-03-09
+
+- v2.0.2
+- fix/silence warnings
+- remove warning flags from cmake
+
+## 2021-03-02
+
+- v2.0.1
+- fix warnings, add -Wall..., -Werrror
+
+## 2021-03-01
+
+- v2.0.0
+
+## 2021-02-28
+
+- rename micro_os_plus
+
+## 2021-02-12
+
+- add support for CMake find_package()
+
+## 2021-02-07
+
+- prepare v2.0.0-pre
+- [#1] - rename micro_test_plus::session
+- [#2] - sample-test: conditional exceptions
+- [#3] - add stm32f4discovery tests
+
+## 2021-02-05
+
+- prepare v1.1.1-pre
+
+## 2021-02-04
+
+- release preliminary v1.1.0

package/CMakeLists.txt

@@ -0,0 +1,98 @@
+#
+# This file is part of the µOS++ distribution.
+#   (https://github.com/micro-os-plus)
+# Copyright (c) 2021 Liviu Ionescu
+#
+# Permission to use, copy, modify, and/or distribute this software
+# for any purpose is hereby granted, under the terms of the MIT license.
+#
+# If a copy of the license was not distributed with this file, it can
+# be obtained from https://opensource.org/licenses/MIT/.
+#
+# -----------------------------------------------------------------------------
+
+# This file is intended to be consumed by applications with:
+#
+# `add_subdirectory("xpacks/micro-os-plus-micro-test-plus")`
+#
+# The result is an interface library that can be added to the linker with:
+#
+# `target_link_libraries(your-target PUBLIC micro-os-plus::micro-test-plus)`
+
+# -----------------------------------------------------------------------------
+## Preamble ##
+
+# https://cmake.org/cmake/help/v3.20/
+cmake_minimum_required(VERSION 3.20)
+
+project(
+  micro-os-plus-micro-test-plus
+  DESCRIPTION "µTest++"
+)
+
+if(COMMAND xpack_get_package_name_and_version)
+  xpack_get_package_name_and_version("${CMAKE_CURRENT_SOURCE_DIR}/package.json")
+  message(VERBOSE "Processing xPack ${PACKAGE_JSON_NAME}@${PACKAGE_JSON_VERSION}...")
+endif()
+
+# -----------------------------------------------------------------------------
+## The project library definitions ##
+
+# https://cmake.org/cmake/help/v3.20/command/add_library.html?highlight=interface#normal-libraries
+# PRIVATE: build definitions, used internally
+# INTERFACE: usage definitions, passed up to targets linking to it
+# PUBLIC: both
+
+add_library(micro-os-plus-micro-test-plus-interface INTERFACE)
+
+# -----------------------------------------------------------------------------
+# Target settings.
+
+target_include_directories(
+  micro-os-plus-micro-test-plus-interface
+
+  INTERFACE
+    "include"
+)
+
+target_sources(
+  micro-os-plus-micro-test-plus-interface
+
+  INTERFACE
+    "src/micro-test-plus.cpp"
+)
+
+target_compile_definitions(
+  micro-os-plus-micro-test-plus-interface
+
+  INTERFACE
+    # ...
+)
+
+target_compile_options(
+  micro-os-plus-micro-test-plus-interface
+
+  INTERFACE
+    # ...
+)
+
+target_link_libraries(
+  micro-os-plus-micro-test-plus-interface
+
+  INTERFACE
+    # ...
+)
+
+if (COMMAND xpack_display_target_lists)
+  xpack_display_target_lists(micro-os-plus-micro-test-plus-interface)
+endif()
+
+# -----------------------------------------------------------------------------
+# Aliases.
+
+# https://cmake.org/cmake/help/v3.20/command/add_library.html#alias-libraries
+add_library(micro-os-plus::micro-test-plus ALIAS micro-os-plus-micro-test-plus-interface)
+message(VERBOSE "> micro-os-plus::micro-test-plus -> micro-os-plus-micro-test-plus-interface")
+
+# -----------------------------------------------------------------------------
+

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 Liviu Ionescu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,456 @@
+[![license](https://img.shields.io/github/license/micro-os-plus/micro-test-plus-xpack)](https://github.com/micro-os-plus/micro-test-plus-xpack/blob/xpack/LICENSE)
+[![CI on Push](https://github.com/micro-os-plus/micro-test-plus-xpack/workflows/CI%20on%20Push/badge.svg)](https://github.com/micro-os-plus/micro-test-plus-xpack/actions?query=workflow%3A%22CI+on+Push%22)
+
+# A source xPack with µTest++, a minimalistic testing framework
+
+The **µTest++** project (_micro test plus_) provides a very simple
+testing framework, intended for running unit tests on embedded
+platforms.
+
+The project is hosted on GitHub as
+[micro-os-plus/micro-test-plus-xpack](https://github.com/micro-os-plus/micro-test-plus-xpack).
+
+## Maintainer info
+
+This page is addressed to developers who plan to include this package
+into their own projects.
+
+For maintainer infos, please see the
+[README-MAINTAINER](README-MAINTAINER.md) file.
+
+## Install
+
+As a source xPacks, the easiest way to add it to a project is via **xpm**,
+but it can also be used as any Git project, for example as a submodule.
+
+### Prerequisites
+
+A recent [xpm](https://xpack.github.io/xpm/),
+which is a portable [Node.js](https://nodejs.org/) command line application.
+
+For details please follow the instructions in the
+[install](https://xpack.github.io/install/) page.
+
+### xpm
+
+This package is available as
+[`@micro-os-plus/micro-test-plus`](https://www.npmjs.com/package/@micro-os-plus/micro-test-plus)
+from the `npmjs.com` registry:
+
+```sh
+cd my-project
+xpm init # Unless a package.json is already present
+
+xpm install @micro-os-plus/micro-test-plus@latest
+```
+
+### Git submodule
+
+If, for any reason, **xpm** is not available, the next recommended
+solution is to link it as a Git submodule below an `xpacks` folder.
+
+```sh
+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
+```
+
+## Branches
+
+Apart from the unused `master` branch, there are two active branches:
+
+- `xpack`, with the latest stable version (default)
+- `xpack-develop`, with the current development version
+
+All development is done in the `xpack-develop` branch, and contributions via
+Pull Requests should be directed to this branch.
+
+When new releases are published, the `xpack-develop` branch is merged
+into `xpack`.
+
+## User info
+
+The **µTest++** framework is inspired by [Node tap](https://node-tap.org),
+but is way simpler and has only a limited number of primitives.
+
+- test suites must be compiled as separate applications, one apllication
+  can return only the result of one test suite
+- a test suite may include any number of test cases
+- each test case may perform any number of tests checks
+- each test check either succeeds or fails
+- the test progress is shown on STDOUT, with each test check on a separate
+  line, prefixed with either a check sign (✓) or a cross sign (✗)
+- the main result of the test is passed back as the process exit code
+
+If there is at least one successful test and there are no failed tests,
+the entire test suite is successful and the process returns
+0 as exit value.
+
+### Build & integration info
+
+The project is written in C++, and the tests are expected to be
+written in C++ too (although there are no
+major reasons to prevent adding C wrappers).
+
+On embedded platforms, the test applications should be built with
+**Arm semihosting** support.
+
+To ease the integration of this package into user projects, there
+are already made CMake and meson configuration files (see below).
+
+For other build systems, consider the following details:
+
+#### Source folders
+
+- `src`
+
+The source file to be added to user projects is: `micro-test-plus.cpp`.
+
+#### Include folders
+
+- `include`
+
+The header file to be included in user project is:
+
+```c++
+#include <micro-os-plus/micro-test-plus.h>
+```
+
+#### Preprocessor definitions
+
+- none required
+
+#### Compiler options
+
+- `-std=c++17` or higher for C++ sources
+- `-std=c11` for C sources
+
+#### C++ Namespaces
+
+- `micro_os_plus::micro_test_plus`
+
+`micro_os_plus` is the top µOS++ namespace, and `micro_test_plus` is the µTest++ namespace.
+
+#### C++ Classes
+
+- `micro_os_plus::micro_test_plus::session`
+
+The project includes only one class, `session`. To automate
+passing the file name and the line number, several macros were added.
+
+#### CMake
+
+To integrate the µTest++ source library into a CMake application, add this
+folder to the build:
+
+```cmake
+add_subdirectory("xpacks/micro-os-plus-micro-test-plus")`
+```
+
+The result is an interface library that can be added as an application
+dependency with:
+
+```cmake
+target_link_libraries(
+  your-target
+
+  PUBLIC
+    ...
+    micro-os-plus::micro-test-plus
+)
+```
+
+#### meson
+
+To integrate the µTest++ source library into a meson application, add this
+folder to the build:
+
+```meson
+subdir('xpacks/micro-os-plus-micro-test-plus')
+```
+
+The result is a dependency object that can be added as an application
+dependency with:
+
+```meson
+exe = executable(
+  your-target,
+
+  dependencies: [
+    ...
+    micro_os_plus_micro_test_plus_dependency
+  ]
+)
+```
+
+### Examples
+
+A simple example showing how to use the µTest++ framework is
+presented below and is also available in
+[tests/sample-test.cpp](tests/sample-test.cpp).
+
+```c++
+#include <micro-os-plus/micro-test-plus.h>
+
+using namespace micro_os_plus;
+
+// ----------------------------------------------------------------------------
+
+// Forward definitions of the test cases.
+void
+test_case_something (micro_test_plus::session& t);
+
+void
+test_case_args (micro_test_plus::session& t);
+
+#if defined(__EXCEPTIONS)
+
+void
+test_case_exception_thrown (micro_test_plus::session& t);
+
+void
+test_case_exception_not_thrown (micro_test_plus::session& t);
+
+#endif // defined(__EXCEPTIONS)
+
+int
+compute_one (void);
+
+const char*
+compute_aaa (void);
+
+bool
+compute_condition (void);
+
+#if defined(__EXCEPTIONS)
+
+void
+exercise_throw (bool mustThrow);
+
+#endif // defined(__EXCEPTIONS)
+
+// ----------------------------------------------------------------------------
+
+static int g_argc;
+static char** g_argv;
+
+// The test suite.
+int
+main (int argc, char* argv[])
+{
+  micro_test_plus::session t (argc, argv);
+
+  g_argc = argc;
+  g_argv = argv;
+
+  t.start_suite ("Sample test");
+
+  t.run_test_case (test_case_something, "Check various conditions");
+
+  t.run_test_case (test_case_args, "Check args");
+
+#if defined(__EXCEPTIONS)
+
+  t.run_test_case (test_case_exception_thrown,
+                   "Check if exceptions are thrown");
+
+  t.run_test_case (test_case_exception_not_thrown,
+                   "Check if exceptions are not thrown");
+
+#endif // defined(__EXCEPTIONS)
+
+  return t.result ();
+}
+
+// ----------------------------------------------------------------------------
+
+// Simple examples of functions to be tested.
+int
+compute_one (void)
+{
+  return 1;
+}
+
+const char*
+compute_aaa (void)
+{
+  return "aaa";
+}
+
+bool
+compute_condition (void)
+{
+  return true;
+}
+
+#if defined(__EXCEPTIONS)
+
+void
+exercise_throw (bool mustThrow)
+{
+  if (mustThrow)
+    {
+      throw "kaboom";
+    }
+}
+
+#endif // defined(__EXCEPTIONS)
+
+// ----------------------------------------------------------------------------
+
+// Test equality or logical conditions.
+void
+test_case_something (micro_test_plus::session& t)
+{
+  // Currently only int and long values can be compared.
+  // For everything else use casts.
+  MTP_EXPECT_EQ (t, compute_one (), 1, "compute_one() == 1");
+
+  // Strings can also be compared (via `strcmp()`).
+  MTP_EXPECT_EQ (t, compute_aaa (), "aaa", "compute_aaa() == 'aaa'");
+
+  // More complex conditions are passed as booleans.
+  MTP_EXPECT_TRUE (t, compute_condition (), "condition() is true");
+}
+
+void
+test_case_args (micro_test_plus::session& t)
+{
+  MTP_EXPECT_EQ (t, g_argc, 3, "argc == 3");
+
+  if (g_argc > 1)
+    {
+      MTP_EXPECT_EQ (t, g_argv[1], "one", "argv[1] == 'one'");
+    }
+
+  if (g_argc > 2)
+    {
+      MTP_EXPECT_EQ (t, g_argv[2], "two", "argv[2] == 'two'");
+    }
+}
+
+// ----------------------------------------------------------------------------
+
+#if defined(__EXCEPTIONS)
+
+// Test is something throws exceptions.
+void
+test_case_exception_thrown (micro_test_plus::session& t)
+{
+  try
+    {
+      // Do something that throws.
+      exercise_throw (true);
+
+      // If we reached here, the exception was not thrown.
+      MTP_FAIL (t, "exception not thrown");
+    }
+  catch (...)
+    {
+      // Got it.
+      MTP_PASS (t, "exception thrown");
+    }
+}
+
+void
+test_case_exception_not_thrown (micro_test_plus::session& t)
+{
+  try
+    {
+      // Do something that may throw, but it doesn't.
+      exercise_throw (false);
+
+      // If we reached here, everything is fine.
+      MTP_PASS (t, "exception not thrown");
+    }
+  catch (...)
+    {
+      MTP_FAIL (t, "exception thrown");
+    }
+}
+
+#endif // defined(__EXCEPTIONS)
+
+```
+
+The output of running such a test looks like:
+
+```console
+$ cd micro-test-plus-xpack.git
+$ xpm install-all
+...
+$ xpm run test-native
+...
+> Executing task: xpm run test --config native-cmake-debug <
+
+> cd build/native-cmake-debug && ctest -V
+UpdateCTestConfiguration  from :/Users/ilg/My Files/WKS Projects/micro-os-plus.github/xPacks/micro-test-plus-xpack.git/build/native-cmake-debug/DartConfiguration.tcl
+UpdateCTestConfiguration  from :/Users/ilg/My Files/WKS Projects/micro-os-plus.github/xPacks/micro-test-plus-xpack.git/build/native-cmake-debug/DartConfiguration.tcl
+Test project /Users/ilg/My Files/WKS Projects/micro-os-plus.github/xPacks/micro-test-plus-xpack.git/build/native-cmake-debug
+Constructing a list of tests
+Done constructing a list of tests
+Updating test list for fixtures
+Added 0 tests to meet fixture requirements
+Checking test dependency graph...
+Checking test dependency graph end
+test 1
+    Start 1: unit-test
+
+1: Test command: /Users/ilg/My\ Files/WKS\ Projects/micro-os-plus.github/xPacks/micro-test-plus-xpack.git/build/native-cmake-debug/platform/unit-test
+...
+1/2 Test #1: unit-test ........................   Passed    0.00 sec
+test 2
+    Start 2: sample-test
+
+2: Test command: /Users/ilg/My\ Files/WKS\ Projects/micro-os-plus.github/xPacks/micro-test-plus-xpack.git/build/native-cmake-debug/platform/sample-test "one" "two"
+2: Test timeout computed to be: 10000000
+2: Built with clang Apple LLVM 13.0.0 (clang-1300.0.29.30), no FP, with exceptions, with DEBUG.
+2: argv[] = '/Users/ilg/My Files/WKS Projects/micro-os-plus.github/xPacks/micro-test-plus-xpack.git/build/native-cmake-debug/platform/sample-test' 'one' 'two'
+2:
+2: Sample test started
+2:
+2:   Check various conditions
+2:     ✓ compute_one() == 1
+2:     ✓ compute_aaa() == 'aaa'
+2:     ✓ condition() is true
+2:
+2:   Check args
+2:     ✓ argc == 3
+2:     ✓ argv[1] == 'one'
+2:     ✓ argv[2] == 'two'
+2:
+2:   Check if exceptions are thrown
+2:     ✓ exception thrown
+2:
+2:   Check if exceptions are not thrown
+2:     ✓ exception not thrown
+2:
+2: Sample test passed (8 tests in 4 test cases)
+2/2 Test #2: sample-test ......................   Passed    0.00 sec
+
+100% tests passed, 0 tests failed out of 2
+
+Total Test time (real) =   0.01 sec
+```
+
+### Known problems
+
+- none
+
+### Tests
+
+The project is fully tested via GitHub
+[Actions](https://github.com/micro-os-plus/micro-test-plus-xpack/actions/)
+on each push.
+The tests run on GNU/Linux, macOS and Windows, are compiled with GCC,
+clang and arm-none-eabi-gcc and run natively or via QEMU.
+
+## License
+
+The original content is released under the
+[MIT License](https://opensource.org/licenses/MIT/),
+with all rights reserved to
+[Liviu Ionescu](https://github.com/ilg-ul/).