3 files changed, 91 insertions, 0 deletions
diff --git a/doc/source/f2py/code/add-test.f b/doc/source/f2py/code/add-test.f
new file mode 100644
index 000000000..1d52e47bb
--- /dev/null
+++ b/doc/source/f2py/code/add-test.f
@@ -0,0 +1,10 @@
+        subroutine addb(k)
+          real(8), intent(inout) :: k(:)
+          k=k+1
+        endsubroutine
+
+        subroutine addc(w,k)
+          real(8), intent(in) :: w(:)
+          real(8), intent(out) :: k(size(w))
+          k=w+1
+        endsubroutine
+\ No newline at end of file
diff --git a/doc/source/f2py/f2py-reference.rst b/doc/source/f2py/f2py-reference.rst
index 28db0bfee..70912bdad 100644
--- a/doc/source/f2py/f2py-reference.rst
+++ b/doc/source/f2py/f2py-reference.rst
@@ -10,3 +10,4 @@ F2PY reference manual
    python-usage
    buildtools/index
    advanced
+   f2py-testing
diff --git a/doc/source/f2py/f2py-testing.rst b/doc/source/f2py/f2py-testing.rst
new file mode 100644
index 000000000..88fc26ce1
--- /dev/null
+++ b/doc/source/f2py/f2py-testing.rst
@@ -0,0 +1,80 @@
+.. _f2py-testing:
+
+===============
+F2PY test suite
+===============
+
+F2PY's test suite is present in the directory ``numpy/f2py/tests``. Its aim
+is to ensure that Fortran language features are correctly translated to Python.
+For example, the user can specify starting and ending indices of arrays in
+Fortran. This behaviour is translated to the generated CPython library where
+the arrays strictly start from 0 index.
+
+The directory of the test suite looks like the following::
+
+	./tests/
+	├── __init__.py
+	├── src
+	│   ├── abstract_interface
+	│   ├── array_from_pyobj
+	│   ├── // ... several test folders
+	│   └── string
+	├── test_abstract_interface.py
+	├── test_array_from_pyobj.py
+	├── // ... several test files
+	├── test_symbolic.py
+	└── util.py
+
+Files starting with ``test_`` contain tests for various aspects of f2py from parsing
+Fortran files to checking modules' documentation. ``src`` directory contains the
+Fortran source files upon which we do the testing. ``util.py`` contains utility 
+functions for building and importing Fortran modules during test time using a 
+temporary location.
+
+Adding a test
+==============
+
+F2PY's current test suite predates ``pytest`` and therefore does not use fixtures.
+Instead, the test files contain test classes that inherit from ``F2PyTest``
+class present in ``util.py``.
+
+.. literalinclude:: ../../../numpy/f2py/tests/util.py
+   :language: python
+   :lines:  327-336
+   :linenos:
+
+This class many helper functions for parsing and compiling test source files. Its child 
+classes can override its ``sources`` data member to provide their own source files.
+This superclass will then compile the added source files upon object creation andtheir
+functions will be appended to ``self.module`` data member. Thus, the child classes will
+be able to access the fortran functions specified in source file by calling
+``self.module.[fortran_function_name]``.
+
+Example
+~~~~~~~
+
+Consider the following subroutines, contained in a file named :file:`add-test.f`
+
+.. literalinclude:: ./code/add-test.f
+   :language: fortran
+
+The first routine `addb` simply takes an array and increases its elements by 1.
+The second subroutine `addc` assigns a new array `k` with elements greater that 
+the elements of the input array `w` by 1.
+
+A test can be implemented as follows::
+
+	class TestAdd(util.F2PyTest):
+	    sources = [util.getpath("add-test.f")]
+
+	    def test_module(self):
+	        k = np.array([1, 2, 3], dtype=np.float64)
+	        w = np.array([1, 2, 3], dtype=np.float64)
+	        self.module.subb(k)
+	        assert np.allclose(k, w + 1)
+	        self.module.subc([w, k])
+	        assert np.allclose(k, w + 1)
+
+We override the ``sources`` data member to provide the source file. The source files
+are compiled and subroutines are attached to module data member when the class object
+is created. The ``test_module`` function calls the subroutines and tests their results.
+\ No newline at end of file