[py-svn] r6833 - py/dist/doc
hpk at codespeak.net
hpk at codespeak.net
Sun Oct 3 22:33:33 CEST 2004
Author: hpk
Date: Sun Oct 3 22:33:32 2004
New Revision: 6833
Added:
py/dist/doc/test.txt
Log:
a first draft of some documentation about the
py.test part.
Added: py/dist/doc/test.txt
==============================================================================
--- (empty file)
+++ py/dist/doc/test.txt Sun Oct 3 22:33:32 2004
@@ -0,0 +1,206 @@
+============================
+The py.test tool and library
+============================
+
+This is very much a draft version.
+
+The ``py.test`` command line tool
+=================================
+
+``py.test`` is the command line tool to run tests. If you
+provide it a file that contains functions or methods starting
+with ``test_`` then it will run those methods. Assertions
+about test outcomes are done via the standard ``assert``
+statement.
+
+The existence of a standalone ``py.test`` tool allows
+to write tests without any boilerplate:
+
+ def test_simple():
+ assert 42 == 43
+
+this would be the complete content of a test script
+and you can simply execute the tests by invoking:
+
+ py.test filename.py
+
+...
+
+Managing Test state 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:
+
+ 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.
+ """
+
+ def setup_class(cls):
+ """ setup up any objects specific to the execution
+ of the given class (which usually contains tests).
+ """
+ def teardown_class(cls):
+ """ teardown any objects that were previously setup
+ with a call to setup_class
+ """
+
+ def setup_method(self, method):
+ """ setup up objects tied to the execution of the given
+ method in a class. setup_method is invoked for every
+ test method of a class.
+ """
+ def teardown_method(self, method):
+ """ teardown any objects that were previously setup
+ 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
+decide to call the setup_module/teardown_module pair more than once
+during the execution of a test module.
+
+Note also that all setup/teardown methods are optional. For
+example, you can have a setup_module but no teardown_module
+and the other way round.
+
+
+
+how to write assertions
+-----------------------
+
+writing assertions is very simple in py.test and this
+is one of its most noticeable features:
+
+ You can simply use the ``assert`` statement.
+
+For example you can write:
+
+ assert hasattr(x, 'something')
+
+and in case this fails the ``test reporter`` will provide
+you with a very helpful analysis and a clean traceback.
+
+Please note that in order to display helpful analysis
+of a failing ``assert`` expression some magic takes
+place behind the scenes. For now, you only need to
+know that if something looks strange or you suspect
+a bug in that behind-the-scenes-magic you may turn
+of the magic by providing the ``--nomagic`` option.
+
+In order to write assertions regarding exceptions, you use
+one of two forms:
+
+ py.test.assert_raises(Exception, func, *args, **kwargs)
+ py.test.assert_raises(Exception, "func(*args, **kwargs)")
+
+both of which executes the given function with args and kwargs
+and asserts that the given ``Exception`` is raised. Again,
+in case of the two possible failures (no exception or wrong
+exception) the reporter provides you with helpful output.
+
+
+The three components of ``py.test``
+===================================
+
+In order to customize py.test you need to understand
+the basic architure of ``py.test``:
+
+ ___________________
+ | |
+ | Collector |
+ |___________________|
+ / \
+ | unit.execute(runner)
+ | /
+ collect/get units /
+ | /called for each
+ | /
+ ___________________/ ________________
+ | | send events | |
+ | Driver |----------------------->| Reporter |
+ |___________________| |________________|
+
+ .......................
+ . "utest.conf" .
+ . cmdline options .
+ .......................
+
+
+The *Driver* basically receives test *Units* from *Collector*.
+executes them via the ``Unit.execute()`` method, and takes the
+outcome (possibly an exception) and sends it over to the
+*reporter*.
+
+The test collection process
+===========================
+
+The collecting process is iterative, i.e. the driver
+does not get a complete list of all test units but
+can start immediately with the first tests that
+were collected.
+
+Also, the collectors are acompletly separated from any
+driving, execution or reporting details. Collectors
+have an __iter__ method, yielding more (sub) collectors or
+Test *Units*. 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
+----------------------------------------------
+
+If you have a module where you want to take responsibility for
+collecting specific test units and possibly even executing a
+test then you can provide your own ``Collector`` at module
+level. The default ModuleCollector looks for the name
+``Collector`` in the modules namespace and turns over
+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.
+It has two parts, a filesystem path and a dotted path leading
+to the python object. Among other niceties, this allows
+to easily invoke setup/teardown operations along the path
+leading up to the python object. *Addressability of test Units*
+is a major concern ...
+
+Customizing execution of Units
+------------------------------
+
+- Units allow total control of executing test methods
+
+- by providing custom collectors you can easily produce
+ your own unit class and instances
+
+- unitinstance.execute() gets called in order to execute a test
+
+- Unit.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.
+
+
+
+
More information about the pytest-commit
mailing list