ITKv3 Procedure for Adding a Test

Appopriate testing is the most important aspects of writing software.

How to Add a Test in ITK

The general procedure involves the following steps

• Write the test itself
• Add the Test to the Test Driver
• Add the Test to the CMakeLists.txt file
• Run the Test locally
• Submit an Experimental build
• Commit the Test to CVS

Write the test

Naming the file

Unit tests should be named with the name of the class they are testing and the word Test at the end.

For example:

• class itkBMPImageIO will have a test called itkBMPImageIOTest.cxx
• class itkIndex will have a test called itkIndexTest.cxx* itkBMPImageIOTest.cxx

Sometimes it may be necessary to have multiple tests, in which case a number will be added after the "Test" string of the name.

For example:

• itkBMPImageIOTest.cxx
• itkBMPImageIOTest2.cxx
• itkBMPImageIOTest3.cxx

Note that we skip the "1" entry. It is implicitly the first test.

Writing the content

The test file must contain a function that has the EXACT same name as the file (without the extension).

For example, the file itkBMPImageIOTest.cxx must contain a function

    int itkBMPImageIOTest( int argc, char * argv [] )

The function must have a return value, and must be one of the following two options:

• EXIT_FAILURE
• EXIT_SUCCESS

Adding The Test to the Test Driver

What are Test Drivers

ITK uses test drivers in order to manage the very large number of unit test. A test driver aggregates many test in a single executable by registering all of them as functions.

As a general guideline, there is a Test driver per major directory. The test driver is named after the directory that it is testing.

For example, the classes in the directory

   Insight/Code/Algorithms

are tested by files in the directory

   Insight/Testing/Code/Algorithms

and will use a test driver file called

   itkAlgorithmsTests.cxx

Note that in some directories, there are so many classes that multiple test drivers are needed. In such cases they are named numerically as:

• itkAlgorithmsTests.cxx
• itkAlgorithmsTests2.cxx
• itkAlgorithmsTests3.cxx
• itkAlgorithmsTests4.cxx

As a general guideline, a Test driver should not contain more than 50 tests. Note however that, in some cases, the reason for having multiple drivers is not necessarily the large number of tests that they aggregate, but their own code size, which tend to give trouble to some linkers (e.g. Borland).

How to add the tests

Check if there are multiple test drivers in the directory, and if so, select the last one in numerical order. For the example above, a new test should be added in itkAlgorithmsTests4.cxx. Check first if this test driver has less than 50 tests inside. If it has more than that, you may have to create a new Driver (e.g. itkAlgorithmsTests5.cxx in this case).

You can add the test by simply inserting the following line

 REGISTER_TEST(itkBMPImageIOTest);

In order to make life easier for maintainers, it is nice to keep the tests sorted alphabetically, but this is not a software requirement.

Add the Test to the CMakeLists.txt file

The tests should be registered as well in the CMakeLists.txt file of the Testing directory were the test file and its driver are.

Typically this can be done with the following procedure

• Find the variable that contains the list of filenames for tests. (e.g. SET( IOTest_SRCS ... )
  • Add the test filename to this list (itkBMPImageIOTest2.cxx for example).