Merge branch 'documentation'.

Author: RKrahl

CHANGES

@@ -5,6 +5,8 @@
 
 ** New features
 
+ + Issue #2: Add documentation.
+
  + Issue #4: Add a depend() function to add a dependency to a test at
    runtime.
 

MANIFEST.in

@@ -2,6 +2,7 @@ include CHANGES
 include LICENSE.txt
 include MANIFEST.in
 include README.rst
+include doc/examples/*.py
 include doc/html/*.html
 include doc/html/*.js
 include doc/html/_static/*

README.rst

@@ -54,6 +54,19 @@ It removes the use of certain language features (dict comprehensions)
 that were introduced in Python 2.7.
 
 
+Documentation
+-------------
+
+The directory doc/html in the source distribution contains the
+documentation in HTML form generated by Sphinx.  The starting point is
+doc/html/index.html.  The documentation can also be found online at
+
+    http://pythonhosted.org/pytest-dependency/
+
+The example test modules used in the documentation can be found in
+doc/examples in the source distribution.
+
+
 Bugs and limitations
 --------------------
 

doc/examples/basic.py

@@ -0,0 +1,22 @@
+import pytest
+
+@pytest.mark.dependency()
+@pytest.mark.xfail(reason="deliberate fail")
+def test_a():
+    assert False
+
+@pytest.mark.dependency()
+def test_b():
+    pass
+
+@pytest.mark.dependency(depends=["test_a"])
+def test_c():
+    pass
+
+@pytest.mark.dependency(depends=["test_b"])
+def test_d():
+    pass
+
+@pytest.mark.dependency(depends=["test_b", "test_c"])
+def test_e():
+    pass

doc/examples/named.py

@@ -0,0 +1,22 @@
+import pytest
+
+@pytest.mark.dependency(name="a")
+@pytest.mark.xfail(reason="deliberate fail")
+def test_a():
+    assert False
+
+@pytest.mark.dependency(name="b")
+def test_b():
+    pass
+
+@pytest.mark.dependency(name="c", depends=["a"])
+def test_c():
+    pass
+
+@pytest.mark.dependency(name="d", depends=["b"])
+def test_d():
+    pass
+
+@pytest.mark.dependency(name="e", depends=["b", "c"])
+def test_e():
+    pass

doc/examples/parametrized.py

@@ -0,0 +1,29 @@
+import pytest
+
+@pytest.mark.parametrize("x,y", [
+    pytest.mark.dependency(name="a1")((0,0)),
+    pytest.mark.dependency(name="a2")(pytest.mark.xfail((0,1))),
+    pytest.mark.dependency(name="a3")((1,0)),
+    pytest.mark.dependency(name="a4")((1,1))
+])
+def test_a(x,y):
+    assert y <= x
+
+@pytest.mark.parametrize("u,v", [
+    pytest.mark.dependency(name="b1", depends=["a1", "a2"])((1,2)),
+    pytest.mark.dependency(name="b2", depends=["a1", "a3"])((1,3)),
+    pytest.mark.dependency(name="b3", depends=["a1", "a4"])((1,4)),
+    pytest.mark.dependency(name="b4", depends=["a2", "a3"])((2,3)),
+    pytest.mark.dependency(name="b5", depends=["a2", "a4"])((2,4)),
+    pytest.mark.dependency(name="b6", depends=["a3", "a4"])((3,4))
+])
+def test_b(u,v):
+    pass
+
+@pytest.mark.parametrize("w", [
+    pytest.mark.dependency(name="c1", depends=["b1", "b2", "b6"])(1),
+    pytest.mark.dependency(name="c2", depends=["b2", "b3", "b6"])(2),
+    pytest.mark.dependency(name="c3", depends=["b2", "b4", "b6"])(3)
+])
+def test_c(w):
+    pass

doc/examples/runtime.py

@@ -0,0 +1,21 @@
+import pytest
+from pytest_dependency import depends
+
+@pytest.mark.dependency()
+def test_a():
+    pass
+
+@pytest.mark.dependency()
+@pytest.mark.xfail(reason="deliberate fail")
+def test_b():
+    assert False
+
+@pytest.mark.dependency()
+def test_c(request):
+    depends(request, ["test_b"])
+    pass
+
+@pytest.mark.dependency()
+def test_d(request):
+    depends(request, ["test_a", "test_c"])
+    pass

doc/src/about.rst

@@ -0,0 +1,89 @@
+About pytest-dependency
+=======================
+
+This module is a plugin for the popular Python testing framework
+`pytest`_.  It manages dependencies of tests: you may mark some tests
+as dependent from other tests.  These tests will then be skipped if
+any of the dependencies did fail or has been skipped.
+
+
+What is the purpose?
+--------------------
+
+In the theory of good test design, tests should be self-contained and
+independent.  Each test should cover one single issue, either verify
+that one single feature is working or that one single bug is fixed.
+Tests should be designed to work in any order independent of each
+other.
+
+So far the theory.  The practice is often more complicated then that.
+Sometimes, the principle of independency of tests is simply
+unrealistic or impractical.  Program features often depend on each
+other.  If some feature B depends on another feature A in such a way
+that B cannot work without A, then it may simply be pointless to run
+the test for B unless the test for A has succeeded.  Another case may
+be if the subject of the tests has an internal state that unavoidably
+is influenced by the tests.  In this situation it may happen that test
+A, as a side effect, sets the system in some state that is the
+precondition to be able to run test B.  Again, in this case it would
+be pointless to try running test B unless test A has been run
+successful.
+
+It should be emphasized however that the principle of independency of
+tests is still valid.  Before using pytest-dependency, it is still
+advisable to reconsider your test design and to avoid dependencies of
+tests whenever possible, rather then to manage these dependencies.
+
+
+How does it work?
+-----------------
+
+The pytest-dependency module defines a marker that can be applied to
+tests.  The marker accepts an argument that allows to list the
+dependencies of the test.  Both tests, the dependency and the
+dependent test should be decorated with the marker.  Behind the
+scenes, the marker arranges for the result of the test to be recorded
+internally.  If a list of dependencies has been given as argument, the
+marker verifies that a successful outcome of all the dependencies has
+been registered previously and causes a skip of the test if this was
+not the case.
+
+
+Why is this useful?
+-------------------
+
+The benefit of skipping dependent tests is the same as for skipping
+tests in general: it avoids cluttering the test report with useless
+and misleading failure reports from tests that have been known
+beforehand not to work in this particular case.
+
+If tests depend on each other in such a way that test B cannot work
+unless test A has been run successfully, a failure of test A will
+likely result in failure messages from both tests.  But the failure
+message from test B will not be helpful in any way.  It will only
+distract the user from the real issue that is the failure of test A.
+Skipping test B in this case will help the user to concentrate on
+those results that really matter.
+
+
+Copyright and License
+---------------------
+
+- Copyright 2013-2015
+  Helmholtz-Zentrum Berlin für Materialien und Energie GmbH
+- Copyright 2016-2017 Rolf Krahl
+
+Licensed under the Apache License, Version 2.0 (the "License"); you
+may not use this file except in compliance with the License.  You may
+obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+implied.  See the License for the specific language governing
+permissions and limitations under the License.
+
+
+.. _pytest: http://pytest.org/

doc/src/conf.py

@@ -10,6 +10,12 @@
 # serve to show the default.
 
 import sys, os
+import os.path
+
+# Add the top source directory to the module path.  This file is
+# exec'ed with its directory as cwd.  This is "doc/src" relativ to the
+# top source directory.  So we need to go 2 dirs up.
+sys.path.insert(0,os.path.dirname(os.path.dirname(os.getcwd())))
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
@@ -39,7 +45,7 @@
 
 # General information about the project.
 project = u'pytest-dependency'
-copyright = u'2016, Rolf Krahl'
+copyright = u'2016-2017, Rolf Krahl'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the

doc/src/index.rst

@@ -5,69 +5,13 @@ This pytest plugin manages dependencies of tests.  It allows to mark
 some tests as dependent from other tests.  These tests will then be
 skipped if any of the dependencies did fail or has been skipped.
 
-Note that there is no real documentation yet, this just repeats the
-content of the README file.
+Content of the documentation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+.. toctree::
+   :maxdepth: 2
 
-System requirements
--------------------
-
-+ Python 2.6, 2.7, or 3.1 and newer.
-  Python 2.6 requires patching the sources, see below.
-+ `setuptools`_.
-+ `pytest`_ 2.8.0 or newer.
-
-
-Installation
-------------
-
-1. Download the sources, unpack, and change into the source directory.
-
-2. Build (optional)::
-
-     $ python setup.py build
-
-3. Test (optional)::
-
-     $ python -m pytest
-
-4. Install::
-
-     $ python setup.py install
-
-The last step might require admin privileges in order to write into
-the site-packages directory of your Python installation.
-
-If you are using Python 2.6, apply python2_6.patch after the first
-step:
-
-1a. Patch::
-
-     $ patch -p1 < python2_6.patch
-
-It removes the use of certain language features (dict comprehensions)
-that were introduced in Python 2.7.
-
-
-Copyright and License
----------------------
-
-- Copyright 2013-2015
-  Helmholtz-Zentrum Berlin für Materialien und Energie GmbH
-- Copyright 2016-2017 Rolf Krahl
-
-Licensed under the Apache License, Version 2.0 (the "License"); you
-may not use this file except in compliance with the License.  You may
-obtain a copy of the License at
-
-    http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
-implied.  See the License for the specific language governing
-permissions and limitations under the License.
-
-
-.. _setuptools: http://pypi.python.org/pypi/setuptools/
-.. _pytest: http://pytest.org/
+   about
+   install
+   usage
+   reference