`test_runner` Class

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

Declaration

class micro_os_plus::micro_test_plus::test_runner { ... }

Included Headers

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

Public Constructors Index

	test_runner ()
	Default constructor for the test_runner class. More...

	test_runner (const test_runner &)=delete
	Deleted copy constructor to prevent copying. More...

	test_runner (test_runner &&)=delete
	Deleted move constructor to prevent moving. More...

Public Destructor Index

	~test_runner ()=default
	Destructor for the test_runner class. More...

Public Operators Index

test_runner &	operator= (const test_runner &)=delete
	Deleted copy assignment operator to prevent copying. More...

test_runner &	operator= (test_runner &&)=delete
	Deleted move assignment operator to prevent moving. More...

Public Member Functions Index

void	abort (void)
	Aborts test execution immediately. More...

int	exit_code (void)
	Returns 0 if all tests were successful, 1 otherwise. More...

void	initialize (int argc, char argv[], const char name)
	Initialises the test runner with command-line arguments and an optional suite name. More...

constexpr const char *	name (void)
	Retrieves the name of the default test suite. More...

void	register_test_suite (test_suite_base *suite)
	Registers a test suite with the runner. More...

size_t	test_suites_count (void)

Public Member Attributes Index

test_suite_base *	default_test_suite = nullptr
	Pointer to the default test suite which groups the main tests. More...

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

std::vector< test_suite_base * > *	test_suites
	Pointer to the array of registered test suites. More...

struct { ... }	totals

Protected Member Attributes Index

int	argc_ = 0
	Stores the argument count passed to the test runner. More...

char **	argv_ = nullptr
	Stores the argument vector passed to the test runner. More...

const char *	default_suite_name_ = "Test"
	The name of the default test suite. More...

Description

The test runner for the µTest++ framework.

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.

Public Constructors

test_runner()

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

Default constructor for the test_runner class.

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.

Declaration at line 107 of file test-runner.h, definition at line 73 of file test-runner.cpp.

73 test_runner::test_runner ()

74 {

75#if defined(MICRO_OS_PLUS_TRACE_MICRO_TEST_PLUS)

76 printf ("%s\n", __PRETTY_FUNCTION__);

77#endif // MICRO_OS_PLUS_TRACE_MICRO_TEST_PLUS

78 }

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

test_runner()

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

delete

Deleted copy constructor to prevent copying.

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

Reference test_runner.

test_runner()

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

delete

Deleted move constructor to prevent moving.

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

Reference test_runner.

Public Destructor

~test_runner()

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

default

Destructor for the test_runner class.

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

Reference name.

Public Operators

operator=()

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

delete

Deleted copy assignment operator to prevent copying.

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

Reference test_runner.

operator=()

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

delete

Deleted move assignment operator to prevent moving.

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

Reference test_runner.

Public Member Functions

abort()

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

Aborts test execution immediately.

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.

Declaration at line 200 of file test-runner.h, definition at line 303 of file test-runner.cpp.

303 test_runner::abort (void)

304 {

305 ::abort ();

306 }

Reference abort.

Referenced by abort.

exit_code()

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

Returns 0 if all tests were successful, 1 otherwise.

Parameters: None.

Returns: Integer exit code representing the overall test result.

Declaration at line 159 of file test-runner.h, definition at line 218 of file test-runner.cpp.

218 test_runner::exit_code (void)

219 {

220 bool was_successful = true;

221

222 if (!default_test_suite->unused ())

223 {

224 default_test_suite->end_test_suite ();

225 was_successful = default_test_suite->was_successful ();

226

227 totals.successful_checks += default_test_suite->successful_checks ();

228 totals.failed_checks += default_test_suite->failed_checks ();

229 totals.test_cases_count += default_test_suite->test_cases_count ();

230 }

231

232 if (test_suites != nullptr)

233 {

234 for (auto test_suite : *test_suites)

235 {

236 current_test_suite = test_suite;

237

238 test_suite->begin_test_suite ();

239 test_suite->run ();

240 test_suite->end_test_suite ();

241

242 was_successful &= test_suite->was_successful ();

243

244 totals.successful_checks += test_suite->successful_checks ();

245 totals.failed_checks += test_suite->failed_checks ();

246 totals.test_cases_count += test_suite->test_cases_count ();

247 }

248 if (reporter->verbosity != verbosity::silent)

249 {

250 // printf ("\n");

251 }

252 }

253

254#if defined(_WIN32) || defined(CLOCK_MONOTONIC)

255#if defined(_WIN32)

256 timespec_get (&end_time, TIME_UTC);

257#else

258 clock_gettime (CLOCK_MONOTONIC, &end_time);

259#endif

260#endif

261

262 reporter->end_test (*this);

263

264 return was_successful ? 0 : 1;

265 }

