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 

Read More