Adding Unit Tests to a C/C++ Project
Introduction
NetBeans IDE 6.9 with the C/C++/Fortran plugin supports unit tests in C/C++ projects.
You can use the IDE to create, run, debug, and view results of your C and C++ tests. This article
shows you how to use unit tests in the IDE with your C/C++ projects.
A managed project is created with a logical folder called Test Files, where you can manage unit tests for the project.
You can create tests directly under this Test Files folder or organize them in logical sub folders.
A test node in the Test Files folder is a special folder with test-related actions. When a test is built, it will exclude
the main file from the project and otherwise use all other project settings.
For managed projects that you created with a previous version of the IDE, the Test Files folder
does not exist. The Test Files folder is created for your existing projects when you create a test
with the wizard, as described in this tutorial.
The IDE supports only CUnit, CppUnit and its own "simple" output format, which means your tests should produce
output of one of these types of tests. The IDE provides templates for unit tests:
C simple test
C++ simple test
CUnit test
CppUnit test
CppUnit test runner
This tutorial uses the CUnit test framework and NetBeans C Simple Tests on Ubuntu Linux, but the techniques demonstrated can help
you with the other types of tests on other platforms as well. The tutorial does not explain the CUnit or
CppUnit testing frameworks. You need to consult the documentation for those frameworks for information
about how to use them.
Install the CUnit Testing Framework
To follow this tutorial, you must install CUnit on your system first. You can download
the CUnit framework from the
C Unit Testing Framework project on sourceforge.
The CUnit files page includes
links to binary downloads for Windows and Linux.
For Solaris systems, you must download the CUnit-2.1-0-src.tar.gz source from the CUnit files page
and use the GNU build system
to build the source and install. You can get the GNU build system components autoconf and automake for Solaris
from sunfreeware.com.
The CUnit documentation is included in the CUnit download, or you can view it at
http://cunit.sourceforge.net/doc/index.html.
Create the Project for the Tutorial
To explore the unit test features, you should first create a new C Application:
Choose File > New Project.
In the project wizard, click C/C++ and then select C/C++ Application.
In the New C/C++ Application dialog box, select Create Main file and select the C language.
Accept the defaults for all other options.
Screenshot of New Project dialog
Click Finish, and the Cpp_Application_1 project is created.
In the Projects window, open the Source Files folder and double-click the main.c file to open it in the editor. The file's
content is similar to that shown here:
Screenshot of main.c file before editing
To give the program something to do, replace the code in the main.c file with the following code
to create a simple factorial calculator:
#include <stdio.h>
#include <stdlib.h>
long factorial(int arg) {
long result = 1;
int i;
for (i = 2; i <= arg; ++i) {
result *= i;
}
return result;
}
int main(int argc, char** argv) {
printf("Type an integer and press Enter to calculate the integer's factorial: \n");
int arg;
fflush(stdout);
scanf("%d", &arg);
printf("factorial(%d) = %ld\n", arg, factorial(arg));
return (EXIT_SUCCESS);
}
The file should look as follows after editing:
Screenshot of main.c file after editing
Save the file by pressing Ctrl+S.
Build and run the project to make sure it works by clicking the Run button in the IDE toolbar.
The output should look similar to the following if you enter 8 as the integer:
Screenshot of factorial program output
Add CUnit Tests to the NetBeans Managed Project
When you are developing an application, it is a good idea to add unit tests as part of
your development process.
Each test should contain one main function and generate one executable.
In the Projects window, right-click the main.c source file and select Create Test > New CUnit Test.
Screenshot of creating a new test
A wizard opens to help you create the test.
In the wizard's Select Elements window, click the checkbox for the main function. This causes all
the functions within main to also be selected. In this program, there is only one other function, factorial().
Click Next.
Keep the default name New CUnit Test and click Finish.
The New CUnit Test node is displayed under the Test Files folder.
The New CUnit Test folder contains the template files for the test. You can add
new files to the folder the same way you add source files to a project, by right-clicking the folder.
Expand the New CUnit Test folder, and see that it contains a
file newcunittest.c which should be open in the source editor.
In the newcunittest.c file, notice the #include "CUnit/Basic.h"
statement to access the CUnit library.
The newcunittest.c file contains an automatically generated test function,
testFactorial, for the factorial() function of
main.c.
Screenshot of newcunittest.c includes
The generated test is a stub that you must edit to make useful tests, but the generated
test can be run successfully even without editing.
Run the C Unit Test
The IDE provides a few ways to run tests. You can right-click the project node, or the Test Files folder, or a test subfolder, and select Test.
You can also use the toolbar and select Run > Test Project, or press Alt+F6.
Run the test by right-clicking the New CUnit Test folder and selecting Test. The IDE
opens a new Test Results window, and you should see output similar to the following,
which shows that the test fails:
Screenshot of initial test run
Notice that the Test Results window is split into two panels.
The right panel displays the console output from the tests. The left
panel displays a summary of the passed and failed tests and the
description of failed tests.
In the Test Results window, double-click the node
testFactorial caused an ERROR to jump to the testFactorial function in
the source editor.
If you look at the function you can see that it does not actually test anything, but merely asserts that
the unit test failed by setting CU_ASSERT(0). The condition evaluates to 0, which is equivalent
to FALSE, so the CUnit framework interprets this as a test failure.
Change the line CU_ASSERT(0) to CU_ASSERT(1) and save the file (Ctrl+S).
Run the test again by right-clicking the New CUnit Test folder and selecting Test.
The Test Results window should indicate that the test passed.
Screenshot of test run after changing CU_ASSERT
Add Another CUnit Test
Create a generic CUnit test template by right-clicking the Test Files folder and selecting
New CUnit Test.
Screenshot of adding new cunit test to Test Files
Name the test My CUnit Test and the test file name mycunittest and click Finish.
Screenshot of Create Test wizard
A new test folder called My CUnit Test is created and it contains a mycunittest.c
file, which opens in the editor.
Examine the mycunittest.c test file and see that it contains two tests. test1 will pass because it evaluates
to TRUE, and test2 will fail because it evaluates to FALSE since 2*2 does not equal 5.
void test1()
{
CU_ASSERT(2*2 == 4);
}
void test2()
{
CU_ASSERT(2*2 == 5);
}
Run the test as before and you should see:
Screenshot of pass and fail tests
Run all the tests from the IDE main menu by selecting Run > Test Project (Cpp_Application_1) and see
that both test suites run and display their success and failure in the Test Results window.
Mouse over the failed test to see more information about the failure.
Screenshot of annotation for failed test
Click the filter button Test filter button in the left margin of the Test Results window to show only the failed tests.
Debug My CUNit Test
You can debug tests using the same techniques you use to debug your project source
files, as described in the
Debugging C/C++ Projects Tutorial.
In the Projects window, right-click the My CUNit Test folder and select
Step Into Test.
You can also run the debugger by right-clicking a test in the Test Results window and selecting Debug.
The debugger toolbar is displayed.
Click the Step Into button
to execute the program one statement at a time with each click of the button.
Screenshot of debug stepinto icon
Open the Call Stack window by selecting Window > Debugging > Call Stack so you can
watch the function calls as you step through the test.
Add a Simple Test
The C simple test uses the IDE's own simple test framework. You do not need to download any test framework
to use simple tests.
In the Projects window, right-click the main.c source file and select Create Test > New C Simple Test.
Screenshot of New Simple Test creation
In the wizard's Select Elements window, click the checkbox for the main function, then click Next.
Screenshot of Select Elements window of test wizard
In the Name and Location window, keep the default name New C Simple Test and click Finish.
The New C Simple Test node is displayed under the Test Files folder.
Expand the New C Simple Test folder, and see that it contains a
file newsimpletest.c. This file should be open in the source editor.
Screenshot of New C Simple test folder
Notice the newsimpletest.c file contains an automatically generated test function,
testFactorial, for the factorial() function of
main.c, just as with the CUnit test.
Screenshot of New C Simple test code
The if statement should test a condition that, if true, indicates that the test failed. The
%%TEST_FAILED%%token triggers display of the graphical indicator of test failures in the Test
Results window. The if statement in the generated test sets the condition to be true by setting it to 1,
so the test always fails when you run it unmodified.
The other tokens in the main function, such as %%TEST_STARTED%% and %%TEST_FINISHED%%
are to help you read the command line output when running the tests.
The time=0 option is used to add time measurement to the test.
The message option enables you to make the test print out a message about the test failure.
Run the test to see that it generates a failure shown in the Test Results window.
Next you edit the test file to see tests that pass.
Edit the C Simple Test
Copy and paste a new function below the testFactorial function.
The new function is:
void testNew() {
int arg = 8;
long result = factorial(arg);
if(result != 40320) {
printf("%%TEST_FAILED%% time=0 testname=testNew (newsimpletest) message=Error calculating %d factorial.\n", arg);
}
}
The main function must also be modified to call the new test function.
In the main function, copy the lines:
printf("%%TEST_STARTED%% testFactorial (newsimpletest)\n");
testFactorial();
printf("%%TEST_FINISHED%% time=0 testFactorial (newsimpletest)\n");
Paste the lines immediately below the ones you copied, and change the name testFactorial
to testNew in the pasted lines. There are three occurrences that need to be changed.
The complete newsimpletest.c file should look as follows:
#include <stdio.h>
#include <stdlib.h>
/*
* Simple C Test Suite
*/
long factorial(int arg);
void testFactorial() {
int arg;
long result = factorial(arg);
if(1 /*check result*/) {
printf("%%TEST_FAILED%% time=0 testname=testFactorial (newsimpletest) message=When value is 1 this statement is executed.\n");
}
}
void testNew() {
int arg = 8;
long result = factorial(arg);
if(result != 40320) {
printf("%%TEST_FAILED%% time=0 testname=testNew (newsimpletest) message=Error calculating %d factorial.\n", arg);
}
}
int main(int argc, char** argv) {
printf("%%SUITE_STARTING%% newsimpletest\n");
printf("%%SUITE_STARTED%%\n");
printf("%%TEST_STARTED%% testFactorial (newsimpletest)\n");
testFactorial();
printf("%%TEST_FINISHED%% time=0 testFactorial (newsimpletest)\n");
printf("%%TEST_STARTED%% testNew (newsimpletest)\n");
testNew();
printf("%%TEST_FINISHED%% time=0 testNew (newsimpletest)\n");
printf("%%SUITE_FINISHED%% time=0\n");
return (EXIT_SUCCESS);
}
In the Projects window, run the test by right-clicking New C Simple Test and choosing Test.
The Test Results should look as follows:
Screenshot of simple test results
The %%TEST_FAILED%% token triggers the display of a test failure in the Test Results window.
The if statement should test for a condition that if it is not true, the test fails.
The %%SUITE_STARTING%% and other similar tokens are not shown in the output in the IDE. They are
used for console output.
Run Tests From the Command Line
You can build tests from the command line outside the IDE with make build-tests and run them with make test.
When the project is in ~/NetBeansProjects/Cpp_Application_1 on a Linux system,
the examples in this article would be built and run as shown below.
Open a terminal window or use the Internal Terminal in the IDE
by selecting Window > Output > Internal (Experminental) and clicking the
Create New Terminal Tab icon.
In the terminal, type the commands shown in bold:
cd ~/NetBeansProjects/Cpp_Application_1
make test
The output of the test build and run should look similar to
the following. Note that some make output has been deleted.
"make" -f nbproject/Makefile-Debug.mk QMAKE= SUBPROJECTS= .build-conf
make[1]: Entering directory `/home/tester/NetBeansProjects/CppApplication_1'
"make" -f nbproject/Makefile-Debug.mk dist/Debug/GNU-Linux-x86/cppapplication_1
make[2]: Entering directory `/home/tester/NetBeansProjects/CppApplication_1'
make[2]: `dist/Debug/GNU-Linux-x86/cppapplication_1' is up to date.
...
CUnit - A Unit testing framework for C - Version 2.1-0
http://cunit.sourceforge.net/
Suite: mycunittest
Test: test1 ... passed
Test: test2 ... FAILED
1. tests/mycunittest.c:33 - 2*2 == 5
Test: test3 ... passed
--Run Summary: Type Total Ran Passed Failed
suites 1 1 n/a 0
tests 3 3 2 1
asserts 3 3 2 1
%SUITE_STARTING% newsimpletest
%SUITE_STARTED%
%TEST_STARTED% testFactorial (newsimpletest)
%TEST_FAILED% time=0 testname=testFactorial (newsimpletest) message=error message sample
%TEST_FINISHED% time=0 testFactorial (newsimpletest)
%SUITE_FINISHED% time=0
CUnit - A Unit testing framework for C - Version 2.1-0
http://cunit.sourceforge.net/
Suite: newcunittest
Test: testFactorial ... passed
--Run Summary: Type Total Ran Passed Failed
suites 1 1 n/a 0
tests 1 1 1 0
asserts 1 1 1 0
make[1]: Leaving directory `/home/tester/NetBeansProjects/CppApplication_1'
Adding Support for Other Test Frameworks
You can add support for your favorite C/C++ test framework by creating a NetBeans module.
See the NetBeans developer's
C/C++ Unit Test Plugin Tutorial on the NetBeans wiki.
Send Feedback on This Tutorial
