Merge pull request #8242 from bluetech/deprecate-unittest-skip-collection

Deprecate raising unittest.SkipTest to skip tests during collection

changelog/8242.deprecation.rst

@@ -0,0 +1,7 @@
+Raising :class:`unittest.SkipTest` to skip collection of tests during the
+pytest collection phase is deprecated. Use :func:`pytest.skip` instead.
+
+Note: This deprecation only relates to using `unittest.SkipTest` during test
+collection. You are probably not doing that. Ordinary usage of
+:class:`unittest.SkipTest` / :meth:`unittest.TestCase.skipTest` /
+:func:`unittest.skip` in unittest test cases is fully supported.

doc/en/deprecations.rst

@@ -18,6 +18,20 @@ Deprecated Features
 Below is a complete list of all pytest features which are considered deprecated. Using those features will issue
 :class:`PytestWarning` or subclasses, which can be filtered using :ref:`standard warning filters <warnings>`.
 
+Raising ``unittest.SkipTest`` during collection
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. deprecated:: 6.3
+
+Raising :class:`unittest.SkipTest` to skip collection of tests during the
+pytest collection phase is deprecated. Use :func:`pytest.skip` instead.
+
+Note: This deprecation only relates to using `unittest.SkipTest` during test
+collection. You are probably not doing that. Ordinary usage of
+:class:`unittest.SkipTest` / :meth:`unittest.TestCase.skipTest` /
+:func:`unittest.skip` in unittest test cases is fully supported.
+
+
 The ``--strict`` command-line option
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

src/_pytest/deprecated.py

@@ -64,6 +64,11 @@ STRICT_OPTION = PytestDeprecationWarning(
 
 PRIVATE = PytestDeprecationWarning("A private pytest class or function was used.")
 
+UNITTEST_SKIP_DURING_COLLECTION = PytestDeprecationWarning(
+    "Raising unittest.SkipTest to skip tests during collection is deprecated. "
+    "Use pytest.skip() instead."
+)
+
 
 # You want to make some `__init__` or function "private".
 #

src/_pytest/runner.py

@@ -2,6 +2,7 @@
 import bdb
 import os
 import sys
+import warnings
 from typing import Callable
 from typing import cast
 from typing import Dict
@@ -27,6 +28,7 @@ from _pytest._code.code import TerminalRepr
 from _pytest.compat import final
 from _pytest.config.argparsing import Parser
 from _pytest.deprecated import check_ispytest
+from _pytest.deprecated import UNITTEST_SKIP_DURING_COLLECTION
 from _pytest.nodes import Collector
 from _pytest.nodes import Item
 from _pytest.nodes import Node
@@ -374,6 +376,11 @@ def pytest_make_collect_report(collector: Collector) -> CollectReport:
             # Type ignored because unittest is loaded dynamically.
             skip_exceptions.append(unittest.SkipTest)  # type: ignore
         if isinstance(call.excinfo.value, tuple(skip_exceptions)):
+            if unittest is not None and isinstance(
+                call.excinfo.value, unittest.SkipTest  # type: ignore[attr-defined]
+            ):
+                warnings.warn(UNITTEST_SKIP_DURING_COLLECTION, stacklevel=2)
+
             outcome = "skipped"
             r_ = collector._repr_failure_py(call.excinfo, "line")
             assert isinstance(r_, ExceptionChainRepr), repr(r_)

testing/deprecated_test.py

@@ -136,3 +136,20 @@ def test_private_is_deprecated() -> None:
 
     # Doesn't warn.
     PrivateInit(10, _ispytest=True)
+
+
+def test_raising_unittest_skiptest_during_collection_is_deprecated(
+    pytester: Pytester,
+) -> None:
+    pytester.makepyfile(
+        """
+        import unittest
+        raise unittest.SkipTest()
+        """
+    )
+    result = pytester.runpytest()
+    result.stdout.fnmatch_lines(
+        [
+            "*PytestDeprecationWarning: Raising unittest.SkipTest*",
+        ]
+    )