core.tests

Definitions of tests, suites, test states, etc.

This provides classes to represent tests, test suites and various supporting objects.

For the future:

Of particular importance is the test decorator.

Module Members

ClassSuite

DirSuite

ModuleSuite

PASS

Suite

Test

TestItem

core.tests.PASS

Each test carries a number of status flags. Each flag can be set to several values.

result    selected  markers
"PASS"    "YES"     "BUG" "BROKEN"
"FAIL"    "NO"
"NOT_RUN"

Most have obvious meanings. BUG means that the test is intended to demonstrate a current (unfixed) bug. BROKEN means that the test has become broken, so a failure does not necessarily indicate that the code under test has a bug.

The result and selected are transient flags, which only have meaning for a particular test run. The markers are set by the test decorator. A test can have multiple markers, but only one value for the result and selected flags.

Classes

class core.tests.TestItem

Base for Test and types of Suite.

Subclasses: Suite Test

core.tests.summary

The summary text for a test item.

This is the first paragraph of the item’s docstring.

class core.tests.Test(func, suite, info)

A managed test.

Every test method or function gets wrapped up in one of these.

Arguments

func suite info

The function that implements the test, its parent suite and the test information.

TODO: Define type of info.

Base class: TestItem

core.tests.func

The actual function instance that is invoked when the test is executed.

core.tests.info

A TestInfo that carries addiional infomrmation about the test.

core.tests.parent

A weak reference to the parent suite.

core.tests.status

A dictionary that records the status of the test for the most recent or current test run. The keys are ‘pre-fixture’, ‘test’ and ‘post-fixture’. The entries are tuples of (stage, result), where the stage is “setUp”, “suiteSetUp”, etc. and the result is ‘pass’ or a RunTimeFailureCatcher instance. Entries are only added when a specific stage is executed.

core.tests.uid

A tuple uniquely identifying this test.

core.tests.name

The (function) name of this test.

core.tests.details

A list of lines provoding the detailed description of this test.

This is the second and subsequent paragraphs of the tests’s docstring.

core.tests.ancestors

A list of this test’s ancestor suites.

The list is oldest first, so the last ancestor is the suite that this test is part of.

core.tests.level

The level for this test.

The outermost suite has level zero. Its child suites and tests have a level of one, and so on.

core.tests.testID

The optional test ID string.

This is the ID defined by the testID argument of the test() decorator. It is None for tests that have no ID.

core.tests.isMarkedBroken

Check is this is test is maked as currently broken.

core.tests.hasFailed

True if the test’s status indicates a failure.

A test is only considered failed if the actual text function or postCheck function failed.

core.tests.fixtureFailed

True if any part of the fixture failed, even of the test passed.

This is used to indicate that some problems other than test failure occurred. The hasFailed() property must be used to detect an actual test failure.

core.tests.getPhaseProblems(phaseName)

Get list of problems encountered running a test and its fixture.

class core.tests.Suite(parent)

Base for all types of managed test suites.

Arguments

parent

The parent suite, which will be None if this is the root of a test suite hierarchy.

Base class: TestItem

Subclasses: ClassSuite DirSuite ModuleSuite

core.tests.fixtureFunctions

A dictionary for any defined fixtureFunctions methods (suiteSetUp, setUp, tearDown, etc.)

core.tests.isActive

This is altered during a test run. When set, then one of its tests or a tests in a descendent suite is the one currently selected to be run. It is principally used to work out when suiteSetUp and suiteTearDown should be invoked.

core.tests.suites

A sequence of the sub-suites within this suite.

core.tests.tests

A sequence of the tests within this suite.

core.tests.level

The level for this suite.

The outermost suite has level zero. Its child suites have a level of one, and so on.

core.tests.ancestors

A list of this test’s ancestor suites.

The list is oldest first, so the last ancestor is the suite that this suite is part of.

Querying

core.tests.getFixtureFunc(name)

Get the function that implements part of the text fixtre provided by this suite.

Arguments

name

Should be one of suiteSetUp, setUp, tearDown, suiteTearDown.

Hierarchy

core.tests.addFixtureFunction(name, func)

Add a function to the set of functions provided by this suite.

Arguments

name, func

The name of the function and the function itself.

core.tests.addSuite(suite)

Add a suite to this suite of tests.

Arguments

suite

A Suite instance.

core.tests.addTest(test)

Add a test to this suite.

Arguments

test

A Test instance.

core.tests.walk(testCallback, suiteCallback=None, sentinel=False)

Perform recursive walk of this suite.

The walk visits immediate child tests before child suites. For each suite and test the provided callback is invoked. The suiteCallback is invoked on this Suite before the walk begins.

Arguments

testCallback

This is invoked as testCallback(suite, test) or each Test instance encountered.

suiteCallback

This is invoked as wih this Suite instance before walking the child tests and suites.

sentinel

If this is a value that evaluates as True then the testCallback is invoked as testCallback(suite, None) after the last test for each suite is processed.

class core.tests.ClassSuite(cls, parent)

A managed suite of tests as collected from a Python class.

Arguments

parent

The parent suite, which will be None if this is the root of a test suite hierarchy.

Base class: Suite

core.tests.uid

A tuple uniquely identifying this test.

core.tests.name

The (class) name of this test.

class core.tests.ModuleSuite(path, parent)

A managed suite of tests as collected from a Python module.

Arguments

parent

The parent suite, which will be None if this is the root of a test suite hierarchy.

Base class: Suite

core.tests.name

The name of this module.

core.tests.setNamespace(namespace)

Set the dictionary that defines the namespace for this module.

class core.tests.DirSuite(path, parent, execDir)

A managed suite of tests as collected from a file system directory.

Arguments

parent

The parent suite, which will be None if this is the root of a test suite hierarchy.

Base class: Suite

core.tests.name

The name of this suite.