Add examples on grouping tests using fixtures to advanced usage.

Author: RKrahl

doc/examples/group-fixture.py

@@ -0,0 +1,18 @@
+import pytest
+from pytest_dependency import depends
+
+@pytest.fixture(scope="module", params=range(1,10))
+def testcase(request):
+    param = request.param
+    return param
+
+@pytest.mark.dependency()
+def test_a(testcase):
+    if testcase % 7 == 0:
+        pytest.xfail("deliberate fail")
+        assert False
+
+@pytest.mark.dependency()
+def test_b(request, testcase):
+    depends(request, ["test_a[%d]" % testcase])
+    pass

doc/examples/group-fixture2.py

@@ -0,0 +1,26 @@
+import pytest
+from pytest_dependency import depends
+
+@pytest.fixture(scope="module", params=range(1,10))
+def testcase(request):
+    param = request.param
+    return param
+
+@pytest.fixture(scope="module")
+def dep_testcase(request, testcase):
+    depends(request, ["test_a[%d]" % testcase])
+    return testcase
+
+@pytest.mark.dependency()
+def test_a(testcase):
+    if testcase % 7 == 0:
+        pytest.xfail("deliberate fail")
+        assert False
+
+@pytest.mark.dependency()
+def test_b(dep_testcase):
+    pass
+
+@pytest.mark.dependency()
+def test_c(dep_testcase):
+    pass

doc/src/advanced.rst

@@ -22,3 +22,33 @@ 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.
+
+Grouping tests using fixtures
+-----------------------------
+
+pytest features the `automatic grouping of tests by fixture
+instances`__.  This is particularly useful if there is a set of test
+cases and a series of tests shall be run for each of the test case
+respectively.
+
+Consider the following example:
+
+.. literalinclude:: ../examples/group-fixture.py
+
+The test instances of `test_b` depend on `test_a` for the same
+parameter value.  The test `test_a[7]` deliberately fails, as a
+consequence `test_b[7]` will be skipped.  Note that we need to call
+:func:`pytest_dependency.depends` to mark the dependencies, because
+there is no way to use the :func:`pytest.mark.dependency` marker on
+the parameter values here.
+
+If many tests in the series depend on a single test, it might be an
+option, to move the call to :func:`pytest_dependency.depends` in a
+fixture on its own.  Consider:
+
+.. literalinclude:: ../examples/group-fixture2.py
+
+In this example, both `test_b[7]` and `test_c[7]` are skipped, because
+`test_a[7]` deliberately fails.
+
+.. __: https://docs.pytest.org/en/latest/fixture.html#automatic-grouping-of-tests-by-fixture-instances