Unit Test Quickstart
Simple recipes and tips for writing unit tests in the Gramps source code tree.
First, some general procedural and structural notes
- unit tests are usually created to verify correct functional behavior of a single module of source code.
- test code goes in a test subdirectory of the subject module's directory
- the test module should be named with a suffix _test so that it can be found by automatic regression test tools.
- the leading part of the test will commonly be named the same as the basename (or a variant) of the module under test, leading, for example, to the following files
- the test subdirectory can contain data or helper programs as required
- the test and such supplementary elements that are persistent will be maintained as part of the source control system.
- the test module can create and delete test data during execution. Commonly this would go in a deeper subdir, named to avoid collision with other test programs.
Please update or expand this section.
Simple Code Recipe
There are only a few firm requirements to fit into the framework. Here is a simple test module that may be considered something of a template.
import unittest # import this test support utility before importing the module under test from test import test_util # test is a Gramps module test_util.path_append_parent() # enables the following import import MyModule # use your module name # look in gramps/src/test/test_util.py for other conveniences (and suggest more ideas) this_dir = test_util.abspath() data_dir = test_util.make_subdir("MyModule_test_data") # unittest requires a TestCase class containing test function members # optional setUp() and tearDown() functions can perform pre/post test housekeeping class Test_top(unittest.TestCase): def setUp(self): ... def tearDown(self): ... def test_function_x(self): ..do stuff.. self.assertTrue(expression, "message to display on failure") #see other assert and fail functions in the unittest module ..more defs for more tests, more classes for possible grouping logic.. if __name__ == "__main__": unittest.main()
Using Your Unit Test
- create a module_test.py if and whenever it seems like it might be useful
- create a test subdir if one is not already there
- one practice might be as follows
cd ...gramps/src export PYTHONPATH=`pwd` cd A/B/test gvim +ba ../module.py module_test.py
- do some editing
- do some testing as follows (optional -v shows extra progress messages)
python module_test.py -v
- until happy
- check-in your module code and test code
- other pages needed
- related topics
- references, tutorials, etc
Perhaps: Just add questions and suggestions to this wiki page!