[py-svn] r6845 - py/dist/doc

[hpk at codespeak.net]

Author: hpk
Date: Mon Oct  4 15:49:22 2004
New Revision: 6845

Modified:
   py/dist/doc/test.txt
Log:
small rest and content fixes here and there 


Modified: py/dist/doc/test.txt
==============================================================================
--- py/dist/doc/test.txt	(original)
+++ py/dist/doc/test.txt	Mon Oct  4 15:49:22 2004
@@ -26,18 +26,20 @@
 
 ... 
 
-Managing Test state across test modules, classes and methods 
-============================================================ 
+Managing test data across test modules, classes and methods 
+===========================================================
 
 Often you want to create some test files, db-connections or
-other state.  With ``py.test`` there are three scopes for
-which you can provide hooks.  These hooks will get called by
-the runner: 
+other state in order to run tests in a certain environment.  
+With ``py.test`` there are three scopes for which you can
+provide hooks to manage such state.  These hooks will get 
+called by the driver::
 
     def setup_module(cls, module):
         """ setup up any objects specific to the execution
             of the given module. 
         """
+
     def teardown_module(cls, module):
         """ teardown any objects that were previously setup 
             with a setup_module method. 
@@ -62,9 +64,9 @@
             with a setup_method call. 
         """
 
-While the test runner guarantees that for every ``setup`` a
-``teardown`` will be invoked (it exists) it does *not* guarantee 
-that it only happens once. For example, the runner might 
+While the test driver guarantees that for every ``setup`` a
+``teardown`` will be invoked (if it exists) it does *not* guarantee 
+that it only happens once. For example, the driver might 
 decide to call the setup_module/teardown_module pair more than once 
 during the execution of a test module. 
 
@@ -97,7 +99,7 @@
 of the magic by providing the ``--nomagic`` option. 
 
 In order to write assertions regarding exceptions, you use
-one of two forms: 
+one of two forms::
 
     py.test.assert_raises(Exception, func, *args, **kwargs) 
     py.test.assert_raises(Exception, "func(*args, **kwargs)")
@@ -112,14 +114,14 @@
 ===================================
 
 In order to customize py.test you need to understand 
-the basic architure of ``py.test``: 
+the basic architure of ``py.test``::
 
      ___________________
     |                   |
     |    Collector      |
     |___________________|
            / \                
-            |                Item.execute(runner)
+            |                Item.execute(driver)
             |               ^
      receive test Items    /
             |             /execute test Item 
@@ -135,33 +137,35 @@
                         .......................
 
 
-The *Driver* basically receives test *Items* from *Collector*.
+The *Driver* basically receives test *Items* from a *Collector*, 
 executes them via the ``Item.execute()`` method, and takes the
 outcome (possibly an exception) and sends it over to the
-*reporter*.  
+*reporter* instance.  
+
 
 The test collection process 
 =========================== 
 
 The collecting process is iterative, i.e. the driver 
-get test Items one by one and can thus start to execute 
-the first collected test Item. 
+get test Items one by one and can thus start immediately 
+to execute the first collected test Item. 
+
+Also, the collectors are completly separated from any driving,
+execution or reporting details.  Collectors have an __iter__
+method, yielding more (sub) collectors or Test *Items*.  They
+should usually not raise exceptions but yield back a specific
+CollectError. This is to avoid that a collecting error
+interrupts the whole collection process. 
+
+Usually, ``py.test`` collects test files that match the glob
+patterns ``test_*.py`` or ``*_test.py`` and it recurses into
+any directory that doesn't start with a leading dot (e.g.
+``.svn`` is ignored). 
+
+It then recurses into the test files and collects functions
+and methods that have a leading ``test_`` name, unless you
+provide a custom collector in your module. 
 
-Also, the collectors are acompletly separated from any
-driving, execution or reporting details.  Collectors 
-have an __iter__ method, yielding more (sub) collectors or
-Test *Items*.  They should usually not raise exceptions but
-yield back a specific CollectError. This is to avoid that a
-collecting error interrupts the whole collection process. 
-
-Usually, ``py.test`` collects test files that match 
-the glob patterns ``test_*.py`` or ``*_test.py`` and 
-it recurses into any directory that doesn't start 
-with a leading dot (e.g. ``.svn`` is ignored). 
-
-It then recurses into the test files and collects
-functions and methods that have a leading ``test_`` name, 
-unless you provide a custom collector in your module. 
 
 Customizing the collection process in a module
 ---------------------------------------------- 
@@ -174,30 +178,30 @@
 reponsibility by invoking it with the "module-path". 
 
 The module path is a ``py.path.py()`` instance and carries
-information needed to get to the module.  Generally, a pypath
-allows to address a python object in the filesystem.
+information needed to traverse to to the module.  In general, 
+a pypath allows to address a python object on the filesystem.
 *Addressability of test Items* is a major concern because we
 want to memorize failing tests across py.test invocations.  A
 ``pypath`` has two parts, a filesystem path and a dotted path
-leading to the python object.  Another benefits apart from 
-from addressability is that invoking setup/teardown operations 
-can simply be implemented by walking the path path to the python 
+leading to the python object.  Another benefits, apart from 
+from addressability, is that invoking setup/teardown operations 
+can simply be implemented by walking the path to the python 
 object. 
 
 Customizing execution of Items 
 ------------------------------ 
 
-- Items allow total control of executing test methods 
-
-- by providing custom collectors you can easily produce
-  your own Item class and instances 
-
-- Iteminstance.execute() gets called in order to execute a test 
+- Items allow total control of executing their contained test
+  method.  iteminstance.execute() gets called in order to 
+  execute a test. 
 
 - Item.execute() methods can provide custom paramters 
   (a db-connection, some initialized application entity, whatever) 
   to the actual underlying method being invoked. 
 
-- lift some of the arbitrary restrictions of unittest.py: allow
-  test functions and allow classes to just provide "grouping" for 
-  tests. 
+- by providing custom collectors you can easily produce
+  your own Item instances 
+
+- lift some of the arbitrary restrictions of unittest.py: 
+  allow plain test functions (without being in a class) and 
+  allow classes to simply mean "grouping" of tests.