Unit Test Framework

Registration, execution, progress/metric reporting and perf comparison for CMSDK tests. More...

Detailed Description

Registration, execution, progress/metric reporting and perf comparison for CMSDK tests.

Why a built-in framework

CMSDK is the bottom layer of the stack, built on every platform Psyclone supports, so its test harness must be dependency-free (no gtest/catch2 to vendor or port) and able to exercise things external frameworks handle poorly: tests that fork real processes, attach shared-memory segments or open sockets, and that may crash or hang without taking down the suite (the runner can execute each test in a forked child). It also records per-test performance metrics to JSON and diffs them against a previous run, turning the unit tests into a lightweight regression benchmark.

Writing a test

A test is any free function bool Func() that reports progress and metrics through the cmlabs::unittest namespace and returns true/false:

bool DataMessage_UnitTest() {
    unittest::progress(10, "building messages");
    uint64 t0 = GetTimeNow();
    for (int i = 0; i < 100000; i++) {
        DataMessage msg;
        msg.setInt("i", i);
        if (msg.getInt("i") != i)
            { unittest::fail("roundtrip mismatch at %d", i); return false; }
    }
    unittest::progress(90, "recording metrics");
    double secs = GetTimeAge(t0) / 1000000.0;
    unittest::metric("set/get roundtrips", 100000.0 / secs, "msg/s");
    unittest::detail("only shown with verbose=1");
    return true;
}

Registering and running

Register the function with the singleton runner (all CMSDK tests are registered in RegisterAllCMSDKTests() in UnitTest_CMSDK.cpp):

UnitTestRunner::instance().registerTest("datamessage", DataMessage_UnitTest,
                                        "DataMessage set/get roundtrip", "core");

and drive it from the Psyclone executable:

Psyclone test=cmsdk                     run all tests
Psyclone test=<objectname>              run a single test in isolation
Psyclone test=cmsdk compare=<oldfile>   show perf deltas vs a previous run
Psyclone test=cmsdk verbose=1           show verbose diagnostics
Psyclone test=cmsdk out=<file>          override perf JSON output path

Note

unittest::progress() draws a single overwriting line on a terminal and is suppressed when output is piped, so CI logs stay clean.

See also

UnitTestRunner, UnitTestRecord, cmlabs::unittest

Files
file	UnitTest_CMSDK.h
	Top-level entry points for running the CMSDK unit test suite.
file	CMSDKTest.cpp
	Standalone console entry point that runs the full CMSDK unit test suite (UnitTest_CMSDK()) outside of the Psyclone executable.
file	UnitTest_CMSDK.cpp
	Suite assembly for the CMSDK unit tests: collects each object's Register_*_Tests() function and implements the RunCMSDKTests() dispatch used by Psyclone's test= command line.
file	UnitTestFramework.cpp
	Implementation of the CMSDK unit test harness (UnitTestRunner and the unittest:: reporting API).

Namespaces
namespace	cmlabs::unittest
	API used by the body of a unit test.

Classes
struct	cmlabs::UnitTestMetric
	One recorded performance metric of a test run. More...
struct	cmlabs::UnitTestRecord
	Registration and result record for a single unit test. More...
class	cmlabs::UnitTestRunner
	The test runner (process-wide singleton). More...

Typedefs
typedef bool(*	cmlabs::UnitTestFunc) ()
	Signature every unit test uses.

Typedef Documentation

UnitTestFunc

typedef bool(* cmlabs::UnitTestFunc) ()

Signature every unit test uses.

Returns

true on success, false on failure.

Definition at line 95 of file UnitTestFramework.h.