How to mark known bugs with pytest xfail in Python

Use @pytest.mark.xfail to mark tests that are expected to fail due to known bugs, with optional strict mode to control pass/fail behavior.

Easy Python 3.9+ Aug 9, 2026 Testing & modern typing 16 views 0 copies

pytest testing xfail
Requires third-party packages — install first
pip install pytest

Python code

26 lines
Python 3.9+ 
import pytest


def divide(a: int, b: int) -> float:
    if b == 0:
        raise ZeroDivisionError("Cannot divide by zero")
    return a / b


@pytest.mark.xfail(reason="Known bug: division returns int instead of float", strict=False)
def test_divide_integer_division():
    result = divide(10, 4)
    assert isinstance(result, float)
    assert result == 2.5


@pytest.mark.xfail(reason="Known bug: does not raise ZeroDivisionError for zero divisor", strict=True)
def test_divide_by_zero():
    result = divide(10, 0)
    assert result is None


if __name__ == "__main__":
    test_divide_integer_division()
    test_divide_by_zero()
    print("All tests executed successfully.")

Output

stdout 
Running pytest on this code will produce xfailed results:

collected 2 items

test_example.py xX                                                               [100%]

=============================== short test summary info ================================
XFAIL test_example.py::test_divide_integer_division
  reason: Known bug: division returns int instead of float
XFAIL test_example.py::test_divide_by_zero
  reason: Known bug: does not raise ZeroDivisionError for zero divisor

=============================== 2 xfailed in 0.02s ====================================

When run as a script: 
All tests executed successfully.

How it works

@pytest.mark.xfail tells pytest that a test is expected to fail, and the test result is reported as xfailed instead of a failure. With strict=False (default), if the test unexpectedly passes, it's reported as xpassed with a warning, while strict=True turns an unexpected pass into a failure. The reason parameter documents why the test is marked, which is useful for tracking known bugs. This decorator works on individual test functions or entire classes.

Common mistakes

  • Using strict=False when you want unexpected passes to fail the suite
  • Forgetting to add a reason, making it unclear why the test is marked
  • Marking tests xfail instead of fixing the bug and removing the marker

Variations

  1. Use `pytest.xfail("reason")` inside the test to conditionally mark based on runtime state
  2. Apply `@pytest.mark.xfail` to a class to mark all tests in it

Real-world use cases

  • Tracking known bugs in legacy code until they are fixed and removed.
  • Marking tests for features not yet implemented, allowing CI to green.
  • Documenting platform-specific failures (e.g., Windows vs. Linux) with strict mode.

Sponsored

Run locally

This sample needs third-party packages, so it cannot run in the browser IDE. Copy the code above, install the packages shown at the top, then run it in your own Python environment.

More from Testing & modern typing

Keep learning

Related tutorials and quizzes for this topic.

Tutorials

Quizzes