@pytest.mark.xfail for expected failures

Introduction

Sometimes tests fail because of known bugs or unfinished features. @pytest.mark.xfail helps us mark these tests so they don't cause confusion.

You know a feature is broken but want to keep the test in your suite.

A bug is reported and you want to track it without failing the whole test run.

You are working on a new feature that is not ready yet but want to prepare tests.

You want to avoid noise from expected failures while focusing on new issues.

Syntax

PyTest

@pytest.mark.xfail(condition=True, reason="", strict=False)
def test_function():
    ...

condition is optional and decides when to mark the test as expected to fail.

reason helps explain why the test is expected to fail.

Examples

This test is always expected to fail.

PyTest

@pytest.mark.xfail
def test_example():
    assert 1 == 2

This test is expected to fail because of a known bug.

PyTest

@pytest.mark.xfail(reason="Bug #123")
def test_bug():
    assert 3 > 5

This test is expected to fail only if the condition is true (here it is false, so test runs normally).

PyTest

@pytest.mark.xfail(condition=(3 > 5), reason="Condition false")
def test_conditional():
    assert 1 == 0

Sample Program

The first test is expected to fail because 1 + 1 is not 3.

The second test is also expected to fail and marked strict, so if it passes, pytest will mark it as an error.

The third test is marked strict but passes, so pytest will report an error because it was expected to fail but didn't.

PyTest

import pytest

@pytest.mark.xfail(reason="Known bug: wrong addition")
def test_addition():
    assert 1 + 1 == 3

@pytest.mark.xfail(strict=True)
def test_strict_fail():
    assert 2 * 2 == 5

@pytest.mark.xfail(strict=True)
def test_strict_pass():
    assert 2 + 2 == 4

Important Notes

Use @pytest.mark.xfail to keep track of tests that fail for known reasons without breaking your test suite.

The strict=True option makes pytest report an error if the test unexpectedly passes.

Always add a reason to explain why the test is expected to fail for better clarity.

Summary

@pytest.mark.xfail marks tests expected to fail.

It helps manage known bugs or unfinished features.

Use strict=True to catch unexpected passes.