floraachy
/
pytest2
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Create reference and moved Objects and Hooks reference from writing_plugins

This commit is contained in:
Bruno Oliveira 2018-02-07 20:53:31 -02:00
parent 28df322500
commit d4c3850231
4 changed files with 206 additions and 190 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
doc/en/_templates/globaltoc.html
View File

@ -2,8 +2,9 @@
<ul> <ul>
<li><a href="{{ pathto('index') }}">Home</a></li> <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('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('example/index') }}">Examples</a></li>
<li><a href="{{ pathto('customize') }}">Customize</a></li> <li><a href="{{ pathto('customize') }}">Customize</a></li>
<li><a href="{{ pathto('contact') }}">Contact</a></li> <li><a href="{{ pathto('contact') }}">Contact</a></li>

1
doc/en/contents.rst
View File

@ -31,6 +31,7 @@ Full pytest documentation
plugins plugins
writing_plugins writing_plugins
logging logging
reference
goodpractices goodpractices
pythonpath pythonpath

198
doc/en/reference.rst Normal file
View File

@ -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:

194
doc/en/writing_plugins.rst
View File

@ -12,9 +12,9 @@ only want to use but not write plugins.
A plugin contains one or multiple hook functions. :ref:`Writing hooks <writinghooks>` 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. explains the basics and details of how you can write a hook function yourself.
``pytest`` implements all aspects of configuration, collection, running and ``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 * :ref:`external plugins <extplugins>`: modules discovered through
`setuptools entry points`_ `setuptools entry points`_
@ -109,10 +109,10 @@ If you want to write a plugin, there are many real-life examples
you can copy from: you can copy from:
* a custom collection example plugin: :ref:`yaml plugin` * 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 * 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. to extend and add functionality.
.. note:: .. note::
@ -167,7 +167,7 @@ it in your setuptools-invocation:
If a package is installed this way, ``pytest`` will load If a package is installed this way, ``pytest`` will load
``myproject.pluginmodule`` as a plugin which can define ``myproject.pluginmodule`` as a plugin which can define
`well specified hooks`_. :ref:`hooks <hook-reference>`.
.. note:: .. 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 This has the added benefit of allowing you to conditionally install hooks
depending on which plugins are installed. 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: