1 new commit in pytest: https://bitbucket.org/hpk42/pytest/commits/a71457338b8b/ Changeset: a71457338b8b Branch: contributing-community User: bubenkoff Date: 2014-08-20 00:52:40 Summary: plugin organization proposal Affected #: 1 file
diff -r d8f5a2a67a5d2de6e075e11bc24a308521093dcf -r a71457338b8b8147e1aa138a28c7fb1859a9e995 doc/en/plugins.txt --- 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 @@ .. _`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 @@ .. _`extplugins`: Installing External Plugins / Searching ------------------------------------------------------- +--------------------------------------- Installing a plugin happens through any usual Python installation tool, for example:: @@ -119,6 +119,16 @@ .. _`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 important for the community +to keep all pieces of the pytest ecosystem supported. External plugins are important for +pytest users, as they implement many useful, and sometimes critical features which the pytest core does +not implement. + + Writing a plugin by looking at examples ------------------------------------------------------ @@ -138,7 +148,7 @@ .. _`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 +179,11 @@ ``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: @@ -187,8 +198,8 @@ invocation: - if no test paths are specified use current dir as a test path - - if exists, load ``conftest.py`` and ``test*/conftest.py`` relative - to the directory part of the first test path. + - if exists, load ``conftest.py`` and ``test*/conftest.py`` relative + to the directory part of the first test path. Note that pytest does not find ``conftest.py`` files in deeper nested sub directories at tool startup. It is usually a good idea to keep @@ -199,7 +210,7 @@ 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 +225,7 @@ Accessing another plugin by name --------------------------------------------- +-------------------------------- If a plugin wants to collaborate with code from another plugin it can obtain a reference through @@ -230,7 +241,7 @@ .. _`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 +255,7 @@ .. _`cmdunregister`: Deactivating / unregistering a plugin by name ----------------------------------------------------------------------------- +--------------------------------------------- You can prevent plugins from loading or unregister them:: @@ -257,7 +268,7 @@ .. _`builtin plugins`: pytest default plugin reference -==================================== +=============================== You can find the source code for the following plugins @@ -305,7 +316,7 @@ hook name itself you get an error showing the available arguments. Initialization, command line and configuration hooks --------------------------------------------------------------------- +---------------------------------------------------- .. currentmodule:: _pytest.hookspec @@ -319,7 +330,7 @@ .. autofunction:: pytest_unconfigure Generic "runtest" hooks ------------------------------- +----------------------- All runtest related hooks receive a :py:class:`pytest.Item` object. @@ -339,7 +350,7 @@ the reporting hook to print information about a test run. Collection hooks ------------------------------- +---------------- ``pytest`` calls the following hooks for collecting files and directories: @@ -359,7 +370,7 @@ .. autofunction:: pytest_collection_modifyitems Reporting hooks ------------------------------- +--------------- Session related reporting hooks: @@ -375,7 +386,7 @@ Debugging/Interaction hooks --------------------------------------- +--------------------------- There are few hooks which can be used for special reporting or interaction with exceptions: @@ -385,7 +396,7 @@ .. autofunction:: pytest_exception_interact Reference of objects involved in hooks -=========================================================== +====================================== .. autoclass:: _pytest.config.Config() :members: Repository URL: https://bitbucket.org/hpk42/pytest/ -- This is a commit notification from bitbucket.org. You are receiving this because you have the service enabled, addressing the recipient of this email. _______________________________________________ pytest-commit mailing list pytest-commit@python.org https://mail.python.org/mailman/listinfo/pytest-commit
