[GRASS-SVN] r61021 - sandbox/wenzeslaus/gunittest

[svn_grass at osgeo.org]

Author: wenzeslaus
Date: 2014-06-27 14:44:05 -0700 (Fri, 27 Jun 2014)
New Revision: 61021

Modified:
   sandbox/wenzeslaus/gunittest/testing.rst
Log:
gunittest: basic documentation for testing using gunittest and unittest, mention Cppcheck

Modified: sandbox/wenzeslaus/gunittest/testing.rst
===================================================================
--- sandbox/wenzeslaus/gunittest/testing.rst	2014-06-27 21:18:37 UTC (rev 61020)
+++ sandbox/wenzeslaus/gunittest/testing.rst	2014-06-27 21:44:05 UTC (rev 61021)
@@ -51,17 +51,78 @@
 generate complex data first, etc. In these cases use unittest.
 
 
+Testing functions with gunittest
+================================
+
+GRASS GIS `gunittest` package and testing framework is similar to the standard
+Python ``unittest`` package, so the ways to build tests are very similar.
+
+    ::
+
+    from guinttest.case import GrassTestCase
+
+    class TestRUnivar(GrassTestCase):
+
+        def test_conting(self):
+            """Test that Python can count"""
+            self.assertEqual(1 + 1, 2)
+
+Note that GRASS-specific invoking of tests is not yet implemented
+but you should try different combinations of adding the following Python
+code to your test and running it from command line::
+
+    if __name__ == '__main__':
+        unittest.main()
+
+adding the directory or parent directory of your tests to ``PYTHONPATH``
+and using::
+
+    python -m unittest test_runivar
+
+or using automatic test discovery which might be sometimes tricky::
+
+    python -m unittest discover some/path
+
+You should be in running GRASS session in GRASS NC sample location in a mapset
+of arbitrary name (except for the predefined mapsets).
+
+Your tests can rely on maps which are present in the GRASS NC sample location.
+But if you can provide tests which are independent on location it is better.
+
+Read the documentation of Python ``unittest`` package for a list of assert
+methods which you can use to test your results. For test of more complex
+GRASS-specific results refer to `GrassTestCase` class documentation.
+
+.. note::
+    gunittest is under development but, so some things can change, however
+    this should not stop you from writing tests since the actual differences
+    in your code will be only subtle.
+
+.. note::
+    gunittest is not part of GRASS GIS source code yet, it is available
+    separately. If you don't want to deal with some other code now,
+    just write tests based only on Python ``unittest``. This will limit
+    your possibilities of convenient testing but should not stop you
+    from writing tests, especially if you will write tests of Python functions,
+    and C functions exposed to Python through ctypes API. (Note that it might
+    be a good idea to write tests for library function you rely on in your
+    GRASS module).
+
+
 Analyzing quality of source code
 ================================
 
 Besides testing, you can also use some tools to check the quality of your code.
 
 For C/C++ code use third party solution `Coverity Scan`_ where GRASS GIS
-is registered as project number `1038`_.
+is registered as project number `1038`_. Also you can use `Cppcheck`_
+which will show a lot of errors which compilers do not check.
+In any case, set your compiler to high error and warning levels,
+check them and fix them in your code.
 
 For Python, we recommend pylint and then for style issues pep8 tool
 (and perhaps also pep257 tool). However, there is more tools available
-you can use together with the recommend ones.
+you can use them together with the recommend ones.
 
 To provide a way to evaluate the Python source code in the whole GRASS source
 tree there is a Python script ``grass_py_static_check.py`` which uses
@@ -89,3 +150,4 @@
 .. _doctest: https://docs.python.org/2/library/doctest.html
 .. _Coverity Scan: https://scan.coverity.com/
 .. _1038: https://scan.coverity.com/projects/1038
+.. _Cppcheck:http://cppcheck.sourceforge.net/