punit.traits#

Traits are categorical name/value pairs associated with a test.

Traits can be used to group tests together for inclusion or exclusion during execution, enabling more flexible testing strategies. Common use-cases include:

  • Grouping by area of functionality (e.g., UI, business logic)

  • Grouping by dependencies (e.g., integration, mock)

  • Flagging tests as slow or flaky to control execution order

Trait filtering with --trait supports several forms:

  • !trait_name – exclude tests with this trait

  • trait_name=value – run only tests matching both name and value

  • Multiple --trait flags match any (OR logic)

  • Exclusions take priority over inclusions

Example#

from punit import theory, inlinedata, trait

@theory
@inlinedata(0, 1, 1)
@trait('integration', 'redis')
@trait('category', 'api')
def test_api_query(a, b, c):
    assert a + b == c

# exclude integration tests
python3 -m punit --trait '!integration'

# run only integration=redis tests
python3 -m punit --trait integration=redis
class TraitManager#

Bases: object

static instance()#
Return type:

TraitManager

get(callable)#
Return type:

list[Trait]

put(callable, trait)#
Return type:

None

class Trait(name, value=None)#

Bases: object

A categorical name/value pair associated with a test.

Traits can be used to group tests together for inclusion or exclusion during execution, allowing more flexible testing strategies. Common use-cases include:

  • Grouping by area of functionality (e.g., UI, business logic)

  • Grouping by dependencies (e.g., integration, mock)

  • Flagging tests as slow or flaky to control execution order

Example#

from punit import fact, trait

@fact
@trait('category', 'ui')
def test_ui_feature():
    assert True
property name: str#
property value: str | None#
trait(name, value=None)#

Decorates a Fact or Theory as having a specific Trait.

Once applied, the trait can be referenced during test execution to include or exclude the test. The --trait flag accepts several forms:

  • !trait_name – exclude tests with this trait

  • trait_name=value – run only tests matching both name and value

  • Multiple --trait flags match any (OR logic)

  • Exclusions take priority over inclusions

Args:

name: The categorical trait name (e.g., ‘integration’, ‘category’) value: Optional trait value for more specific matching (e.g., ‘redis’)

Returns:

A wrapper that attaches the trait to the target via TraitManager

Example#

from punit import theory, inlinedata, trait

@theory
@inlinedata(0, 1, 1)
@trait('integration', 'redis')
@trait('category', 'api')
def myFunction(a, b, c):
    assert a + b == c

Note: The @trait decorator can be applied more than once to a single test.

rtype:

Callable