The test runner for the µTest++ framework. More...

#include <micro-os-plus/micro-test-plus.h>

Public Member Functions
	test_runner ()
	Default constructor for the test_runner class.
	test_runner (const test_runner &)=delete
	Deleted copy constructor to prevent copying.
	test_runner (test_runner &&)=delete
	Deleted move constructor to prevent moving.
	~test_runner ()=default
	Destructor for the test_runner class.
void	abort (void)
	Aborts test execution immediately.
int	exit_code (void)
	Returns 0 if all tests were successful, 1 otherwise.
void	initialize (int argc, char argv[], const char name)
	Initialises the test runner with command-line arguments and an optional suite name.
constexpr const char *	name (void)
	Retrieves the name of the default test suite.
test_runner &	operator= (const test_runner &)=delete
	Deleted copy assignment operator to prevent copying.
test_runner &	operator= (test_runner &&)=delete
	Deleted move assignment operator to prevent moving.
void	register_test_suite (test_suite_base *suite)
	Registers a test suite with the runner.
size_t	test_suites_count (void)

Public Attributes
test_suite_base *	default_test_suite = nullptr
	Pointer to the default test suite which groups the main tests.
std::vector< test_suite_base * > *	test_suites
	Pointer to the array of registered test suites.
struct {
size_t failed_checks = 0
	Total number of failed checks in the test suite. More...
size_t successful_checks = 0
	Total number of successful checks in the test suite. More...
size_t test_cases_count = 0
	Total number of test cases in the test suite. More...
}	totals

Protected Attributes
int	argc_ = 0
	Stores the argument count passed to the test runner.
char **	argv_ = nullptr
	Stores the argument vector passed to the test runner.
const char *	default_suite_name_ = "Test"
	The name of the default test suite.

Detailed Description

The test_runner class is responsible for managing the registration and execution of test suites within the µTest++ framework. It maintains a collection of test suites, each of which registers itself automatically upon construction, enabling seamless integration and execution of tests across different components and folders of a project.

The test runner provides methods for initialising the test environment, registering test suites, retrieving the runner's name, and determining the overall test result via an exit code. It also offers an abort mechanism for terminating test execution in exceptional circumstances.

All members and methods are defined within the micro_os_plus::micro_test_plus namespace, ensuring clear separation from user code and minimising the risk of naming conflicts.

Definition at line 98 of file test-runner.h.

Constructor & Destructor Documentation

◆ test_runner() [1/3]

micro_os_plus::micro_test_plus::test_runner::test_runner ( )

The rule of five is enforced to prevent accidental copying or moving.

The constructor initialises a new instance of the test_runner class, preparing the test runner for managing test suites and cases within the µTest++ framework. If tracing is enabled, it outputs the function signature for diagnostic purposes. This setup ensures the test runner is ready to coordinate the registration, execution, and reporting of tests across all test cases and folders.

Definition at line 73 of file test-runner.cpp.

  {
#if defined(MICRO_OS_PLUS_TRACE_MICRO_TEST_PLUS)
    printf ("%s\n", __PRETTY_FUNCTION__);
#endif // MICRO_OS_PLUS_TRACE_MICRO_TEST_PLUS
  }

Referenced by test_runner(), test_runner(), operator=(), and operator=().

◆ test_runner() [2/3]

micro_os_plus::micro_test_plus::test_runner::test_runner ( const test_runner & )

delete

References test_runner().

◆ test_runner() [3/3]

micro_os_plus::micro_test_plus::test_runner::test_runner ( test_runner && )

delete

References test_runner().

◆ ~test_runner()

micro_os_plus::micro_test_plus::test_runner::~test_runner ( )

default

References name().

Member Function Documentation

◆ abort()

void micro_os_plus::micro_test_plus::test_runner::abort ( void )

Parameters: None.

Returns: Nothing.

This method immediately terminates the process by invoking the standard C library abort() function. It is used to halt test execution in critical failure scenarios, ensuring that no further tests are run and that the cause of the failure can be promptly investigated. This approach provides a robust mechanism for enforcing strict test outcomes across all test cases and folders.

Definition at line 303 of file test-runner.cpp.

  {
    ::abort ();
  }

References abort().

Referenced by abort().

◆ exit_code()

int micro_os_plus::micro_test_plus::test_runner::exit_code ( void )

Parameters: None.

Returns: Integer exit code representing the overall test result.

Definition at line 218 of file test-runner.cpp.

  {
    bool was_successful = true;
 
    if (!default_test_suite->unused ())
      {
        default_test_suite->end_test_suite ();
        was_successful = default_test_suite->was_successful ();
 
        totals.successful_checks += default_test_suite->successful_checks ();
        totals.failed_checks += default_test_suite->failed_checks ();
        totals.test_cases_count += default_test_suite->test_cases_count ();
      }
 
    if (test_suites != nullptr)
      {
        for (auto test_suite : *test_suites)
          {
            current_test_suite = test_suite;
 
            test_suite->begin_test_suite ();
            test_suite->run ();
            test_suite->end_test_suite ();
 
            was_successful &= test_suite->was_successful ();
 
            totals.successful_checks += test_suite->successful_checks ();
            totals.failed_checks += test_suite->failed_checks ();
            totals.test_cases_count += test_suite->test_cases_count ();
          }
        if (reporter->verbosity != verbosity::silent)
          {
            // printf ("\n");
          }
      }
 
#if defined(_WIN32) || defined(CLOCK_MONOTONIC)
#if defined(_WIN32)
    timespec_get (&end_time, TIME_UTC);
#else
    clock_gettime (CLOCK_MONOTONIC, &end_time);
#endif
#endif
 
    reporter->end_test (*this);
 
    return was_successful ? 0 : 1;
  }

