Adding Unit Tests to a C Project - NetBeans IDE Tutorial

Contents

Content on this page applies to NetBeans IDE 7.1, 7.2 and 7.3
Requirements
Introduction
Install the CUnit Testing Framework
Create the Project for the Tutorial
Add CUnit Tests to the NetBeans Managed Project
Run the CUnit Test
Add Another CUnit Test
Debug a Test
Add a Simple Test
Edit the Simple Test
Run Tests From the Command Line

Requirements

To follow this tutorial, you need the following software.

Software Version Required
NetBeans IDE (including C/C++/Fortran support) version 7.1, 7.2 or 7.3 with NetBeans C/C++ plugin
Java Development Kit (JDK) Version 6 or 7
CUnit 2.1 test framework C Unit Testing Framework project on sourceforge.

See the NetBeans IDE 7.2 Installation Instructions and Configuring the NetBeans IDE for C/C++/Fortran
for information about downloading and installing the required NetBeans software.

Introduction

NetBeans IDE 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:

  1. Choose File > New Project.
  2. In the project wizard, click C/C++ and then select C/C++ Application.
  3. 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
  4. Click Finish, and the Cpp_Application_1 project is created.
  5. 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
  6. 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
  7. Save the file by pressing Ctrl+S.
  8. 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.

  1. 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.

  2. 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().
  3. Click Next.
  4. 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.
  5. Expand the New CUnit Test folder, and see that it contains a file newcunittest.c which should be open in the source editor.
  6. 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.

  1. 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
  2. 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.
  3. 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.
  4. Change the line CU_ASSERT(0) to CU_ASSERT(1) and save the file (Ctrl+S).
  5. 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

  1. 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
  2. Name the test My CUnit Test and the test file name mycunittest and click Finish.
    Screenshot of Create Test wizard
  3. A new test folder called My CUnit Test is created and it contains a mycunittest.c file, which opens in the editor.
  4. 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);
    }    
  5. Run the test as before and you should see:
    Screenshot of pass and fail tests
  6. 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.
  7. Mouse over the failed test to see more information about the failure.
    Screenshot of annotation for failed test
  8. 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.

  1. 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.
  2. 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
  3. 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.

  1. 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
  2. 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
  3. 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.

  4. 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
  5. 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.

  6. 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

  1. 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.

  2. In the main function, copy the lines:
    printf("%%TEST_STARTED%%  testFactorial (newsimpletest)\n");
        testFactorial();
        printf("%%TEST_FINISHED%% time=0 testFactorial (newsimpletest)\n");
        
  3. 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);
    }
    
    
  4. 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.

  1. 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.
  2. 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.


get support for the NetBeans

Support


By use of this website, you agree to the NetBeans Policies and Terms of Use. © 2013, Oracle Corporation and/or its affiliates. Sponsored by Oracle logo