Fix skip signature

changelog/8384.bugfix.rst

@@ -0,0 +1 @@
+The ``@pytest.mark.skip`` decorator now correctly handles its arguments. When the ``reason`` argument is accidentally given both positional and as a keyword (e.g. because it was confused with ``skipif``), a ``TypeError`` now occurs. Before, such tests were silently skipped, and the positional argument ignored. Additionally, ``reason`` is now documented correctly as positional or keyword (rather than keyword-only).

doc/en/reference.rst

@@ -150,7 +150,7 @@ pytest.mark.skip
 
 Unconditionally skip a test function.
 
-.. py:function:: pytest.mark.skip(*, reason=None)
+.. py:function:: pytest.mark.skip(reason=None)
 
     :keyword str reason: Reason why the test function is being skipped.
 

src/_pytest/skipping.py

@@ -161,7 +161,7 @@ def evaluate_condition(item: Item, mark: Mark, condition: object) -> Tuple[bool,
 class Skip:
     """The result of evaluate_skip_marks()."""
 
-    reason = attr.ib(type=str)
+    reason = attr.ib(type=str, default="unconditional skip")
 
 
 def evaluate_skip_marks(item: Item) -> Optional[Skip]:
@@ -184,13 +184,10 @@ def evaluate_skip_marks(item: Item) -> Optional[Skip]:
                 return Skip(reason)
 
     for mark in item.iter_markers(name="skip"):
-        if "reason" in mark.kwargs:
-            reason = mark.kwargs["reason"]
-        elif mark.args:
-            reason = mark.args[0]
-        else:
-            reason = "unconditional skip"
-        return Skip(reason)
+        try:
+            return Skip(*mark.args, **mark.kwargs)
+        except TypeError as e:
+            raise TypeError(str(e) + " - maybe you meant pytest.mark.skipif?") from None
 
     return None
 

testing/test_skipping.py

@@ -861,9 +861,25 @@ def test_hello():
                 pass
         """
         )
-        result = pytester.runpytest("-rs")
+        result = pytester.runpytest("-rs", "--strict-markers")
         result.stdout.fnmatch_lines(["*unconditional skip*", "*1 skipped*"])
 
+    def test_wrong_skip_usage(self, pytester: Pytester) -> None:
+        pytester.makepyfile(
+            """
+            import pytest
+            @pytest.mark.skip(False, reason="I thought this was skipif")
+            def test_hello():
+                pass
+        """
+        )
+        result = pytester.runpytest()
+        result.stdout.fnmatch_lines(
+            [
+                "*TypeError: __init__() got multiple values for argument 'reason' - maybe you meant pytest.mark.skipif?"
+            ]
+        )
+
 
 class TestSkipif:
     def test_skipif_conditional(self, pytester: Pytester) -> None: