expectedFailure Decorator

expectedFailure Decorator

@unittest.expectedFailure marks a test that is expected to fail. If the test fails, it's counted as an expected failure (not a regression). If the test unexpectedly passes, it's counted as an unexpected success.

Basic Usage

import unittest

class TestKnownIssues(unittest.TestCase):
    @unittest.expectedFailure
    def test_known_bug(self):
        """This test documents a known bug."""
        self.assertEqual(2 + 2, 5)  # Expected failure

    @unittest.expectedFailure
    def test_unfinished_feature(self):
        """Feature not fully implemented yet."""
        result = half_implemented_function()
        self.assertIsNotNone(result)

Test Outcomes

# Four possible outcomes:
# 1. Test FAILS as expected → "expected failure" (OK)
# 2. Test PASSES unexpectedly → "unexpected success" (PROBLEM)
# 3. Test PASSES as expected → normal success
# 4. Test ERRORS → normal error

# Outcome 1: Expected failure (good)
@unittest.expectedFailure
def test_known_bug(self):
    self.assertEqual(1, 2)

# Outcome 2: Unexpected success (bad — bug was fixed!)
@unittest.expectedFailure
def test_was_broken_now_fixed(self):
    self.assertEqual(1, 1)  # This will report as "unexpected success"

When to Use

• Documenting known bugs that haven't been fixed yet.
• Tracking partially implemented features.
• Test-driven development: write the test first, mark as expected failure, then fix the code.
• Tracking issues in third-party libraries you depend on.

Key Takeaway

Use @unittest.expectedFailure to mark tests for known bugs or incomplete features. When the underlying issue is fixed, the test will become an "unexpected success" — which signals you should remove the decorator.