# Selecting tests with attributes

Note

New in version 0.2

Filter tests by attribute, excluding any tests whose attributes do not match any of the specified attributes.

Attributes may be simple values or lists, and may be attributes of a test method (or function), a test case class, or the callable yielded by a generator test.

Given the following test module, the attrib plugin can be used to select tests in the following ways (and others!):

Note

All examples assume the attrib plugin has been activated in a config file:

    [unittest]
    plugins = nose2.plugins.attrib

    import unittest

    class Test(unittest.TestCase):
        def test_fast(self):
            pass

        test_fast.fast = 1
        test_fast.layer = 2
        test_fast.flags = ["blue", "green"]

        def test_faster(self):
            pass

        test_faster.fast = 1
        test_faster.layer = 1
        test_faster.flags = ["red", "green"]

        def test_slow(self):
            pass

        test_slow.fast = 0
        test_slow.slow = 1
        test_slow.layer = 2

        def test_slower(self):
            pass

        test_slower.slow = 1
        test_slower.layer = 3
        test_slower.flags = ["blue", "red"]

## Select tests having an attribute

Running nose2 like this:

    nose2 -v -A fast

Runs these tests:

    test_fast (attrib_example.Test) ... ok
    test_faster (attrib_example.Test) ... ok

This selects all tests that define the attribute as any `True` value.

## Select tests that do not have an attribute

Running nose2 like this:

    nose2 -v -A '!fast'

Runs these tests:

    test_slow (attrib_example.Test) ... ok
    test_slower (attrib_example.Test) ... ok

This selects all tests that define the attribute as a `False` value, and those tests that do not have the attribute at all.

### Select tests having an attribute with a particular value

Running nose2 like this:

    nose2 -v -A layer=2

Runs these tests:

    test_fast (attrib_example.Test) ... ok
    test_slow (attrib_example.Test) ... ok

This selects all tests that define the attribute with a matching value. The attribute value of each test case is converted to a string before comparison with the specified value. Comparison is case-insensitive.

### Select tests having a value in a list attribute

Running nose2 like this:

    nose2 -v -A flags=red

Runs these tests:

    test_faster (attrib_example.Test) ... ok
    test_slower (attrib_example.Test) ... ok

Since the `flags` attribute is a list, this test selects all tests with the value `red` in their `flags` attribute. Comparison done after string conversion and is case-insensitive.

### Select tests that do not have a value in a list attribute

Running nose2 like this:

    nose2 -v -A '!flags=red'

Runs these tests:

    test_fast (attrib_example.Test) ... ok

The result in this case can be somewhat counter-intuitive. What the `attrib` plugin selects when you negate an attribute that is in a list are only those tests that have the list attribute but without the value specified. Tests that do not have the attribute at all are not selected.

### Select tests using Python expressions

For more complex cases, you can use the `-E` command-line option to pass a Python expression that will be evaluated in the context of each test case. Only those test cases where the expression evaluates to `True` (and don’t raise an exception) will be selected.

Running nose2 like this:

    nose2 -v -E '"blue" in flags and layer > 2'

Runs only one test:

    test_slower (attrib_example.Test) ... ok

#### Command-line options

-A DEFAULT, --attribute DEFAULT

  Select tests with matching attribute

-E DEFAULT, --eval-attribute DEFAULT

  Select tests for whose attributes the given Python expression evaluates to `True`

#### Plugin class reference: AttributeSelector

class nose2.plugins.attrib.AttributeSelector(*args, **kwargs)

  Filter tests by attribute

  handleArgs(args)

    Register if any attribs defined

  moduleLoadedSuite(event)

    Filter event.suite by specified attributes