punit.results#

Decorators for controlling test results.

Example#

from punit import fact, fails

@fact
@fails(reason='bug #123')
def test_known_issue():
    assert False  # expected to fail

fails(*, reason)#

Mark a test as expected to fail for the given reason.

This is a marker decorato, it does not wrap the target function.

Return type:: Callable

Semantics#

A test decorated with @fails has its pass/fail result inverted:

Test fails → reported as passing.
Test passes → reported as failing.

In both cases expected_failure_reason is set so reporting and automation tools can know that the test was expected to fail.

Usage#

Stack this decorator below @fact or @theory, closest to the function definition:

@fact
@fails(reason='bug #123: assert order is reversed')
def test_reversed_order():
    assert get_items() == ['b', 'a']

For parameterized tests:

@theory
@inlinedata('unsorted', [3, 1, 2], [1, 2, 3])
@fails(reason='edge case in sort comparison')
def theory_sort(unused: str, unsorted: list[int], then: list[int]):
    assert sorted(unsorted) == then

Parameters#

reasonstr: A human-readable explanation of why the test is expected to fail.

Returns#

Callable: The original, undecorated target – no wrapper is installed.

Raises#

Exception: If target is not a function or method, if it has already been decorated by @fails, or if it already carries a __punit_decorator attribute set by another pUnit decorator (@fact, @theory, @setup, @teardown).