Merge branch 'scope' into develop

Author: RKrahl

doc/examples/nodeid.out

@@ -0,0 +1,17 @@
+$ pytest --verbose
+============================= test session starts ==============================
+platform linux -- Python 3.8.1, pytest-5.3.4, py-1.8.1, pluggy-0.13.1 -- /usr/bin/python3
+cachedir: .pytest_cache
+rootdir: /home/user
+plugins: dependency-0.4.0
+collected 7 items                                                              
+
+tests/test_nodeid.py::test_a PASSED                                      [ 14%]
+tests/test_nodeid.py::test_b[7-True] PASSED                              [ 28%]
+tests/test_nodeid.py::test_b[0-False] PASSED                             [ 42%]
+tests/test_nodeid.py::test_b[-1-False] XFAIL                             [ 57%]
+tests/test_nodeid.py::TestClass::test_c PASSED                           [ 71%]
+tests/test_nodeid.py::TestClass::test_d[order] PASSED                    [ 85%]
+tests/test_nodeid.py::TestClass::test_d[disorder] PASSED                 [100%]
+
+========================= 6 passed, 1 xfailed in 0.08s =========================

doc/examples/nodeid.py

@@ -0,0 +1,26 @@
+import random
+import pytest
+
+def test_a():
+    pass
+
+@pytest.mark.parametrize("i,b", [
+    (7, True),
+    (0, False),
+    pytest.param(-1, False, marks=pytest.mark.xfail(reason="nonsense"))
+])
+def test_b(i, b):
+    assert bool(i) == b
+
+ordered = list(range(10))
+unordered = random.sample(ordered, k=len(ordered))
+
+class TestClass:
+
+    def test_c(self):
+        pass
+
+    @pytest.mark.parametrize("l,ll", [(ordered, 10), (unordered, 10)],
+                             ids=["order", "disorder"])
+    def test_d(self, l, ll):
+        assert len(l) == ll

doc/examples/scope_class.py

@@ -0,0 +1,32 @@
+import pytest
+
+@pytest.mark.dependency()
+@pytest.mark.xfail(reason="deliberate fail")
+def test_a():
+    assert False
+
+
+class TestClass1(object):
+
+    @pytest.mark.dependency()
+    def test_b(self):
+        pass
+
+
+class TestClass2(object):
+
+    @pytest.mark.dependency()
+    def test_a(self):
+        pass
+
+    @pytest.mark.dependency(depends=["test_a"])
+    def test_c(self):
+        pass
+
+    @pytest.mark.dependency(depends=["test_a"], scope='class')
+    def test_d(self):
+        pass
+
+    @pytest.mark.dependency(depends=["test_b"], scope='class')
+    def test_e(self):
+        pass

doc/examples/scope_module.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"], scope='module')
+def test_c():
+    pass
+
+@pytest.mark.dependency(depends=["test_b"], scope='module')
+def test_d():
+    pass
+
+@pytest.mark.dependency(depends=["test_b", "test_c"], scope='module')
+def test_e():
+    pass

doc/examples/scope_session_mod_01.py

@@ -0,0 +1,23 @@
+# test_mod_01.py
+
+import pytest
+
+@pytest.mark.dependency()
+def test_a():
+    pass
+
+@pytest.mark.dependency()
+@pytest.mark.xfail(reason="deliberate fail")
+def test_b():
+    assert False
+
+@pytest.mark.dependency(depends=["test_a"])
+def test_c():
+    pass
+
+
+class TestClass(object):
+
+    @pytest.mark.dependency()
+    def test_b(self):
+        pass

doc/examples/scope_session_mod_02.py

@@ -0,0 +1,29 @@
+# test_mod_02.py
+
+import pytest
+
+@pytest.mark.dependency()
+@pytest.mark.xfail(reason="deliberate fail")
+def test_a():
+    assert False
+
+@pytest.mark.dependency(
+    depends=["tests/test_mod_01.py::test_a", "tests/test_mod_01.py::test_c"],
+    scope='session'
+)
+def test_e():
+    pass
+
+@pytest.mark.dependency(
+    depends=["tests/test_mod_01.py::test_b", "tests/test_mod_02.py::test_e"],
+    scope='session'
+)
+def test_f():
+    pass
+
+@pytest.mark.dependency(
+    depends=["tests/test_mod_01.py::TestClass::test_b"],
+    scope='session'
+)
+def test_g():
+    pass

doc/src/changelog.rst

@@ -2,6 +2,9 @@ History of changes to pytest-dependency
 =======================================
 
 dev (not yet released)
+    New features
+      + Issue #3, PR #35: add a scope to dependencies.
+
     Bug fixes and minor changes
       + Issue #34: failing test with pytest 4.2.0 and newer.
 

doc/src/index.rst

@@ -14,7 +14,9 @@ Content of the documentation
    about
    install
    usage
+   scope
    advanced
+   names
    configuration
    changelog
    reference

doc/src/names.rst

