core.runner

Support for executing and processing test trees.

Module Members

RunTimeFailureCatcher

Runner

RunningOrderBuilder

StackFrame

Status

StatusStore

saveStack()

stripCommonPrefix()

Classes

class core.runner.StackFrame

A snippet of code or program output.

Base class: tuple

core.runner.context

The code’s filename, line number, function name and context lines. These are simply copied from the standard Python frame object.

core.runner.funcname

The code’s filename, line number, function name and context lines. These are simply copied from the standard Python frame object.

core.runner.index

The code’s filename, line number, function name and context lines. These are simply copied from the standard Python frame object.

core.runner.lineno

The code’s filename, line number, function name and context lines. These are simply copied from the standard Python frame object.

core.runner.path

The code’s filename, line number, function name and context lines. These are simply copied from the standard Python frame object.

core.runner.tags

A set of short strings providing additional information about the frame. The values defined are:

‘outer’/’inner’

Whether the frame is part of the outer (framework) code or the actual test/fixture execution.

‘cov’

The frame appears to be part of Ned Batchelder’s coverage.py.

‘sys’

The frame appears to be for code that is part of Python, its standard library or an installed third party library.

‘cs’

The frame is part of the CleverSheep test framework.

‘assertion’

The frame is for a function that implements test assertion. Such functions are typically created by the assertion() decorator. By default, displayed tracebacks stop just before such functions.

‘string’

The code comes from an executed string and thus cannot be correctly assigned as ‘cov’, ‘sys’ or ‘cs’.

core.runner.__getnewargs__()

Return self as a plain tuple. Used by copy and pickle.

core.runner.__getstate__()

Exclude the OrderedDict from pickling

core.runner.__repr__()

Return a nicely formatted representation string

class core.runner.StatusStore(rtf=None)

Test status information.

Abstraction used as a base for Status and RunTimeFailureCatcher. In the case of a RunTimeFailureCatcher this is the single base class and the stack, excType and exc are set by the RunTimeFailureCatcher code. In the case of the Status class this is used as a mixin to extend the str class and and the stack, excType and exc are from a RunTimeFailureCatcher instance.

The stack attribute

Subclasses: RunTimeFailureCatcher Status

core.runner.exc

The type and instance of the raised exception. Both are None if no unhandled exception occurred.

core.runner.excType

The type and instance of the raised exception. Both are None if no unhandled exception occurred.

core.runner.stack

If an exception is caught then this will contain details of the stack as captured by saveStack(). If no unhandled exception occurred then this is an empty tuple.

core.runner.rootCause

One of the strings ‘fail’, ‘unexpectedFail’ or ‘possibleFrameworkBug’.

class core.runner.Status(value, rtf=None)

Test status. A string with additional information.

This is used to store the status of a test or one of its fixture methods. For a failure status this is initialised with a RunTimeFailureCatcher instance, which provides details of the stack and exception.

See StatusStore for details of the additional instance variables.

Base classes: str StatusStore

class core.runner.RunningOrderBuilder(rootSuite)

Helper class to prepare the test and fixture running order.

This is used to work out the order in which all selected test should be executed. Each test is also grouped with the pre and post fixture steps that are required.

__call__()

Build a running order sequence for a suite tree.

This generates a sequence of test execution groups. Each group is a dictionary with three phase entries, each containing a sequence of actions. The phases are:

pre-fixture

Can contain the suiteSetUp and setUp action.

test

Always has the test action and may also contain the postCheck action.

post-fixture

Can contain the tearDown and suiteTearDown action.

Each action is a tuple of (name, suite, function, test). The name is ‘setUp’, ‘test’, etc. The suite is the test.Suite instance or None. The function is the test/fixture function to be executed and the test is the tests.Test instance.

handleTest(suite, test)

Add fixture and execution funcions for a given test.

class core.runner.RunTimeFailureCatcher(rtf=None)

Context to catch any run-time exception and store details about it.

This is intended to be used like this:

with RunTimeFailureCatcher() as rtf:
    ...
if rtf:
    # An exception occurred.
    ...

The instance is unstable until the context has been exited. None of the instance variables or properties can be safely used until then. If no exception is caught then the instance will not contain any useful information.

See StatusStore for details of the instance variables.

Base class: StatusStore

getStack(getter)

Get a stack with as full a set of context lines as possible.

This uses the getter to extract a Python multiple times, using different contexts; essentially with different current working directories. This allows program code context to be obtained for more stack frames when ‘os.chdir()’ has been invoked between imports.

Arguments

getter

This must be a function that returns a Python stack. Typically this is inspect.getinnerframes or inspect.getouterframes ‘curried’ using functools.partial.

class core.runner.Runner(reporter, logger, recorder)

Controller of test runs.

This is responsible for the following:

• Running one or more tests, each within the appropriate fixture.
• Trapping any failures during the run.
• Informing its reporter, logger and recorder of key information during the execution of the tests.

Initialisation/cleanup

cleanUp()

Clean up after running a suite of tests.

After this has been invoked, this instance is not useable for running another suite.

setSuite(suite)

Set the root suite for this runner.

Other

run()

Perform a test run.

A RunningOrderBuilder instance is used to wrap each test into a fixture. Then each test is excuted within its fixture.