initialize()

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

Initialises the test runner with command-line arguments and an optional suite 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.

Declaration at line 149 of file test-runner.h, definition at line 97 of file test-runner.cpp.

97 test_runner::initialize (int argc, char* argv[], const char* name)

98 {

99#if defined(MICRO_OS_PLUS_TRACE_MICRO_TEST_PLUS)

100 printf ("%s\n", __PRETTY_FUNCTION__);

101#endif // MICRO_OS_PLUS_TRACE_MICRO_TEST_PLUS

102

103#if defined(_WIN32) || defined(CLOCK_MONOTONIC)

104#if defined(_WIN32)

105 timespec_get (&begin_time, TIME_UTC);

106#else

107 clock_gettime (CLOCK_MONOTONIC, &begin_time);

108#endif

109#endif

110

111 argc_ = argc;

112 argv_ = argv;

113

114 default_suite_name_ = name;

115

116#if !(defined(MICRO_OS_PLUS_INCLUDE_STARTUP) && defined(MICRO_OS_PLUS_TRACE))

117#if defined(MICRO_OS_PLUS_DEBUG)

118 printf ("argv[");

119 for (int i = 0; i < argc; ++i)

120 {

121 if (i > 0)

122 {

123 printf (", ");

124 }

125 printf ("'%s'", argv[i]);

126 }

127 puts ("]");

128#endif // defined(MICRO_OS_PLUS_DEBUG)

129#endif // !defined(MICRO_OS_PLUS_INCLUDE_STARTUP)

130

131 verbosity_t verbosity = verbosity::normal;

132 const char* reporter_name = "tap";

133 for (int i = 0; i < argc; ++i)

134 {

135 if (strcmp (argv[i], "--verbose") == 0)

136 {

137 verbosity = verbosity::verbose;

138 }

139 else if (strcmp (argv[i], "--quiet") == 0)

140 {

141 verbosity = verbosity::quiet;

142 }

143 else if (strcmp (argv[i], "--silent") == 0)

144 {

145 verbosity = verbosity::silent;

146 }

147 else if (strncmp (argv[i], "--reporter=", 11) == 0)

148 {

149 reporter_name = argv[i] + 11;

150 }

151 }

152

153 // Initialize and configure the reporter.

154 if (strcmp (reporter_name, "basic") == 0)

155 {

156 reporter = new test_reporter_basic ();

157 }

158 else if (strcmp (reporter_name, "tap") == 0)

159 {

160 reporter = new test_reporter_tap ();

161 }

162 else

163 {

164 fprintf (stderr, "error: unknown reporter '%s'\n", reporter_name);

165 exit (1);

166 }

167 reporter->verbosity = verbosity;

168

169 // ------------------------------------------------------------------------

170

171#if !(defined(MICRO_OS_PLUS_INCLUDE_STARTUP) && defined(MICRO_OS_PLUS_TRACE))

172 if (verbosity == verbosity::normal || verbosity == verbosity::verbose)

173 {

174#if defined(__clang__)

175 printf ("Built with clang " __VERSION__);

176#elif defined(__GNUC__)

177 printf ("Built with GCC " __VERSION__);

178#elif defined(_MSC_VER)

179 // https://docs.microsoft.com/en-us/cpp/preprocessor/predefined-macros?view=msvc-170

180 printf ("Built with MSVC %d", _MSC_VER);

181#else

182 printf ("Built with an unknown compiler");

183#endif

184#if !(defined(__APPLE__) || defined(__linux__) || defined(__unix__) \

185 || defined(WIN32))

186// This is relevant only on bare-metal.

187#if defined(__ARM_PCS_VFP) || defined(__ARM_FP)

188 printf (", with FP");

189#else

190 printf (", no FP");

191#endif

192#endif

193#if defined(__EXCEPTIONS)

194 printf (", with exceptions");

195#else

196 printf (", no exceptions");

197#endif

198#if defined(MICRO_OS_PLUS_DEBUG)

199 printf (", with MICRO_OS_PLUS_DEBUG");

200#endif

201 puts (".");

202 }

