From a7d646c5e7db7f0f67f19ea73db056abdc269001 Mon Sep 17 00:00:00 2001 From: holger krekel Date: Wed, 5 May 2010 21:01:54 +0200 Subject: [PATCH] updating docs --HG-- branch : trunk --- bin-for-dist/makepluginlist.py | 8 ++-- doc/install.txt | 2 +- doc/test/plugin/hookspec.txt | 81 ++++++++++++++++++++++------------ doc/test/plugin/links.txt | 36 +++++++-------- doc/test/plugin/skipping.txt | 21 +++++++-- doc/test/plugin/terminal.txt | 4 +- doc/test/plugin/xdist.txt | 12 ----- 7 files changed, 95 insertions(+), 69 deletions(-) diff --git a/bin-for-dist/makepluginlist.py b/bin-for-dist/makepluginlist.py index bf2152541..321a0f362 100644 --- a/bin-for-dist/makepluginlist.py +++ b/bin-for-dist/makepluginlist.py @@ -151,10 +151,10 @@ class PluginOverview(RestWriter): class HookSpec(RestWriter): def makerest(self, config): - module = config.pluginmanager.hook._hookspecs - source = py.code.Source(module) - self.h1("hook specification sourcecode") - self.sourcecode(source) + for module in config.pluginmanager.hook._hookspecs: + source = py.code.Source(module) + self.h1("hook specification sourcecode") + self.sourcecode(source) class PluginDoc(RestWriter): def makerest(self, config, name): diff --git a/doc/install.txt b/doc/install.txt index 67d727c4d..1e895fa3b 100644 --- a/doc/install.txt +++ b/doc/install.txt @@ -4,7 +4,7 @@ py.test/pylib installation info in a nutshell =================================================== -**Pythons**: 2.4, 2.5, 2.6, 3.0, 3.1, Jython-2.5.1, PyPy-1.1 +**Pythons**: 2.4, 2.5, 2.6, 3.0, 3.1, 3.2, Jython-2.5.1, PyPy-1.2 **Operating systems**: Linux, Windows, OSX, Unix diff --git a/doc/test/plugin/hookspec.txt b/doc/test/plugin/hookspec.txt index bbfe81055..a0034b7ca 100644 --- a/doc/test/plugin/hookspec.txt +++ b/doc/test/plugin/hookspec.txt @@ -12,11 +12,14 @@ hook specification sourcecode # Command line and configuration # ------------------------------------------------------------------------- - def pytest_addoption(parser): - """ called before commandline parsing. """ - def pytest_namespace(): - """ return dict of name->object which will get stored at py.test. namespace""" + "return dict of name->object which will get stored at py.test. namespace" + + def pytest_addoption(parser): + "add optparse-style options via parser.addoption." + + def pytest_addhooks(pluginmanager): + "add hooks via pluginmanager.registerhooks(module)" def pytest_configure(config): """ called after command line options have been parsed. @@ -30,6 +33,13 @@ hook specification sourcecode # collection hooks # ------------------------------------------------------------------------- + def pytest_ignore_collect(path, config): + """ return true value to prevent considering this path for collection. + This hook is consulted for all files and directories prior to considering + collection hooks. + """ + pytest_ignore_collect.firstresult = True + def pytest_collect_directory(path, parent): """ return Collection node or None for the given path. """ pytest_collect_directory.firstresult = True @@ -58,6 +68,14 @@ hook specification sourcecode # Python test function related hooks # ------------------------------------------------------------------------- + def pytest_pycollect_makemodule(path, parent): + """ return a Module collector or None for the given path. + This hook will be called for each matching test module path. + The pytest_collect_file hook needs to be used if you want to + create test modules for files that do not match as a test module. + """ + pytest_pycollect_makemodule.firstresult = True + def pytest_pycollect_makeitem(collector, name, obj): """ return custom item/collector for a python object in a module, or None. """ pytest_pycollect_makeitem.firstresult = True @@ -139,31 +157,6 @@ hook specification sourcecode """ return processed content for a given doctest""" pytest_doctest_prepare_content.firstresult = True - # ------------------------------------------------------------------------- - # distributed testing - # ------------------------------------------------------------------------- - - def pytest_gwmanage_newgateway(gateway, platinfo): - """ called on new raw gateway creation. """ - - def pytest_gwmanage_rsyncstart(source, gateways): - """ called before rsyncing a directory to remote gateways takes place. """ - - def pytest_gwmanage_rsyncfinish(source, gateways): - """ called after rsyncing a directory to remote gateways takes place. """ - - def pytest_testnodeready(node): - """ Test Node is ready to operate. """ - - def pytest_testnodedown(node, error): - """ Test Node is down. """ - - def pytest_rescheduleitems(items): - """ reschedule Items from a node that went down. """ - - def pytest_looponfailinfo(failreports, rootdirs): - """ info for repeating failing tests. """ - # ------------------------------------------------------------------------- # error handling and internal debugging hooks @@ -184,4 +177,34 @@ hook specification sourcecode def pytest_trace(category, msg): """ called for debug info. """ +hook specification sourcecode +============================= + +.. sourcecode:: python + + + def pytest_gwmanage_newgateway(gateway, platinfo): + """ called on new raw gateway creation. """ + + def pytest_gwmanage_rsyncstart(source, gateways): + """ called before rsyncing a directory to remote gateways takes place. """ + + def pytest_gwmanage_rsyncfinish(source, gateways): + """ called after rsyncing a directory to remote gateways takes place. """ + + def pytest_configure_node(node): + """ configure node information before it gets instantiated. """ + + def pytest_testnodeready(node): + """ Test Node is ready to operate. """ + + def pytest_testnodedown(node, error): + """ Test Node is down. """ + + def pytest_rescheduleitems(items): + """ reschedule Items from a node that went down. """ + + def pytest_looponfailinfo(failreports, rootdirs): + """ info for repeating failing tests. """ + .. include:: links.txt diff --git a/doc/test/plugin/links.txt b/doc/test/plugin/links.txt index a3aea95d3..2ae720209 100644 --- a/doc/test/plugin/links.txt +++ b/doc/test/plugin/links.txt @@ -1,46 +1,46 @@ .. _`helpconfig`: helpconfig.html -.. _`pytest_recwarn.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.2.1/py/_plugin/pytest_recwarn.py +.. _`pytest_recwarn.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.3.0/py/_plugin/pytest_recwarn.py .. _`unittest`: unittest.html -.. _`pytest_monkeypatch.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.2.1/py/_plugin/pytest_monkeypatch.py -.. _`pytest_genscript.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.2.1/py/_plugin/pytest_genscript.py +.. _`pytest_monkeypatch.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.3.0/py/_plugin/pytest_monkeypatch.py +.. _`pytest_genscript.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.3.0/py/_plugin/pytest_genscript.py .. _`pastebin`: pastebin.html .. _`skipping`: skipping.html .. _`genscript`: genscript.html .. _`plugins`: index.html .. _`mark`: mark.html .. _`tmpdir`: tmpdir.html -.. _`pytest_doctest.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.2.1/py/_plugin/pytest_doctest.py +.. _`pytest_doctest.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.3.0/py/_plugin/pytest_doctest.py .. _`capture`: capture.html -.. _`pytest_nose.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.2.1/py/_plugin/pytest_nose.py -.. _`pytest_restdoc.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.2.1/py/_plugin/pytest_restdoc.py +.. _`pytest_nose.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.3.0/py/_plugin/pytest_nose.py +.. _`pytest_restdoc.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.3.0/py/_plugin/pytest_restdoc.py .. _`restdoc`: restdoc.html .. _`xdist`: xdist.html -.. _`pytest_pastebin.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.2.1/py/_plugin/pytest_pastebin.py -.. _`pytest_tmpdir.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.2.1/py/_plugin/pytest_tmpdir.py +.. _`pytest_pastebin.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.3.0/py/_plugin/pytest_pastebin.py +.. _`pytest_tmpdir.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.3.0/py/_plugin/pytest_tmpdir.py .. _`terminal`: terminal.html -.. _`pytest_hooklog.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.2.1/py/_plugin/pytest_hooklog.py +.. _`pytest_hooklog.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.3.0/py/_plugin/pytest_hooklog.py .. _`capturelog`: capturelog.html .. _`junitxml`: junitxml.html -.. _`pytest_skipping.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.2.1/py/_plugin/pytest_skipping.py +.. _`pytest_skipping.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.3.0/py/_plugin/pytest_skipping.py .. _`checkout the py.test development version`: ../../install.html#checkout -.. _`pytest_helpconfig.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.2.1/py/_plugin/pytest_helpconfig.py +.. _`pytest_helpconfig.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.3.0/py/_plugin/pytest_helpconfig.py .. _`oejskit`: oejskit.html .. _`doctest`: doctest.html -.. _`pytest_mark.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.2.1/py/_plugin/pytest_mark.py +.. _`pytest_mark.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.3.0/py/_plugin/pytest_mark.py .. _`get in contact`: ../../contact.html -.. _`pytest_capture.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.2.1/py/_plugin/pytest_capture.py +.. _`pytest_capture.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.3.0/py/_plugin/pytest_capture.py .. _`figleaf`: figleaf.html .. _`customize`: ../customize.html .. _`hooklog`: hooklog.html -.. _`pytest_terminal.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.2.1/py/_plugin/pytest_terminal.py +.. _`pytest_terminal.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.3.0/py/_plugin/pytest_terminal.py .. _`recwarn`: recwarn.html -.. _`pytest_pdb.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.2.1/py/_plugin/pytest_pdb.py +.. _`pytest_pdb.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.3.0/py/_plugin/pytest_pdb.py .. _`monkeypatch`: monkeypatch.html .. _`coverage`: coverage.html .. _`resultlog`: resultlog.html -.. _`pytest_junitxml.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.2.1/py/_plugin/pytest_junitxml.py +.. _`pytest_junitxml.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.3.0/py/_plugin/pytest_junitxml.py .. _`django`: django.html -.. _`pytest_unittest.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.2.1/py/_plugin/pytest_unittest.py +.. _`pytest_unittest.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.3.0/py/_plugin/pytest_unittest.py .. _`nose`: nose.html -.. _`pytest_resultlog.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.2.1/py/_plugin/pytest_resultlog.py +.. _`pytest_resultlog.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.3.0/py/_plugin/pytest_resultlog.py .. _`pdb`: pdb.html diff --git a/doc/test/plugin/skipping.txt b/doc/test/plugin/skipping.txt index 95b370395..04e2ee19b 100644 --- a/doc/test/plugin/skipping.txt +++ b/doc/test/plugin/skipping.txt @@ -15,9 +15,8 @@ The need for skipping a test is usually connected to a condition. If a test fails under all conditions then it's probably better to mark your test as 'xfail'. -By passing ``--report=xfailed,skipped`` to the terminal reporter -you will see summary information on skips and xfail-run tests -at the end of a test run. +By passing ``-rxs`` to the terminal reporter you will see extra +summary information on skips and xfail-run tests at the end of a test run. .. _skipif: @@ -88,10 +87,17 @@ Same as with skipif_ you can also selectively expect a failure depending on platform:: @py.test.mark.xfail("sys.version_info >= (3,0)") - def test_function(): ... +To not run a test and still regard it as "xfailed":: + + @py.test.mark.xfail(..., run=False) + +To specify an explicit reason to be shown with xfailure detail:: + + @py.test.mark.xfail(..., reason="my reason") + skipping on a missing import dependency -------------------------------------------------- @@ -120,6 +126,13 @@ within test or setup code. Example:: if not valid_config(): py.test.skip("unsuppored configuration") +command line options +-------------------- + + +``--runxfail`` + run tests even if they are marked xfail + Start improving this plugin in 30 seconds ========================================= diff --git a/doc/test/plugin/terminal.txt b/doc/test/plugin/terminal.txt index fa9f46aae..cf1912300 100644 --- a/doc/test/plugin/terminal.txt +++ b/doc/test/plugin/terminal.txt @@ -14,10 +14,12 @@ command line options ``-v, --verbose`` increase verbosity. +``-r chars`` + show extra test summary info as specified by chars (f)ailed, (s)skipped, (x)failed, (X)passed. ``-l, --showlocals`` show locals in tracebacks (disabled by default). ``--report=opts`` - show more info, valid: skipped,xfailed + (deprecated, use -r) ``--tb=style`` traceback print mode (long/short/line/no). ``--fulltrace`` diff --git a/doc/test/plugin/xdist.txt b/doc/test/plugin/xdist.txt index faeaa9816..3768dc746 100644 --- a/doc/test/plugin/xdist.txt +++ b/doc/test/plugin/xdist.txt @@ -28,18 +28,6 @@ You may specify different Python versions and interpreters. .. _`pytest-xdist`: http://pypi.python.org/pypi/pytest-xdist -Install / Uninstall ---------------------- - -To install the xdist plugin simply type:: - - easy_install pytest-xdist # or - pip install pytest-xdist - -and to uninstall:: - - pip uninstall pytest-xdist - Usage examples ---------------------