Skip to content

Docs: improve/cleanup reference from/to recwarn #12866

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.

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 3 commits into from
Oct 10, 2024
Merged
Changes from all commits
Commits
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
1 change: 1 addition & 0 deletions changelog/12866.doc.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Improved cross-references concerning the :fixture:`recwarn` fixture.
3 changes: 1 addition & 2 deletions doc/en/builtin.rst
Original file line number Diff line number Diff line change
@@ -234,8 +234,7 @@ For information about fixtures, see :ref:`fixtures`. To see a complete list of a
recwarn -- .../_pytest/recwarn.py:35
Return a :class:`WarningsRecorder` instance that records all warnings emitted by test functions.

See https://docs.pytest.org/en/latest/how-to/capture-warnings.html for information
on warning categories.
See :ref:`warnings` for information on warning categories.

tmp_path_factory [session scope] -- .../_pytest/tmpdir.py:242
Return a :class:`pytest.TempPathFactory` instance for the test session.
17 changes: 8 additions & 9 deletions doc/en/how-to/capture-warnings.rst
Original file line number Diff line number Diff line change
@@ -195,7 +195,7 @@ user code and third-party libraries, as recommended by :pep:`565`.
This helps users keep their code modern and avoid breakages when deprecated warnings are effectively removed.

However, in the specific case where users capture any type of warnings in their test, either with
:func:`pytest.warns`, :func:`pytest.deprecated_call` or using the :ref:`recwarn <recwarn>` fixture,
:func:`pytest.warns`, :func:`pytest.deprecated_call` or using the :fixture:`recwarn` fixture,
no warning will be displayed at all.

Sometimes it is useful to hide some specific deprecation warnings that happen in code that you have no control over
@@ -332,10 +332,10 @@ additional information:
assert record[0].message.args[0] == "another warning"

Alternatively, you can examine raised warnings in detail using the
:ref:`recwarn <recwarn>` fixture (see below).
:fixture:`recwarn` fixture (see :ref:`below <recwarn>`).


The :ref:`recwarn <recwarn>` fixture automatically ensures to reset the warnings
The :fixture:`recwarn` fixture automatically ensures to reset the warnings
filter at the end of the test, so no global state is leaked.

.. _`recording warnings`:
@@ -345,8 +345,8 @@ filter at the end of the test, so no global state is leaked.
Recording warnings
------------------

You can record raised warnings either using :func:`pytest.warns` or with
the ``recwarn`` fixture.
You can record raised warnings either using the :func:`pytest.warns` context manager or with
the :fixture:`recwarn` fixture.

To record with :func:`pytest.warns` without asserting anything about the warnings,
pass no arguments as the expected warning type and it will default to a generic Warning:
@@ -361,7 +361,7 @@ pass no arguments as the expected warning type and it will default to a generic
assert str(record[0].message) == "user"
assert str(record[1].message) == "runtime"

The ``recwarn`` fixture will record warnings for the whole function:
The :fixture:`recwarn` fixture will record warnings for the whole function:

.. code-block:: python

@@ -377,12 +377,11 @@ The ``recwarn`` fixture will record warnings for the whole function:
assert w.filename
assert w.lineno

Both ``recwarn`` and :func:`pytest.warns` return the same interface for recorded
warnings: a WarningsRecorder instance. To view the recorded warnings, you can
Both the :fixture:`recwarn` fixture and the :func:`pytest.warns` context manager return the same interface for recorded
warnings: a :class:`~_pytest.recwarn.WarningsRecorder` instance. To view the recorded warnings, you can
iterate over this instance, call ``len`` on it to get the number of recorded
warnings, or index into it to get a particular recorded warning.

Full API: :class:`~_pytest.recwarn.WarningsRecorder`.

.. _`warns use cases`:

3 changes: 2 additions & 1 deletion doc/en/reference/reference.rst
Original file line number Diff line number Diff line change
@@ -529,13 +529,14 @@ record_testsuite_property
recwarn
~~~~~~~

**Tutorial**: :ref:`assertwarnings`
**Tutorial**: :ref:`recwarn`

.. autofunction:: _pytest.recwarn.recwarn()
:no-auto-options:

.. autoclass:: pytest.WarningsRecorder()
:members:
:special-members: __getitem__, __iter__, __len__


.. fixture:: request
3 changes: 1 addition & 2 deletions src/_pytest/recwarn.py
Original file line number Diff line number Diff line change
@@ -35,8 +35,7 @@
def recwarn() -> Generator[WarningsRecorder]:
"""Return a :class:`WarningsRecorder` instance that records all warnings emitted by test functions.

See https://docs.pytest.org/en/latest/how-to/capture-warnings.html for information
on warning categories.
See :ref:`warnings` for information on warning categories.
"""
wrec = WarningsRecorder(_ispytest=True)
with wrec:
Loading