Unit Testing

EnergyPlus Unit Testing

Unit testing has been added to EnergyPlus with tests located in the tst/EnergyPlus/unit subdirectory. A small set of "starter" tests has been committed to demonstrate some of the key usage.

Googletest (gtest)

We are using Googletest, also known as gtest. It offers a lot of nice capabilities and a low burden on developers to add new tests. Some of the features are:

• New tests are added by just putting the test file in the unit test directory (and adding the file to the CMakeLists.txt if building with CMake -- until we automate that)
• "Death" tests to check that exceptions or assertions should fire with certain inputs
• Tolerant equality checks for floating point values
• Simple setup/teardown support for tests with dependencies
• Filtering so that only certain tests are run (good while trying to correct test failures)
• Nice colored reports

Googletest documentation can be found [here}(https://code.google.com/p/googletest/wiki/Documentation).

Writing Tests

Writing tests is simple:

• Add a file (if it doesn't exist) with a name of the form MyClass.unit.cc or MyFunction.unit.cc
  • Copying an existing file is a quick way to get the boilerplate structure
• Include the necessary headers for the code being tested
• Add using declarations to simplify the names you must type
• Add tests, where each test can include as few or as many checks as you want

Tests may include some application object declarations, operations, and function calls interspersed with some gtest check statements, such as EXPECT_EQ( a, b );, which says that a and b should be equal. If the check fails then the test fails and gtest will report the test and line number where the failure occurred.

Strategy

Some strategies for growing the unit testing coverage of EnergyPlus:

• Tackle the easy code first:
  • Code with fewer dependencies, esp. on global data
  • Simple functions with clearly defined inputs, outputs, and actions
• Add unit tests for any new classes and functions
• Most EnergyPlus classes are just containers at this point so there isn't much to test but as functions are brought into the classes tests should be added
• For code that is too hard to unit test currently at least use assertions to verify pre and post conditions
• As you work on code think about refactoring it to make it unit test friendly