Testing within the GPSTk

As an open source project, the source of the GPSTk is subject to intermittent updates, contributions, and corrections. The GPSTk library testing process has been redesigned to build confidence in the functionality of the library. Testing within the GPSTk library is designed with three distinct goals in mind:

• Testing is repeatable with a low amount of effort.
• Testing is distributed along with the library to support both internal regression testing and to assure outside users and contributors of the quality of the library.
• Testing is designed to accommodate easy additions to the existing test suite.

1 Building and Running the GPSTk Test Suite

For installation of the GPSTk test suite, a computer running a Linux operating system is required along with a current GPSTk installation. GPSTk testing implements three more tools to assist in testing.

• CppUnit - A C++ unit testing framework which is used as the backbone for GPSTk unit testing. CppUnit is free, open source, and can be downloaded from http://sourceforge.net/projects/cppunit.

• gcov - A GNU code coverage tool for the GCC (GNU Compiler Collection). This tool should come standard with most versions of GCC.

• Perl scripts - Perl is an open source, cross platform programming language licensed under the GNU General Public License. Perl is supported on Unix systems, Macintosh, Windows and many more. For more information on Perl please visit http://www.perl.org. A Perl interpreter is common on most platforms.

1.1 Testing Procedure

After the previous tools have been installed and/or are ready to be utilized, the GPSTk test suite is ready to be built. In order to build the GPSTk test suite, please do the following:

1. Enter the main tests folder gpstk/dev/tests
2. Set environmental variables by executing
   
   source SetVariables
   
   
3. Run the entire test suite by executing
   
   $ ./TotalTest.pl
   
   
4. To view test results open
   
   TestResults.log
   
   
5. To view coverage results open
   
   CovResults.log
   
   

The following items are important to note -

• The sourced environmental variables are only available for the current terminal session and are not available after the session is terminated. If you plan to manipulate the tests or jam many times, you should consider adding the following environmental to your .bashrc file to make ``resourcing" unnecessary.
  
  CPPUNIT_LIB=(Path to the CppUnit Libraries)

CPPUNIT_INC=(Path to the CppUnit Includes)

• TotalTest.pl is a Perl script which will clean old compiled tests and coverage data, and then compile, execute, and run coverage analysis on each test within the tests directory. Coverage analysis is available under the CovResults.log. Test results are available under TestResults.log.
• At this time, there is too much data within the Coverage results. The coverage analysis is there, but please disregard data which gives, for example, 1 line covered or 100% of 2 lines. This bug will be fixed in later iterations.

1.2 Individual Testing without Analysis

If you wish to build and execute a single test without analysis, follow the following steps:

1. Enter the directory of the test you wish to execute
2. Execute
   
   $ jam
   
   
3. Execute
   
   $ ./ClassName.tst
   
   where ClassName is the name of the class you wish to test.
   
   
4. OPTIONAL: To clean folders and remove built files, execute
   
   $ jam clean
   
   within the directory of the test you wish to clean.

1.3 Group Building without Analysis

If you wish to build (but not execute) multiple tests without the use of the TotalTest.pl script, follow the following steps:

1. Within the main tests directory gpstk/dev/tests, execute
   
   $ jam
   
   
2. OPTIONAL: To clean and remove the items that were built, execute
   
   $ jam clean
   
   within the main tests directory gpstk/dev/tests.

1.4 Individual Testing with gcov Analysis

If you wish to build, execute, and analyze a test with gcov, follow the following steps:

1. Enter the directory of the test you wish to build, execute, and analyze
2. Execute
   
   $ jam
   
   
3. Execute
   
   $ ./ClassName.tst
   
   where ClassName is the name of the class you wish to test.
4. Execute
   
   $ gcov ClassName.gcda | grep ClassName.cpp -A 1
   
   where ClassName is the name of the class you are testing and ClassName.cpp is the name of the file you wish to run line coverage analysis on.
   
   
5. OPTIONAL: To clean and remove the items that were built, execute
   
   $ jam clean
   
   within the current directory.

-- EricHagen - 19 Dec 2006