Add a documentation page explaining how pytest node ids are built and

how dependencies must be referenced depending on the scope.

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/src/index.rst

@@ -15,6 +15,7 @@ Content of the documentation
    install
    usage
    advanced
+   names
    configuration
    changelog
    reference

doc/src/names.rst

@@ -0,0 +1,80 @@
+.. _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
+
+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/usage.rst

@@ -42,9 +42,9 @@ Naming tests
 ------------
 
 Tests are referenced by their name in the `depends` argument.  The
-default for this name is the node ID defined by pytest, that is the
+default for this name is the node id defined by pytest, that is the
 name of the test function, extended by the parameters if applicable.
-In some cases, it's not easy to predict the names of the node IDs.
+In some cases, it's not easy to predict the names of the node ids.
 For this reason, the name of the tests can be overridden by an
 explicit `name` argument to the marker.  The names must be unique in
 the scope, which is currently the test module.  The following example