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

[svn_grass at osgeo.org]

Author: wenzeslaus
Date: 2014-06-20 20:24:09 -0700 (Fri, 20 Jun 2014)
New Revision: 60907

Added:
   sandbox/wenzeslaus/gunittest/testing.rst
Log:
gunittest: basic info about current posibilities of testing (mainly description of doctest)

Added: sandbox/wenzeslaus/gunittest/testing.rst
===================================================================
--- sandbox/wenzeslaus/gunittest/testing.rst	                        (rev 0)
+++ sandbox/wenzeslaus/gunittest/testing.rst	2014-06-21 03:24:09 UTC (rev 60907)
@@ -0,0 +1,91 @@
+Introduction
+=============
+
+For the testing we will be using system based on Python `unittest`_ package.
+The system is not finished yet.
+
+For now, the best way is to use just Python unittest package as is.
+Additionally, it is possible to use Python `doctest`_ package
+which is compatible with unittest at certain level.
+Both packages are part of the standard  Python distribution.
+
+The content of this document may become part of submitting files and
+the documentation of testing framework classes and scripts.
+
+
+Testing functions with doctest
+==============================
+
+In Python, the easiest thing to test are functions which performs some computations
+or string manipulations, i.e. they have sum numbers or strings on the input and
+some others on the output.
+
+At the beginning you can use doctest for this purpose. The syntax is as follows::
+
+    def sum_list(list_to_sum):
+        """Here is some documentation in docstring.
+
+        And here is the test::
+
+        >>> sum_list([2, 5, 3])
+        10
+        """
+
+In case of GRASS modules which are Python scripts, you can add something like
+this to your script::
+
+    if __name__ == "__main__":
+        if len(sys.argv) == 2 and sys.argv[1] == '--doctest':
+            import doctest
+            doctest.testmod()
+        else:
+           grass.parser()
+           main()
+
+No output means that everything was successful. Note that you cannot use all
+the ways of running doctest since doctest will fail don the module file due
+to the dot or dots in the file name. Moreover, it is sometimes required that
+the file is accessible through sys.path which is not true for case of GRASS modules.
+
+Do not use use doctest for tests of edge cases, for tests which require
+generate complex data first, etc. In these cases use unittest.
+
+
+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`_.
+
+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.
+
+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
+pylint and pep8 with GRASS-specific settings. Run the tool in GRASS session
+in the source code root directory. A HTML report will be created in
+``pylint_report`` directory.
+
+::
+
+    grass_py_static_check.py
+
+Additionally, if you are invoking your Python code manually using python command,
+e.g. when testing, use parameters::
+
+    python -Qwarn -tt -3 some_module.py
+
+This will warn you about usage of old division semantics for integers
+and about incompatibilities with Python 3 (if you are using Python 2)
+which 2to3 tool cannot fix. Finally, it will issue errors if are using tabs
+for indentation inconsistently (note that you should not use tabs for
+indentation at all).
+
+
+.. _unittest: https://docs.python.org/2/library/unittest.html
+.. _doctest: https://docs.python.org/2/library/doctest.html
+.. _Coverity Scan: https://scan.coverity.com/
+.. _1038: https://scan.coverity.com/projects/1038