Knowledge baseExam Center
ENEnglish
Choose language13

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.expectedFailure

Marks 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.

Sources