Unit Testing Tutorial - Revision history

243 user2: /* Source and Extra References */

2017-02-21T03:56:04Z

‎Source and Extra References

243 user2 at 03:54, 21 February 2017

2017-02-21T03:54:13Z

243 user2 at 03:45, 21 February 2017

2017-02-21T03:45:04Z

Show changes

243 user2: Created page with "==== Introduction ==== If you're reading this now then I am assuming you have the Embedded ARM Development Package downloaded and unzipped. There is a UNIT_TESTING_README.txt..."

2017-02-21T02:43:37Z

Created page with "==== Introduction ==== If you're reading this now then I am assuming you have the Embedded ARM Development Package downloaded and unzipped. There is a UNIT_TESTING_README.txt..."

New page

==== Introduction ====
If you're reading this now then I am assuming you have the Embedded ARM Development Package downloaded and unzipped. There is a UNIT_TESTING_README.txt file located in the parent directory with instructions on how to set up your environment to start unit testing the SJSU project with CGreen unit testing framework.

==== What is Unit Testing exactly? ====
Unit testing is a level of software testing where individual components or modules are tested. The purpose of unit testing is to validate that your code performs as you designed it. With the use of unit testing frameworks, stubs, and mock objects, code can be manipulated and tested without ever having to load compiled code onto a MCU.

==== Benefits of Unit Testing ====
* Increase confidence in code
* Results in modular code. Modular code is more reusable.
* Saves potential time that could be wasted debugging on a live system.
* Finds bugs before they get loaded onto a live system.
* Increases reliability of code.
* Instant visual feedback of passed/failed tests
* Regression testing - changing code either results in confidence that nothing broke or confidence that something broke and you should fix it.

==== Getting Started ====
Let's first setup our main function in '''''test_main.cpp''''', which will be our foundation for future unit tests in the project :

<syntaxhighlight lang="c">
// test_main.cpp

#include <cgreen/cgreen.h>
#include <cgreen/mocks.h>
using namespace cgreen;

int main(int argc, char **argv)
{
TestSuite *suite = create_test_suite();
add_suite(suite, c_list_suite());

return run_test_suite(suite, create_text_reporter());
}
// create_test_suite(); only needs to be done once.
// Add your own "suite" of tests by calling add_suite() and providing a pointer to your suite.
// In this case, c_list_suite() is created
</syntaxhighlight>

Now, in the '''''test_c_list.c''''' file, let's create the suite that we added to main() above.

<syntaxhighlight lang="c">
// test_c_list.c

#include <cgreen/cgreen.h>
#include <cgreen/mocks.h>

// The file under test
#include "c_list.h"

TestSuite *c_list_suite()
{
TestSuite *suite = create_test_suite();
add_test(suite, add_element_to_end); // Sub-test, which we will add after.
return suite;
}
</syntaxhighlight>

==== A Simple Test ====
Continuing on from our '''''test_c_list.c''''' file, let's perform one very basic test to verify the functionality of our C-code. We'll start by creating an Ensure() function. This is nothing more than a sub-routine test apart of the entire test suite we created. Typically, you will have an Ensure test function to test one specific functionality of your code. In this example, we only want to test the ability to add one element to the end of our linked list of c_list. The input argument to Ensure is simply a description of the test you're performing. Let's start this example by creating a pointer list.

<syntaxhighlight lang="c">
Ensure(add_element_to_end)
{
c_list_ptr list = c_list_create();
assert_that(c_list_node_count(list), is_equal_to(1));
}
</syntaxhighlight>

Compile the program by calling '''make''', which defaults to '''make all'''. To execute the program, simply perform '''./test_all.exe'''

<syntaxhighlight lang="c">
$ ./test_all.exe
Running "main" (2 tests)...
Completed "foo_suite": 1 pass in 11ms.
code/test_c_list.c:15: Failure: c_list_suite -> add_element_to_end
Expected [c_list_node_count(list)] to [equal] [1]
actual value: [0]
expected value: [1]

Completed "c_list_suite": 1 pass, 1 failure in 9ms.
Completed "main": 1 pass, 1 failure in 20ms.
</syntaxhighlight>