◆ initialize()

void micro_os_plus::micro_test_plus::test_runner::initialize	(	int	argc,
		char *	argv[],
		const char *	name )

Parameters

argc	The argument count from main().
argv	The argument vector from main().
name	The name of the default test suite.

Returns: Nothing.

This method initialises the test runner by capturing the command-line arguments and the default test suite name, configuring the framework for subsequent test execution. It parses the arguments to determine the desired verbosity level (normal, verbose, quiet, or silent) and applies this setting to the test reporter. The method also outputs build and environment information when appropriate, aiding diagnostics and transparency. Finally, it creates and registers the default test suite, preparing the framework to manage and execute all test cases and suites across the project’s folders.

Definition at line 97 of file test-runner.cpp.

  {
#if defined(MICRO_OS_PLUS_TRACE_MICRO_TEST_PLUS)
    printf ("%s\n", __PRETTY_FUNCTION__);
#endif // MICRO_OS_PLUS_TRACE_MICRO_TEST_PLUS
 
#if defined(_WIN32) || defined(CLOCK_MONOTONIC)
#if defined(_WIN32)
    timespec_get (&begin_time, TIME_UTC);
#else
    clock_gettime (CLOCK_MONOTONIC, &begin_time);
#endif
#endif
 
    argc_ = argc;
    argv_ = argv;
 
    default_suite_name_ = name;
 
#if !(defined(MICRO_OS_PLUS_INCLUDE_STARTUP) && defined(MICRO_OS_PLUS_TRACE))
#if defined(MICRO_OS_PLUS_DEBUG)
    printf ("argv[");
    for (int i = 0; i < argc; ++i)
      {
        if (i > 0)
          {
            printf (", ");
          }
        printf ("'%s'", argv[i]);
      }
    puts ("]");
#endif // defined(MICRO_OS_PLUS_DEBUG)
#endif // !defined(MICRO_OS_PLUS_INCLUDE_STARTUP)
 
    verbosity_t verbosity = verbosity::normal;
    const char* reporter_name = "tap";
    for (int i = 0; i < argc; ++i)
      {
        if (strcmp (argv[i], "--verbose") == 0)
          {
            verbosity = verbosity::verbose;
          }
        else if (strcmp (argv[i], "--quiet") == 0)
          {
            verbosity = verbosity::quiet;
          }
        else if (strcmp (argv[i], "--silent") == 0)
          {
            verbosity = verbosity::silent;
          }
        else if (strncmp (argv[i], "--reporter=", 11) == 0)
          {
            reporter_name = argv[i] + 11;
          }
      }
 
    // Initialize and configure the reporter.
    if (strcmp (reporter_name, "basic") == 0)
      {
        reporter = new test_reporter_basic ();
      }
    else if (strcmp (reporter_name, "tap") == 0)
      {
        reporter = new test_reporter_tap ();
      }
    else
      {
        fprintf (stderr, "error: unknown reporter '%s'\n", reporter_name);
        exit (1);
      }
    reporter->verbosity = verbosity;
 
    // ------------------------------------------------------------------------
 
#if !(defined(MICRO_OS_PLUS_INCLUDE_STARTUP) && defined(MICRO_OS_PLUS_TRACE))
    if (verbosity == verbosity::normal || verbosity == verbosity::verbose)
      {
#if defined(__clang__)
        printf ("Built with clang " __VERSION__);
#elif defined(__GNUC__)
        printf ("Built with GCC " __VERSION__);
#elif defined(_MSC_VER)
        // https://docs.microsoft.com/en-us/cpp/preprocessor/predefined-macros?view=msvc-170
        printf ("Built with MSVC %d", _MSC_VER);
#else
        printf ("Built with an unknown compiler");
#endif
#if !(defined(__APPLE__) || defined(__linux__) || defined(__unix__) \
      || defined(WIN32))
// This is relevant only on bare-metal.
#if defined(__ARM_PCS_VFP) || defined(__ARM_FP)
        printf (", with FP");
#else
        printf (", no FP");
#endif
#endif
#if defined(__EXCEPTIONS)
        printf (", with exceptions");
#else
        printf (", no exceptions");
#endif
#if defined(MICRO_OS_PLUS_DEBUG)
        printf (", with MICRO_OS_PLUS_DEBUG");
#endif
        puts (".");
      }
#endif // !defined(MICRO_OS_PLUS_INCLUDE_STARTUP)
 
    // ------------------------------------------------------------------------
 
    default_test_suite = new test_suite_base (default_suite_name_);
    current_test_suite = default_test_suite;
 
    // Deferred to first test case or test suite end, to allow various
    // initialisations to display their messages.
    // reporter->begin_test (test_suites_count ());
    // default_test_suite_->begin_test_suite ();
  }

References argc_, argv_, micro_os_plus::micro_test_plus::current_test_suite, default_suite_name_, default_test_suite, name(), micro_os_plus::micro_test_plus::normal, micro_os_plus::micro_test_plus::quiet, micro_os_plus::micro_test_plus::reporter, micro_os_plus::micro_test_plus::silent, and micro_os_plus::micro_test_plus::verbose.

◆ name()

const char * micro_os_plus::micro_test_plus::test_runner::name ( void )

inlineconstexpr

Parameters: None.

Returns: The name of the default test suite as a constant character pointer.

Definition at line 186 of file test-runner.h.

    {
      return default_suite_name_;
    }

References default_suite_name_.

Referenced by ~test_runner(), and initialize().

◆ operator=() [1/2]

test_runner & micro_os_plus::micro_test_plus::test_runner::operator= ( const test_runner & )

delete

References test_runner().

◆ operator=() [2/2]

test_runner & micro_os_plus::micro_test_plus::test_runner::operator= ( test_runner && )

delete

References test_runner().

◆ register_test_suite()

void micro_os_plus::micro_test_plus::test_runner::register_test_suite ( test_suite_base * suite )

Parameters

suite Pointer to the test suite to register.

Returns: Nothing.

This method registers a new test suite with the test runner. If the internal collection of test suites has not yet been created, it is initialised at this point. The provided test suite is then added to the collection, enabling the framework to manage and execute multiple test suites across different files and folders within the project.

Called by test suite constructors to register themselves with the runner, enabling automatic management and execution.

Definition at line 279 of file test-runner.cpp.

  {
#if 0 // defined(MICRO_OS_PLUS_TRACE_MICRO_TEST_PLUS)
    printf ("%s\n", __PRETTY_FUNCTION__);
#endif // MICRO_OS_PLUS_TRACE_MICRO_TEST_PLUS
 
    if (test_suites == nullptr)
      {
        test_suites = new std::vector<test_suite_base*> ();
      }
    test_suites->push_back (suite);
    suite->index = test_suites->size () + 1;
  }

References micro_os_plus::micro_test_plus::test_suite_base::index, and test_suites.

◆ test_suites_count()

size_t micro_os_plus::micro_test_plus::test_runner::test_suites_count ( void )

inline

Definition at line 172 of file test-runner.h.

    {
      return (test_suites != nullptr) ? test_suites->size () + 1 : 1;
    }

References test_suites.

Member Data Documentation

◆ argc_

int micro_os_plus::micro_test_plus::test_runner::argc_ = 0

protected

Definition at line 253 of file test-runner.h.

Referenced by initialize().

◆ argv_

char** micro_os_plus::micro_test_plus::test_runner::argv_ = nullptr

protected

Definition at line 258 of file test-runner.h.

Referenced by initialize().

◆ default_suite_name_

const char* micro_os_plus::micro_test_plus::test_runner::default_suite_name_ = "Test"

protected

Definition at line 263 of file test-runner.h.

Referenced by initialize(), and name().

◆ default_test_suite

test_suite_base* micro_os_plus::micro_test_plus::test_runner::default_test_suite = nullptr

Definition at line 247 of file test-runner.h.

Referenced by exit_code(), and initialize().

◆ failed_checks

size_t micro_os_plus::micro_test_plus::test_runner::failed_checks = 0

Definition at line 224 of file test-runner.h.

◆ successful_checks

size_t micro_os_plus::micro_test_plus::test_runner::successful_checks = 0

Definition at line 219 of file test-runner.h.

◆ test_cases_count

size_t micro_os_plus::micro_test_plus::test_runner::test_cases_count = 0

Definition at line 229 of file test-runner.h.

◆ test_suites

std::vector<test_suite_base*>* micro_os_plus::micro_test_plus::test_runner::test_suites

Statically initialised to zero as BSS, such that test suites defined as static objects in different compilation units can be automatically executed.

Definition at line 212 of file test-runner.h.

Referenced by exit_code(), register_test_suite(), and test_suites_count().

◆ [struct]

struct { ... } micro_os_plus::micro_test_plus::test_runner::totals

Referenced by exit_code().

The documentation for this class was generated from the following files:

Public Member Functions

Public Attributes

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ test_runner() [1/3]

◆ test_runner() [2/3]

◆ test_runner() [3/3]

◆ ~test_runner()

Member Function Documentation

◆ abort()

◆ exit_code()

◆ initialize()

◆ name()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ register_test_suite()

◆ test_suites_count()

Member Data Documentation

◆ argc_

◆ argv_

◆ default_suite_name_

◆ default_test_suite

◆ failed_checks

◆ successful_checks

◆ test_cases_count

◆ test_suites

◆ [struct]