203#endif // !defined(MICRO_OS_PLUS_INCLUDE_STARTUP)

204

205 // ------------------------------------------------------------------------

206

207 default_test_suite = new test_suite_base (default_suite_name_);

208 current_test_suite = default_test_suite;

209

210 // Deferred to first test case or test suite end, to allow various

211 // initialisations to display their messages.

212 // reporter->begin_test (test_suites_count ());

213 // default_test_suite_->begin_test_suite ();

214 }

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)

inline constexpr

Retrieves the name of the default test suite.

Parameters: None.

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

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

186 name (void)

187 {

188 return default_suite_name_;

189 }

Reference default_suite_name_.

Referenced by ~test_runner and initialize.

register_test_suite()

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

Registers a test suite with the runner.

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.

Declaration at line 169 of file test-runner.h, definition at line 279 of file test-runner.cpp.

279 test_runner::register_test_suite (test_suite_base* suite)

280 {

281#if 0 // defined(MICRO_OS_PLUS_TRACE_MICRO_TEST_PLUS)

282 printf ("%s\n", __PRETTY_FUNCTION__);

283#endif // MICRO_OS_PLUS_TRACE_MICRO_TEST_PLUS

284

285 if (test_suites == nullptr)

286 {

287 test_suites = new std::vector<test_suite_base*> ();

288 }

289 test_suites->push_back (suite);

290 suite->index = test_suites->size () + 1;

291 }

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.

172 test_suites_count (void)

173 {

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

175 }

Reference test_suites.

Public Member Attributes

default_test_suite

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

Pointer to the default test suite which groups the main tests.

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

247 test_suite_base* default_test_suite = nullptr;

Referenced by exit_code and initialize.

failed_checks

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

Total number of failed checks in the test suite.

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

224 size_t failed_checks = 0;

successful_checks

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

Total number of successful checks in the test suite.

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

219 size_t successful_checks = 0;

test_cases_count

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

Total number of test cases in the test suite.

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

229 size_t test_cases_count = 0;

test_suites

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

Pointer to the array of registered 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.

212 std::vector<test_suite_base*>* test_suites; // DO NOT INITIALISE!

Referenced by exit_code, register_test_suite and test_suites_count.

totals

struct micro_os_plus::micro_test_plus::test_runner micro_os_plus::micro_test_plus::test_runner::totals

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

Referenced by exit_code.

Protected Member Attributes

argc_

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

protected

Stores the argument count passed to the test runner.

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

253 int argc_ = 0;

Referenced by initialize.

argv_

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

protected

Stores the argument vector passed to the test runner.

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

258 char** argv_ = nullptr;

Referenced by initialize.

default_suite_name_

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

protected

The name of the default test suite.

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

263 const char* default_suite_name_ = "Test";

Referenced by initialize and name.

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

Generated via doxygen2docusaurus 2.0.0 by Doxygen 1.14.0.

Declaration​

Included Headers​

Public Constructors Index​

Public Destructor Index​

Public Operators Index​

Public Member Functions Index​

Public Member Attributes Index​

Protected Member Attributes Index​

Description​

Public Constructors​

test_runner()​

test_runner()​

test_runner()​

Public Destructor​

~test_runner()​

Public Operators​

operator=()​

operator=()​

Public Member Functions​

abort()​

exit_code()​

initialize()​

name()​

register_test_suite()​

test_suites_count()​

Public Member Attributes​

default_test_suite​

failed_checks​

successful_checks​

test_cases_count​

test_suites​

totals​

Protected Member Attributes​

argc_​

argv_​

default_suite_name_​

Declaration

Included Headers

Public Constructors Index

Public Destructor Index

Public Operators Index

Public Member Functions Index

Public Member Attributes Index

Protected Member Attributes Index

Description

Public Constructors

test_runner()

test_runner()

test_runner()

Public Destructor

~test_runner()

Public Operators

operator=()

operator=()

Public Member Functions

abort()

exit_code()

initialize()

name()

register_test_suite()

test_suites_count()

Public Member Attributes

default_test_suite

failed_checks

successful_checks

test_cases_count

test_suites

totals

Protected Member Attributes

argc_

argv_

default_suite_name_