Stories Modular Code and Unit Testing

Stories are a way to define the functionality of software from the perspective of the user of the software. Why use a story instead of a function statement or a requirement? The simple answer is that a story is interesting and starts a conversation. Do you go to a movie at the movie theater to listen to a set of functions or requirements? If you did, people would fall asleep or start to play with their phones after a couple of minutes. No, people go to a movie because the story draws them in and involves them. So what is a story when it relates to software? A great description of a story can be found at Mountain Goat Software. A story takes the form of:

As a <user role/name> I want <goal of function> so that <reason why>.

Stories are a great way to discuss what the software should do. Details or specifics that result from this discussion are captured in the form of short statements called requirements. Requirements are what gets tested.

Modular code is all about taking a big problem, breaking it apart into smaller pieces, and solving the small problems one at a time. Software modules can then be quickly assembled to solve bigger problems. Think of a software module like a tool in your tool box. Is your command to aggressive? Try adding a limiter or a rate limiter. Is your signal noisy? Try adding a lowpass filter. Good software modules can also easily evolve or specialize over time without impacting the software in a negative way. To do this, software modules have 3 very important parts, the function or goal, the interface, and the strategy. Each of these parts needs to exist for the module to be useful as a building block over time. For example, I can take put the software in one module or file that implements one story. Robot C provides one tool to help with modular code, the include statement.

Include will insert any file into my Robot C software.

Unit testing tests the story or function a module of code implements.

Put it all together - Why the introduction to stories, modular code, and unit testing? Because these 3 elements are what makes up the contents of one modular file. Lets walk through the example of a function that I used in the last blog post called "riseedge.c" as shown below:

// Story: As a software designer I want to find the rising edge of a signal so that I can trigger an event
// Usage: Make sure globalBoolEqF is initialized equal to false
//   bool globalBoolEqF = false; //global
//   outBool = RiseEdge( inBool, globalBoolEqF );
bool RiseEdge(bool in, bool &z1)
{
  bool out;

  out=false;
  if ((in==true) && (z1==false)) out=true;
  z1=in;

  return(out);
}

#define TEST
#ifdef TEST //-------------------------------------------------
// Add this code to a while loop in main
// Unit Test
// [x] Rise Edge of input results in a true output for 1 frame
// [x] Fall Edge of input results in no change to the output
// [x] True input for more than one frame results in a false output
// [x] False input results in a false output

task main(){
 char str[20];
 
  int iFrameCnt=0;
  bool z=false;
  bool out,in=false;
  short DebugFile;
  //TFileHandle DebugFile;
  TFileIOResult isOk;
  int nFileSize=4000;
  OpenWrite(DebugFile, isOk, "debug.txt", nFileSize);
  while(iFrameCnt<10){

    if (iFrameCnt<2) in=false;
    else if (iFrameCnt<4) in=true;
    else if (iFrameCnt<6) in=false;
    else if (iFrameCnt<8) in=true;

    out=RiseEdge(in, z);
  
    if (iFrameCnt==0){
      sprintf(str,"Frame,In,Out\n");
      WriteString(DebugFile, isOk, str);   
      writeDebugStream(str);
    }
    
    sprintf(str, "%2d,%2d,%2d\n", iFrameCnt, in, out);
    WriteString(DebugFile, isOk, str);
    writeDebugStream(str);
 
    wait1Msec(50);
    iFrameCnt++;
  }
  Close(DebugFile,isOk);
}
#endif

The first four lines of the file contain the story and the usage of the software module as shown below:

// Story: As a software designer I want to find the rising edge of a signal so that I can trigger an event
// Usage: Make sure globalBoolEqF is initialized equal to false
//   bool globalBoolEqF = false; //global
//   outBool = RiseEdge( inBool, globalBoolEqF );

The story quickly describes the purpose of the function. The usage helps a person understand how to add this module to their software. With the usage, it is important to describe the details or requirements of the interface. In this case, the interface is a boolean and it must be defined as a global. If the interface contained an integer, it is important to understand the expected range of the interface (i.e. -179 to 180 degrees, positive turns the robot to the left) the units of the interface, and the context. I often find reusable components defined without the the interface details. I end up running experiments to figure out the range of values, the units, and the context. This is part of software programming that is not that much fun. The function called RiseEdge follows the story and usage. This is followed by the software needed for unit testing. The software #ifdef begins the test. If "#define TEST" is commented out, the module can be inserted into your code. If it is not commented out, as shown below, the software can be loaded directly onto the NXT for unit testing. For unit testing use:

#define TEST
#ifdef TEST

To turn off the unit testing and use the file as an insert, use:

//#define TEST
#ifdef TEST

The unit test code begins with the requirements for the use case as shown below:

// Add this code to a while loop in main
// Unit Test
// [x] Rise Edge of input results in a true output for 1 frame
// [x] Fall Edge of input results in no change to the output
// [x] True input for more than one frame results in a false output
// [x] False input results in a false output

The requirements use a [x] to indicate that the test has been run and passes this requirement test. I start with a [] to indicate that the test has not passed yet. This pass/fail marking gives confidence that the function has been tested and should work as advertised. The main portion of the unit test is shown below:

    if (iFrameCnt<2) in=false;
    else if (iFrameCnt<4) in=true;
    else if (iFrameCnt<6) in=false;
    else if (iFrameCnt<8) in=true;

This software toggles the input true and false for 2 frames. This is enough to check the requirements for the test. The results are output to both the debug stream and to a local file on the NXT. If I want a time-history plot of the test output I open the Robot C program. I use the main menu "Robot->NXT Brick->File Management Utility" to copy the "Debug.txt" file to my PC. I can then use MS Excel to plot the results.