Skip to content

Add reference docs for pytest.mark.usefixtures #3663

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Jul 7, 2018
Merged

Add reference docs for pytest.mark.usefixtures #3663

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d7b722e
Add reference docs for pytest.mark.usefixtures
nicoddemus Jul 6, 2018
d26a596
Add a warning about usefixtures mark not working in fixtures
nicoddemus Jul 7, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 17 additions & 1 deletion doc/en/fixture.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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`:

Expand Down
19 changes: 19 additions & 0 deletions doc/en/reference.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wonder if it could be a good idea to add an explicit warning/reminder here that you can only mark test functions like this and not other fixtures to address #1014

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ahh good idea, will do

Copy link
Member

@obestwalter obestwalter Jul 7, 2018 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Something like:

"Be aware that although you can use fixtures from oher fixtures by adding them to the function parameters, you can not do this by marking the fixture function with usefixtures."

Maybe even with an example?

This works:

@pytest.fixture
def my_fixture(my_other_fixture):
    [...]

This will not yield the wanted result and currently not result in an error or a warning either.

@pytest.mark.usefixtures("my_other_fixture")
@pytest.fixture
def my_fixture_that_sadly_wont_use_my_other_fixture():
    [...]

I would even suggest to put this in a warning box, because this can be surprising even for experienced pytest users, especially due to the lack of an error atm.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @obestwalter!

I added the warning but the example I added to the tutorial/normal documentation. IMHO we should keep the reference as lean as possible.


.. warning::

This mark can be used with *test functions* only, having no affect when applied
to a **fixture** function.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

perfect :)

.. py:function:: pytest.mark.usefixtures(*names)

:param args: the names of the fixture to use, as strings


.. _`pytest.mark.xfail ref`:

pytest.mark.xfail
Expand Down