CIBC:Documentation:SCIRun:UnitTestingHowTo

Unit Testing instructions

This guide shows the steps for adding unit test source files, building them as executables, and running them to verify/test drive your code. It assumes basic knowledge of SVN and CMake. By convention, all directory paths will be relative to the cibc trunk.

1. Navigate to the source directory of the code you wish to test, e.g. SCIRun/src/Core/Math.
2. If not done already, modify the CMakeLists.txt file in this directory. Add the lines:

   IF(BUILD_TESTING)

     ADD_SUBDIRECTORY(Tests)

   ENDIF(BUILD_TESTING)

3. If not present already, create a new subdirectory called "Tests", in which unit test source files will live.
4. Make a copy of the CMakeLists.txt file present in SCIRun/src/Core/Math/Tests, and put it in your new Tests directory.
5. By convention, the new project name should be <Source_Project>_Tests. Modify the newly copied CMakeLists.txt file to refer to this new test project: change the SET line, the ADD_EXECUTABLE line, and the first parameter of TARGET_LINK_LIBRARIES accordingly.
6. At this point add your desired target link libraries to the TARGET_LINK_LIBRARIES call. Usually they'll be the same link dependencies as the project you're testing, including the project under test itself.
7. By virtue of the link dependency ${SCI_GTESTMAIN_LIBRARY}, your new project will be built as an executable with main() already implemented. This makes it faster to start writing actual test code.
8. Start by adding a new source file in the SET command, typically <SubjectUnderTest>Tests.cc.
9. Now you can run cmake to generate the new project. Make sure to enable the BUILD_TESTING flag.
10. Once your test project is created, you can begin writing tests. It's super easy with GoogleTest. The simplest unit test follows this format:

    #include <gtest/gtest.h>

    TEST(NameOfTestClass, NameOfTestMethod)

    {

      ClassToTest foo;

      EXPECT_EQUAL(1, foo.methodThatShouldReturnOne());

      EXPECT_DOUBLE_EQ(3.14, foo.methodThatShouldReturnRoughPiApproximation());

    }

11. And that's it. The main() gets linked in and all your tests are discovered automatically. Once the test project is built, it can be run on the command line with pretty green/red color highlighting for success/failure of your assertions and tests.
12. Please refer to our initial (and currently only) unit test file at SCIRun/src/Core/Math/Tests/SinCosTableTests.cc for a very simple example, including a test of a constructor precondition.
13. Don't forget to add the test code and new CMakeLists file to svn. We want as much test code as possible checked in! Of course, it won't be shipped with SCIRun, but eventually we'd like to run tests as part of a continuous build.
14. Try to make your test code stand-alone, i.e. don't depend on external files, especially. If you want to write a test that needs to load lots of data (too much to embed in the source file itself), we will have a separate repository for these files. Check back soon. For now, try to test small bits of functionality that don't need that much input; or, hold off on checking in until the separate test data repository is ready to go. For instance, one could test matrix algorithms on small matrices less than 5x5, say.
15. Refer to revision number 45149 for an example "bare-bones" unit test check-in.
16. Coming very soon will be utilities to ease matrix/vector testing, including equality assertions, with plenty of examples to reuse.
17. And for more info on GoogleTest, including different assertion types and test fixtures (to allow data sharing between tests), please refer to http://code.google.com/p/googletest/wiki/V1_6_Documentation.