runner.cpp

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.
 */
 
// ----------------------------------------------------------------------------

 
// ----------------------------------------------------------------------------
 
#include "micro-os-plus/micro-test-plus/runner.h"
#include "micro-os-plus/micro-test-plus/utility.h"
#include "micro-os-plus/micro-test-plus/reporter-tap.h"
#include "micro-os-plus/micro-test-plus/reporter-human.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 <algorithm>
#include <string>
 
// ----------------------------------------------------------------------------
 
#if defined(__GNUC__)
#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-c++11-c++14-compat"
#pragma clang diagnostic ignored "-Wpre-c++17-compat"
#pragma clang diagnostic ignored "-Wunsafe-buffer-usage-in-libc-call"
#endif // defined(__clang__)
#endif // defined(__GNUC__)
 
// ============================================================================
 
#if defined(MICRO_OS_PLUS_MICRO_TEST_PLUS_ENABLED)
 
// ----------------------------------------------------------------------------
 
namespace micro_os_plus::micro_test_plus
{
  // --------------------------------------------------------------------------

  runner&
  detail::to_runner (static_runner& static_runner_ref) noexcept
  {
    return static_cast<runner&> (static_runner_ref);
  }

  void
  detail::register_static_suite (static_runner& static_runner_ref,
                                 static_suite& static_suite_ref)
  {
    static_runner::register_static_suite (static_runner_ref, static_suite_ref);
  }
 
  // --------------------------------------------------------------------------

  runner::runner (void) : test_node{ "runner" }, top_suite_{ "", *this }
  {
#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
  }

  runner::runner (const char* top_suite_name)
      : test_node{ "runner" }, top_suite_{ top_suite_name, *this }
  {
#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
  }

  runner::~runner ()
  {
#if defined(MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_CONSTRUCTORS_ENABLED)
    trace::printf ("%s\n", __PRETTY_FUNCTION__);
#endif // MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_CONSTRUCTORS_ENABLED
 
    // reporter_ is a unique_ptr; destroyed automatically.
  }
 
#if defined(__GNUC__)
#pragma GCC diagnostic push
 
#if defined(__clang__)
#pragma clang diagnostic ignored "-Wunsafe-buffer-usage"
#endif // defined(__clang__)
#endif // defined(__GNUC__)

  suite&
  runner::initialise (int argc, char* argv[], const char* top_suite_name)
  {
#if defined(MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_ENABLED)
    trace::printf ("%s\n", __PRETTY_FUNCTION__);
 
#if !(defined(MICRO_OS_PLUS_STARTUP_ENABLED) \
      && defined(MICRO_OS_PLUS_DIAG_TRACE_ENABLED))
#if defined(MICRO_OS_PLUS_DEBUG_ENABLED)
    trace::printf ("argv[");
    for (int i = 0; i < argc; ++i)
      {
        if (i > 0)
          {
            trace::printf (", ");
          }
        trace::printf ("'%s'", argv[i]);
      }
    trace::puts ("]");
#endif // defined(MICRO_OS_PLUS_DEBUG_ENABLED)
#endif // !defined(MICRO_OS_PLUS_STARTUP_ENABLED)
#endif // MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_ENABLED
 
    if (strlen (top_suite_name) > 0)
      {
        // If provided by this call, use it, possibly override the
        // deprecated constructor.
        top_suite_name_ = top_suite_name;
        top_suite_.name (top_suite_name_.c_str ());
      }
    else if (strlen (top_suite_.name ()) == 0)
      {
        // If not provided by the constructor or by this call, try to extract a
        // name from argv[0], which is commonly the executable name. If that
        // fails, use a default name.
        if (argc > 0 && argv != nullptr && argv[0] != nullptr)
          {
            std::string_view top_suite_name_view{ utility::extract_file_name (
                argv[0]) };
 
            const auto dot_pos = top_suite_name_view.rfind ('.');
            if (dot_pos != std::string_view::npos)
              {
                top_suite_name_view = top_suite_name_view.substr (0, dot_pos);
              }
 
            top_suite_name_ = top_suite_name_view;
          }
        else
          {
            top_suite_name_ = "default suite";
          }
        top_suite_.name (top_suite_name_.c_str ());
      }
 
