Skip to content

Commit

Permalink
Expand docs about registering markers
Browse files Browse the repository at this point in the history
  • Loading branch information
Zac-HD committed Mar 16, 2019
1 parent 4f2ace8 commit 067328a
Show file tree
Hide file tree
Showing 3 changed files with 41 additions and 8 deletions.
2 changes: 2 additions & 0 deletions changelog/4826.feature.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
A warning is now emitted when unknown marks are used as a decorator.
This is often due to a typo, which can lead to silently broken tests.
23 changes: 15 additions & 8 deletions doc/en/mark.rst
Original file line number Diff line number Diff line change
Expand Up @@ -26,14 +26,15 @@ which also serve as documentation.
:ref:`fixtures <fixtures>`.


Raising errors on unknown marks: --strict
-----------------------------------------
.. _unknown-marks:

When the ``--strict`` command-line flag is passed, any unknown marks applied
with the ``@pytest.mark.name_of_the_mark`` decorator will trigger an error.
Marks defined or added by pytest or by a plugin will not trigger an error.
Raising errors on unknown marks
-------------------------------

Marks can be registered in ``pytest.ini`` like this:
Unknown marks applied with the ``@pytest.mark.name_of_the_mark`` decorator
will always emit a warning, in order to avoid silently doing something
surprising due to mis-typed names. You can disable the warning for custom
marks by registering them in ``pytest.ini`` like this:

.. code-block:: ini
Expand All @@ -42,8 +43,11 @@ Marks can be registered in ``pytest.ini`` like this:
slow
serial
This can be used to prevent users mistyping mark names by accident. Test suites that want to enforce this
should add ``--strict`` to ``addopts``:
When the ``--strict`` command-line flag is passed, any unknown marks applied
with the ``@pytest.mark.name_of_the_mark`` decorator will trigger an error.
Marks added by pytest or by a plugin instead of the decorator will not trigger
the warning or this error. Test suites that want to enforce a limited set of
markers can add ``--strict`` to ``addopts``:

.. code-block:: ini
Expand All @@ -53,6 +57,9 @@ should add ``--strict`` to ``addopts``:
slow
serial
Third-party plugins should always :ref:`register their markers <registering-markers>`
so that they appear in pytest's help text and do not emit warnings.


.. _marker-revamp:

Expand Down
24 changes: 24 additions & 0 deletions doc/en/writing_plugins.rst
Original file line number Diff line number Diff line change
Expand Up @@ -286,6 +286,30 @@ the plugin manager like this:
If you want to look at the names of existing plugins, use
the ``--trace-config`` option.


.. _registering-markers:

Registering custom markers
--------------------------

If your plugin uses any markers, you should register them so that they appear in
pytest's help text and do not :ref:`cause spurious warnings <unknown-marks>`.
For example, the following plugin would register ``cool_marker`` and
``mark_with`` for all users:

.. code-block:: python
def pytest_configure(config):
config.addinivalue_line(
"markers",
"cool_marker: this one is for cool tests.",
)
config.addinivalue_line(
"markers",
"mark_with(arg, arg2): this marker takes arguments.",
)
Testing plugins
---------------

Expand Down

0 comments on commit 067328a

Please sign in to comment.