Minor documentation update

- add information about interaction with some ordering plugins

Author: mrbean-bremen

docs/source/other_plugins.rst

@@ -10,23 +10,26 @@ want to execute the tests in a specific order to each other, you can use
 ``pytest-order``. If you want to skip or xfail tests dependent on other
 tests you can use ``pytest-dependency``. If you want to have both behaviors
 combined, you can use both plugins together with the
-option :ref:`order-dependencies`, described above. As mentioned before, only
+option :ref:`order-dependencies`. As mentioned before, only
 static ``dependency`` markers are considered for ordering.
 
 Usage with other ordering plugins
 ---------------------------------
 There is a number of other pytest plugins that change the order in which tests
-are executed, the most widely known probably being
-`pytest-randomly`_, which
-executes tests in a random order to avoid unknown test dependencies.
-``pytest-order`` should still work with these as long as it is executed
-*after* the other plugins (which it should by default, except if you use
-the option :ref:`indulgent-ordering`).
-The marked tests still shall be ordered correctly, but the order of the
-unordered tests will change, depending on the order the tests have been
-after these other plugins have reordered them.
-For example, if you have installed ``pytest-randomly``, and run the
-following tests:
+are executed. Most of these plugins only reorder tests if given some command
+line options or in the presence of specific markers (as does ``pytest-order``).
+These plugins will not have any effect on ``pytest-order`` if not actively
+used. A few plugins always do reordering, most notably ``pytest-randomly``.
+
+`pytest-randomly`_
+~~~~~~~~~~~~~~~~~~
+This plugin executes tests in a random order to avoid unknown test
+dependencies. The plugin is effective if installed and not actively disabled.
+``pytest-order`` should still work correctly, because it is executed after
+``pytest-randomly`` (except if you use the option
+:ref:`indulgent-ordering`). The marked tests will be ordered correctly, but
+the order of the unordered tests will change unpredictably. For example, if
+you run the following tests:
 
 .. code:: python
 
@@ -64,15 +67,59 @@ or:
 
 The same is true for relative ordering. The tests will be correctly ordered
 before and after the tests as configured, but all other tests will be in an
-arbitrary order.
-
-Note that it does not make much sense to use ordering plugins together that
-have a similar goal as ``pytest-order``, as for example ``pytest-ordering``.
-As mentioned, both plugins can co-exist without problems due to the
-different marker names, but using markers of both plugins in the same test
+arbitrary order. If you want the tests to execute in a random order except the
+ones that you know depend on each other, this can be a good strategy to
+prevent test dependencies.
+
+If you don't want the installed ``pytest-randomly`` be effective in a test
+run, you can exclude it explicitly on the command line::
+
+  python -m pytest -p no:randomly
+
+`pytest-reverse`_
+~~~~~~~~~~~~~~~~~
+`pytest-reverse`_ is another plugin by the same author to find test
+dependencies by running tests in the reverse order. Other than
+``pytest-randomly``, it is only effective if the tests are called with the
+command line option ``--reverse``.
+As with ``pytest-randomly``, you can use this plugin combined with
+``pytest-ordering`` to make sure that all known test dependencies are
+handled, and possible unknown dependencies are found.
+
+`pytest-random-order`_
+~~~~~~~~~~~~~~~~~~~~~~
+`pytest-random-order`_ is very similar to ``pytest-randomly``, except that the
+tests are only reordered if the option ``--random-order`` is given. Except
+from that, what was mentioned for ``pytest-randomly`` is also true for
+this plugin.
+
+`pytest-ordering`_
+~~~~~~~~~~~~~~~~~~
+As mentioned, `pytest-ordering`_ can coexist with ``pytest-order`` due to
+the different marker names, but using markers of both plugins in the same test
 run is not recommended. One plugin may partially revert the effects of the
-other plugin in unpredictable ways. The same is true for other plugins that
-define the test order.
+other plugin in unpredictable ways, because the order in which they are
+executed is not deterministic. The same is true for other plugins that define
+the test order and are run last.
+
+`pytest-depends`_
+~~~~~~~~~~~~~~~~~
+`pytest-depends`_ has a goal somewhat similar to `pytest-dependency`_ with
+additional ordering, but due to a known issue it always reorders the tests.
+If you have installed this plugin, the order of the unordered tests will
+change even without using it actively.
+
+`pytest-find-dependencies`_
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+This is a small plugin by the same author as ``pytest-order`` that tries to
+find specific dependencies between tests by running a subset of them repeatedly
+in reverse order until the dependencies are found. This plugin would run the
+tests as ordered by any ordering plugin in the first run, but reverse the
+test order in the second run, so that already ordered tests are not run in
+the correct order. You have the possibility to exclude ordered tests
+completely by using the ``--markers-to-ignore`` option::
+
+  python -m pytest --find-dependencies --markers-to-ignore=order
 
 Usage with pytest-xdist
 -----------------------
@@ -89,3 +136,8 @@ each group of dependent tests in one file, and call pytest with
 .. _`pytest-xdist`: https://pypi.org/project/pytest-xdist/
 .. _`pytest-randomly`: https://pypi.org/project/pytest-randomly/
 .. _`pytest-dependency`: https://pypi.org/project/pytest-dependency/
+.. _`pytest-reverse`: https://pypi.org/project/pytest-reverse/
+.. _`pytest-depends`: https://pypi.org/project/pytest-depends/
+.. _`pytest-random-order`: https://pypi.org/project/pytest-random-order/
+.. _`pytest-find-dependencies`: https://pypi.org/project/pytest-find-dependencies/
+.. _`pytest-ordering`: https://pypi.org/project/pytest-ordering/