CKTIS / Python
unittest.expectedFailure
Marks a known failing test so an observed failure is recorded as expected.
Version: Python 3.14; repository image, production runtime not attested
Syntax
@unittest.expectedFailureMarks a known failing test so an observed failure is recorded as expected.
An unexpected success is tracked separately, which makes a repaired known failure visible to the suite.
The default result accepts failures and ordinary errors in the decorated test body as expected, handling SkipTest as a skip. A successful body becomes an unexpected success and makes wasSuccessful() false. An error in setUp or tearDown remains an error. The example records one expected failure and zero ordinary failures. SkipTest raised by the decorated method records a skip rather than an expected failure.
import unittest
class Known(unittest.TestCase):
@unittest.expectedFailure
def test_broken(self): raise ValueError('broken')
@unittest.expectedFailure
def test_fixed(self): pass
class Setup(Known):
def setUp(self): raise ValueError('fixture')
r=unittest.TestResult()
Known('test_broken').run(r)
assert len(r.expectedFailures)==1 and r.wasSuccessful()
Known('test_fixed').run(r)
assert len(r.unexpectedSuccesses)==1 and not r.wasSuccessful()
Setup('test_broken').run(r)
assert len(r.errors)==1
class Omit(unittest.TestCase):
@unittest.expectedFailure
def test_skip(self): raise unittest.SkipTest('reason')
r=unittest.TestResult()
Omit('test_skip').run(r)
assert len(r.skipped)==1 and not r.expectedFailures
Examples
import unittest
class Check(unittest.TestCase):
@unittest.expectedFailure
def test_known(self): self.assertEqual(2, 3)
r = unittest.TestResult()
Check("test_known").run(r)
print(len(r.expectedFailures), len(r.failures))
Result
1 0
The default result accepts failures and ordinary errors in the decorated test body as expected, handling SkipTest as a skip. A successful body becomes an unexpected success and makes wasSuccessful() false. An error in setUp or tearDown remains an error. The example records one expected failure and zero ordinary failures. SkipTest raised by the decorated method records a skip rather than an expected failure.