Improvement #10094

changelog/10094.improvement.rst

@@ -0,0 +1,4 @@
+The documentation for pytest.mark.xfail():
+reason=None: If no conditions are passed, reason’s default is "" (code). Adding @pytest.mark.xfail(reason=None, strict=True) to a passing test results in “TypeError: can only concatenate str (not "NoneType") to str”. If a condition is passed, passing no reason behaves like passing None to it (code). I’m unsure how this subtlety could be captured in the function signature. pytest.mark.skipif() has the same issue. pytest.mark.skip()’s default value for reason is in fact "unconditional skip" (code).
+raises: The type (according to the type annotations) is Union[Type[BaseException], Tuple[Type[BaseException], ...]] instead of Type[Exception]. Neither captures the fact that None can be passed to it (which is also the documented default value).
+strict=False: The default value of strict is actually determined by the xfail_strict config (code).

doc/en/reference/reference.rst

@@ -246,22 +246,25 @@ Marks a test function as *expected to fail*.
         to specify ``reason`` (see :ref:`condition string <string conditions>`).
     :keyword str reason:
         Reason why the test function is marked as xfail.
-    :keyword Type[Exception] raises:
+        If no conditions are passed, the default value of `reason` is an empty string ("").
+        However, please note that you should avoid passing `None` as the `reason`, as this can result in a TypeError.
+        If a condition is passed and no `reason` is specified, it behaves as if you passed `None` as the `reason`.
+    :keyword Union[Type[BaseException], Tuple[Type[BaseException], ...]] raises:
         Exception subclass (or tuple of subclasses) expected to be raised by the test function; other exceptions will fail the test.
+        You can also pass `None` to this argument if no specific exceptions are expected.
     :keyword bool run:
-        Whether the test function should actually be executed. If ``False``, the function will always xfail and will
-        not be executed (useful if a function is segfaulting).
+        Whether the test function should actually be executed.
+        If set to ``False``, the function will always xfail and will not be executed (useful if a function is segfaulting).
     :keyword bool strict:
-        * If ``False`` the function will be shown in the terminal output as ``xfailed`` if it fails
-          and as ``xpass`` if it passes. In both cases this will not cause the test suite to fail as a whole. This
-          is particularly useful to mark *flaky* tests (tests that fail at random) to be tackled later.
-        * If ``True``, the function will be shown in the terminal output as ``xfailed`` if it fails, but if it
-          unexpectedly passes then it will **fail** the test suite. This is particularly useful to mark functions
-          that are always failing and there should be a clear indication if they unexpectedly start to pass (for example
-          a new release of a library fixes a known bug).
+        * The value of `strict` is determined by the `xfail_strict` configuration.
+        * If set to ``False``, the function will be shown in the terminal output as "xfailed" if it fails and as "xpassed" if it passes. In both cases, this will not cause the test suite to fail as a whole. This is particularly useful to mark flaky tests (tests that fail at random) to be tackled later.
+        * If set to ``True``, the function will be shown in the terminal output as "xfailed" if it fails, and if it unexpectedly passes, it will fail the test suite. This is useful for marking functions that are always failing, and there should be a clear indication if they unexpectedly start to pass (e.g., a new release of a library fixes a known bug).
+        * The default value for `strict` is determined by the `xfail_strict` configuration, which is `False` by default.
 
         Defaults to :confval:`xfail_strict`, which is ``False`` by default.
 
+    .. py:function:: pytest.mark.xfail(condition=None, *, reason=None, raises=None, run=True, strict=xfail_strict)
+
 
 Custom marks
 ~~~~~~~~~~~~