128 lines
3.8 KiB
Plaintext
128 lines
3.8 KiB
Plaintext
======================================
|
|
Writing plugins and extensions
|
|
======================================
|
|
|
|
|
|
.. _`local plugin`:
|
|
|
|
Local Plugins
|
|
==================================
|
|
|
|
You can easily specify a project-specific or "local"
|
|
plugin by defining a ``ConftestPlugin`` in a ``conftest.py``
|
|
file like this::
|
|
|
|
class ConftestPlugin:
|
|
""" my local plugin. """
|
|
|
|
|
|
Learning by examples
|
|
=====================
|
|
|
|
XXX
|
|
|
|
adding custom options
|
|
----------------------
|
|
|
|
py.test supports adding of standard optparse_ Options.
|
|
A plugin may implement the ``addoption`` hook for registering
|
|
custom options::
|
|
|
|
class ConftestPlugin:
|
|
def pytest_addoption(self, parser):
|
|
parser.addoption("-M", "--myopt", action="store",
|
|
help="specify string to set myopt")
|
|
|
|
def pytest_configure(self, config):
|
|
if config.option.myopt:
|
|
# do action based on option value
|
|
|
|
.. _optparse: http://docs.python.org/library/optparse.html
|
|
|
|
Setting default values for test options
|
|
=======================================
|
|
|
|
You can see all available command line options by running::
|
|
|
|
py.test -h
|
|
|
|
py.test will lookup values of options in this order:
|
|
|
|
* option value supplied at command line
|
|
* content of environment variable ``PYTEST_OPTION_NAME=...``
|
|
* ``name = ...`` setting in the nearest ``conftest.py`` file.
|
|
|
|
The name of an option usually is the one you find
|
|
in the longform of the option, i.e. the name
|
|
behind the ``--`` double-dash.
|
|
|
|
IOW, you can set default values for options per project, per
|
|
home-directoray, per shell session or per test-run.
|
|
|
|
.. _`collection process`:
|
|
|
|
Test Collection process
|
|
======================================================
|
|
|
|
The collecting process is iterative so that distribution
|
|
and execution of tests can start as soon as the first test
|
|
item is collected. Collection nodes with children are
|
|
called "Collectors" and terminal nodes are called "Items".
|
|
Here is an example of such a tree, generated with the
|
|
command ``py.test --collectonly py/xmlobj``::
|
|
|
|
<Directory 'xmlobj'>
|
|
<Directory 'testing'>
|
|
<Module 'test_html.py' (py.__.xmlobj.testing.test_html)>
|
|
<Function 'test_html_name_stickyness'>
|
|
<Function 'test_stylenames'>
|
|
<Function 'test_class_None'>
|
|
<Function 'test_alternating_style'>
|
|
<Module 'test_xml.py' (py.__.xmlobj.testing.test_xml)>
|
|
<Function 'test_tag_with_text'>
|
|
<Function 'test_class_identity'>
|
|
<Function 'test_tag_with_text_and_attributes'>
|
|
<Function 'test_tag_with_subclassed_attr_simple'>
|
|
<Function 'test_tag_nested'>
|
|
<Function 'test_tag_xmlname'>
|
|
|
|
By default all directories not starting with a dot are traversed,
|
|
looking for ``test_*.py`` and ``*_test.py`` files. Those Python
|
|
files are imported under their `package name`_.
|
|
|
|
The Module collector looks for test functions
|
|
and test classes and methods. Test functions and methods
|
|
are prefixed ``test`` by default. Test classes must
|
|
start with a capitalized ``Test`` prefix.
|
|
|
|
.. _`package name`:
|
|
|
|
constructing the package name for test modules
|
|
-------------------------------------------------
|
|
|
|
Test modules are imported under their fully qualified
|
|
name. Given a filesystem ``fspath`` it is constructed as follows:
|
|
|
|
* walk the directories up to the last one that contains
|
|
an ``__init__.py`` file.
|
|
|
|
* perform ``sys.path.insert(0, basedir)``.
|
|
|
|
* import the root package as ``root``
|
|
|
|
* determine the fully qualified name for ``fspath`` by either:
|
|
|
|
* calling ``root.__pkg__.getimportname(fspath)`` if the
|
|
``__pkg__`` exists.` or
|
|
|
|
* otherwise use the relative path of the module path to
|
|
the base dir and turn slashes into dots and strike
|
|
the trailing ``.py``.
|
|
|
|
|
|
|
|
Plugin hooks and events
|
|
=======================================
|
|
|
|
XXX
|