Test suites

Test suites are named groups of related test cases. More...

Classes
class	micro_os_plus::micro_test_plus::located_name
	A name of a suite or of a test case, with the location where it was given. More...
class	micro_os_plus::micro_test_plus::static_suite
	A test suite designed for static (namespace-scope) registration with a runner. More...
class	micro_os_plus::micro_test_plus::suite
	A named, runnable test suite registered with the test runner. More...
class	micro_os_plus::micro_test_plus::top_suite
	The optional top suite owned by every runner instance. More...

Detailed Description

A suite has a name and a body, a function that creates its test cases. The suites are either added in main() with runner::add_suite(), or defined as static suites, and runner::run_suites() runs them all, sorted by name.

The top suite is a shortcut: a suite whose body is the code of main() itself. runner::add_top_suite() adds it and returns it, and the test cases created on it in main() run immediately, before runner::run_suites() is called. It therefore always runs before all the other suites, whatever their names. It is optional; a program may put all its test cases in the other suites.

A test case can be created only on the suite whose body is running: on the top suite from main(), or on the suite received by the body of another suite. A call on another suite, for example on the top suite captured in the body of another suite, is reported as a failure, and the test case is not run.

The static suites are mt::static_suite objects, defined at namespace scope, usually in separate source files, and constructed with a name, a reference to the runner, and a callable (usually a function or a lambda with a mt::suite& first parameter, which creates the test cases), along with any optional arguments. They register themselves in their constructors, so they are included in the test run without other calls.

Important

The runner referred to by the static suites in other source files must have external linkage (not static), and be declared extern in a header shared by these files.

A static suite does not need the runner to be constructed first; it can be defined in any source file, before or after the runner.

Execution order

The top suite runs first, as described above. runner::run_suites() then runs all the other suites, the added and the static ones together, sorted by name:

• the names are compared byte by byte, as by std::strcmp(), so the upper-case letters come before the lower-case ones ("Gamma" runs before "alpha");
• suites with the same name run in the order in which they were created; the static suites are created before main() starts, so they run before the added suites with the same name;
• the order of static suites with the same name, defined in different source files, is not specified; give them distinct names.

To set the order explicitly, start the names with zero-padded numbers ("01 - Init", "02 - Run"). Even so, write each suite so that it does not depend on the others having run before it.

Examples

// In a header shared by the source files.
extern micro_os_plus::micro_test_plus::runner tr;

namespace mt = micro_os_plus::micro_test_plus;
 
// In main.cpp: the runner, with external linkage.
mt::runner tr;
 
int
main (int argc, char* argv[])
{
  tr.initialise (argc, argv);
 
  auto& ts = tr.add_top_suite ("Sample");
 
  ts.test ("Check one", [] (auto& t) {
    t.expect (true) << "Passed";
  });
 
  return tr.run_suites ();
}

namespace mt = micro_os_plus::micro_test_plus;
 
// In a separate source file: a self-registering suite.
static mt::static_suite ts_extra
    = { "Extra suite", tr, [] (mt::suite& ts) {
  ts.test ("Check two", [] (auto& t) { t.expect (true) << "Passed"; });
} };
 
// Parametrised test suite accepting additional arguments.
static void
test_suite_with_args (mt::suite& ts, int ic, int iv,
                      int& ir, int* ip1, int* ip2)
{
  ts.test ("args", [&] (auto& t) {
    t.expect (mt::eq (ic, 42)) << "ic is 42";
    t.expect (mt::eq (iv, 43)) << "iv is 43";
    t.expect (mt::eq (ir, 44)) << "ir is 44";
    t.expect (mt::eq (*ip1, 45)) << "*ip1 is 45";
    t.expect (mt::eq (*ip2, 46)) << "*ip2 is 46";
  });
}
 
static int in = 43;
static int in44 = 44;
static int& ir = in44;
static int in45 = 45;
static int in46 = 46;
static int* ip2 = &in46;
 
static mt::static_suite ts_args
    = { "Args suite", tr, test_suite_with_args,
        42, in, ir, &in45, ip2 };