[master 1/1] Include automatic and manual test documentation.

atodorov installerbot-noreply at redhat.com
Fri May 29 13:46:32 UTC 2015


From: Alexander Todorov <atodorov at redhat.com>

---
 .gitignore                |  1 +
 doc/Makefile              |  4 +++
 doc/index.rst             |  1 +
 doc/inheritance/conf.py   | 11 +++++++
 doc/inheritance/index.rst | 28 ++++++++++++++++
 doc/intro.rst             |  2 ++
 tests/README.rst          | 84 +++++++++++++++++++++++++++++++++++++++++++++++
 7 files changed, 131 insertions(+)
 create mode 100644 doc/inheritance/conf.py
 create mode 100644 doc/inheritance/index.rst
 create mode 100644 tests/README.rst

diff --git a/.gitignore b/.gitignore
index 54c7439..5966691 100644
--- a/.gitignore
+++ b/.gitignore
@@ -6,6 +6,7 @@ doc/blivet.devicelibs.rst
 doc/blivet.formats.rst
 doc/blivet.rst
 doc/modules.rst
+doc/tests*.rst
 doc/_build
 po/*.gmo
 po/*.po
diff --git a/doc/Makefile b/doc/Makefile
index 2fc38ee..2a9e741 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -43,8 +43,12 @@ help:
 
 clean:
 	-rm -rf $(BUILDDIR)/*
+	-rm -f $(addprefix ./, tests.*)
 
 apidoc:
+	-rm -f $(addprefix ./, tests.* modules.rst)
+	$(SPHINXAPIDOC) -o . ../tests/
+	-cp modules.rst tests.modules.rst
 	-rm $(addprefix ./, $(MODULE_NAMES))
 	$(SPHINXAPIDOC) -o . $(SOURCEDIR)
 
diff --git a/doc/index.rst b/doc/index.rst
index 5c32438..d10131b 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -13,6 +13,7 @@ Contents:
 
    intro
    modules
+   tests.modules
 
 Indices and tables
 ==================
diff --git a/doc/inheritance/conf.py b/doc/inheritance/conf.py
new file mode 100644
index 0000000..a35237a
--- /dev/null
+++ b/doc/inheritance/conf.py
@@ -0,0 +1,11 @@
+import os
+import sys
+sys.path.append(os.path.abspath('..'))
+
+from ..conf import *
+
+sys.path.insert(0, os.path.abspath('../..'))
+
+extensions.extend(('sphinx.ext.inheritance_diagram', 'sphinx.ext.graphviz'))
+
+inheritance_graph_attrs = dict(rankdir="LR", size='""')
diff --git a/doc/inheritance/index.rst b/doc/inheritance/index.rst
new file mode 100644
index 0000000..3a5ed45
--- /dev/null
+++ b/doc/inheritance/index.rst
@@ -0,0 +1,28 @@
+Test Suite Inheritance Diagram
+------------------------------
+
+Blivet's test suite relies on the base classes shown below. These classes
+take care of working with fake block or loop devices.
+
+.. inheritance-diagram::
+    tests.imagebackedtestcase
+    tests.loopbackedtestcase
+    tests.storagetestcase
+    tests.devicetree_test.BlivetResetTestCase
+
+Actual test cases inherit either :class:`unittest.TestCase` or one of
+these base classes. Some use cases require more levels of abstraction
+which is shown on the following diagram.
+
+.. inheritance-diagram::
+    tests.devicetree_test
+    tests.formats_test.fs_test
+    tests.formats_test.fslabeling
+
+Note: with :class:`sphinx.ext.inheritance_diagram` it is not possible to
+generate an inheritance diagram of all available classes. The ones shown above
+are considered a bit more important. If you want to see the inheritance diagram
+for other classes add the following markup to this document and rebuild it::
+
+    .. inheritance-diagram::
+        tests.module_name.className
diff --git a/doc/intro.rst b/doc/intro.rst
index 158fe05..2cdafa8 100644
--- a/doc/intro.rst
+++ b/doc/intro.rst
@@ -197,3 +197,5 @@ from which to allocate the partition::
     new_part = b.newPartition(start=2048, end=204802048, parents=[sdb])
 
 All the rest is the same as the previous partitioning example.
+
+.. include:: ../tests/README.rst
diff --git a/tests/README.rst b/tests/README.rst
new file mode 100644
index 0000000..db732e6
--- /dev/null
+++ b/tests/README.rst
@@ -0,0 +1,84 @@
+Testing Blivet
+==============
+
+Note: The test suite documented here is available only from the git repository
+not as part of any installable packages.
+
+In order to execute blivet's test suite from inside the source directory execute
+the command::
+
+    make test
+
+Tests descending from :class:`~.imagebackedtestcase.ImageBackedTestCase` or
+:class:`~.loopbackedtestcase.LoopBackedTestCase` require root access on the
+system and will be skipped if you're running as non-root user.
+Tests descending from :class:`~.imagebackedtestcase.ImageBackedTestCase` will
+also be skipped if the environment variable JENKINS_HOME is not defined. If
+you'd like to execute them use the following commands (as root)::
+
+    # export JENKINS_HOME=`pwd`
+    # make test
+
+To execute the Pylint code analysis tool run::
+
+    make check
+
+Running Pylint doesn't require root privileges.
+
+It is also possible to generate test coverage reports using the Python coverage
+tool. To do that execute::
+
+    make coverage
+
+It is also possible to check all external links in the documentation for
+integrity. To do this::
+
+    cd doc/
+    make linkcheck
+
+Test Suite Architecture
+------------------------
+
+Blivet's test suite relies on several base classes listed below. All test cases
+inherit from them.
+
+- :class:`unittest.TestCase` - the standard unit test class in Python.
+  Used for tests which don't touch disk space;
+
+
+- :class:`~tests.storagetestcase.StorageTestCase` - intended as a base class for
+  higher-level tests. Most of what it does is stub out operations that touch
+  disks. Currently it is only used in
+  :class:`~tests.action_test.DeviceActionTestCase`;
+
+
+- :class:`~tests.loopbackedtestcase.LoopBackedTestCase` and
+  :class:`~tests.imagebackedtestcase.ImageBackedTestCase` - both classes
+  represent actual storage space.
+  :class:`~tests.imagebackedtestcase.ImageBackedTestCase` uses the same stacks
+  as anaconda disk image installations. These mimic normal disks more closely
+  than using loop devices directly. Usually
+  :class:`~tests.loopbackedtestcase.LoopBackedTestCase` is used for stacks of
+  limited depth (eg: md array with two loop members) and
+  :class:`~tests.imagebackedtestcase.ImageBackedTestCase` for stacks of greater
+  or arbitrary depth.
+
+
+In order to get a high level view of how test classes inherit from each other
+you can generate an inheritance diagram::
+
+    PYTHONPATH=.:tests/ python3-pyreverse -p "Blivet_Tests" -o svg -SkAmy tests/
+
+
+Alternatively you may try::
+
+    cd doc/
+    make clean apidoc
+    sphinx-build -b html -c inheritance/ . _build/html/
+
+
+and view the `_build/html/inheritance/index.html` document.
+
+Note: pyreverse is part of pylint while sphinx.ext.inheritance_diagram is part
+of Sphinx itself. Both should be installed on your system if you're building
+Blivet from source.


-- 
To view this commit on github, visit https://github.com/rhinstaller/blivet/commit/7a4114048508f7016f2138cd9fdd8d53a1014d24


More information about the anaconda-patches mailing list