diff --git a/changelog/4036.removal.rst b/changelog/4036.removal.rst new file mode 100644 index 000000000..a124028c4 --- /dev/null +++ b/changelog/4036.removal.rst @@ -0,0 +1,9 @@ +The ``item`` parameter of ``pytest_warning_captured`` hook is now documented as deprecated. We realized only after +the ``3.8`` release that this parameter is incompatible with ``pytest-xdist``. + +Our policy is to not deprecate features during bugfix releases, but in this case we believe it makes sense as we are +only documenting it as deprecated, without issuing warnings which might potentially break test suites. This will get +the word out that hook implementers should not use this parameter at all. + +In a future release ``item`` will always be ``None`` and will emit a proper warning when a hook implementation +makes use of it. diff --git a/src/_pytest/hookspec.py b/src/_pytest/hookspec.py index 1a9326149..533806964 100644 --- a/src/_pytest/hookspec.py +++ b/src/_pytest/hookspec.py @@ -562,6 +562,9 @@ def pytest_warning_captured(warning_message, when, item): * ``"runtest"``: during test execution. :param pytest.Item|None item: + **DEPRECATED**: This parameter is incompatible with ``pytest-xdist``, and will always receive ``None`` + in a future release. + The item being executed if ``when`` is ``"runtest"``, otherwise ``None``. """