Tagging

Tagging allows you to attach arbitrary labels to testcases and tests which can then be selected using a logical expression.

Tagging is a very useful feature to group tests or to partition and paralell long running test suites easily without any additional effort.

Adding tags to testcases and tests

Tagging is done using the htf.tags decorator which can be used for testcases and tests. Tests inherit the tags from the testcase they are located in. Inherited tags are merged with local tags.

import htf

@htf.tags("foo")
class TestFoo(htf.TestCase):

    @htf.tags("one")
    def test_one(self):
        pass

    @htf.tags("two")
    def test_two(self):
        pass

    @htf.tags("three", "io")
    def test_three(self):
        # use io
        pass

@htf.tags("bar")
class TestBar(htf.TestCase):

    @htf.tags("one")
    def test_one(self):
        pass

    @htf.tags("two")
    def test_two(self):
        pass

    @htf.tags("three", "io")
    def test_three(self):
        # use io
        pass

All tests in TestFoo are tagged with "foo" and all tests in TestBar are tagged with "bar".

Logical expression to select tags

Tagged tests can be selected using a logical expression that is evaluated to find matching tests.

A logical expression is a string consisting of tag names, operators and pairs of brackets.

The parser supports the following tokens:

Token	Description
tag	A string matching the regular expression `r'[a-zA-Z0-9_\-\.\=]+'`. So it consists of `a..z`, `A-Z` `0..9`, `_`, `-`, `=` and `.`.
&	Logical and
\|	Logical or
^	Logical xor
!	Logical not
(	Left bracket
)	Right bracket

Groups are built using the brackets. Groups are evaluated first.

Whitespaces are ignored.

For example to select all tests that have the "foo" tag the logical expression would be "foo".

To select all tests that do not have the "foo" tag the logical expression would be "!foo".

To select all tests that uses "io" and "bar" the expression is "io&bar" (or "io & bar" for better readability).

To select all tests that are tagged with "bar" or "io" and "three" the expression is "bar | (io & three)".

Selecting tests using tags

To select tests using a logical expression and tags is easy.

htf.main, htf.run and htf.dryrun have the tags option set to a logical expression.

For example:

htf.main(tags="bar | (io & three)")

For the command line utilities htf run and htf dryrun use the -t or --tags option followed by a logical expression.

For example:

htf run --tags='bar | (io & three)'

Showing available tags

To get a list of available tags you can use $ htf tags from the command line or htf.get_tags from within a Python script.

For the initial example this would lead to a sorted list of tags consisting of bar, foo, io, one, three and two.