test-inlines.h

Go to the documentation of this file.

/*
 * This file is part of the µOS++ project (https://micro-os-plus.github.io/).
 * Copyright (c) 2021-2026 Liviu Ionescu. All rights reserved.
 *
 * 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.
 *
 * Major parts of the code are inspired from v1.1.8 of the Boost UT project,
 * released under the terms of the Boost Version 1.0 Software License,
 * which can be obtained from https://www.boost.org/LICENSE_1_0.txt.
 */
 
// ----------------------------------------------------------------------------

 
#ifndef MICRO_OS_PLUS_MICRO_TEST_PLUS_INLINES_TEST_INLINES_H_
#define MICRO_OS_PLUS_MICRO_TEST_PLUS_INLINES_TEST_INLINES_H_
 
// ----------------------------------------------------------------------------
 
#if defined(__cplusplus)
 
// ----------------------------------------------------------------------------
 
#include "micro-os-plus/micro-test-plus/deferred-reporter.h"
#include "micro-os-plus/micro-test-plus/reporter.h"
 
#if __has_include("micro-os-plus/diag/trace.h")
#include "micro-os-plus/diag/trace.h"
#endif // __has_include("micro-os-plus/diag/trace.h")
 
#include <cstdio>
#include <cstring>
 
// ----------------------------------------------------------------------------
 
#if defined(__GNUC__)
#pragma GCC diagnostic push
 
#pragma GCC diagnostic ignored "-Waggregate-return"
#if defined(__clang__)
#pragma clang diagnostic ignored "-Wunknown-warning-option"
#pragma clang diagnostic ignored "-Wc++98-compat"
#pragma clang diagnostic ignored "-Wc++98-compat-pedantic"
#pragma clang diagnostic ignored "-Wunsafe-buffer-usage-in-libc-call"
#else // GCC only
#pragma GCC diagnostic ignored "-Wredundant-tags"
#endif // defined(__clang__)
#endif // defined(__GNUC__)
 
// ============================================================================
 
namespace micro_os_plus::micro_test_plus
{
  namespace detail
  {
    // ========================================================================

    inline const char*
    test_node::name (void) const noexcept
    {
      return name_;
    }

    inline runner_totals&
    test_node::totals () noexcept
    {
      return totals_;
    }

    inline const runner_totals&
    test_node::totals () const noexcept
    {
      return totals_;
    }
 
    // ========================================================================

    inline size_t
    runnable_base::own_index () const noexcept
    {
      return own_index_;
    }

    inline void
    runnable_base::own_index (size_t index) noexcept
    {
      own_index_ = index;
    }

    inline size_t
    runnable_base::current_subtest_index () const noexcept
    {
      return current_subtest_index_;
    }

    inline size_t
    runnable_base::increment_subtest_index () noexcept
    {
      return ++current_subtest_index_;
    }

    inline size_t
    runnable_base::children_subtests_count (void) const noexcept
    {
      return children_subtests_.size ();
    }

    inline class runner&
    runnable_base::runner (void) const noexcept
    {
      return runner_;
    }
 
    // ========================================================================

    template <typename Self_T>
    template <typename Callable_T, typename... Args_T>
    runnable<Self_T>::runnable (const char* name, class runner& runner,
                                size_t own_index, Callable_T&& callable,
                                Args_T&&... arguments)
        : runnable_base{ name, runner, own_index }
    {
      // When there are no extra arguments the callable already has the
      // signature void(Self_T&), so store it directly. Only use std::bind when
      // additional arguments must be pre-bound, to avoid triggering a GCC ARM
      // bug in
      // __is_nothrow_invocable<_Bind<...>, Self_T&> (GCC 15.2.1).
      if constexpr (sizeof...(arguments) == 0)
        {
          callable_ = std::forward<Callable_T> (callable);
        }
      else
        {
          callable_ = std::bind (std::forward<Callable_T> (callable),
                                 std::placeholders::_1,
                                 std::forward<Args_T> (arguments)...);
        }
 
#if defined(MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_CONSTRUCTORS_ENABLED)
      trace::printf ("%s '%s' %zu\n", __PRETTY_FUNCTION__, name, own_index_);
#endif // MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_CONSTRUCTORS_ENABLED
    }

     * trace message identifying the instance being destroyed.
     */
    template <typename Self_T>
    runnable<Self_T>::~runnable ()
    {
#if defined(MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_CONSTRUCTORS_ENABLED)
      trace::printf ("%s '%s'\n", __PRETTY_FUNCTION__, name_);
#endif // MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_CONSTRUCTORS_ENABLED
    }
 
    // ------------------------------------------------------------------------
  } // namespace detail
 
  // ==========================================================================

  template <typename Callable_T, typename... Args_T>
  subtest::subtest (const char* name, class runner& runner,
                    suite& parent_suite, size_t own_index,
                    size_t nesting_depth, Callable_T&& callable,
                    Args_T&&... arguments)
      : runnable<subtest>{ name, runner, own_index,
                           std::forward<Callable_T> (callable),
                           std::forward<Args_T> (arguments)... },
        parent_suite_{ parent_suite }, nesting_depth_{ nesting_depth }
  {
#if defined(MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_CONSTRUCTORS_ENABLED)
    trace::printf ("%s '%s' %zu %zu\n", __PRETTY_FUNCTION__, name, own_index_,
                   nesting_depth_);
#endif // MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_CONSTRUCTORS_ENABLED
  }

