A State Machine – Unit Testing

Last time I talked about how I implemented a state-machine to control the lifetester that I’ve been developing. In the process, I relied heavily on unit testing the code as I wrote it. In fact, by unit testing the code while refactoring, all the development was done on my desktop machine! This is a big departure from how I used to do things a year ago where all the development that I did was using the Arduino IDE and code was compiled and run on the target. I only needed to compile for the Arduino and plug in a reference solar cell at the very end to check that everything worked as I expected and I’m pleased to say that it did. My eyes were opened to this in my first job as an embedded software engineer at CMR. I found this was one of the most striking differences between the professional and home project software development worlds. In essence, unit testing is software designed to exercise all of the behaviour of the code (as independent units) we’re intending to write. We’re trying to check that it works as we expect, whether we give the functions good or bad inputs – there are positive and negative tests. It was put to me like this once: “Unit-test the code like a burglar rather than a postman”.

How to write unit tests

I think it’s worth saying here that there are good and bad ways of unit testing and as with anything. I really like this guide. In short, unit-tests should be F.I.R.S.T:

  • Fast – probably more important on very large projects than here but who wants to wait ages for their tests to run?
  • Independent/Isolated – tests should follow the arrange, act assert format.
  • Repeatable – the order that test run shouldn’t matter and the results should be the same every time they’re run. They should be responsible for setup and teardown all of their data.
  • Self-validating – we don’t need to inspect anything to see if a test has passed or failed. The results should be reported automatically.
  • Thorough and timely – cover every use scenario and be done drive the development of the source code not be written later.

My attempt

Clearly, I can’t go through all the unit tests for this module as this post would be far too long but I can show you a couple of examples to give you an idea how this might work. Here goes…

TEST(IVTestGroup, SaturatedCurrentDetectedIncrementsErrorReadingsCounter)
{
    mockLifeTester->data.delayDone = true;
    mockLifeTester->data.iSampleSum = MAX_CURRENT;
    mockLifeTester->data.nSamples = 1U;
    mockLifeTester->data.nErrorReads = 0U;
    mockLifeTester->state = &StateMeasureThisDataPoint;
    const uint32_t tInit = 34524U;
    mockTime = tInit + SETTLE_TIME + SAMPLING_TIME;
    ActivateThisMeasurement(mockLifeTester);
    MocksForTrackingModeStep();
    MocksForMeasureDataNoAdcRead();
    StateMachine_UpdateStep(mockLifeTester);
    POINTERS_EQUAL(&StateTrackingMode, mockLifeTester->state);
    CHECK_EQUAL(1U, mockLifeTester->data.nErrorReads);
    CHECK_EQUAL(currentLimit, mockLifeTester->error);
    mock().checkExpectations();
}

Above is a test the checks that if the adc readings are saturated (the current from the device goes outside the available range), the reading is counted as a bad reading and added to a counter – the lifetester should accepts a few bad readings before transitioning to the error state. In the test module, I’ve setup a mockLifeTester variable (instance) that I reset before every test. So the first thing to do in the test is set the lifetester to the correct mode (MeasureThisDataPoint), reset the error readings counter and most importantly saturate the current reading. mockTime is my way of returning a value from millis() in the source code. You can see that I’ve incremented the timer so that the sampling window and tracking delay have expired before calling the state-machine update function. Now I do the asserts and check that we’ve transitioned back to TrackingMode (parent state), as the sampling time is over and that the error has been counted and recorded in the mockLifeTester data. Of course, too many bad readings should lead to a transition to the StateError as follows…

TEST(IVTestGroup, TrackingModeTooManyBadReadingsTransitionToErrorState)
{
    // Setup for tracking mode.
    mockLifeTester->data.nErrorReads = MAX_ERROR_READS + 1U;
    mockLifeTester->state = &StateTrackingMode;
    MocksForTrackingModeStep();
    MocksForErrorEntry(mockLifeTester);
    StateMachine_UpdateStep(mockLifeTester);
    POINTERS_EQUAL(&StateError, mockLifeTester->state);
    mock().checkExpectations();
}

All I need to do here is setup the the number of error readings above the allowed limit before calling the update function. This should lead to a transition to the error mode which will have happened for the test to pass in the POINTERS_EQUAL(...) statement.

Mocking

The question on my mind before I began unit-testing embedded code was “How do we execute code written for an embedded platform on a PC? Won’t it try to call hardware specific functions that don’t exist?”. This is accomplished by mocking – any calls to low level i/o are replaced with our own mock functions. I’ve given an example here that I needed in the last test…

static void MocksForErrorLedSetup(void)
{
    mock().expectOneCall("Flasher::t")
        .withParameter("onNew", ERROR_LED_ON_TIME)
        .withParameter("offNew", ERROR_LED_OFF_TIME);
    mock().expectOneCall("Flasher::keepFlashing");
}

static void MocksForSetDacToVoltage(LifeTester_t const *const lifeTester,
                                    uint8_t v)
{
    mock().expectOneCall("DacSetOutput")
        .withParameter("output", v)
        .withParameter("channel", lifeTester->io.dac);
}

static void MocksForErrorEntry(LifeTester_t const *const lifeTester)
{
    MocksForErrorLedSetup();
    MocksForSetDacToVoltage(lifeTester, 0U);
}

When the lifetester transitions into the error state, we expect it to set the dac and setup the flash rate of an led to indicate that the device is in its error state. So we expect our mock functions to be called. You’ll see in the tests that there’s this statement mock().checkExpectations() which is responsible for checking that the correct mocks are actually called number of times we expect. If we don’t say expectOneCall("DacSetOutput"), and a call is made to this function by the source then the test will fail. Alternatively, if we do make an expect and the function isn’t called, the test will fail too; mocking and expects are a really important tool for checking the behaviour of our code too. Asserting on the data returned is only half the picture.

 Thoughts

In this post, I’ve discussed in brief how unit testing can be used to refactor and write code that’s more robust. I hope you like it. Personally, I write unit tests for all the code that I write now even though it means you have to write twice as much code. I like the way that it helps me to think through what I’m doing and encourages me to write cleaner code where the lower layers are abstracted so they can be mocked effectively. I believe that it could be better understood and used by the ‘hacker’ community to good effect…but then would it really be hacking?

Leave a Reply

Your email address will not be published. Required fields are marked *