test.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_TEST_H_
#define MICRO_OS_PLUS_MICRO_TEST_PLUS_TEST_H_
 
// ----------------------------------------------------------------------------
 
#if defined(__cplusplus)
 
// ----------------------------------------------------------------------------
 
#if __has_include("micro-os-plus/project-config.h")
#include "micro-os-plus/project-config.h"
#endif // __has_include("micro-os-plus/project-config.h")
 
#if __has_include("micro-os-plus/micro-test-plus-defines.h")
#include "micro-os-plus/micro-test-plus-defines.h"
#endif // __has_include("micro-os-plus/micro-test-plus-defines.h")
 
#include "runner-totals.h"
#include "type-traits.h"
#include "timings.h"
#include "reflection.h"
 
#include <functional>
#include <memory>
 
// ----------------------------------------------------------------------------
 
#if defined(__GNUC__)
#pragma GCC diagnostic push
 
#pragma GCC diagnostic ignored "-Wpadded"
#if defined(__clang__)
#pragma clang diagnostic ignored "-Wc++98-compat"
#else // GCC only
#pragma GCC diagnostic ignored "-Wsuggest-final-types"
#pragma GCC diagnostic ignored "-Wsuggest-final-methods"
#pragma GCC diagnostic ignored "-Wredundant-tags"
#endif // defined(__clang__)
#endif // defined(__GNUC__)
 
// =============================================================================
 
namespace micro_os_plus::micro_test_plus
{
  // --------------------------------------------------------------------------
 
  class runner;
  class static_runner;
  class reporter;
  class runner_totals;
  class subtest;
  class suite;
  class static_suite;
 
  namespace detail
  {
    // ========================================================================

    runner&
    to_runner (static_runner& static_runner_ref) noexcept;

    void
    register_static_suite (static_runner& static_runner_ref,
                           static_suite& static_suite_ref);

    class test_node
    {
    public:
      test_node (const char* name);

      test_node (const test_node&) = delete;

      test_node (test_node&&) = delete;

      test_node&
      operator= (const test_node&)
          = delete;

      test_node&
      operator= (test_node&&)
          = delete;

      virtual ~test_node ();
 
      // ----------------------------------------------------------------------

      [[nodiscard]] const char*
      name (void) const noexcept;
 
    public:
      [[nodiscard]] runner_totals&
      totals () noexcept;

      [[nodiscard]] const runner_totals&
      totals () const noexcept;
 
    protected:
      const char* name_;

      runner_totals totals_;
    };
 
    // ========================================================================

    class runnable_base : public test_node
    {
    public:
      runnable_base (const char* name, runner& runner, size_t own_index);

      runnable_base (const runnable_base&) = delete;

      runnable_base (runnable_base&&) = delete;

      runnable_base&
      operator= (const runnable_base&)
          = delete;

      runnable_base&
      operator= (runnable_base&&)
          = delete;

      virtual ~runnable_base () override;
 
      // ----------------------------------------------------------------------

      [[nodiscard]] size_t
      own_index () const noexcept;

      void
      own_index (size_t index) noexcept;

      [[nodiscard]] size_t
      current_subtest_index () const noexcept;

      size_t
      increment_subtest_index () noexcept;

      [[nodiscard]] size_t
      children_subtests_count (void) const noexcept;

      [[nodiscard]] class reporter&
      reporter (void) const noexcept;

      [[noreturn]] void
      abort (const reflection::source_location& sl
             = reflection::source_location::current ());

      [[nodiscard]] class runner&
      runner (void) const noexcept;
 
    protected:
      void
      after_subtest_create_ (std::unique_ptr<subtest> child_test,
                             suite& suite);
 
    protected:
      class runner& runner_;

      size_t own_index_;

      size_t current_subtest_index_ = 0;

      std::vector<std::unique_ptr<subtest>> children_subtests_;
    };
 
    // ========================================================================

    template <typename Self_T>
    class runnable : public detail::runnable_base
    {
    public:
      template <typename Callable_T, typename... Args_T>
      runnable (const char* name, class runner& runner, size_t own_index,
                Callable_T&& callable, Args_T&&... arguments);

      runnable (const runnable&) = delete;

      runnable (runnable&&) = delete;

      runnable&
      operator= (const runnable&)
          = delete;

      runnable&
      operator= (runnable&&)
          = delete;

      virtual ~runnable () override;
 
      // ----------------------------------------------------------------------

