TDD-ing a Circular Buffer in Google Test Framework

 TDD is quite a popular practice among the software developers but in the firmware development case it's not quite so. One of the reasons behind this is the hurdle in setting up the TDD environment. In this blog post I am not going to explain the importance of doing TDD, rather in this post I will be showing you how we can set up a TDD build environment using google test and  develop a circular buffer following the TDD approach. So Let’s engage in TDD-ing 


gTest Setup 


Firstly we have to install google Test , this is available from the apt-repository 

~$ sudo apt-get install libgtest-dev


The above command will pull down the sources and it is upto us to build the gTest. This process Requires CMake

~$ sudo apt-get install cmake
~$ sudo apt-get install build-essential


Now go to gtest src which got downloaded by apt & build gTest

/usr/src/gtest$ sudo cmake CMakeLists.txt
/usr/src/gtest$ sudo make


Now Lets copy the libraries to system default /usr/lib so that it is accessible from any PATH  

/usr/src/gtest$ sudo cp lib/*.a /usr/lib


Requirements Gathering  


Before starting to code we do have a mental model of the module that we want to develop . The idea of TDD is to write test cases first and then do coding . We will do the same but first let’s write down the requirements of the module in our imagination. 


Circular Buffer spec 

  1. The buffer will be 4 in size 

  2. Data can be put into the buffer 

  3. Data can be read from the buffer

  4. The buffer should be FIFO in nature 

  5. The buffer should be fixed sized 

  6. User should know if buffer is empty

  7. User should have the option to clear the buffer


TDD project Folder Structure 


The Project folder has the following structure 



Now let’s look what each of the elements are 


CMakeLists.txt

This is the CMake file required for the overall build . 


It has linkage to the gTest binaries and rules to add the module headers under include folder 

CBuffer.h

This is the Module Header File

CBuffer.cpp

This is the Module Implementation File 

main.cpp

The Test Driver and the Test framework

It contains all the Test Cases  


Let’s create all the folders and files 


~/$ mkdir circular-buffer
~/$ cd circular-buffer/
~/circular-buffer$ mkdir include src
~/circular-buffer$ touch include/CBuffer.h
~/circular-buffer$ touch src/CBuffer.cpp
~/circular-buffer$ touch src/main.cpp

~/circular-buffer$ touch CMakeLists.txt 


Linking gTest & CMake 


Now we will prepare the CMake makefile so that our sources gets linked with the compiled gTest libraries that we built at top . This CMake file is very easy to understand . the contents are 


CMakeLists.txt 

cmake_minimum_required(VERSION 2.8.9)
project (circular-buffer-test)

#For the static library:
set ( PROJECT_LINK_LIBS libgtest.a libgtest_main.a )
link_directories( /usr/lib )

set(CMAKE_CXX_FLAGS "-Wall -std=c++11 -pthread")

#Bring the headers
include_directories(include)

#if multiple files
file(GLOB SOURCES "src/*.cpp")
add_executable(circular-buffer-test ${SOURCES})

target_link_libraries(circular-buffer-test ${PROJECT_LINK_LIBS} )

message("CMAKE_CXX_FLAGS is ${CMAKE_CXX_FLAGS}")
message("CMAKE_CXX_FLAGS_DEBUG is ${CMAKE_CXX_FLAGS_DEBUG}")
message("CMAKE_CXX_FLAGS_RELEASE is ${CMAKE_CXX_FLAGS_RELEASE}")


Test Driver Structure 


Now that our CMakeFile is ready we will prepare the main.cpp the Test Driver File .


main.cpp 

#include <iostream>      //standard header inclusion
#include <gtest/gtest.h> //google test header inclusion

#include "CBuffer.h"     //module header inclusion

int main(int argc, char** argv) {
  // The following line must be executed to initialize Google Mock
  // (and Google Test) before running the tests.
  ::testing::InitGoogleTest(&argc, argv);
  return RUN_ALL_TESTS();
}


Now let’s put some minimum code in our sources and check if build passes


CBuffer.h

#ifndef CBUFFER_H_   /* Include guard */
#define CBUFFER_H_


#endif


CBuffer.cpp

#include "CBuffer.h"



Build System Check 

Now let’s check if the Test Build system prepared so far works or not

~/circular-buffer$ cmake .


The job of CMake is to create a makefile


Let’s use make to build our executable binary 

~/circular-buffer$ make clean
~/circular-buffer$ make


Now run the executable created

~/circular-buffer$ ./circular-buffer-test
[==========] Running 0 tests from 0 test suites.
[==========] 0 tests from 0 test suites ran. (0 ms total)
[  PASSED  ] 0 tests.


Writing The First Test Case


In TDD we have to follow 4 major steps 

  1. Setup 

  2. Exercise

  3. Verify

  4. Cleanup 


Each Test Case should go through the above steps 


  • We will write test cases for spec 6 & 7 

  • We will call clear function to empty out the buffer 

  • And then check if buffer is empty 


Now let’s compile again 

$ make clean && make


You will get compilation error 


Getting compilation/build errors first is also part of The TDD process. The mandatory rule is to write test cases first no matter what . The hidden gem of TDD is that by writing the test cases first we get to think about the module API calls and the code grows with this approach 


Now Let’s put code

CBuffer.cpp

CBuffer.h 


Next step is to add our 3rd step Verify

main.cpp

 


Now Compile again and you will see successful build output 

$ make clean && make 


Let’s run the executable binary 

~/circular-buffer$ ./circular-buffer-test


This time we see Test Case output of the verification stage. In this step we see Test cases getting failed This is the way TDD development progresses. We observe code getting failed and then we write code to pass the test cases. This is what we are going to do now 


CBuffer.cpp


Add the orange marked code and Now if you compile and run the test executable again then you will see that the test have passed 


Similarly you will be adding all the other test cases and code will get developed along the away 

I am not going to explain all the other test cases here anymore as this has already been a very long post. You can find the rest of the test cases along with all the other source files available in this link 

https://github.com/hassin23ayz/TDD-practice/tree/master/cpp/circular-buffer 


1 comment:

  1. you are spreading knowledge and it helps a people to understand the problem on embeded systems i apreciate your work


    JTAG

    ReplyDelete

Categories

Pages

Firmware Engineer

My photo
Works on Firmware, Embedded Linux, Smart Metering, RTOS, IoT backend

Contact Form

Name

Email *

Message *

Copyrighted by Hassin. Powered by Blogger.