Getting Started with Unity — Throw The Switch

Getting Started

Let's do this! First, you need to download your tools. Very likely, you'll start with just Unity. But you may choose to use Ceedling or CMock too. If you're not sure, maybe you want to start by using our Decide-O-Tron 3000. If you opted for Ceedling, you can start there to learn more. Otherwise, let's learn a bit about making a Unit Test with Unity.

The smallest realistic Unit Test build you can do is a source file, a test file, and Unity. Compile all three and link them together. We'll start with a native built app, because they're usually the simplest to get started. If you want to migrate to a simulated target later, we'll walk you through that too.

Let's say we have a C file that we want to test named DumbExample.c. It looks like this:

#include "DumbExample.h"

int8_t AverageThreeBytes(int8_t a, int8_t b, int8_t c)
{
return (int8_t)(((int16_t)a + (int16_t)b + (int16_t)c) / 3);
}

It has a header file that looks like this:

#include <stdint.h>

int8_t AverageThreeBytes(int8_t a, int8_t b, int8_t c);

Then we make a test file TestDumbExample.c which checks for some basic things like rollovers and whatnot:

#include "unity.h"
#include "DumbExample.h"

void test_AverageThreeBytes_should_AverageMidRangeValues(void)
{
TEST_ASSERT_EQUAL_HEX8(40, AverageThreeBytes(30, 40, 50));
TEST_ASSERT_EQUAL_HEX8(40, AverageThreeBytes(10, 70, 40));
TEST_ASSERT_EQUAL_HEX8(33, AverageThreeBytes(33, 33, 33));
}

void test_AverageThreeBytes_should_AverageHighValues(void)
{
TEST_ASSERT_EQUAL_HEX8(80, AverageThreeBytes(70, 80, 90));
TEST_ASSERT_EQUAL_HEX8(127, AverageThreeBytes(127, 127, 127));
TEST_ASSERT_EQUAL_HEX8(84, AverageThreeBytes(0, 126, 126));
}

int main(void)
{
UNITY_BEGIN();
RUN_TEST(test_AverageThreeBytes_should_AverageMidRangeValues);
RUN_TEST(test_AverageThreeBytes_should_AverageHighValues);
return UNITY_END();
}

So we have a test file which contains two tests. Each test has multiple assertions. If any of those assertions fail, that particular test should fail and we should move on to the next test. When done, it should output our results.

Let's build and run executable! Assuming we have gcc installed, we can use it for the first step, and then directly run the binary produced

gcc TestDumbExample.c DumbExample.c ./unity/src/unity.c -o TestDumbExample
./TestDumbExample

or slightly differently on Windows:

gcc TestDumbExample.c DumbExample.c unity/src/unity.c -o TestDumbExample.exe
TestDumbExample

Either way, your command prompt should output something like this:

testUnit1.c:21:test_AverageThreeBytes_should_AverageMidRangeValues:PASS
testUnit1.c:22:test_AverageThreeBytes_should_AverageHighValues:PASS
-----------------------
2 Tests 0 Failures 0 Ignored
OK

SO that seemed to work. Of course, it's going to be very tedious to do all of this manually. We don't live in the stone age, here. We have tools! So, your next step is to determine what tools you want to use. You can use the Decide-O-Tron to help figure that out, or just follow the links below: