Testing

Testing in OpenEngine is implemented on top of the  boost testing framework and linked in with our  build system with CTest. We highly recommend using tests as a means of development and as a source of documentation.

Creating Tests

Imagine we have an OpenEngine extension called MyExtension that we wish to test. Our extension contains a single utility class placed in extensions/MyExtension/Utils/MyUtil.h.

First we create a directory to hold all of our tests as extensions/MyExtension/tests and within this directory we create our test file: extensions/MyExtension/tests/testMyUtil.cpp This file will contain the following stub code:

// Include the OpenEngine testing utilities.
#include <Testing/Testing.h>

// Include the stuff we wish to test.
#include <Utils/MyUtil.h>

// Create the test method.
int test_main(int argc, char* argv[]) {

    // ... your testing goes here ... ala:
    MyUtil util;
    OE_CHECK(util.x == util.y);    

    return 0;
}

The full list of available testing macros is:

OE_CHECK(exp)            // Signal error if 'exp' evaluates to a non-zero value
OE_REQUIRE(exp)          // Abort if 'exp' evaluates to a non-zero value
OE_ERROR(msg)            // Signal error 'msg'
OE_FAIL(msg)             // Abort with error 'msg'
OE_CHECK_THROW(exp, exc) // Signal error if 'exp' does not throw an exception of type 'exc'

Now we have a test and need to add it to the system. First we need to tell the system about the tests folder. Add the following line to extensions/MyExtension/CMakeLists.txt:

SUBDIRS(tests)

Now in the tests directory we add a test to the file extensions/MyExtension/tests/CMakeLists.txt:

# Create an executable out of the test file
ADD_EXECUTABLE(testMyUtil testMyUtil.cpp)
# Link the test to our extension library
TARGET_LINK_LIBRARIES(testMyUtil Extensions_MyExtension)
# Add the executable as a test
ADD_TEST(MyUtil testMyUtil)

After adding the above and running a full ./make.py rebuild your tests should show up in the test targets.

Running from the Shell

The test targets are integrated with our build system. The targets are:

• test: runs all tests.
• testv: verbosely run all tests, providing detailed error messages.

Thus, running the tests would look like:

./make.py
./make.py test

(Note that the test target does not build changes)

Emacs

If you are using Emacs and have loaded the conf/emacs/openengine.el file you can run the tests in verbose mode with C-c C-t . After that you may use the usual next-error command to browse errors.

Visual studio

This is outdated info. If you are a VS user please feel free to correct it.

If you are using visual studio you may right click on one of the three test targets and select build.

Documentation via. Testing

Testing can be very useful during development, but also as a source of usage examples for users of your code. To help make users aware of this resource please consider writing your tests with descriptive comments and linking to the test file in your class documentation. In doxygen this can be done as follows.

/**
 * Utility to do useful things.
 * For examples of usage please look at the testing file:
 * testMyUtil.cpp
 *
 * @see testMyUtil.cpp
 */
class MyUtil {
    // ... class header info ...
};

With this information as useful link should appear in the generated documentation, allowing users to view the testing file.