Testing Base Module

Defines the core sphinx project based test case utilities.

All project based test cases should inherit from testing.base.ExhaleTestCase.

testing.base.make_default_config(project)

Return a default configuration for exhale.

Parameters

project (str)

The name of the project that will be searched for in testing/projects/{project}.

Return

dict

The global default testing configuration to supply to confoverrides with @pytest.mark.sphinx, these are values that would ordinarily be written in a conf.py.

class testing.base.ExhaleTestCaseMetaclass(name, bases, attrs)

Metaclass to enforce mandatory attributes on testing.base.ExhaleTestCase.

static __new__(mcs, name, bases, attrs)

Return a new instance with the specified attributes.

Parameters

mcs (type)

This metaclass (testing.base.ExhaleTestCaseMetaclass).

name (str)

The name of the class being instantiated.

bases (list)

The list of base classes of name.

attrs (dict)

The class-level attributes. These will be inspected / modified as needed to produce a final class definition that can use sphinx test applications where desired.

class testing.base.ExhaleTestCase(methodName='runTest')

The primary project based test class to inherit from.

The __metaclass__ is set to testing.base.ExhaleTestCaseMetaclass. Inherits from unittest.TestCase.

Attributes Populated by the Metaclass Fixtures for Each Test

These attributes are populated during the setup of a test function, and then later set to None during the test function teardown. These are only available inside the method body of a testing function (a function with a name starting with test_).

self.app (sphinx.testing.util.SphinxTestApp)

The sphinx testing application. Acquire the conf.py values (and corresponding @confoverrides) via self.app.config like any traditional sphinx application.

self.testroot (str)

The testroot supplied to pytest.mark.sphinx, the “docs” directory. Its value will be testing/projects/{test_project}/docs_{ClassName}_{test_function_name}.

Todo

This value is saved in order to be able to distinguish when a “separate source and build” directory is being tested. At this time this is not fully implemented, self.app.srcdir should be a subdirectory of self.testroot and conf.py / index.rst should be generated there.

Currently, these are always generated in testroot, implying that there is no “separate source and build” directory structure. Solution requires further investigation of the sphinx testing suite.

Danger

As a consequence, running tests in parallel is not and never will be supported (e.g., when running tox -e py).

test_project = None

The string representing the project to run Doxygen / exhale on.

This variable is used to index into testing/projects/{test_project}. For example, with test_project = "c_maths", the directory used is testing/projects/c_maths. That is, this variable is joined with the path defined by testing.TEST_PROJECTS_ROOT.

This class-level string variable must be set in subclasses.

cross_validate(contents, required=None, forbidden=None)

Validate all required and no forbidden items found in contents.

For each item in required an assertion of item in contents is made, and for each item in forbidden an assertion of item not in contents is made.

If neither required nor forbidden are supplied, no checks are performed.

Parameters

contents (str or Iterable)

The contents to cross validate that all required items and no forbidden items are found in.

required (None or Iterable)

The listing of all required entries that are required to be in contents.

forbidden (None or Iterable)

The listing of all forbidden entries that are not allowed in contents.

contents_for_node(node)

Return the generated file contents for the specified node.

Parameters

node (exhale.graph.ExhaleNode)

The node whose generated file contents are desired. Note that this must be a proper ExhaleNode instance, since node.file_name is what is used. That is, a mocked testing node should not be used!

Return (str)

The contents of node.file_name.

Raises

If os.path.join(self.getAbsContainmentFolder(), node.file_name) does not exist.

getAbsContainmentFolder()

Return the absolute path to "containmentFolder".

If exhale_args["containmentFolder"] is an absolute path, it will be returned unchanged. Otherwise, it will be resolved against app.srcdir.

Return

str

An absolute path to the "containmentFolder" where Exhale will be generating its reStructuredText documents.

Note

When platform.system() == "Windows", this string will always be prefixed with \\?\ to deal with maximum path length issues. This is to accommodate the somewhat long containment folders generated by using the testing class name as well as the test name. See MAXIMUM_WINDOWS_PATH_LENGTH for more information.

If this is not done, then even if self.app.build() is skipped for the test cases that cause this (in CPPLongNames), shutil.rmtree() will crash during test teardown. Better to just always include it.

checkRequiredConfigs()

Validate the four required configuration arguments in exhale_args.

1. Checks that {containmentFolder} was created.

2. Checks that {containmentFolder}/{rootFileName} was created.

3. Checks that {rootFileTitle} is found in {containmentFolder}/{rootFileName}.

Todo

4. identify via a file_* method that {doxygenStripFromPath} was correctly removed / wielded.

Automatically Tested

This method is tested automatically for every derived type of ExhaleTestCase that is not decorated with no_run(). The metaclass ExhaleTestCaseMetaclass generates a testing method test_common that invokes this method.

checkAllFilesGenerated()

Validate that all files are actually generated.

Automatically Tested

This method is tested automatically for every derived type of ExhaleTestCase that is not decorated with no_run(). The metaclass ExhaleTestCaseMetaclass generates a testing method test_common that invokes this method.

checkAllFilesIncluded()

Validate that all files are actually included in the library root.

Automatically Tested

This method is tested automatically for every derived type of ExhaleTestCase that is not decorated with no_run(). The metaclass ExhaleTestCaseMetaclass generates a testing method test_common that invokes this method.