From ce3b260b0b895fb7ad51137c47ec297b39456bc1 Mon Sep 17 00:00:00 2001 From: holger krekel Date: Mon, 11 Oct 2010 00:49:54 +0200 Subject: [PATCH] start documenting hooks, improve hookspec docstrings a bit --HG-- branch : trunk --- doc/customize.txt | 84 ++++++++------------------------- doc/links.inc | 2 +- doc/reporting.txt | 4 +- doc/skipping.txt | 2 +- doc/test/plugin/xmlresult.txt | 9 ---- pytest/{plugin => }/hookspec.py | 27 +++++++---- pytest/pluginmanager.py | 2 +- 7 files changed, 41 insertions(+), 89 deletions(-) delete mode 100644 doc/test/plugin/xmlresult.txt rename pytest/{plugin => }/hookspec.py (91%) diff --git a/doc/customize.txt b/doc/customize.txt index e6acfd0cc..e04113f91 100644 --- a/doc/customize.txt +++ b/doc/customize.txt @@ -228,83 +228,39 @@ the ``--traceconfig`` option. .. _`well specified hooks`: .. _`implement hooks`: -Important py.test hooks +py.test hook reference ==================================== -py.test calls hooks functions to implement its `test collection`_, -running and reporting process. When py.test loads a plugin it validates -that all hook functions conform to the `hook definition specification`_. +hook specification and validation +----------------------------------------- -The hook function name and its -argument names need to match exactly but it is allowed for an implementation -to accept *less* parameters. You'll get useful errors on mistyped hook or -argument names. Read on for some introductory information on particular -hooks. It's sensible to look at existing plugins so see example usages -and start off with your own plugin. +py.test calls hook functions to implement initialization, running, +test execution and reporting. When py.test loads a plugin it validates +that all hook functions conform to their respective hook specification. +Each hook function name and its argument names need to match a hook +specification exactly but it is allowed for a hook function to accept +*less* parameters than specified. If you mistype argument names or the +hook name itself you get useful errors. -.. _`hook definition specification`: plugin/hookspec.html - -.. _`configuration hooks`: - -command line parsing and configuration hooks +initialisation, command line and configuration hooks -------------------------------------------------------------------- -When the `test tool starts up`_ it will invoke all hooks that add -command line options in the python standard optparse style. - -.. sourcecode:: python - - def pytest_addoption(parser): - """ add command line options. """" - parser.addoption("--myopt", dest="myopt", action="store_true") - -After all these hooks have been called, the command line is parser -and a ``config`` object is created and another hook is invoked, -for example: - -.. sourcecode:: python - - def pytest_configure(config): - config.getvalue("myopt") - -When the test run finishes this corresponding finalizer hook is called: - -.. sourcecode:: python - - def pytest_unconfigure(config): - ... - - -adding global py.test helpers and functionality --------------------------------------------------------------------- - -If you want to make global helper functions or objects available -to your test code you can implement: - -.. sourcecode:: python - - def pytest_namespace(): - """ return dictionary with items to be made available on py.test. namespace """ - -All such returned items will be made available directly on -the ``py.test`` namespace. - -If you want to provide helpers that are specific to a test function run or need -to be setup per test function run, please refer to the `funcargs mechanism`_. - -.. _`funcargs mechanism`: funcargs.html +.. currentmodule:: pytest.hookspec +.. autofunction:: pytest_namespace +.. autofunction:: pytest_addoption +.. autofunction:: pytest_cmdline_main +.. autofunction:: pytest_configure +.. autofunction:: pytest_unconfigure generic "runtest" hooks ------------------------------ Each test item is usually executed by calling the following three hooks: -.. sourcecode:: python - - pytest_runtest_setup(item) - pytest_runtest_call(item) - pytest_runtest_teardown(item) +.. autofunction:: pytest_runtest_setup +.. autofunction:: pytest_runtest_call +.. autofunction:: pytest_runtest_teardown For each of the three invocations a `call object`_ encapsulates information about the outcome of the call and is subsequently used diff --git a/doc/links.inc b/doc/links.inc index 6a15c9998..679b7eb4b 100644 --- a/doc/links.inc +++ b/doc/links.inc @@ -11,4 +11,4 @@ .. _mercurial: http://mercurial.selenic.com/wiki/ .. _`setuptools`: http://pypi.python.org/pypi/setuptools .. _`distribute`: http://pypi.python.org/pypi/distribute -.. _hudon: http://hudson-ci.org/ +.. _hudson: http://hudson-ci.org/ diff --git a/doc/reporting.txt b/doc/reporting.txt index 593fca5b4..0d3d268e6 100644 --- a/doc/reporting.txt +++ b/doc/reporting.txt @@ -1,8 +1,6 @@ -Sending output to files or to remote services +Sending test report output to XML files or to remote services ================================================================= - - creating JUnitXML format files ---------------------------------------------------- diff --git a/doc/skipping.txt b/doc/skipping.txt index 66f9871e5..95a9a445d 100644 --- a/doc/skipping.txt +++ b/doc/skipping.txt @@ -80,7 +80,7 @@ apply the function will be skipped. .. _xfail: -mark a test function as **expected to fail** +mark a test function as expected to fail ------------------------------------------------------- You can use the ``xfail`` marker to indicate that you diff --git a/doc/test/plugin/xmlresult.txt b/doc/test/plugin/xmlresult.txt deleted file mode 100644 index cee159cfb..000000000 --- a/doc/test/plugin/xmlresult.txt +++ /dev/null @@ -1,9 +0,0 @@ -pytest_xmlresult plugin (EXTERNAL) -========================================== - -This plugin allows to write results in an XML format -compatible to CruiseControl_, see here for download: - - http://github.com/rozza/py.test-plugins - -.. _CruiseControl: http://cruisecontrol.sourceforge.net/ diff --git a/pytest/plugin/hookspec.py b/pytest/hookspec.py similarity index 91% rename from pytest/plugin/hookspec.py rename to pytest/hookspec.py index 02a310da5..7b75f3aed 100644 --- a/pytest/plugin/hookspec.py +++ b/pytest/hookspec.py @@ -3,34 +3,41 @@ hook specifications for py.test plugins """ # ------------------------------------------------------------------------- -# Command line and configuration +# Initialization # ------------------------------------------------------------------------- def pytest_namespace(): - "return dict of name->object which will get stored at py.test. namespace" + """return dict of name->object to be made globally available in + the py.test/pytest namespace. This hook is called before command + line options are fully parsed. If you want to provide helper functions + that can interact with a test function invocation, please refer to + :ref:`funcarg mechanism`. + """ def pytest_addoption(parser): - "add optparse-style options via parser.addoption." + """allows to add optparse-style command line options via a call to + ``parser.addoption(...)``.""" def pytest_addhooks(pluginmanager): - "add hooks via pluginmanager.registerhooks(module)" + "allows to add new hooks via pluginmanager.registerhooks(module)" + +def pytest_cmdline_main(config): + """ called for performing the main command line action. The default + implementation will invoke the configure hooks and runtest_mainloop. """ +pytest_cmdline_main.firstresult = True def pytest_configure(config): """ called after command line options have been parsed. and all plugins and initial conftest files been loaded. """ -def pytest_cmdline_main(config): - """ called for performing the main (cmdline) action. """ -pytest_cmdline_main.firstresult = True +def pytest_unconfigure(config): + """ called before test process is exited. """ def pytest_runtest_mainloop(session): """ called for performing the main runtest loop (after collection. """ pytest_runtest_mainloop.firstresult = True -def pytest_unconfigure(config): - """ called before test process is exited. """ - # ------------------------------------------------------------------------- # collection hooks # ------------------------------------------------------------------------- diff --git a/pytest/pluginmanager.py b/pytest/pluginmanager.py index ba39b8e7a..e599cdbe1 100644 --- a/pytest/pluginmanager.py +++ b/pytest/pluginmanager.py @@ -15,7 +15,7 @@ def check_old_use(mod, modname): class PluginManager(object): def __init__(self): - from pytest.plugin import hookspec + from pytest import hookspec self.registry = Registry() self._name2plugin = {} self._hints = []