diff options
Diffstat (limited to 'doc/en/plugins.txt')
| -rw-r--r-- | doc/en/plugins.txt | 73 |
1 files changed, 54 insertions, 19 deletions
diff --git a/doc/en/plugins.txt b/doc/en/plugins.txt index 3ef24e019..6ede5a0af 100644 --- a/doc/en/plugins.txt +++ b/doc/en/plugins.txt @@ -1,7 +1,7 @@ .. _plugins: Working with plugins and conftest files -============================================= +======================================= ``pytest`` implements all aspects of configuration, collection, running and reporting by calling `well specified hooks`_. Virtually any Python module can be registered as a plugin. It can implement any number of hook functions (usually two or three) which all have a ``pytest_`` prefix, making hook functions easy to distinguish and find. There are three basic location types: @@ -16,7 +16,7 @@ Working with plugins and conftest files .. _`conftest`: conftest.py: local per-directory plugins --------------------------------------------------------------- +---------------------------------------- local ``conftest.py`` plugins contain directory-specific hook implementations. Session and test running activities will @@ -55,7 +55,7 @@ Here is how you might run it:: .. _`extplugins`: Installing External Plugins / Searching ------------------------------------------------------- +--------------------------------------- Installing a plugin happens through any usual Python installation tool, for example:: @@ -119,8 +119,42 @@ You may also discover more plugins through a `pytest- pypi.python.org search`_. .. _`available installable plugins`: .. _`pytest- pypi.python.org search`: http://pypi.python.org/pypi?%3Aaction=search&term=pytest-&submit=search + +External plugin development +--------------------------- + +Pytest community cares about pytest users, in particular, it's crucial for the community +to keep all pieces of the pytest ecosystem well supported. External plugins are important for +pytest users, as they implement many useful, and sometimes critical features which the pytest core does +not implement. + +To simplify the plugin development and/or support, it was decided to create teams(companies) on popular code hosting +services (at the moment it's github and bitbucket): + +* `<https://github.com/pytest-dev>`_: + probably the most popular hosting for pytest plugins + the name ``pytest-dev`` is choosen because ``pytest`` was already taken by + some unknown person, who's not active on the github or just doesn't check the email used to register + that organization. +* `<https://bitbucket.org/pytest-dev>`_: + pytest is hosted on the bitbucket, also a lot of pytest plugins are hosted there. + +More code hosting services can be added in the future. + +Community encourages pytest plugin developers to move their plugins under those organizations (eg transfer ownership), +paying with a better support, faster feedback, better discoverability, etc. + +Generic workflow of the ownership transfer looks like: + +* If not a member already, developer asks for a membership in the `pytest plugin developers community` organizations listed above, sending an email to `<pytest-dev@python.org>`_. + +* Developer transfers the ownership of his plugin repository to the organization listed above. + +* Existing organization members will make sure proper write permissions are set up for developer who transfered the ownership to the organization. + + Writing a plugin by looking at examples ------------------------------------------------------- +--------------------------------------- .. _`Distribute`: http://pypi.python.org/pypi/distribute .. _`setuptools`: http://pypi.python.org/pypi/setuptools @@ -138,7 +172,7 @@ to extend and add functionality. .. _`setuptools entry points`: Making your plugin installable by others ------------------------------------------------ +---------------------------------------- If you want to make your plugin externally available, you may define a so-called entry point for your distribution so @@ -169,10 +203,11 @@ If a package is installed this way, ``pytest`` will load ``myproject.pluginmodule`` as a plugin which can define `well specified hooks`_. + .. _`pluginorder`: Plugin discovery order at tool startup --------------------------------------------- +-------------------------------------- ``pytest`` loads plugin modules at tool startup in the following way: @@ -199,7 +234,7 @@ Plugin discovery order at tool startup Requiring/Loading plugins in a test module or conftest file -------------------------------------------------------------- +----------------------------------------------------------- You can require plugins in a test module or a conftest file like this:: @@ -214,7 +249,7 @@ which will import the specified module as a ``pytest`` plugin. Accessing another plugin by name --------------------------------------------- +-------------------------------- If a plugin wants to collaborate with code from another plugin it can obtain a reference through @@ -230,7 +265,7 @@ the ``--traceconfig`` option. .. _`findpluginname`: Finding out which plugins are active ----------------------------------------------------------------------------- +------------------------------------ If you want to find out which plugins are active in your environment you can type:: @@ -244,7 +279,7 @@ and their names. It will also print local plugins aka .. _`cmdunregister`: Deactivating / unregistering a plugin by name ----------------------------------------------------------------------------- +--------------------------------------------- You can prevent plugins from loading or unregister them:: @@ -257,7 +292,7 @@ how to obtain the name of a plugin. .. _`builtin plugins`: pytest default plugin reference -==================================== +=============================== You can find the source code for the following plugins @@ -291,10 +326,10 @@ in the `pytest repository <http://bitbucket.org/hpk42/pytest/>`_. .. _`well specified hooks`: pytest hook reference -==================================== +===================== Hook specification and validation ------------------------------------------ +--------------------------------- ``pytest`` calls hook functions to implement initialization, running, test execution and reporting. When ``pytest`` loads a plugin it validates @@ -305,7 +340,7 @@ by simply not specifying them. If you mistype argument names or the hook name itself you get an error showing the available arguments. Initialization, command line and configuration hooks --------------------------------------------------------------------- +---------------------------------------------------- .. currentmodule:: _pytest.hookspec @@ -319,7 +354,7 @@ Initialization, command line and configuration hooks .. autofunction:: pytest_unconfigure Generic "runtest" hooks ------------------------------- +----------------------- All runtest related hooks receive a :py:class:`pytest.Item` object. @@ -339,7 +374,7 @@ The :py:mod:`_pytest.terminal` reported specifically uses the reporting hook to print information about a test run. Collection hooks ------------------------------- +---------------- ``pytest`` calls the following hooks for collecting files and directories: @@ -359,7 +394,7 @@ items, delete or otherwise amend the test items: .. autofunction:: pytest_collection_modifyitems Reporting hooks ------------------------------- +--------------- Session related reporting hooks: @@ -375,7 +410,7 @@ test execution: Debugging/Interaction hooks --------------------------------------- +--------------------------- There are few hooks which can be used for special reporting or interaction with exceptions: @@ -468,7 +503,7 @@ that result, however. Reference of objects involved in hooks -=========================================================== +====================================== .. autoclass:: _pytest.config.Config() :members: |