Unity: a unit test framework for C/C++

The Unity unit test framework is an (easy) to use framework that will let us to implement TDD in a daily basis. This framework is mentioned in the book “Test Driven Development for Embedded C” by James W. Greening, and a tutorial for the same author can be found here.

BTW, that book is the only I ever seen for the topic of TDD for embedded systems. Luckily I own mine =) .

Although there are many unit tests frameworks out there, what makes this one special is the fact that optionally it uses a Ruby scripts in order to automate the error prone task of adding tests by hand. Besides it supports mocking, which is a priceless utility when applying TDD on hardware.

In this post I’ll talk about how to setup the framework as painless as possible. Once the job is done, it’s a pleasure to work with, though. If you have no experience in TDD you should look among the tons of tutorials in the net; or better off, get the book if you are an embedded enginner as I am.

Instructions for WinXP (soon for Linux, though it’s pretty the same procedure)

Download Unity from here.

If your are planning to use the Ruby scripts, then you should download and install it from here. Otherwise, skip this step.

Unzip Unity to wherever you want, later we are gonna take it what is really important for our TDD. After unzipping it you’ll see a lot of folders. In the root folder there are some interesting and strange files that we are not to use, so don’t worry for them. Look in the “src” folder: in there resides three files that we need to move to a better location, but not yet. Now look in the “extras\fixture\src” folder: there you’ll find four others files that we are going to move too.

A good programming practice is to build a library from this framework, but we’ll defer this step ‘til later, so for now we’re going to use the raw files. And before we can exercise any TDDing we need a minimal scaffolding to start working with:

main.c
Every C application starts at main(). But watch out! This is not your production main(), it’s only for TDDing
mod1.c, mod1.h
The modules that we want to test. Of course they must be named according to your application, but keep in mind that for each module to be tested, you’ll need at least that couple of files: .c and .h
testmod1.c
Here is where you’ll write your tests. If you plan to use the Ruby support, then all the files names that will allocate your tests MUST start with the word test. In this little example my module under test is mod1, so I named the test files as testmod1.c and testmod1.h
testmod1.h
Optional, but here you can place all your #include(s) helper files
Makefile
This file will led all the tests compilation (but for this example, I’ll skip it)

That is the minimum amount of files before we jump into the TDD process.

Now, What is inside of each file? The recommended tutorial above from the framework’s co-author is full of code-snippets, but nothing concrete, so if you are new at TDDing you’ll get lost and frustrated, that’s way I decided to write this tutorial. Let’s start with the code of our module under test. In this case this is a really silly example, but as this tutorial is not about teaching TDD, let’s focus on getting  the framework up and running as quickly as possible.

mod1.h
#ifndef mod1_INC
#define mod1_INC

int foo1();

#endif /* —– #ifndef mod1_INC —– */

mod1.c
#include "mod1.h"

int foo1()
{
return 1;
}

testmod1.h

#ifndef testmod1_INC
#define testmod1_INC

#include “unity_fixture.h”
#include “testmod1.h”

#endif /* —– #ifndef testmod1_INC —– */

testmod1.c
#include "unity_fixture.h"
#include "testmod1.h"

TEST_GROUP(mod1);

TEST_SETUP(mod1)
{
}

TEST_TEAR_DOWN(mod1)
{
}

TEST(mod1, DoNothing)
{
TEST_ASSERT_EQUAL(1, foo1());
}

TEST_GROUP_RUNNER(mod1)
{
RUN_TEST_CASE(mod1, DoNothing);
}

main.c
#include "unity_fixture.h"

static void RunAllTests()
{
RUN_TEST_GROUP(mod1);
}

int main(int argc, const char *argv[])
{
return UnityMain(argc, argv, RunAllTests);
}

(Sorry for the poorly formatted output).

Now we are close to run our first TDD, but besides our scaffolding we’ll need files from the framework. Pick a convenient folder to place all the files we just wrote, plus the ones that we’re going to include, and create a new folder. From the “src” folder copy the three files to the location where the scaffolding is, and from the “extras\fixture\src” folder copy the four files to that same location, so in they are in total seven files. Your file structure ‘til this point should look like:

pruebaUnity_files_structure

Armed with the scaffolding and the framework is time to compile and run our tests. I told you before that for this tutorial we aren’t going to use a Makefile, instead we are going to write the complete command in the console:

gcc -o main.exe main.c mod1.c testmod1.c unity.c unity_fixture.c

After that you’ll find a bunch of other files in your working folder: some objects files .o, and one executable, main.exe. Run it:

C:\proyectos_C\pruebaUnity>main
Unity test run 1 of 1
.
———————–
1 Tests 0 Failures 0 Ignored
 OK

Maybe you’ll get some warnings from the compiler, but those are from the framework, so the Unity admins should take care about them.

Final words

From here hopefully you’re able to write and run your own tests. But in case you don’t feel yourself very confident yet, use my scaffolding to add more tests and explore some or all the Unity features. And don’t forget to visit the Unity co-author tutorial, and the tests examples found in the “examples” folder from the Unity tree files.

(Note about the source code: I don’t know how to include here the source code, however, you can copy and paste the code above for each file.)

In a newer post I’ll include a Makefile and other stuff that was missing here. Meanwhile any comments are appreciated.

Happy TDDing !!

Anuncios

Responder

Introduce tus datos o haz clic en un icono para iniciar sesión:

Logo de WordPress.com

Estás comentando usando tu cuenta de WordPress.com. Cerrar sesión / Cambiar )

Imagen de Twitter

Estás comentando usando tu cuenta de Twitter. Cerrar sesión / Cambiar )

Foto de Facebook

Estás comentando usando tu cuenta de Facebook. Cerrar sesión / Cambiar )

Google+ photo

Estás comentando usando tu cuenta de Google+. Cerrar sesión / Cambiar )

Conectando a %s