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 topytest.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 topytest.mark.sphinx
. These are the overrides toconf.py
.
- Return
- (
class
ortypes.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 checkif isinstance(self.testroot, six.string_types)
.As such, since
self.testroot
may be desired in the given@no_cleanup
function, you must acquire it withtestroot = 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 parameterself
.
- Return
- (
types.FunctionType
) The decorated function, which simply calls the provided function and sets
self.testroot = None
. Click on[source]
link forExhaleTestCaseMetaclass.__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
ortypes.FunctionType
)The class or function to disable exhale from generating reStructuredText documents for.
- Return
class
ortypes.FunctionType
The decorated
obj
.
Decorator Helper Functions¶
-
testing.decorators.
_apply_confoverride_to_class
(cls, config, priority)[source]¶ Apply a configuration override
config
to classcls
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 ofkwargs
to apply topytest.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 oftesting.base.ExhaleTestCase
)The class to apply the
confoverride
to.config
(dict
)The dictionary of
confoverrides
as would be supplied topytest.mark.sphinx
. These are the overrides toconf.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 is1
. When the decoratortesting.decorators.confoverrides()
is applied to a class, the priority is2
. Finally, whentesting.decorators.confoverrides()
is applied to a test function, its priority is3
. 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.
- Subclass of
-
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 thetesting.decorators.confoverrides()
decorator applied to test classes and functions.- Parameters
cls
(Subclass oftesting.base.ExhaleTestCase
)The class to apply the
config
dictionary asconfoverrides
to.config
(dict
)The dictionary of
confoverrides
as would be supplied topytest.mark.sphinx
. These are the overrides toconf.py
.
- Return
- Subclass of
testing.base.ExhaleTestCase
The input
cls
is returned.
- Subclass of