@@ -0,0 +1,90 @@
+.. _names:
+
+Names
+=====
+
+Dependencies of tests are referenced by name.  The default name is the
+`node id`__ assigned to the test by pytest.  This default may be
+overridden by an explicit `name` argument to the
+:func:`pytest.mark.dependency` marker.  The references also depend on
+the scope.
+
+.. __: https://docs.pytest.org/en/latest/example/markers.html#node-id
+
+Node ids
+--------
+
+The node ids in pytest are built of several components, separated by a
+double colon "::".  For test functions, these components are the
+relative path of the test module and the name of the function.  In the
+case of a method of a test class the components are the module path,
+the name of the class, and the name of the method.  If the function or
+method is parameterized, the parameter values, separated by minus "-",
+in square brackets "[]" are appended to the node id.  The
+representation of the parameter values in the node id may be
+overridden using the `ids` argument to the
+`pytest.mark.parametrize()`__ marker.
+
+.. __: https://docs.pytest.org/en/latest/reference.html#pytest-mark-parametrize-ref
+
+
+One may check the node ids of all tests calling pytest with the
+`--verbose` command line option.  As an example, consider the
+following test module:
+
+.. literalinclude:: ../examples/nodeid.py
+
+If this module is stored as `tests/test_nodeid.py`, the output will
+look like:
+
+.. literalinclude:: ../examples/nodeid.out
+
+.. note::
+    Old versions of pytest used to include an extra "()" component to
+    the node ids of methods of test classes.  This has been
+    `removed in pytest 4.0.0`__.  pytest-dependency strips this
+    if present.  Thus, when referencing dependencies, the new style
+    node ids as described above may (and must) be used, regardless of
+    the pytest version.
+
+.. __: https://docs.pytest.org/en/latest/changelog.html#pytest-4-0-0-2018-11-13
+
+References and scope
+--------------------
+
+When referencing dependencies of tests, the names to be used in the
+`depends` argument to the :func:`pytest.mark.dependency` marker or the
+`other` argument to the :func:`pytest_dependency.depends` function
+depend on the scope as follows:
+
+`session`
+    The full node id must be used.
+`package`
+    The full node id must be used.
+`module`
+    The node id with the leading module path including the "::"
+    separator removed must be used.
+`class`
+    The node id with the module path and the class name including the
+    "::" separator removed must be used.
+
+That is, in the example above, when referencing `test_a` as a
+dependency, it must be referenced as `tests/test_nodeid.py::test_a` in
+session scope and as `test_a` in module scope.  When referencing the
+first invocation of `test_d` as a dependency, it must be referenced as
+`tests/test_nodeid.py::TestClass::test_d[order]` in session scope, as
+`TestClass::test_d[order]` in module scope, and as `test_d[order]` in
+class scope.
+
+If the name of the dependency has been set with an explicit `name`
+argument to the :func:`pytest.mark.dependency` marker, this name must
+always be used as is, regardless of the scope.
+
+.. note::
+    The module path in the node id is the path relative to the current
+    working directory.  This depends on the invocation of pytest.  In
+    the example above, if you change into the `tests` directory before
+    invoking pytest, the module path in the node ids will be
+    `test_nodeid.py`.  If you use references in session scope, you'll
+    need to make sure pytest is always invoked from the same working
+    directory.

doc/src/reference.rst

@@ -1,7 +1,7 @@
 Reference
 =========
 
-.. py:decorator:: pytest.mark.dependency(name=None, depends=[])
+.. py:decorator:: pytest.mark.dependency(name=None, depends=[], scope='module')
 
     Mark a test to be used as a dependency for other tests or to
     depend on other tests.
@@ -11,16 +11,25 @@ Reference
     for the test may be set in the depends argument.
 
     :param name: the name of the test to be used for referencing by
-	dependent tests.  If not set, it defaults to the node ID
-	defined by pytest, that is the name of the test function,
-	extended by the parameters if applicable.  The name must be
-	unique in the scope, which is currently the test module.
+        dependent tests.  If not set, it defaults to the node ID
+        defined by pytest.  The name must be unique.
     :type name: :class:`str`
     :param depends: dependencies, a list of names of tests that this
         test depends on.  The test will be skipped unless all of the
-	dependencies have been run successfully.  The dependencies
-	must also have been decorated by the marker.
+        dependencies have been run successfully.  The dependencies
+        must also have been decorated by the marker.  The names of the
+        dependencies must be adapted to the scope.
     :type depends: iterable of :class:`str`
+    :param scope: the scope to search for the dependencies.  Must be
+        either `'session'`, `'package'`, `'module'`, or `'class'`.
+    :type scope: :class:`str`
+
+    See Section :ref:`names` for details on the default name if the
+    `name` argument is not set and on how references in the `depends`
+    argument must be adapted to the scope.
+
+    .. versionchanged:: 0.5.0
+        the scope parameter has been added.
 
 .. py:module:: pytest_dependency