  template <typename Callable_T, typename... Args_T>
  void
  subtest::test (const char* name, Callable_T&& callable,
                 Args_T&&... arguments)
  {
#if defined(MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_ENABLED)
    trace::printf ("%s '%s'\n", __PRETTY_FUNCTION__, name);
#endif // MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_ENABLED
 
    size_t own_index = increment_subtest_index ();
    auto child_subtest = std::make_unique<subtest> (
        name, runner (), parent_suite_, own_index, nesting_depth_ + 1,
        std::forward<Callable_T> (callable),
        std::forward<Args_T> (arguments)...);
 
    after_subtest_create_ (std::move (child_subtest), parent_suite_);
  }

  template <class Expr_T>
    requires type_traits::checkable<Expr_T>
  auto
  subtest::expect (const Expr_T& expr, const reflection::source_location& sl)
  {
    return detail::deferred_reporter{ expr, false, sl, *this,
                                      reporter ().expression () };
  }

  template <class Expr_T>
    requires type_traits::checkable<Expr_T>
  auto
  subtest::assume (const Expr_T& expr, const reflection::source_location& sl)
  {
    return detail::deferred_reporter{ expr, true, sl, *this,
                                      reporter ().expression () };
  }

  /**
   * @details
   * Top-level subtests (direct children of a `suite`) have depth 1.
   * Each additional level of nesting increments the depth by 1.
   */
  inline size_t
  subtest::nesting_depth () const noexcept
  {
    return nesting_depth_;
  }
 
  // ==========================================================================

   * @details
   * Delegates to `runnable`, which binds the callable with
   * its arguments. After construction, the suite is registered with the
   * static test runner.
   */
  template <typename Callable_T, typename... Args_T>
  suite::suite (const char* name, class runner& runner, Callable_T&& callable,
                Args_T&&... arguments)
      : runnable<suite>{ name, runner, 0, std::forward<Callable_T> (callable),
                         std::forward<Args_T> (arguments)... }
  {
#if defined(MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_CONSTRUCTORS_ENABLED)
    trace::printf ("%s '%s' %zu\n", __PRETTY_FUNCTION__, name, own_index_);
#endif // MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_CONSTRUCTORS_ENABLED
  }
 
#if defined(__GNUC__)
#pragma GCC diagnostic push
 
#if defined(__clang__)
#pragma clang diagnostic ignored "-Wdocumentation"
#endif // defined(__clang__)
#endif // defined(__GNUC__)

   * the provided name, and its execution is managed by the framework's test
   * runner.
   *
   * Each test case typically involves evaluating a logical expression, such as
   * comparing a computed result to an expected value. For C++ projects, it is
   * also possible to verify whether evaluating an expression throws
   * exceptions. Each test either succeeds or fails, and for expectations, the
   * test runner maintains counts of successful and failed checks.
   *
   * This function template enables flexible and expressive test case
   * definitions, supporting both parameterised and non-parameterised tests. It
   * is typically invoked at global scope or within test suite definitions to
   * ensure automatic registration and execution.
   *
   * A test case is characterised by a name, a function that performs the
   * checks, and optionally, arguments to be passed to that function. The
   * implementation of `test` invokes the provided function with the given
   * arguments and reports the results to the test runner.
   *
   * @par Example
   *
   * @code{.cpp}
   *   namespace mt = micro_os_plus::micro_test_plus;
   *
   *   ts.test ("Check answer with comparator", [] (auto& t) {
   *     t.expect (mt::eq (compute_answer (), 42)) << "answer is 42";
   *   });
   * @endcode
   */
 
  template <typename Callable_T, typename... Args_T>
  void
  suite::test (const char* name, Callable_T&& callable, Args_T&&... arguments)
  {
#if defined(MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_ENABLED)
    trace::printf ("%s '%s'\n", __PRETTY_FUNCTION__, name);
#endif // MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_ENABLED
 
    size_t own_index = increment_subtest_index ();
    auto child_subtest
        = std::make_unique<subtest> (name, runner (), *this, own_index, 1,
                                     std::forward<Callable_T> (callable),
                                     std::forward<Args_T> (arguments)...);
 
    after_subtest_create_ (std::move (child_subtest), *this);
  }

  inline detail::timestamps&
  suite::timings () noexcept
  {
    return timings_;
  }

  inline const detail::timestamps&
  suite::timings () const noexcept
  {
    return timings_;
  }
 
  // ==========================================================================

  inline void
  top_suite::name (const char* new_name) noexcept
  {
    name_ = new_name;
  }
 
  // ==========================================================================

  template <typename Callable_T, typename... Args_T>
  static_suite::static_suite (const char* name, static_runner& runner,
                              Callable_T&& callable, Args_T&&... arguments)
      // The nullptr passed to the base constructor is an optimisation to save
      // some space, since this callble is not used by the static runner.
      : suite{ name, detail::to_runner (runner), nullptr }
  {
    if constexpr (sizeof...(arguments) == 0)
      {
        static_callable_ = std::forward<Callable_T> (callable);
      }
    else
      {
        static_callable_ = std::bind (std::forward<Callable_T> (callable),
                                      std::placeholders::_1,
                                      std::forward<Args_T> (arguments)...);
      }
 
#if defined(MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_CONSTRUCTORS_ENABLED)
    trace::printf ("%s '%s' %zu\n", __PRETTY_FUNCTION__, name, own_index_);
#endif // MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_CONSTRUCTORS_ENABLED
 
    detail::register_static_suite (runner, *this);
  }
 
  // --------------------------------------------------------------------------
} // namespace micro_os_plus::micro_test_plus
 
// ----------------------------------------------------------------------------
 
#if defined(__GNUC__)
#pragma GCC diagnostic pop
#pragma GCC diagnostic pop
#endif // defined(__GNUC__)
 
// ----------------------------------------------------------------------------
 
#endif // defined(__cplusplus)
 
// ----------------------------------------------------------------------------
 
#endif // MICRO_OS_PLUS_MICRO_TEST_PLUS_INLINES_TEST_INLINES_H_
 
// ----------------------------------------------------------------------------