Introducing CppUTest For SST

Matthew Eshleman

11 hours ago

CppUTest for SST (cpputest-for-sst) is a host-PC unit testing library for well-formed Super-Simple-Tasker (SST) Tasks. The purpose is to enable rapid TDD of SST-based firmware on a host PC.

A sister repository, cpputest-for-sst-examples, shows how to pull the library into a CMake project and how to unit test a realistic SST Task. Both repositories depend on Quantum Leaps’ Super-Simple-Tasker (SST).

If you have already used cpputest-for-qpcpp, cpputest-for-qpc, or cpputest-for-freertos, this will feel familiar. Same overall goals and feel, but targetting the SST kernel and associated Tasks instead.

Why SST, and why a test port?

SST is an event-driven, priority-based kernel for creating firmware. Tasks are run-to-completion and non-blocking. That execution model matches the active object pattern I have recommended for years: one thread of control, one incoming event queue, and behavior that runs to completion when an event arrives.

So what is the benefit of a host-PC SST port? Easier TDD. Module privates stay private. How?

Take a look at timers. If a Task uses an SST::TimeEvt for periodic behavior and we want host-PC unit tests, the options include:

Run a “real” SST scheduler on the PC and wait for wall-clock time to pass. (Too slow. What if the period is ten seconds? Or ten minutes?)
Expose the internal timeout handler and call it from the test. (Exposes internals. No thank you.)
Inject a unit-test-created event that looks like the timer event. (Again, the test now knows private signaling details.)
Or, and this is what this library enables, run a host port of SST and give the test an API such as cms::test::sst_ctrl::MoveTimeForward(...). The test can say “move time forward 10 seconds.” The kernel ticks, timer events post, Tasks dispatch, and the whole sequence finishes in microseconds. The test reads more like a requirement, and it does not reach into private details.

What the library actually provides

The library is C++ only, matching the C++ edition of SST. It is not a collection of empty stubs. The Task-under-test talks to SST. The test talks to a small control API that decides when SST is allowed to run.

The important pieces:

A host port of SST, suitable for unit testing. There are no threads. Interrupts and critical sections are no-ops. CPU time is given to Tasks only when a test asks for it.
cms::test::sst_ctrl::Setup() / Teardown() for the CppUTest setup() / teardown() pair.
ProcessEvents() — drain ready Tasks exactly as SST would, then return.
MoveTimeForward(std::chrono::milliseconds) — tick the kernel forward and process events after each tick.
PostAndProcess(...) — post an event to a Task and immediately give it processing time.
cms::test::DummyActiveObject — a collaborator Task that records or callbacks on posted events, useful when the unit under test talks to another Task.
cms::SstFlatStateMachineTask — an SST Task that is also a flat state machine, if that is the structure you want. MIT licensed too.
Assert support so a test can expect a design-by-contract failure, i.e. you can actually test your DBC based asserts.

The examples repository

cpputest-for-sst-examples is a top-level CMake project that:

pulls cpputest-for-sst and SST in as git submodules
builds with CppUTest 4.0, C++17, and C11
runs on GitHub Actions so every commit builds and executes the tests
includes the same HwLockCtrlService active object I have used in earlier posts, now living on SST.

That service is intentionally familiar. It locks and unlocks hardware, runs a self-test and returns to history, and polls communication status on a timer. The tests cover the happy path, the silent no-op path, self-test pass/fail, and timer edge cases. If you have read “Unit Testing of Active Objects and State Machines,” it will likely be familar to you.

SST, QP, and when to look elsewhere

SST is deliberately small. If the SST approach is too simple for your firmware project, look at QP/C or QP/C++ and the associated cpputest-for-qp* libraries.

My generally thinking at this time: if a project is complex enough to need preemptive tasks, then look to QP instead. Exceptions apply.

If this project and its related projects inspire your team to select a QP framework for commercial use, please note “Matthew Eshleman” or “Cove Mountain Software” in the referral field when acquiring a commercial license from Quantum Leaps. Referrals encourage and support efforts like this. Thank you.

Licensing

cpputest-for-sst and the examples project are MIT licensed. SST itself is also MIT. SST, CppUTest, and any other third-party code keep their own licenses.

Where to start

I hope this library proves useful to firmware teams that chose SST and still want a fast TDD loop. Start here: