========== core.tests ========== .. toctree:: :hidden: .. index:: core.tests .. module:: core.tests :noindex: 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 ============== | :class:`~ClassSuite` | :class:`~DirSuite` | :class:`~ModuleSuite` | :attr:`~PASS` | :class:`~Suite` | :class:`~Test` | :class:`~TestItem` .. index:: PASS; cstest.core.tests .. data:: PASS :noindex: 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:: TestItem() Base for `Test` and types of `Suite`. .. graphviz:: digraph foo { rankdir=BT; ranksep=0.3; node[fontsize=10 margin=0.01 height=0.2 width=0.4]; edge[arrowsize=0.6 arrowhead=onormal]; "cstest.core.tests.TestItem" [color=blue height=0.4 width=0.6]; "cstest.core.tests.Suite" -> "cstest.core.tests.TestItem"; "cstest.core.tests.Test" -> "cstest.core.tests.TestItem"; } Subclasses: :class:`~cstest.core.tests.Suite` :class:`~cstest.core.tests.Test` .. property:: summary :noindex: The summary text for a test item. This is the first paragraph of the item's docstring. .. class:: 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 :attr:`info`. .. graphviz:: digraph foo { rankdir=BT; ranksep=0.3; node[fontsize=10 margin=0.01 height=0.2 width=0.4]; edge[arrowsize=0.6 arrowhead=onormal]; "cstest.core.tests.Test" [color=blue height=0.4 width=0.6]; "cstest.core.tests.Test" -> "cstest.core.tests.TestItem"; } Base class: :class:`~cstest.core.tests.TestItem` .. index:: func; cstest.core.tests.Test .. attribute:: func :noindex: The actual function instance that is invoked when the test is executed. .. index:: info; cstest.core.tests.Test .. attribute:: info :noindex: A :class:`TestInfo` that carries addiional infomrmation about the test. .. index:: parent; cstest.core.tests.Test .. attribute:: parent :noindex: A weak reference to the parent suite. .. index:: status; cstest.core.tests.Test .. attribute:: status :noindex: 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. .. property:: uid :noindex: A tuple uniquely identifying this test. .. property:: name :noindex: The (function) name of this test. .. property:: details :noindex: A list of lines provoding the detailed description of this test. This is the second and subsequent paragraphs of the tests's docstring. .. property:: ancestors :noindex: 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. .. property:: level :noindex: The level for this test. The outermost suite has level zero. Its child suites and tests have a level of one, and so on. .. property:: testID :noindex: The optional test ID string. This is the ID defined by the ``testID`` argument of the :func:`test` decorator. It is ``None`` for tests that have no ID. .. property:: isMarkedBroken :noindex: Check is this is test is maked as currently broken. .. property:: hasFailed :noindex: True if the test's status indicates a failure. A test is only considered failed if the actual text function or postCheck function failed. .. property:: fixtureFailed :noindex: 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 :meth:`hasFailed` property must be used to detect an actual test failure. .. method:: getPhaseProblems(phaseName) :noindex: Get list of problems encountered running a test and its fixture. .. class:: 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. .. graphviz:: digraph foo { rankdir=BT; ranksep=0.3; node[fontsize=10 margin=0.01 height=0.2 width=0.4]; edge[arrowsize=0.6 arrowhead=onormal]; "cstest.core.tests.Suite" [color=blue height=0.4 width=0.6]; "cstest.core.tests.Suite" -> "cstest.core.tests.TestItem"; "cstest.core.tests.ClassSuite" -> "cstest.core.tests.Suite"; "cstest.core.tests.DirSuite" -> "cstest.core.tests.Suite"; "cstest.core.tests.ModuleSuite" -> "cstest.core.tests.Suite"; } Base class: :class:`~cstest.core.tests.TestItem` Subclasses: :class:`~cstest.core.tests.ClassSuite` :class:`~cstest.core.tests.DirSuite` :class:`~cstest.core.tests.ModuleSuite` .. index:: fixtureFunctions; cstest.core.tests.Suite .. attribute:: fixtureFunctions :noindex: A dictionary for any defined fixtureFunctions methods (suiteSetUp, setUp, tearDown, *etc*.) .. index:: isActive; cstest.core.tests.Suite .. attribute:: isActive :noindex: 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. .. index:: suites; cstest.core.tests.Suite .. attribute:: suites :noindex: A sequence of the sub-suites within this suite. .. index:: tests; cstest.core.tests.Suite .. attribute:: tests :noindex: A sequence of the tests within this suite. .. property:: level :noindex: The level for this suite. The outermost suite has level zero. Its child suites have a level of one, and so on. .. property:: ancestors :noindex: 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. .. rubric:: Querying .. method:: getFixtureFunc(name) :noindex: Get the function that implements part of the text fixtre provided by this suite. **Arguments** *name* Should be one of suiteSetUp, setUp, tearDown, suiteTearDown. .. rubric:: Hierarchy .. method:: addFixtureFunction(name, func) :noindex: Add a function to the set of functions provided by this suite. **Arguments** *name*, *func* The name of the function and the function itself. .. method:: addSuite(suite) :noindex: Add a suite to this suite of tests. **Arguments** *suite* A `Suite` instance. .. method:: addTest(test) :noindex: Add a test to this suite. **Arguments** *test* A `Test` instance. .. method:: walk(testCallback, suiteCallback=None, sentinel=False) :noindex: 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:: 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. .. graphviz:: digraph foo { rankdir=BT; ranksep=0.3; node[fontsize=10 margin=0.01 height=0.2 width=0.4]; edge[arrowsize=0.6 arrowhead=onormal]; "cstest.core.tests.ClassSuite" [color=blue height=0.4 width=0.6]; "cstest.core.tests.ClassSuite" -> "cstest.core.tests.Suite"; } Base class: :class:`~cstest.core.tests.Suite` .. property:: uid :noindex: A tuple uniquely identifying this test. .. property:: name :noindex: The (class) name of this test. .. class:: 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. .. graphviz:: digraph foo { rankdir=BT; ranksep=0.3; node[fontsize=10 margin=0.01 height=0.2 width=0.4]; edge[arrowsize=0.6 arrowhead=onormal]; "cstest.core.tests.ModuleSuite" [color=blue height=0.4 width=0.6]; "cstest.core.tests.ModuleSuite" -> "cstest.core.tests.Suite"; } Base class: :class:`~cstest.core.tests.Suite` .. property:: name :noindex: The name of this module. .. method:: setNamespace(namespace) :noindex: Set the dictionary that defines the namespace for this module. .. class:: 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. .. graphviz:: digraph foo { rankdir=BT; ranksep=0.3; node[fontsize=10 margin=0.01 height=0.2 width=0.4]; edge[arrowsize=0.6 arrowhead=onormal]; "cstest.core.tests.DirSuite" [color=blue height=0.4 width=0.6]; "cstest.core.tests.DirSuite" -> "cstest.core.tests.Suite"; } Base class: :class:`~cstest.core.tests.Suite` .. property:: name :noindex: The name of this suite.