From 4a33940d82ac1cd1d569a62ccecdeb6b9cffd3de Mon Sep 17 00:00:00 2001 From: holger krekel Date: Mon, 13 Apr 2009 16:29:06 +0200 Subject: [PATCH] section on xUnit style setups, better linking, some streamlining --HG-- branch : trunk --- doc/test/features.txt | 14 +++++++- doc/test/funcargs.txt | 4 +-- doc/test/statemanage.txt | 65 ----------------------------------- doc/test/xunit_setup.txt | 73 ++++++++++++++++++++++++++++++++++++++++ 4 files changed, 88 insertions(+), 68 deletions(-) delete mode 100644 doc/test/statemanage.txt create mode 100644 doc/test/xunit_setup.txt diff --git a/doc/test/features.txt b/doc/test/features.txt index 68e0b2a71..1a535d162 100644 --- a/doc/test/features.txt +++ b/doc/test/features.txt @@ -36,8 +36,20 @@ or class with a leading ``Test`` name is collected. Rapidly write integration, functional, unit tests =================================================== -py.test provides +XXX +Unique test state setup/fixture methods +=================================================== + +py.test provides the `unique funcargs mechanism`_ +for constructing test fixtures and handling +complex test scenarios. You can also +use `traditional xUnit style setup`_ for +existing code bases or if you prefer +it for your unit tests. + +.. _`unique funcargs mechanism`: funcargs.html +.. _`traditional xUnit style setup`: xunit_setup.html load-balance tests to multiple CPUs =================================== diff --git a/doc/test/funcargs.txt b/doc/test/funcargs.txt index a24b97e9c..07b9ada03 100644 --- a/doc/test/funcargs.txt +++ b/doc/test/funcargs.txt @@ -153,7 +153,7 @@ into ``myapp.py``: def question(self): return 6 * 9 -.. _`local plugin`: test-ext.html#local-plugin +.. _`local plugin`: ext.html#local-plugin Example: specifying funcargs in test modules or classes --------------------------------------------------------- @@ -294,7 +294,7 @@ function argument is provided. Note that we make use here of `py.path.local`_ objects that provide uniform access to the local filesystem. -.. _`py.path.local`: path.html#local +.. _`py.path.local`: ../path.html#local Questions and Answers ================================== diff --git a/doc/test/statemanage.txt b/doc/test/statemanage.txt deleted file mode 100644 index a33383e81..000000000 --- a/doc/test/statemanage.txt +++ /dev/null @@ -1,65 +0,0 @@ -================= -Managing state -================= - -funcargs: provding arguments for test functions -=========================================================== - -XXX write docs - -Managing test state across test modules, classes and methods -============================================================ - -Often you want to create some files, database connections or 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. Again, ``py.test`` will detect these hooks in -modules on a name basis. The following module-level hooks will -automatically be called by the session:: - - def setup_module(module): - """ setup up any state specific to the execution - of the given module. - """ - - def teardown_module(module): - """ teardown any state that was previously setup - with a setup_module method. - """ - -The following hooks are available for test classes:: - - def setup_class(cls): - """ setup up any state specific to the execution - of the given class (which usually contains tests). - """ - - def teardown_class(cls): - """ teardown any state that was previously setup - with a call to setup_class. - """ - - def setup_method(self, method): - """ setup up any state 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 state that was previously setup - with a setup_method call. - """ - -The last two hooks, ``setup_method`` and ``teardown_method``, are -equivalent to ``setUp`` and ``tearDown`` in the Python standard -library's ``unitest`` module. - -All setup/teardown methods are optional. You could have a -``setup_module`` but no ``teardown_module`` and the other way round. - -Note that while the test session guarantees that for every ``setup`` a -corresponding ``teardown`` will be invoked (if it exists) it does -*not* guarantee that any ``setup`` is called only happens once. For -example, the session might decide to call the ``setup_module`` / -``teardown_module`` pair more than once during the execution of a test -module. diff --git a/doc/test/xunit_setup.txt b/doc/test/xunit_setup.txt new file mode 100644 index 000000000..d8d8756df --- /dev/null +++ b/doc/test/xunit_setup.txt @@ -0,0 +1,73 @@ +==================================== +xUnit style setup +==================================== + +.. _`funcargs`: funcargs.html +.. _`xUnit`: http://en.wikipedia.org/wiki/XUnit + +** Note that since version 1.0 py.test offers `funcargs`_ +for simple and complex test setup needs. Especially +if you want to do functional and integration testing, +but also fo runittesting, it is highly recommended +that you consider using `funcargs`_ for keeping +a clean and maintenable test suite. ** + +Python, Java and other languages have a tradition +of using xUnit_ style testing. This typically +involves the call of a ``setup`` method before +a test function is run and ``teardown`` after +it finishes. With ``py.test`` there are three +scopes for which you can provide setup/teardown +hooks to provide test fixtures: per-module, per-class +and per-method/function. ``py.test`` will +discover and call according methods automatically. +All setup/teardown methods are optional. + +The following methods are called at module level if they exist: + +.. sourcecode:: python + + def setup_module(module): + """ setup up any state specific to the execution + of the given module. + """ + + def teardown_module(module): + """ teardown any state that was previously setup + with a setup_module method. + """ + +The following hooks are available for test classes: + +.. sourcecode:: python + + def setup_class(cls): + """ setup up any state specific to the execution + of the given class (which usually contains tests). + """ + + def teardown_class(cls): + """ teardown any state that was previously setup + with a call to setup_class. + """ + + def setup_method(self, method): + """ setup up any state 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 state that was previously setup + with a setup_method call. + """ + +The last two hooks, ``setup_method`` and ``teardown_method``, are +equivalent to ``setUp`` and ``tearDown`` in the Python standard +library's `unittest.py module`_. + +Note that it possible that setup/teardown pairs are invoked multiple +times per testing process. + +.. _`unittest.py module`: http://docs.python.org/library/unittest.html +