This rule raises an issue when @pytest.mark.xfail is used without a reason parameter.

Why is this an issue?

When writing tests, @pytest.mark.xfail marks a test as expected to fail, for example while a known bug remains unfixed.

@pytest.mark.xfail without reason leaves future maintainers without context for why the failure is expected. The reason must appear on the decorator; comments or docstrings do not satisfy this rule.

What is the potential impact?

Undocumented expected failures accumulate as the codebase changes, so teams cannot tell which markers still reflect real defects.

How to fix it

Add the reason parameter with a concise explanation or issue reference.

Code examples

Noncompliant code example

@pytest.mark.xfail  # Noncompliant
def test_division_by_zero():
    result = divide(10, 0)
    assert result is None

Compliant solution

@pytest.mark.xfail(reason='Issue #456: divide() should raise ValueError for zero divisor')
def test_division_by_zero():
    result = divide(10, 0)
    assert result is None

Resources

Documentation

• pytest documentation - How to use skip and xfail to deal with tests that cannot succeed
• pytest documentation - pytest.mark.xfail