Add a page on advanced usage.

Author: RKrahl

doc/examples/dyn-parametrized.py

@@ -0,0 +1,47 @@
+import pytest
+
+# Test data
+# Consider a bunch of Nodes, some of them are parents and some are children.
+
+class Node(object):
+    NodeMap = {}
+    def __init__(self, name, parent=None):
+        self.name = name
+        self.children = []
+        self.NodeMap[self.name] = self
+        if parent:
+            self.parent = self.NodeMap[parent]
+            self.parent.children.append(self)
+        else:
+            self.parent = None
+    def __str__(self):
+        return self.name
+
+parents = [ Node("a"),  Node("b"),  Node("c"),  Node("d"), ]
+childs =  [ Node("e", "a"), Node("f", "a"), Node("g", "a"), 
+            Node("h", "b"), Node("i", "c"), Node("j", "c"), 
+            Node("k", "d"), Node("l", "d"), Node("m", "d"), ]
+
+# The test for the parent shall depend on the test of all its children.
+# Create enriched parameter lists, decorated with the dependency marker.
+
+childparam = [ 
+    pytest.mark.dependency(name="test_child[%s]" % c)(c) for c in childs
+]
+parentparam = [
+    pytest.mark.dependency(
+        name="test_parent[%s]" % p, 
+        depends=["test_child[%s]" % c for c in p.children]
+    )(p) for p in parents
+]
+
+@pytest.mark.parametrize("c", childparam)
+def test_child(c):
+    if c.name == "l":
+        pytest.xfail("deliberate fail")
+        assert False
+
+@pytest.mark.parametrize("p", parentparam)
+def test_parent(p):
+    pass
+

doc/src/advanced.rst

@@ -0,0 +1,24 @@
+Advanced usage
+==============
+
+This section contains some advanced examples for using
+pytest-dependency.
+
+Dynamic compilation of marked parameters
+----------------------------------------
+
+Sometimes, the parameter values for parametrized tests cannot easily
+be typed as a simple list.  It may need to be compiled at run time
+depending on a set of test data.  This also works together with
+marking dependencies in the individual test instances.
+
+Consider the following example test module:
+
+.. literalinclude:: ../examples/dyn-parametrized.py
+
+In principle, this example works the very same way as the basic
+example for parametrized tests, see :ref:`usage-parametrized`.  The
+only difference is that the lists of paramters are dynamically
+compiled beforehand.  The test for child `l` deliberately fails, just
+to show the effect.  As a consequence, the test for its parent `d`
+will be skipped.

doc/src/index.rst

@@ -14,4 +14,5 @@ Content of the documentation
    about
    install
    usage
+   advanced
    reference

doc/src/usage.rst

@@ -47,6 +47,8 @@ set:
 
 .. literalinclude:: ../examples/named.py
 
+.. _usage-parametrized:
+
 Parametrized tests
 ------------------