Create reference and moved Objects and Hooks reference from writing_plugins
This commit is contained in:
Bruno Oliveira
parent
28df322500
commit
d4c3850231
|
|
@ -2,8 +2,9 @@
|
|||
|
||||
<ul>
|
||||
<li><a href="{{ pathto('index') }}">Home</a></li>
|
||||
<li><a href="{{ pathto('contents') }}">Contents</a></li>
|
||||
<li><a href="{{ pathto('getting-started') }}">Install</a></li>
|
||||
<li><a href="{{ pathto('contents') }}">Contents</a></li>
|
||||
<li><a href="{{ pathto('reference') }}">Reference</a></li>
|
||||
<li><a href="{{ pathto('example/index') }}">Examples</a></li>
|
||||
<li><a href="{{ pathto('customize') }}">Customize</a></li>
|
||||
<li><a href="{{ pathto('contact') }}">Contact</a></li>
|
||||
|
|
|
|||
|
|
@ -31,6 +31,7 @@ Full pytest documentation
|
|||
plugins
|
||||
writing_plugins
|
||||
logging
|
||||
reference
|
||||
|
||||
goodpractices
|
||||
pythonpath
|
||||
|
|
|
|||
|
|
@ -0,0 +1,198 @@
|
|||
|
||||
Reference
|
||||
=========
|
||||
|
||||
This page contains the full reference to pytest's API.
|
||||
|
||||
|
||||
.. _`hook-reference`:
|
||||
|
||||
Hooks
|
||||
-----
|
||||
|
||||
|
||||
.. currentmodule:: _pytest.hookspec
|
||||
|
||||
Reference to all hooks which can be implemented by :ref:`conftest.py files <localplugin>` and :ref:`plugins <plugins>`.
|
||||
|
||||
Bootstrapping hooks
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Bootstrapping hooks called for plugins registered early enough (internal and setuptools plugins).
|
||||
|
||||
.. autofunction:: pytest_load_initial_conftests
|
||||
.. autofunction:: pytest_cmdline_preparse
|
||||
.. autofunction:: pytest_cmdline_parse
|
||||
.. autofunction:: pytest_cmdline_main
|
||||
|
||||
Initialization hooks
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Initialization hooks called for plugins and ``conftest.py`` files.
|
||||
|
||||
.. autofunction:: pytest_addoption
|
||||
.. autofunction:: pytest_configure
|
||||
.. autofunction:: pytest_unconfigure
|
||||
|
||||
Test running hooks
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
|
||||
All runtest related hooks receive a :py:class:`pytest.Item <_pytest.main.Item>` object.
|
||||
|
||||
.. autofunction:: pytest_runtestloop
|
||||
.. autofunction:: pytest_runtest_protocol
|
||||
.. autofunction:: pytest_runtest_logstart
|
||||
.. autofunction:: pytest_runtest_logfinish
|
||||
.. autofunction:: pytest_runtest_setup
|
||||
.. autofunction:: pytest_runtest_call
|
||||
.. autofunction:: pytest_runtest_teardown
|
||||
.. autofunction:: pytest_runtest_makereport
|
||||
|
||||
For deeper understanding you may look at the default implementation of
|
||||
these hooks in :py:mod:`_pytest.runner` and maybe also
|
||||
in :py:mod:`_pytest.pdb` which interacts with :py:mod:`_pytest.capture`
|
||||
and its input/output capturing in order to immediately drop
|
||||
into interactive debugging when a test failure occurs.
|
||||
|
||||
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:
|
||||
|
||||
.. autofunction:: pytest_collection
|
||||
.. autofunction:: pytest_ignore_collect
|
||||
.. autofunction:: pytest_collect_directory
|
||||
.. autofunction:: pytest_collect_file
|
||||
|
||||
For influencing the collection of objects in Python modules
|
||||
you can use the following hook:
|
||||
|
||||
.. autofunction:: pytest_pycollect_makeitem
|
||||
.. autofunction:: pytest_generate_tests
|
||||
.. autofunction:: pytest_make_parametrize_id
|
||||
|
||||
After collection is complete, you can modify the order of
|
||||
items, delete or otherwise amend the test items:
|
||||
|
||||
.. autofunction:: pytest_collection_modifyitems
|
||||
|
||||
Reporting hooks
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
Session related reporting hooks:
|
||||
|
||||
.. autofunction:: pytest_collectstart
|
||||
.. autofunction:: pytest_itemcollected
|
||||
.. autofunction:: pytest_collectreport
|
||||
.. autofunction:: pytest_deselected
|
||||
.. autofunction:: pytest_report_header
|
||||
.. autofunction:: pytest_report_collectionfinish
|
||||
.. autofunction:: pytest_report_teststatus
|
||||
.. autofunction:: pytest_terminal_summary
|
||||
.. autofunction:: pytest_fixture_setup
|
||||
.. autofunction:: pytest_fixture_post_finalizer
|
||||
|
||||
And here is the central hook for reporting about
|
||||
test execution:
|
||||
|
||||
.. autofunction:: pytest_runtest_logreport
|
||||
|
||||
You can also use this hook to customize assertion representation for some
|
||||
types:
|
||||
|
||||
.. autofunction:: pytest_assertrepr_compare
|
||||
|
||||
|
||||
Debugging/Interaction hooks
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
There are few hooks which can be used for special
|
||||
reporting or interaction with exceptions:
|
||||
|
||||
.. autofunction:: pytest_internalerror
|
||||
.. autofunction:: pytest_keyboard_interrupt
|
||||
.. autofunction:: pytest_exception_interact
|
||||
.. autofunction:: pytest_enter_pdb
|
||||
|
||||
|
||||
|
||||
Objects
|
||||
-------
|
||||
|
||||
Full reference to objects accessible from :ref:`fixtures <fixture>` or hooks
|
||||
|
||||
.. autoclass:: _pytest.config.Config()
|
||||
:members:
|
||||
|
||||
.. autoclass:: _pytest.config.Parser()
|
||||
:members:
|
||||
|
||||
.. autoclass:: _pytest.nodes.Node()
|
||||
:members:
|
||||
|
||||
.. autoclass:: _pytest.nodes.Collector()
|
||||
:members:
|
||||
:show-inheritance:
|
||||
|
||||
.. autoclass:: _pytest.nodes.FSCollector()
|
||||
:members:
|
||||
:show-inheritance:
|
||||
|
||||
.. autoclass:: _pytest.main.Session()
|
||||
:members:
|
||||
:show-inheritance:
|
||||
|
||||
.. autoclass:: _pytest.nodes.Item()
|
||||
:members:
|
||||
:show-inheritance:
|
||||
|
||||
.. autoclass:: _pytest.python.Module()
|
||||
:members:
|
||||
:show-inheritance:
|
||||
|
||||
.. autoclass:: _pytest.python.Class()
|
||||
:members:
|
||||
:show-inheritance:
|
||||
|
||||
.. autoclass:: _pytest.python.Function()
|
||||
:members:
|
||||
:show-inheritance:
|
||||
|
||||
.. autoclass:: _pytest.fixtures.FixtureDef()
|
||||
:members:
|
||||
:show-inheritance:
|
||||
|
||||
.. autoclass:: _pytest.runner.CallInfo()
|
||||
:members:
|
||||
|
||||
.. autoclass:: _pytest.runner.TestReport()
|
||||
:members:
|
||||
:inherited-members:
|
||||
|
||||
.. autoclass:: pluggy._Result
|
||||
:members:
|
||||
|
||||
.. autofunction:: _pytest.config.get_plugin_manager()
|
||||
|
||||
.. autoclass:: _pytest.config.PytestPluginManager()
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
.. autoclass:: pluggy.PluginManager()
|
||||
:members:
|
||||
|
||||
.. currentmodule:: _pytest.pytester
|
||||
|
||||
.. autoclass:: Testdir()
|
||||
:members: runpytest,runpytest_subprocess,runpytest_inprocess,makeconftest,makepyfile
|
||||
|
||||
.. autoclass:: RunResult()
|
||||
:members:
|
||||
|
||||
.. autoclass:: LineMatcher()
|
||||
:members:
|
||||
|
||||
|
|
@ -12,9 +12,9 @@ only want to use but not write plugins.
|
|||
A plugin contains one or multiple hook functions. :ref:`Writing hooks <writinghooks>`
|
||||
explains the basics and details of how you can write a hook function yourself.
|
||||
``pytest`` implements all aspects of configuration, collection, running and
|
||||
reporting by calling `well specified hooks`_ of the following plugins:
|
||||
reporting by calling :ref:`well specified hooks <hook-reference>` of the following plugins:
|
||||
|
||||
* :ref:`builtin plugins`: loaded from pytest's internal ``_pytest`` directory.
|
||||
* builtin plugins: loaded from pytest's internal ``_pytest`` directory.
|
||||
|
||||
* :ref:`external plugins <extplugins>`: modules discovered through
|
||||
`setuptools entry points`_
|
||||
|
|
@ -109,10 +109,10 @@ If you want to write a plugin, there are many real-life examples
|
|||
you can copy from:
|
||||
|
||||
* a custom collection example plugin: :ref:`yaml plugin`
|
||||
* around 20 :ref:`builtin plugins` which provide pytest's own functionality
|
||||
* builtin plugins which provide pytest's own functionality
|
||||
* many `external plugins <http://plugincompat.herokuapp.com>`_ providing additional features
|
||||
|
||||
All of these plugins implement the documented `well specified hooks`_
|
||||
All of these plugins implement :ref:`hooks <hook-reference>` and/or :ref:`fixtures <fixture>`
|
||||
to extend and add functionality.
|
||||
|
||||
.. note::
|
||||
|
|
@ -167,7 +167,7 @@ it in your setuptools-invocation:
|
|||
|
||||
If a package is installed this way, ``pytest`` will load
|
||||
``myproject.pluginmodule`` as a plugin which can define
|
||||
`well specified hooks`_.
|
||||
:ref:`hooks <hook-reference>`.
|
||||
|
||||
.. note::
|
||||
|
||||
|
|
@ -577,191 +577,7 @@ declaring the hook functions directly in your plugin module, for example::
|
|||
This has the added benefit of allowing you to conditionally install hooks
|
||||
depending on which plugins are installed.
|
||||
|
||||
.. _`well specified hooks`:
|
||||
|
||||
.. currentmodule:: _pytest.hookspec
|
||||
|
||||
pytest hook reference
|
||||
=====================
|
||||
|
||||
|
||||
Initialization, command line and configuration hooks
|
||||
----------------------------------------------------
|
||||
|
||||
Bootstrapping hooks
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Bootstrapping hooks called for plugins registered early enough (internal and setuptools plugins).
|
||||
|
||||
.. autofunction:: pytest_load_initial_conftests
|
||||
.. autofunction:: pytest_cmdline_preparse
|
||||
.. autofunction:: pytest_cmdline_parse
|
||||
.. autofunction:: pytest_cmdline_main
|
||||
|
||||
Initialization hooks
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Initialization hooks called for plugins and ``conftest.py`` files.
|
||||
|
||||
.. autofunction:: pytest_addoption
|
||||
.. autofunction:: pytest_configure
|
||||
.. autofunction:: pytest_unconfigure
|
||||
|
||||
Generic "runtest" hooks
|
||||
-----------------------
|
||||
|
||||
All runtest related hooks receive a :py:class:`pytest.Item <_pytest.main.Item>` object.
|
||||
|
||||
.. autofunction:: pytest_runtestloop
|
||||
.. autofunction:: pytest_runtest_protocol
|
||||
.. autofunction:: pytest_runtest_logstart
|
||||
.. autofunction:: pytest_runtest_logfinish
|
||||
.. autofunction:: pytest_runtest_setup
|
||||
.. autofunction:: pytest_runtest_call
|
||||
.. autofunction:: pytest_runtest_teardown
|
||||
.. autofunction:: pytest_runtest_makereport
|
||||
|
||||
For deeper understanding you may look at the default implementation of
|
||||
these hooks in :py:mod:`_pytest.runner` and maybe also
|
||||
in :py:mod:`_pytest.pdb` which interacts with :py:mod:`_pytest.capture`
|
||||
and its input/output capturing in order to immediately drop
|
||||
into interactive debugging when a test failure occurs.
|
||||
|
||||
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:
|
||||
|
||||
.. autofunction:: pytest_collection
|
||||
.. autofunction:: pytest_ignore_collect
|
||||
.. autofunction:: pytest_collect_directory
|
||||
.. autofunction:: pytest_collect_file
|
||||
|
||||
For influencing the collection of objects in Python modules
|
||||
you can use the following hook:
|
||||
|
||||
.. autofunction:: pytest_pycollect_makeitem
|
||||
.. autofunction:: pytest_generate_tests
|
||||
.. autofunction:: pytest_make_parametrize_id
|
||||
|
||||
After collection is complete, you can modify the order of
|
||||
items, delete or otherwise amend the test items:
|
||||
|
||||
.. autofunction:: pytest_collection_modifyitems
|
||||
|
||||
Reporting hooks
|
||||
---------------
|
||||
|
||||
Session related reporting hooks:
|
||||
|
||||
.. autofunction:: pytest_collectstart
|
||||
.. autofunction:: pytest_itemcollected
|
||||
.. autofunction:: pytest_collectreport
|
||||
.. autofunction:: pytest_deselected
|
||||
.. autofunction:: pytest_report_header
|
||||
.. autofunction:: pytest_report_collectionfinish
|
||||
.. autofunction:: pytest_report_teststatus
|
||||
.. autofunction:: pytest_terminal_summary
|
||||
.. autofunction:: pytest_fixture_setup
|
||||
.. autofunction:: pytest_fixture_post_finalizer
|
||||
|
||||
And here is the central hook for reporting about
|
||||
test execution:
|
||||
|
||||
.. autofunction:: pytest_runtest_logreport
|
||||
|
||||
You can also use this hook to customize assertion representation for some
|
||||
types:
|
||||
|
||||
.. autofunction:: pytest_assertrepr_compare
|
||||
|
||||
|
||||
Debugging/Interaction hooks
|
||||
---------------------------
|
||||
|
||||
There are few hooks which can be used for special
|
||||
reporting or interaction with exceptions:
|
||||
|
||||
.. autofunction:: pytest_internalerror
|
||||
.. autofunction:: pytest_keyboard_interrupt
|
||||
.. autofunction:: pytest_exception_interact
|
||||
.. autofunction:: pytest_enter_pdb
|
||||
|
||||
|
||||
Reference of objects involved in hooks
|
||||
======================================
|
||||
|
||||
.. autoclass:: _pytest.config.Config()
|
||||
:members:
|
||||
|
||||
.. autoclass:: _pytest.config.Parser()
|
||||
:members:
|
||||
|
||||
.. autoclass:: _pytest.nodes.Node()
|
||||
:members:
|
||||
|
||||
.. autoclass:: _pytest.nodes.Collector()
|
||||
:members:
|
||||
:show-inheritance:
|
||||
|
||||
.. autoclass:: _pytest.nodes.FSCollector()
|
||||
:members:
|
||||
:show-inheritance:
|
||||
|
||||
.. autoclass:: _pytest.main.Session()
|
||||
:members:
|
||||
:show-inheritance:
|
||||
|
||||
.. autoclass:: _pytest.nodes.Item()
|
||||
:members:
|
||||
:show-inheritance:
|
||||
|
||||
.. autoclass:: _pytest.python.Module()
|
||||
:members:
|
||||
:show-inheritance:
|
||||
|
||||
.. autoclass:: _pytest.python.Class()
|
||||
:members:
|
||||
:show-inheritance:
|
||||
|
||||
.. autoclass:: _pytest.python.Function()
|
||||
:members:
|
||||
:show-inheritance:
|
||||
|
||||
.. autoclass:: _pytest.fixtures.FixtureDef()
|
||||
:members:
|
||||
:show-inheritance:
|
||||
|
||||
.. autoclass:: _pytest.runner.CallInfo()
|
||||
:members:
|
||||
|
||||
.. autoclass:: _pytest.runner.TestReport()
|
||||
:members:
|
||||
:inherited-members:
|
||||
|
||||
.. autoclass:: pluggy._Result
|
||||
:members:
|
||||
|
||||
.. autofunction:: _pytest.config.get_plugin_manager()
|
||||
|
||||
.. autoclass:: _pytest.config.PytestPluginManager()
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
.. autoclass:: pluggy.PluginManager()
|
||||
:members:
|
||||
|
||||
.. currentmodule:: _pytest.pytester
|
||||
|
||||
.. autoclass:: Testdir()
|
||||
:members: runpytest,runpytest_subprocess,runpytest_inprocess,makeconftest,makepyfile
|
||||
|
||||
.. autoclass:: RunResult()
|
||||
:members:
|
||||
|
||||
.. autoclass:: LineMatcher()
|
||||
:members:
|
||||
|
|
|
|||
Loading…
Reference in New Issue