Oops. Looks like we got a unit test failure because we inserted a test assert that failed. The following line '''assert_that(c_list_node_count(list), is_equal_to(1));''' tests that the c_list ''list'' has a node list count of 1, but this failed because we didn't add any items into the ''c_list'', thus, this did not match our expectation of having a node list of 1. Let's go ahead and add that now and see if the test passes.

<syntaxhighlight lang="c">
Ensure(add_element_to_end)
{
c_list_ptr list = c_list_create();
c_list_insert_elm_end(list, (void*) 1);
assert_that(c_list_node_count(list), is_equal_to(1));
}
</syntaxhighlight>

Compiling and running gives:

<syntaxhighlight lang="c">
$ ./test_all.exe
Running "main" (2 tests)...
Completed "foo_suite": 1 pass in 14ms.
Completed "c_list_suite": 2 passes in 21ms.
Completed "main": 2 passes in 35ms.
</syntaxhighlight>

The output shows that by adding an element into the list returned a '''c_list_node_count''' of 1. We were able to test this by inserting a constraint on the unit test, which ultimately fails if the given inputs are not successful when ran. Here is a list of constraints you can use in your unit tests:

{| class="wikitable"
|-
! scope="col"| Constraint
! scope="col"| Passes if actual value/expression…
|-
| is_true
| evaluates to true
|-
| is_false
| evaluates to false
|-
| is_null
| equals null
|-
| is_non_null
| is a non null value
|-
| is_equal_to(value)
| '== value'
|-
| is_not_equal_to(value)
| '!= value'
|-
| is_greater_than(value)
| '> value'
|-
| is_less_than(value)
| '< value'
|-
| is_equal_to_contents_of(pointer, size)
| matches the data pointed to by pointer to a size of size bytes
|-
|}

@@ Line 350: / Line 350: @@
 Please, take a look inside '''''test_main.cpp''''' and you will find a #define where there are many examples of how you can test your code.
-==== Source and Extra References ====
+==== Sources and Extra References ====
 * https://cgreen-devs.github.io
 * http://cgreen.sourceforge.net/
 * https://github.com/cgreen-devs/cgreen

@@ Line 1: / Line 1: @@
 ==== Introduction ====
-If you're reading this now then I am assuming you have the Embedded ARM Development Package downloaded and unzipped. There is a UNIT_TESTING_README.txt file located in the parent directory with instructions on how to set up your environment to start unit testing the SJSU project with CGreen unit testing framework.
+This tutorial contains a few examples and a walk-through of how to start unit testing the SJSU project, which utilizes the CGreen unit testing framework.  I am assuming you have the Embedded ARM Development Package downloaded and unzipped. There is a UNIT_TESTING_README.txt file located in the parent directory with instructions on how to set up your environment to start unit testing the SJSU project with CGreen unit testing framework.
 ==== What is Unit Testing exactly? ====
-Unit testing is a level of software testing where individual components or modules are tested. The purpose of unit testing is to validate that your code performs as you designed it. With the use of unit testing frameworks, stubs, and mock objects, code can be manipulated and tested without ever having to load compiled code onto a MCU.
+Unit testing is a level of software testing where individual components or modules are tested. The purpose of unit testing is to validate that your code performs as you designed it. With the use of unit testing frameworks, stubs, and mock objects, code can be manipulated and tested without ever having to load compiled code onto a MCU. This statement is by no means saying that you shouldn't system test your code, but rather a statement of the power of using unit tests in your development life-cycle.
 ==== Benefits of Unit Testing ====
@@ Line 13: / Line 13: @@
 * Instant visual feedback of passed/failed tests
 * Regression testing - changing code either results in confidence that nothing broke or confidence that something broke and you should fix it.
 ==== Getting Started ====
@@ Line 287: / Line 290: @@
 </syntaxhighlight>
-Let's pause to take a break and go over what a mock  is:
+Let's pause to take a break and go over what a mock is:
 * Mock - a mock is a programmable object. In C objects are limited to function, and in C++ mocks are basically classes. The macro mock() compares the incoming parameters with any expected values and dispatches messages to the test suite if there is a mismatch. It also returns any values that have been preprogrammed in the test.
@@ Line 345: / Line 348: @@
 As expected our test failed because the assertion result did not match because the return value was changed.
 This example demonstrates the fact that you can manipulate any external libraries or code that your source code depends on and you can test that it performs the way you expect it should.