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.

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
nicoddemus merged 3 commits into from
Oct 10, 2024
Merged

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

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
bb834e2
Docs: improve/cleanup reference from/to recwarn
soxofaan Oct 9, 2024
0c39cf1
PR #12866 add changelog item
soxofaan Oct 9, 2024
7cc8094
Update to use "fixture" rst/sphinx role
soxofaan Oct 10, 2024
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
Next Next commit
Docs: improve/cleanup reference from/to recwarn
  • Loading branch information
@soxofaan
soxofaan committed Oct 10, 2024
commit bb834e2b0608a51298414f6f6ebc389f87f79700
3 changes: 1 addition & 2 deletions doc/en/builtin.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
17 changes: 8 additions & 9 deletions doc/en/how-to/capture-warnings.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 :func:`recwarn <_pytest.recwarn.recwarn>` fixture,
Comment thread
soxofaan marked this conversation as resolved.
Outdated
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
Expand Down Expand Up @@ -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).
:func:`recwarn <_pytest.recwarn.recwarn>` fixture (see :ref:`below <recwarn>`).
Comment thread
soxofaan marked this conversation as resolved.
Outdated


The :ref:`recwarn <recwarn>` fixture automatically ensures to reset the warnings
The :func:`recwarn <_pytest.recwarn.recwarn>` fixture automatically ensures to reset the warnings
Comment thread
soxofaan marked this conversation as resolved.
Outdated
filter at the end of the test, so no global state is leaked.

.. _`recording warnings`:
Expand All @@ -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 :func:`recwarn <_pytest.recwarn.recwarn>` fixture.
Comment thread
soxofaan marked this conversation as resolved.
Outdated

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:
Expand All @@ -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 :func:`recwarn <_pytest.recwarn.recwarn>` fixture will record warnings for the whole function:
Comment thread
soxofaan marked this conversation as resolved.
Outdated

.. code-block:: python

Expand All @@ -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 :func:`recwarn <_pytest.recwarn.recwarn>` fixture and the :func:`pytest.warns` context manager return the same interface for recorded
Comment thread
soxofaan marked this conversation as resolved.
Outdated
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`:

Expand Down
3 changes: 2 additions & 1 deletion doc/en/reference/reference.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
3 changes: 1 addition & 2 deletions src/_pytest/recwarn.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down