Testing Decorators Module

The decorators module defines useful class / function decorators for test cases.

Available Decorators

testing.decorators.confoverrides(**config)[source]

Override the defaults of testing.base.make_default_config() to supply to pytest.mark.sphinx.

It can be applied to a test method or a test class, which is equivalent to decorating every method in that class.

Usage:

@confoverrides(var1=value1, var2=value2)
def test_something(self):
    ...

or:

@confoverrides(var1=value1, var2=value2)
class MyTestCase(ExhaleTestCase):
    test_project = 'my_project'
    ...

Typical usage of this decorator is to modify a value in exhale_args, such as

@confoverrides(exhale_args={"containmentFolder": "./alt_api"})
def test_alt_out(self):
   ...

However, this decorator can be used to change or set any value you would typically find in a conf.py file.

Parameters

**config (dict): The dictionary of confoverrides as would be supplied to pytest.mark.sphinx. These are the overrides to conf.py.

Return

(class or types.FunctionType): The decorated class or function.

testing.decorators.no_cleanup(method)[source]

Prevent the “docs” directory and generated Doxygen / API from being deleted.

Usage:

class CMathsTests(ExhaleTestCase):
    # docs dir, generated API, and Doxygen will not be deleted so that you can
    # inspect what may be causing your test to fail
    @no_cleanup
    def test_being_developed(self):
        pass

Danger

This decorator performs self.testroot = [self.testroot] as an internal bypass to the fixtures created in __new__ for the metaclass. Specifically, the fixtures generated check if isinstance(self.testroot, six.string_types).

As such, since self.testroot may be desired in the given @no_cleanup function, you must acquire it with testroot = self.testroot[0]. This is a hacky solution, but should be sufficient. You have been warned.

Parameters

method (types.FunctionType): Must be an instance-level testing function of a derived type of testing.base.ExhaleTestCase. The function should have only a single parameter self.

Return

(types.FunctionType): The decorated function, which simply calls the provided function and sets self.testroot = None. Click on [source] link for ExhaleTestCaseMetaclass.__new__ and search for @no_cleanup to see how this prevents cleanup.

testing.decorators.no_run(obj)[source]

Disable the generation of *.rst files in a specific test method.

It can be applied to a test class, which will be equivalent to decorating every method in that class.

Usage:

@no_run
def test_something(self):
    ...

or:

@no_run
class MyTestCase(ExhaleTestCase):
    test_project = 'my_project'
    ...

Internally this will use the testing.fixtures.no_run() fixture.

Parameters

obj (class or types.FunctionType): The class or function to disable exhale from generating reStructuredText documents for.

Return

class or types.FunctionType: The decorated obj.

Decorator Helper Functions

testing.decorators._apply_confoverride_to_class(cls, config, priority)[source]

Apply a configuration override config to class cls with a given priority.

We need the priority trick as the default configuration is applied before a possible class-wide decorator, which should supersede the default configuration. We use pytest.mark.exhale as a store of kwargs to apply to pytest.mark.sphinx, and we use the priority to combine these kwargs with respect to priorities.

This method performs the ultimate pytest.mark.sphinx.

Parameters

cls (Subclass of testing.base.ExhaleTestCase)

The class to apply the confoverride to.

config (dict)

The dictionary of confoverrides as would be supplied to pytest.mark.sphinx. These are the overrides to conf.py.

priority (int)

The positive integer indicating the priority of the new config updates, higher values take precedence over lower values.

For example, when testing.decorators.default_confoverrides() calls this function, the priority is 1. When the decorator testing.decorators.confoverrides() is applied to a class, the priority is 2. Finally, when testing.decorators.confoverrides() is applied to a test function, its priority is 3. Thus the function-level override has the highest priority, meaning any conflicting values with lower level priorities will lose out to the function-level override.

Return

Subclass of testing.base.ExhaleTestCase: The input cls is returned.

testing.decorators.default_confoverrides(cls, config)[source]

Apply the default configuration config to test class cls.

This configuration is set with a priority of 1 so that it may be overridden by the testing.decorators.confoverrides() decorator applied to test classes and functions.

Parameters

cls (Subclass of testing.base.ExhaleTestCase): The class to apply the config dictionary as confoverrides to.
config (dict): The dictionary of confoverrides as would be supplied to pytest.mark.sphinx. These are the overrides to conf.py.

Return

Subclass of testing.base.ExhaleTestCase: The input cls is returned.