[py-svn] r36895 - in py/branch/conftest/py: doc test
hpk at codespeak.net
hpk at codespeak.net
Thu Jan 18 05:31:11 CET 2007
Author: hpk
Date: Thu Jan 18 05:31:10 2007
New Revision: 36895
Modified:
py/branch/conftest/py/doc/test.txt
py/branch/conftest/py/test/collect.py
py/branch/conftest/py/test/session.py
Log:
shift some documentation to docstrings,
fix an inheritance problem uncovered by that.
Modified: py/branch/conftest/py/doc/test.txt
==============================================================================
--- py/branch/conftest/py/doc/test.txt (original)
+++ py/branch/conftest/py/doc/test.txt Thu Jan 18 05:31:10 2007
@@ -422,38 +422,6 @@
.. _`collector API`:
-collector API invoked by sessions
----------------------------------
-
-Apart from initialization the default session object invokes
-a very uniform API on collectors and test items:
-
-*colitem.run()*
-
- returns a list of names available from this collector.
- You can return an empty list. Callers of this method
- must take care to catch exceptions properly. The session
- object guards its calls to ``colitem.run()`` in its
- ``session.runtraced(colitem)`` method, including
- catching of stdout.
-
-*colitem.join(name)*
-
- return a child item from the given name. Usually the
- session feeds the join method with each name obtained
- from ``colitem.run()``. If the return value is None
- it means the ``colitem`` was not able to resolve
- with the given name.
-
-*colitem.parent*
-
- attribute pointing to the parent collector.
-
-*colitem.name*
-
- name of this sub item. This is the name that is
- passed to ``colitem.join()`` above.
-
test items are collectors as well
---------------------------------
@@ -507,48 +475,16 @@
and test classes and methods. Test functions and methods
are prefixed ``test`` by default. Test classes must
start with a capitalized ``Test`` prefix.
-
-Reporting hooks of the session object
--------------------------------------
-
-Part of the default session API deals with reporting
-test outcomes and collection details. These methods
-are reponsible for representing the testing process
-to the user or other programs:
-
-*session.header()*
-
- invoked once by ``session.run()`` before the whole
- test session starts.
-*session.footer()*
-
- invoked once by ``session.run()`` after the collection
- and running process finished.
-
-
-*session.start(colitem)*
-
- invoked before each ``colitem.run()`` invocation
-
-
-*session.finish(colitem, outcome)*
-
- invoked after each ``colitem.run()`` invocation
+Customizing the testing process
+===============================
+writing conftest.py files
+-----------------------------------
-XXX the names of these session objects are likely to change
-soon because the session object now has too many names that
-aren't easily distinguishable regarding their purposes. It is
-also likely that collectors/test items will become more
-self-responsible for presenting outcomes in textual ways.
-Currently, session object have to know too much about the
-representation of failures/successes to the user which makes
-it harder than neccessary to write custom test items.
+XXX
-Customizing the testing process
-===============================
customizing the collecting and running process
-----------------------------------------------
Modified: py/branch/conftest/py/test/collect.py
==============================================================================
--- py/branch/conftest/py/test/collect.py (original)
+++ py/branch/conftest/py/test/collect.py Thu Jan 18 05:31:10 2007
@@ -55,6 +55,14 @@
return current
class Collector(object):
+ """ Collector instances are iteratively generated
+ (through their run() and join() methods)
+ and form a tree. attributes::
+
+ parent: attribute pointing to the parent collector
+ (or None if it is the root collector)
+ name: basename of this collector object
+ """
def __init__(self, name, parent=None):
self.name = name
self.parent = parent
@@ -113,6 +121,25 @@
#print "cmp", s1, s2
return cmp(s1, s2)
+
+ def run(self):
+ """ returns a list of names available from this collector.
+ You can return an empty list. Callers of this method
+ must take care to catch exceptions properly. The session
+ object guards its calls to ``colitem.run()`` in its
+ ``session.runtraced(colitem)`` method, including
+ catching of stdout.
+ """
+ raise NotImplementedError("abstract")
+
+ def join(self, name):
+ """ return a child item for the given name. Usually the
+ session feeds the join method with each name obtained
+ from ``colitem.run()``. If the return value is None
+ it means the ``colitem`` was not able to resolve
+ with the given name.
+ """
+
def obj():
def fget(self):
try:
@@ -454,7 +481,7 @@
Collector.Function.__get__(self)) # XXX for python 2.2
Function = property(Function)
-class Generator(Collector, PyCollectorMixin):
+class Generator(PyCollectorMixin, Collector):
def run(self):
self._prepare()
itemlist = self._name2items
Modified: py/branch/conftest/py/test/session.py
==============================================================================
--- py/branch/conftest/py/test/session.py (original)
+++ py/branch/conftest/py/test/session.py Thu Jan 18 05:31:10 2007
@@ -13,20 +13,21 @@
return False
def header(self, colitems):
- """ setup any neccessary resources. """
+ """ setup any neccessary resources ahead of the test run. """
if not self.config.option.nomagic:
py.magic.invoke(assertion=1)
def footer(self, colitems):
- """ teardown any resources we know about. """
+ """ teardown any resources after a test run. """
py.test.Function.state.teardown_all()
if not self.config.option.nomagic:
py.magic.revoke(assertion=1)
def start(self, colitem):
- pass
+ """ hook invoked before each colitem.run() invocation. """
def finish(self, colitem, outcome):
+ """ hook invoked after each colitem.run() invocation. """
self._memo.append((colitem, outcome))
def startiteration(self, colitem, subitems):
More information about the pytest-commit
mailing list