    std::vector<std::string_view> argvs (argv, argv + argc);
 
    std::string_view reporter_name{ "tap" };
    static constexpr std::string_view reporter_prefix{ "--reporter=" };
    for (size_t i = 0; i < argvs.size (); ++i)
      {
        if (argvs[i].starts_with (reporter_prefix))
          {
            reporter_name = argvs[i].substr (reporter_prefix.size ());
          }
        else if (argvs[i]
                 == reporter_prefix.substr (0, reporter_prefix.size () - 1))
          {
            if (i + 1 < argvs.size ())
              {
                reporter_name = argvs[++i];
              }
            else
              {
                fprintf (stderr, "error: --reporter option requires a "
                                 "reporter name argument\n");
                exit (1);
              }
          }
      }
 
    // Initialise and configure the reporter.
    if (reporter_name == "human")
      {
        reporter_ = std::make_unique<reporter_human> (
            std::make_unique<std::vector<std::string_view>> (
                std::move (argvs)));
      }
    else if (reporter_name == "tap")
      {
        reporter_ = std::make_unique<reporter_tap> (
            std::make_unique<std::vector<std::string_view>> (
                std::move (argvs)));
      }
    else
      {
        fprintf (stderr, "error: unknown reporter '%.*s'\n",
                 static_cast<int> (reporter_name.size ()),
                 reporter_name.data ());
        exit (1);
      }
 
    // ------------------------------------------------------------------------
 
    timings_.timestamp_begin ();
    reporter_->begin_session (*this);
 
    top_suite_.timings ().timestamp_begin ();
    reporter_->begin_suite (top_suite_);
 
    return top_suite_;
  }
 
