core – Test Loading and Execution

core contains the primary interfaces for loading test specifications and case definitions. The operations and interface used in dtf build upon this infrastructure. If you want to implement a different base behavior test selection and running, use these classes as a starting point.

class core.CaseDefinition(case_paths=[])

Parameters:case_paths (list) – A list of paths that hold case definitions. May be empty upon object creation.

CaseDefinition is a base class for loading and importing cases into the dtf process. Sub-classes must implement load() and add() methods, depending on the desired behavior.

_add(f, path=None)

Parameters:

• f – A file name that contains the path name to _add() provides no validation of this module.
• path – Defaults to None. If specified, this becomes the path that dtf uses as the base path to import the module.

An internal method used to add a single case definition to a CaseDefinition object’s modules attribute. Typically CaseDefinition sub-classes’ add() methods will wrap _add().

_load_case(name, path)

Parameters:

• name – The name of the case definition, as you would use to import the module in a Python import statement.
• path – The filesystem path of the Python module.

Internal function to be called by import() which loads case donations into the current dtf instance. Will not not load a case named __init__.

add()

Not implemented in the base class. Raises a NotImplemented exception

case_paths = None

The list of paths that contain cases.

cases = None

A dictionary of loaded cases.

load()

Not implemented in the base class. Raises a NotImplemented exception

class core.MultiCaseDefinition(case_paths=[])

Provides an interface to add a group of case definition modules to the current dtf process. Use in conjunction with case_paths to load a directory of case modules.

add()

Adds all modules, recursively, in case_paths and calls _add() for each module. No arguments required when case_paths is set.

load()

If modules is empty, calls add() before iterating through modules and loading all relevant modules.

class core.MultiTestRunner(test_paths=[])

MultiTestRunner is a sub-class of TestRunner, intended as a base class for test runner implementations that run more than one test at a time.

load(path=None)

Parameters:path (string) – A relative or absolute path that contains test specifications.

This load() loads, (by way of _load_tree(), all .yaml test files within the specified path.

class core.SingleCaseDefinition(case_paths=[])

Provides an interface to add and load a single case definition. used by dtf for invocations that run a single test. May also be more efficent when running a suite of tests that depend on a single case module (this operational mode is not currently implemented.)

You do not need to instantiate SingleCaseDefinition with the case_paths` argument as in CaseDefinition, as it has no impact given the current implementation.

add(f, path=None)

A passthrough wrapper of _add().

load(filename)

Parameters:filename – The full path to the case definition module definition.

Given the full path of the case module, filename, load() will load the case definition into the current dtf instance.

Will produce a err.DtfDiscoveryException if:

1. You have not added this case using add(), or
2. The path of the filename does not exist.

The fundamental operation uses _load_case()

class core.SingleTestRunner(test_paths=[])

SingleTestRunner is a sub-class of TestRunner implements load() and run() to run a single test at a time. dtf --single uses this interface.

From a script, use SingleTestRunner to run a single test as follows:

dfn = SingleCaseDefinition()
dfn.load(<test>)

t = SingleTestRunner()
t.load(<case>)
t.definitions(dfn.cases)
t.run(<test-name>)

load(test)

Parameters:test (string) – The name of the test to load into dtf.

You must call load() after calling definitions().

run(test)

Parameters:test (string) – The name of the test to run.

Runs the single named test. If case_definition is None or if test_specs does not contain the specified test, run() raises DtfDiscoveryException.

To prevent make sure to call definitions() and load().

class core.SuiteTestRunner(test_paths=[])

SuiteTestRunner() is a sub-class of MultiTestRunner() that runs all test represented in the test_specs dict.

run(definitions=None)

Parameters:definitions (dict) – Optional. A dictionary in the format of case_definition, and if specified will override case_definition if specified.

Raises DtfDiscoveryException when definitions is not defined and case_definition is empty.

Runs all tests in test_specs sequentially.

class core.TestRunner(test_paths=[])

Parameters:test_paths (list) – A list of paths that contain test definitions. Empty by default.

TestRunner is a base class used as the basis for implementing interfaces for running dtf cases. Makes it possible for sub-classes to implement different operational modes with a common interface. TestRunner sub-classes implement running a single test, or running multiple tests at once with different parallelism options.

_add_to_queue(name, func)

Parameters:

• name (string) – The identifier of a the test.
• func (callable) – A callable that ipmplements the test.

Appends a three-tuple to the queue list, that dtf.

_load(spec)

Parameters:spec – The filename of a test spec.

An internal function to load a test function into the test_specs and :attr:`~core.TestRunner.queue attributes of the TestRunner object.

_load_tree(path)

Parameters:path – A file system path containing tests.

An internal method that recursively loads all .yaml files, selected using expand_tree(), in path using _load().

_run(name, func)

Parameters:

• name (string) – Specifies the name of the test, by the same name used in test_specs.
• func (callable) –

  A callable that takes two arguments:

  • name of the test.
  • the test spec.

Runs the test, passing the callable the name value, and the value of name in the dict test_specs, which is itself a dict representation of the test spec.

case_definition = None

A CaseDefinition() object.

definitions(definitions)

Parameters:definitions – A CaseDefinition() object.

Use definitions() to add CaseDefinition() after run-time. Provides fo a more gentle interface around the following operation in addition to the possibility for additional validation in the future:

t = TestRunner()
t.case_definitions = CaseDefinition(['cases/'])

load()

Raises :NotImplementedError.

Not Implemented in the base class. All sub-classes must implement load().

queue = None

A list of the test_specs used to support parallel test running.

run()

Raises :NotImplementedError.

Not Implemented in the base class. All sub-classes must implement run().

test_paths = None

A list of paths that contain tests. Passed as an argument when instantiating TestRunner.

test_specs = None

A dictionary of test specifications in the form of { <test_name>: <test_definitions> }