Merge pull request #3663 from nicoddemus/usefixtures-reference

Add reference docs for pytest.mark.usefixtures

doc/en/fixture.rst

@@ -943,7 +943,7 @@ a generic feature of the mark mechanism:
 Note that the assigned variable *must* be called ``pytestmark``, assigning e.g.
 ``foomark`` will not activate the fixtures.
 
-Lastly you can put fixtures required by all tests in your project
+It is also possible to put fixtures required by all tests in your project
 into an ini-file:
 
 .. code-block:: ini
@@ -953,6 +953,22 @@ into an ini-file:
     usefixtures = cleandir
 
 
+.. warning::
+
+    Note this mark has no effect in **fixture functions**. For example,
+    this **will not work as expected**:
+
+    .. code-block:: python
+
+        @pytest.mark.usefixtures("my_other_fixture")
+        @pytest.fixture
+        def my_fixture_that_sadly_wont_use_my_other_fixture():
+            ...
+
+    Currently this will not generate any error or warning, but this is intended
+    to be handled by `#3664 <https://github.com/pytest-dev/pytest/issues/3664>`_.
+
+
 .. _`autouse`:
 .. _`autouse fixtures`:
 

doc/en/reference.rst

@@ -161,6 +161,25 @@ Skip a test function if a condition is ``True``.
     :keyword str reason: Reason why the test function is being skipped.
 
 
+.. _`pytest.mark.usefixtures ref`:
+
+pytest.mark.usefixtures
+~~~~~~~~~~~~~~~~~~~~~~~
+
+**Tutorial**: :ref:`usefixtures`.
+
+Mark a test function as using the given fixture names.
+
+.. warning::
+
+    This mark can be used with *test functions* only, having no affect when applied
+    to a **fixture** function.
+
+.. py:function:: pytest.mark.usefixtures(*names)
+
+    :param args: the names of the fixture to use, as strings
+
+
 .. _`pytest.mark.xfail ref`:
 
 pytest.mark.xfail