#if defined(__GNUC__)
#pragma GCC diagnostic pop
#endif // defined(__GNUC__)
 
  // --------------------------------------------------------------------------

  void
  runner::register_suite_ (std::unique_ptr<class suite> suite)
  {
#if defined(MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_ENABLED)
    trace::printf ("%s '%s'\n", __PRETTY_FUNCTION__, suite->name ());
#endif // MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_ENABLED
 
    children_suites_.push_back (std::move (suite));
  }

  void
  runner::run_suites_ (void)
  {
    // Use selection sort with unique_ptr::swap (returns void) to avoid
    // std::sort triggering -Waggregate-return via std::move_backward,
    // which returns a class-type iterator when operating on unique_ptr
    // elements.
    const size_t n = children_suites_.size ();
    for (size_t i = 0; i < n; ++i)
      {
        size_t min_idx = i;
        for (size_t j = i + 1; j < n; ++j)
          {
            if (std::string_view{ children_suites_[j]->name () }
                < std::string_view{ children_suites_[min_idx]->name () })
              min_idx = j;
          }
        if (min_idx != i)
          children_suites_[i].swap (children_suites_[min_idx]);
      }
 
    for (size_t i = 0; i < n; ++i)
      {
        auto* suite_ptr = children_suites_[i].get ();
 
        // +1 for 1-based index, +1 for top suite
        suite_ptr->own_index (i + 1 + 1);
 
        // Run the child suite immediately.
        suite_ptr->run ();
 
        // Accumulate the totals from the child suite into the runner
        // totals.
        // DO NOT increment executed_subtests here.
        totals_ += suite_ptr->totals ();
      }
  }

  int
  runner::exit_code (void)
  {
#if defined(MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_ENABLED)
    trace::printf ("%s\n", __PRETTY_FUNCTION__);
#endif // MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_ENABLED
 
    if (reporter_ == nullptr)
      {
        fprintf (stderr, "error: test runner not initialised\n");
        return 1;
      }
 
    top_suite_.timings ().timestamp_end ();
    reporter_->end_suite (top_suite_);
    totals_ += top_suite_.totals ();
 
    run_suites_ ();
 
    timings_.timestamp_end ();
    reporter_->end_session (*this);
 
    const int result = totals_.was_successful () ? 0 : 1;
 
#if defined(MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_ENABLED)
    trace::printf ("%s -> %d\n", __PRETTY_FUNCTION__, result);
#endif // MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_ENABLED
 
    return result;
  }

  void
  runner::abort (const reflection::source_location& sl)
  {
#if defined(MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_ENABLED)
    trace::printf ("%s\n", __PRETTY_FUNCTION__);
#endif // MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_ENABLED
 
    fprintf (stderr, "\nerror: test execution aborted at %s:%u\n",
             reflection::short_name (sl.file_name ()), sl.line ());
 
    ::abort ();
  }

  size_t
  runner::suites_count (void) const noexcept
  {
    return children_suites_.size () + 1;
  }

  size_t
  runner::total_suites_count (void) const noexcept
  {
    return suites_count ();
  }
 
  // ==========================================================================

  static_runner::static_runner (void) : runner{}
  {
#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
  }

  static_runner::static_runner (const char* top_suite_name)
      : runner{ top_suite_name }
  {
#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
  }

  static_runner::~static_runner ()
  {
#if defined(MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_CONSTRUCTORS_ENABLED)
    trace::printf ("%s\n", __PRETTY_FUNCTION__);
#endif // MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_CONSTRUCTORS_ENABLED
 
    if (static_children_suites_ != nullptr)
      {
        // The tests are static, so we do not delete them, but we need to
        // delete the array of pointers.
        delete static_children_suites_;
        static_children_suites_ = nullptr;
      }
  }

  size_t
  static_runner::static_suites_count (void) const noexcept
  {
    return static_children_suites_ != nullptr
               ? static_children_suites_->size ()
               : 0;
  }

  size_t
  static_runner::total_suites_count (void) const noexcept
  {
    return suites_count () + static_suites_count ();
  }

  void
  static_runner::run_suites_ (void)
  {
#if defined(MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_ENABLED)
    trace::printf ("%s\n", __PRETTY_FUNCTION__);
#endif // MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_ENABLED
 
    runner::run_suites_ ();
 
    if (static_children_suites_ != nullptr)
      {
        // Use selection sort with std::swap on raw pointers (returns void)
        // to avoid std::sort triggering -Waggregate-return via
        // std::move_backward returning a class-type iterator.
        const size_t n = static_children_suites_->size ();
        auto& suites = *static_children_suites_;
        for (size_t i = 0; i < n; ++i)
          {
            size_t min_idx = i;
            for (size_t j = i + 1; j < n; ++j)
              {
                if (std::string_view{ suites[j]->name () }
                    < std::string_view{ suites[min_idx]->name () })
                  min_idx = j;
              }
            if (min_idx != i)
              std::swap (suites[i], suites[min_idx]);
          }
 
        for (size_t i = 0; i < n; ++i)
          {
            auto* suite_ptr = suites[i];
 
            suite_ptr->own_index (i + 1 + suites_count ());
 
            // Run the child suite immediately.
            suite_ptr->run ();
 
            // Accumulate the totals from the static suite into the runner
            // totals.
            // DO NOT increment executed_subtests here.
            totals_ += suite_ptr->totals ();
          }
      }
  }

  void
  static_runner::register_static_suite (static_runner& runner,
                                        static_suite& suite)
  {
#if defined(MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_ENABLED)
    trace::printf ("%s '%s'\n", __PRETTY_FUNCTION__, suite.name ());
#endif // MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_ENABLED
 
    if (runner.static_children_suites_ == nullptr)
      {
#if defined(MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_ENABLED)
        trace::printf ("%s new static_children_suites_ array\n",
                       __PRETTY_FUNCTION__);
#endif // MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_ENABLED
        runner.static_children_suites_ = new std::vector<static_suite*>;
      }
    runner.static_children_suites_->push_back (&suite);
  }
 
  // --------------------------------------------------------------------------
} // namespace micro_os_plus::micro_test_plus
 
// ----------------------------------------------------------------------------
 
#endif // defined(MICRO_OS_PLUS_MICRO_TEST_PLUS_ENABLED)
 
// ----------------------------------------------------------------------------