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

[svn_grass at osgeo.org]

Author: wenzeslaus
Date: 2014-08-06 15:55:28 -0700 (Wed, 06 Aug 2014)
New Revision: 61558

Modified:
   grass/trunk/lib/python/docs/src/gunittest_testing.rst
Log:
gunittest: remove obsolate notes and add quick links to documentation

Modified: grass/trunk/lib/python/docs/src/gunittest_testing.rst
===================================================================
--- grass/trunk/lib/python/docs/src/gunittest_testing.rst	2014-08-06 21:46:27 UTC (rev 61557)
+++ grass/trunk/lib/python/docs/src/gunittest_testing.rst	2014-08-06 22:55:28 UTC (rev 61558)
@@ -1,21 +1,30 @@
 Testing GRASS GIS source code and modules
 =========================================
 
+If you are already familiar with the basic concepts
+of GRASS testing framework, you might want to skip to one of:
+
+* :ref:`test-module` section
+* :ref:`test-c` section
+* :ref:`test-python` section
+* :ref:`test-doctest` section
+* :class:`~gunittest.case.TestCase` class
+
+
 Introduction
 ------------
 
-For the testing we will be using system based on Python `unittest`_ package.
-The system is not finished yet.
+For the testing in GRASS GIS, we are using a `gunittest` package and
+we usually refer to the system of writing and running tests
+as to a *GRASS testing framework*.
 
-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 framework is based on Python `unittest`_ package with a large number
+of GRASS-specific improvements, extensions and changes. These include
+things such as creation of GRASS-aware HTML test reports,
+or running of test in the way that process terminations potentially
+caused by C library functions does not influence the main testing process.
 
-The content of this document may become part of submitting files and
-the documentation of testing framework classes and scripts.
 
-
 Basic example
 -------------
 
@@ -105,7 +114,7 @@
 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*
+    A *test function* is referred to as *test method*, *individual test*
     or just *test*.
 
 assert function and assert method
@@ -115,18 +124,24 @@
     other or that module run ends with successfully.
 
 test case
+    The test methods testing one particular topic or feature are in one
+    test case class.
+
+    From another point of view, one test case class contains all tests
+    which require the same preparation and cleanup steps. 
     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
+
+    There 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``
+    topic, functionality or unit (similarly to test case).
+    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.
@@ -134,6 +149,9 @@
     The term *test suite* may also refer to ``TestSuite`` class
     which is part of Python `unittest`_ test invocation mechanism
     used by `gunittest` internally.
+    
+    More generally, a *test suite* is a group of test cases or any tests
+    (test methods, test cases and other test suites) in one or more files.
 
 test file
     A *test file* is a Python script executable as a standalone process.
@@ -145,7 +163,12 @@
     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.
+    describing which functionality is tested. The name should not contain
+    dots (except for the ``.py`` suffix).
+    
+    Alternatively, a test file could be called *test script* or
+    *test module* (both in Python and GRASS sense) but note that
+    none of these is used.
 
 test runner and test invoker
     Both *test runner* and *test invoker* refer to classes, functions or
@@ -172,7 +195,14 @@
     or generating random maps. The cleanup step should remove temporary
     region as well as remove all created maps and files.
 
+test report
+    A *test report* is a document or set of documents.
 
+    Note that also *test result* is used also used in similar context
+    because the class responsible for representing or creating the report
+    in Python `unittest`_ package is called ``TestResult``.
+
+
 Testing with gunittest package in general
 -----------------------------------------
 
@@ -236,6 +266,8 @@
 documentation.
 
 
+.. _test-module:
+
 Tests of GRASS modules
 ----------------------
 
@@ -301,16 +333,37 @@
     applicable in some cases but in most cases `in` is exactly the
     operation needed).
 
+.. _test-c:
 
 Tests of C and C++ code
 -----------------------
 
+There are basically two possibilities how to test C and C++ code.
+If you are testing GRASS library code the functions which are part of API
+these functions are exposed through Python ``ctypes`` and thus can be tested
+in Python. See section :ref:`test-python` for reference.
+
+However, more advantageous and more preferable (although sometimes
+more complicated) solution is to write a special program, possibly
+GRASS module (i.e., using ``G_parser``).
+
+
+.. _test-python:
+
 Tests of Python code
 --------------------
 
-Use `gunittest` for this purpose in the same way as `unittest`_ would be used.
+For testing of Python code contained in some package, use
+`gunittest` in the same way as `unittest`_ would be used.
+This basically means that if you will write tests of Python functions
+and C functions exposed to Python
+through ``ctypes`` API, you might want to focus more on `unittest`_
+documentation since you will perhaps need the more standard
+assert functions rather then the GRASS-specific ones.
 
 
+.. _test-doctest:
+
 Testing Python code with doctest
 --------------------------------
 
@@ -434,22 +487,7 @@
     can applied to your tests and the more different circumstances can be tried
     with your tests.
 
-.. 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).
-
-
 Data specific to one test
 -------------------------