[GRASS-SVN] r61557 - grass/trunk/lib/python/docs/src

[svn_grass at osgeo.org]

Author: wenzeslaus
Date: 2014-08-06 14:46:27 -0700 (Wed, 06 Aug 2014)
New Revision: 61557

Modified:
   grass/trunk/lib/python/docs/src/gunittest_testing.rst
Log:
gunittest: simple example at the beginning and terms

Modified: grass/trunk/lib/python/docs/src/gunittest_testing.rst
===================================================================
--- grass/trunk/lib/python/docs/src/gunittest_testing.rst	2014-08-06 21:45:42 UTC (rev 61556)
+++ grass/trunk/lib/python/docs/src/gunittest_testing.rst	2014-08-06 21:46:27 UTC (rev 61557)
@@ -16,6 +16,163 @@
 the documentation of testing framework classes and scripts.
 
 
+Basic example
+-------------
+
+If you are writing a test of a GRASS module, 
+create a Python script with the content derived from the example bellow.
+When using existing existing maps, suppose you are in North Carolina SPM
+GRASS sample location.
+
+The file can contain one or more test case classes. Each class
+can contain one or more test methods (functions).
+Here we create one test case class with one test method.
+The other two methods are class methods ensuring the right environment
+for all test methods inside a test case class.
+When a test file becomes part of source code (which is the usual case)
+it must be placed into a directory named ``testsuite``.
+
+.. code-block:: python
+
+    from grass.gunittest import TestCase, test
+
+
+    # test case class must be derived from grass.gunittest.TestCase
+    class TestSlopeAspect(TestCase):
+
+        @classmethod
+        def setUpClass(cls):
+            """Ensures expected computational region"""
+            # to not override mapset's region (which might be used by other tests)
+            cls.use_temp_region()
+            # cls.runModule or self.runModule is used for general module calls
+            cls.runModule('g.region', rast='elevation')
+            # note that the region set by default for NC location is the same as
+            # the elevation raster map, this is an example shows what to do
+            # in the general case
+
+        @classmethod
+        def tearDownClass(cls):
+            cls.del_temp_region()
+
+        # test method must start with test_
+        def test_limits(self):
+            """Test that slope and aspect are in expected limits"""
+            # we don't have to delete (g.remove) the maps
+            # but we need to use unique names within one test file
+            slope = 'limits_slope'
+            aspect = 'limits_aspect'
+            # self.assertModule is used to call module which we test
+            # we expect module to finish successfully
+            self.assertModule('r.slope.aspect', elevation='elevation',
+                              slope=slope, aspect=aspect)
+            # function tests if map's min and max are within expected interval
+            self.assertRasterMinMax(map=slope, refmin=0, refmax=90,
+                                    msg="Slope in degrees must be between 0 and 90")
+            self.assertRasterMinMax(map=aspect, refmin=0, refmax=360,
+                                    msg="Aspect in degrees must be between 0 and 360")
+
+
+    if __name__ == '__main__':
+        test()
+
+In the example we have used only two assert methods, one to check that
+module runs and end successfully and the other to test that map values are
+within an expect interval. There is a much larger selection of assert methods
+in :class:`~gunittest.case.TestCase` class documentation
+and also in Python `unittest`_ package documentation.
+
+To run the test, run GRASS GIS, use NC SPM sample location and create
+a separate mapset (name it ``test`` for example). Then go to the directory
+with the test file and run it:
+
+.. code-block:: sh
+
+    python some_test_file.py
+
+The output goes to the terminal in this case. Read further to see
+also more advanced ways of invoking the tests.
+
+We have shown a test of a GRASS module using NC sample location.
+However, tests can be written also for C and Python library and also
+for internal functions in modules. See the rests of this document
+for a complete guide.
+
+
+Building blocks and terminology
+-------------------------------
+
+test function and test method
+    A *test function* is a test of one particular feature or a test of
+    one particular result.
+    A *test function* is referred as *test method*, *individual test*
+    or just *test*.
+
+assert function and assert method
+    An *assert function* (or *assert method*) refers to a function
+    which checks that some predicate is fulfilled. For example,
+    predicate can be that two raster maps does not differ from each
+    other or that module run ends with successfully.
+
+test case
+    In other words, a *test case* class contains all tests which are
+    using the same *test fixture*.
+    
+    The is also a general :class:`~gunittest.case.TestCase` class which
+    all concrete test case classes should inherit from to get all
+    GRASS-specific testing functionality and also to be found
+    by the testing framework.
+
+test suite
+    A *test suite*, or also *testsuite*, is a set of tests focused on one
+    topic, functionality or unit. In GRASS GIS, it is a set of files in
+    one ``testsuite`` directory. The test files in one ``testsuite``
+    directory are expected to test what is in the parent directory
+    of a given ``testsuite`` directory. This is used to organize
+    tests in the source code and also to generate test reports.
+
+    The term *test suite* may also refer to ``TestSuite`` class
+    which is part of Python `unittest`_ test invocation mechanism
+    used by `gunittest` internally.
+
+test file
+    A *test file* is a Python script executable as a standalone process.
+    It does not set up any special environment and runs where it was invoked.
+    The testing framework does not rely on the file to end in a standard
+    way which means that if one file ends with segmentation fault
+    the testing framework can continue in testing of other test files. 
+    Test files are central part `gunittest` system and are also the biggest
+    difference from Python `unittest`_. Test file name should be unique
+    but does not have to contain all parent directory names, for example
+    it can consist from a simplified name of a module plus a word or two
+    describing which functionality is tested.
+
+test runner and test invoker
+    Both *test runner* and *test invoker* refer to classes, functions or
+    scripts used to run (invoke) tests or test files. One of the terms may
+    fade of in the future (probably *invoke* because it is not used by
+    Python `unittest`_).
+
+test fixture (test set up and tear down)
+    The preparation of the test is called *setup* or *set up* and the cleaning
+    after the test is called *teardown* or *tear down*. A *test fixture* refers
+    to these two steps and also to the environment where the test or tests
+    are executed.
+
+    Each test case class can define ``setUp``, ``setUpClass``, ``tearDown``
+    and ``tearDownClass`` methods to implement preparation and cleanup
+    steps for tests it contains. The methods ending with ``Class`` are
+    class methods (in Python terminology) and should be defined using
+    ``@classmethod`` decorator and with ``cls`` as first argument. These
+    methods are executed once for the whole class while the methods
+    without ``Class`` are executed for each test method. 
+
+    In GRASS GIS, the preparation may, but does not have to, contain imports
+    of maps, using temporary region, setting computational region,
+    or generating random maps. The cleanup step should remove temporary
+    region as well as remove all created maps and files.
+
+
 Testing with gunittest package in general
 -----------------------------------------