      virtual void
      run (void)
          = 0;
 
    protected:
      std::function<void (Self_T&)> callable_;
    };
 
    // ------------------------------------------------------------------------
  } // namespace detail
 
  // ==========================================================================

  class subtest : public detail::runnable<subtest>
  {
  public:
    template <typename Callable_T, typename... Args_T>
    subtest (const char* name, class runner& runner, suite& parent_suite,
             size_t own_index, size_t nesting_depth, Callable_T&& callable,
             Args_T&&... arguments);

    subtest (const subtest&) = delete;

    subtest (subtest&&) = delete;

    subtest&
    operator= (const subtest&)
        = delete;

    subtest&
    operator= (subtest&&)
        = delete;

    virtual ~subtest () override;
 
    // ------------------------------------------------------------------------

    template <typename Callable_T, typename... Args_T>
    void
    test (const char* name, Callable_T&& callable, Args_T&&... arguments);
 
    // ------------------------------------------------------------------------

    template <class Expr_T>
      requires type_traits::checkable<Expr_T>
    auto
    expect (const Expr_T& expr, const reflection::source_location& sl
                                = reflection::source_location::current ());

    template <class Expr_T>
      requires type_traits::checkable<Expr_T>
    auto
    assume (const Expr_T& expr, const reflection::source_location& sl
                                = reflection::source_location::current ());
 
    // ------------------------------------------------------------------------

    virtual void
    run (void) override;

    [[nodiscard]] size_t
    nesting_depth () const noexcept;
 
  protected:
    suite& parent_suite_;

    size_t nesting_depth_;
  };
 
  // ==========================================================================

  class suite : public detail::runnable<suite>
  {
  public:
    template <typename Callable_T, typename... Args_T>
    suite (const char* name, class runner& runner, Callable_T&& callable,
           Args_T&&... arguments);

    suite (const suite&) = delete;

    suite (suite&&) = delete;

    suite&
    operator= (const suite&)
        = delete;

    suite&
    operator= (suite&&)
        = delete;

    virtual ~suite () override;
 
    // ------------------------------------------------------------------------

    template <typename Callable_T, typename... Args_T>
    void
    test (const char* name, Callable_T&& callable, Args_T&&... arguments);
 
    // ------------------------------------------------------------------------

    [[nodiscard]] detail::timestamps&
    timings () noexcept;

    [[nodiscard]] const detail::timestamps&
    timings () const noexcept;

    virtual void
    run (void) override;
 
  protected:
    detail::timestamps timings_;
  };
 
  // ==========================================================================

  class top_suite : public suite
  {
  public:
    // Expose the accessor for the suite name from the base test_node class,
    // since the top_suite may need to change its name after construction, and
    // the base class provides the necessary interface for that purpose.
    using detail::test_node::name;

    top_suite (const char* name, class runner& runner);

    top_suite (const top_suite&) = delete;

    top_suite (top_suite&&) = delete;

    top_suite&
    operator= (const top_suite&)
        = delete;

    top_suite&
    operator= (top_suite&&)
        = delete;

    virtual ~top_suite () override;

    void
    name (const char* new_name) noexcept;
  };
 
  // ==========================================================================

  class static_suite : public suite
  {
  public:
    template <typename Callable_T, typename... Args_T>
    static_suite (const char* name, static_runner& runner,
                  Callable_T&& callable, Args_T&&... arguments);

    static_suite (const static_suite&) = delete;

    static_suite (static_suite&&) = delete;

    static_suite&
    operator= (const static_suite&)
        = delete;

    static_suite&
    operator= (static_suite&&)
        = delete;

    virtual ~static_suite () override;
 
    // ------------------------------------------------------------------------

    virtual void
    run (void) override;
 
  protected:
    std::function<void (static_suite&)> static_callable_;
  };
 
  // --------------------------------------------------------------------------
} // namespace micro_os_plus::micro_test_plus
 
#if defined(__GNUC__)
#pragma GCC diagnostic pop
#endif // defined(__GNUC__)
 
// ----------------------------------------------------------------------------
 
#endif // defined(__cplusplus)
 
// ============================================================================
// Templates, inlines & constexpr implementations.
 
#include "inlines/test-inlines.h"
 
// ----------------------------------------------------------------------------
 
#endif // MICRO_OS_PLUS_MICRO_TEST_PLUS_TEST_H_
 
// ----------------------------------------------------------------------------