diff --git a/doc/en/reference.rst b/doc/en/reference.rst index 1a5deca05de..70cda3b842e 100644 --- a/doc/en/reference.rst +++ b/doc/en/reference.rst @@ -80,266 +80,6 @@ pytest.warns .. autofunction:: _pytest.recwarn.warns :with: - -.. _`hook-reference`: - -Hooks ------ - -**Tutorial**: :doc:`writing_plugins`. - -.. currentmodule:: _pytest.hookspec - -Reference to all hooks which can be implemented by :ref:`conftest.py files ` and :ref:`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 ` or hooks. - - -CallInfo -~~~~~~~~ - -.. autoclass:: _pytest.runner.CallInfo() - :members: - - -Class -~~~~~ - -.. autoclass:: _pytest.python.Class() - :members: - :show-inheritance: - -Collector -~~~~~~~~~ - -.. autoclass:: _pytest.nodes.Collector() - :members: - :show-inheritance: - -Config -~~~~~~ - -.. autoclass:: _pytest.config.Config() - :members: - -ExceptionInfo -~~~~~~~~~~~~~ - -.. autoclass:: _pytest._code.ExceptionInfo - :members: - -FixtureDef -~~~~~~~~~~ - -.. autoclass:: _pytest.fixtures.FixtureDef() - :members: - :show-inheritance: - -FSCollector -~~~~~~~~~~~ - -.. autoclass:: _pytest.nodes.FSCollector() - :members: - :show-inheritance: - -Function -~~~~~~~~ - -.. autoclass:: _pytest.python.Function() - :members: - :show-inheritance: - -Item -~~~~ - -.. autoclass:: _pytest.nodes.Item() - :members: - :show-inheritance: - -MarkDecorator -~~~~~~~~~~~~~ - -.. autoclass:: _pytest.mark.MarkDecorator - :members: - -MarkGenerator -~~~~~~~~~~~~~ - -.. autoclass:: _pytest.mark.MarkGenerator - :members: - -MarkInfo -~~~~~~~~ - -.. autoclass:: _pytest.mark.MarkInfo - :members: - -Metafunc -~~~~~~~~ - -.. autoclass:: _pytest.python.Metafunc - :members: - -Module -~~~~~~ - -.. autoclass:: _pytest.python.Module() - :members: - :show-inheritance: - -Node -~~~~ - -.. autoclass:: _pytest.nodes.Node() - :members: - -Parser -~~~~~~ - -.. autoclass:: _pytest.config.Parser() - :members: - -PluginManager -~~~~~~~~~~~~~ - -.. autoclass:: pluggy.PluginManager() - :members: - - -PytestPluginManager -~~~~~~~~~~~~~~~~~~~ - -.. autoclass:: _pytest.config.PytestPluginManager() - :members: - :undoc-members: - :show-inheritance: - -Session -~~~~~~~ - -.. autoclass:: _pytest.main.Session() - :members: - :show-inheritance: - -TestReport -~~~~~~~~~~ - -.. autoclass:: _pytest.runner.TestReport() - :members: - :inherited-members: - -_Result -~~~~~~~ - -.. autoclass:: pluggy._Result - :members: - Marks ----- @@ -553,171 +293,431 @@ capfd .. code-block:: python - def test_system_echo(capfd): - os.system('echo "hello"') - captured = capsys.readouterr() - assert captured.out == "hello\n" + def test_system_echo(capfd): + os.system('echo "hello"') + captured = capsys.readouterr() + assert captured.out == "hello\n" + + +capfdbinary +~~~~~~~~~~~~ + +**Tutorial**: :doc:`capture`. + +.. autofunction:: capfdbinary() + :no-auto-options: + + Returns an instance of :py:class:`CaptureFixture`. + + Example: + + .. code-block:: python + + def test_system_echo(capfdbinary): + os.system('echo "hello"') + captured = capfdbinary.readouterr() + assert captured.out == b"hello\n" + + +doctest_namespace +~~~~~~~~~~~~~~~~~ + +**Tutorial**: :doc:`doctest`. + +.. autofunction:: _pytest.doctest.doctest_namespace() + + Usually this fixture is used in conjunction with another ``autouse`` fixture: + + .. code-block:: python + + @pytest.fixture(autouse=True) + def add_np(doctest_namespace): + doctest_namespace['np'] = numpy + + For more details: :ref:`doctest_namespace`. + + +request +~~~~~~~ + +**Tutorial**: :ref:`request example`. + +The ``request`` fixture is a special fixture providing information of the requesting test function. + +.. autoclass:: _pytest.fixtures.FixtureRequest() + :members: + + +pytestconfig +~~~~~~~~~~~~ + +.. autofunction:: _pytest.fixtures.pytestconfig() + + +record_xml_property +~~~~~~~~~~~~~~~~~~~ + +**Tutorial**: :ref:`record_xml_property example`. + +.. autofunction:: _pytest.junitxml.record_xml_property() + +caplog +~~~~~~ + +**Tutorial**: :doc:`logging`. + +.. autofunction:: _pytest.logging.caplog() + :no-auto-options: + + This returns a :class:`_pytest.logging.LogCaptureFixture` instance. + +.. autoclass:: _pytest.logging.LogCaptureFixture + :members: + + +monkeypatch +~~~~~~~~~~~ + +.. currentmodule:: _pytest.monkeypatch + +**Tutorial**: :doc:`monkeypatch`. + +.. autofunction:: _pytest.monkeypatch.monkeypatch() + :no-auto-options: + + This returns a :class:`MonkeyPatch` instance. + +.. autoclass:: _pytest.monkeypatch.MonkeyPatch + :members: + +testdir +~~~~~~~ + +.. currentmodule:: _pytest.pytester + +This fixture provides a :class:`Testdir` instance useful for black-box testing of test files, making it ideal to +test plugins. + +To use it, include in your top-most ``conftest.py`` file:: + + pytest_plugins = 'pytester' + + + +.. autoclass:: Testdir() + :members: runpytest,runpytest_subprocess,runpytest_inprocess,makeconftest,makepyfile + +.. autoclass:: RunResult() + :members: + +.. autoclass:: LineMatcher() + :members: + + +recwarn +~~~~~~~ + +**Tutorial**: :ref:`assertwarnings` + +.. currentmodule:: _pytest.recwarn + +.. autofunction:: recwarn() + :no-auto-options: + +.. autoclass:: _pytest.recwarn.WarningsRecorder() + :members: + +Each recorded warning is an instance of :class:`warnings.WarningMessage`. + +.. note:: + :class:`RecordedWarning` was changed from a plain class to a namedtuple in pytest 3.1 + +.. note:: + ``DeprecationWarning`` and ``PendingDeprecationWarning`` are treated + differently; see :ref:`ensuring_function_triggers`. + + +tmpdir +~~~~~~ + +**Tutorial**: :doc:`tmpdir` + +.. currentmodule:: _pytest.tmpdir + +.. autofunction:: tmpdir() + :no-auto-options: + + +tmpdir_factory +~~~~~~~~~~~~~~ + +**Tutorial**: :ref:`tmpdir factory example` + +.. _`tmpdir factory api`: + +``tmpdir_factory`` instances have the following methods: + +.. currentmodule:: _pytest.tmpdir + +.. automethod:: TempdirFactory.mktemp +.. automethod:: TempdirFactory.getbasetemp + + +.. _`hook-reference`: + +Hooks +----- + +**Tutorial**: :doc:`writing_plugins`. + +.. currentmodule:: _pytest.hookspec + +Reference to all hooks which can be implemented by :ref:`conftest.py files ` and :ref:`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 +~~~~~~~~~~~~~~~~~~~~ -capfdbinary -~~~~~~~~~~~~ +Initialization hooks called for plugins and ``conftest.py`` files. -**Tutorial**: :doc:`capture`. +.. autofunction:: pytest_addoption +.. autofunction:: pytest_configure +.. autofunction:: pytest_unconfigure -.. autofunction:: capfdbinary() - :no-auto-options: +Test running hooks +~~~~~~~~~~~~~~~~~~ - Returns an instance of :py:class:`CaptureFixture`. +All runtest related hooks receive a :py:class:`pytest.Item <_pytest.main.Item>` object. - Example: +.. 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 - .. code-block:: python +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. - def test_system_echo(capfdbinary): - os.system('echo "hello"') - captured = capfdbinary.readouterr() - assert captured.out == b"hello\n" +The :py:mod:`_pytest.terminal` reported specifically uses +the reporting hook to print information about a test run. +Collection hooks +~~~~~~~~~~~~~~~~ -doctest_namespace -~~~~~~~~~~~~~~~~~ +``pytest`` calls the following hooks for collecting files and directories: -**Tutorial**: :doc:`doctest`. +.. autofunction:: pytest_collection +.. autofunction:: pytest_ignore_collect +.. autofunction:: pytest_collect_directory +.. autofunction:: pytest_collect_file -.. autofunction:: _pytest.doctest.doctest_namespace() +For influencing the collection of objects in Python modules +you can use the following hook: - Usually this fixture is used in conjunction with another ``autouse`` fixture: +.. autofunction:: pytest_pycollect_makeitem +.. autofunction:: pytest_generate_tests +.. autofunction:: pytest_make_parametrize_id - .. code-block:: python +After collection is complete, you can modify the order of +items, delete or otherwise amend the test items: - @pytest.fixture(autouse=True) - def add_np(doctest_namespace): - doctest_namespace['np'] = numpy +.. autofunction:: pytest_collection_modifyitems - For more details: :ref:`doctest_namespace`. +Reporting hooks +~~~~~~~~~~~~~~~ +Session related reporting hooks: -request -~~~~~~~ +.. 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 -**Tutorial**: :ref:`request example`. +And here is the central hook for reporting about +test execution: -The ``request`` fixture is a special fixture providing information of the requesting test function. +.. autofunction:: pytest_runtest_logreport -.. autoclass:: _pytest.fixtures.FixtureRequest() - :members: +You can also use this hook to customize assertion representation for some +types: +.. autofunction:: pytest_assertrepr_compare -pytestconfig -~~~~~~~~~~~~ -.. autofunction:: _pytest.fixtures.pytestconfig() - +Debugging/Interaction hooks +~~~~~~~~~~~~~~~~~~~~~~~~~~~ -record_xml_property -~~~~~~~~~~~~~~~~~~~ +There are few hooks which can be used for special +reporting or interaction with exceptions: -**Tutorial**: :ref:`record_xml_property example`. +.. autofunction:: pytest_internalerror +.. autofunction:: pytest_keyboard_interrupt +.. autofunction:: pytest_exception_interact +.. autofunction:: pytest_enter_pdb -.. autofunction:: _pytest.junitxml.record_xml_property() -caplog -~~~~~~ +Objects +------- -**Tutorial**: :doc:`logging`. +Full reference to objects accessible from :ref:`fixtures ` or :ref:`hooks `. -.. autofunction:: _pytest.logging.caplog() - :no-auto-options: - This returns a :class:`_pytest.logging.LogCaptureFixture` instance. +CallInfo +~~~~~~~~ -.. autoclass:: _pytest.logging.LogCaptureFixture +.. autoclass:: _pytest.runner.CallInfo() :members: -monkeypatch -~~~~~~~~~~~ +Class +~~~~~ -.. currentmodule:: _pytest.monkeypatch +.. autoclass:: _pytest.python.Class() + :members: + :show-inheritance: -**Tutorial**: :doc:`monkeypatch`. +Collector +~~~~~~~~~ -.. autofunction:: _pytest.monkeypatch.monkeypatch() - :no-auto-options: +.. autoclass:: _pytest.nodes.Collector() + :members: + :show-inheritance: - This returns a :class:`MonkeyPatch` instance. +Config +~~~~~~ -.. autoclass:: _pytest.monkeypatch.MonkeyPatch +.. autoclass:: _pytest.config.Config() :members: -testdir -~~~~~~~ +ExceptionInfo +~~~~~~~~~~~~~ -.. currentmodule:: _pytest.pytester +.. autoclass:: _pytest._code.ExceptionInfo + :members: -This fixture provides a :class:`Testdir` instance useful for black-box testing of test files, making it ideal to -test plugins. +FixtureDef +~~~~~~~~~~ -To use it, include in your top-most ``conftest.py`` file:: +.. autoclass:: _pytest.fixtures.FixtureDef() + :members: + :show-inheritance: - pytest_plugins = 'pytester' +FSCollector +~~~~~~~~~~~ +.. autoclass:: _pytest.nodes.FSCollector() + :members: + :show-inheritance: +Function +~~~~~~~~ -.. autoclass:: Testdir() - :members: runpytest,runpytest_subprocess,runpytest_inprocess,makeconftest,makepyfile +.. autoclass:: _pytest.python.Function() + :members: + :show-inheritance: -.. autoclass:: RunResult() +Item +~~~~ + +.. autoclass:: _pytest.nodes.Item() :members: + :show-inheritance: -.. autoclass:: LineMatcher() +MarkDecorator +~~~~~~~~~~~~~ + +.. autoclass:: _pytest.mark.MarkDecorator :members: +MarkGenerator +~~~~~~~~~~~~~ -recwarn -~~~~~~~ +.. autoclass:: _pytest.mark.MarkGenerator + :members: -**Tutorial**: :ref:`assertwarnings` +MarkInfo +~~~~~~~~ -.. currentmodule:: _pytest.recwarn +.. autoclass:: _pytest.mark.MarkInfo + :members: -.. autofunction:: recwarn() - :no-auto-options: +Metafunc +~~~~~~~~ -.. autoclass:: _pytest.recwarn.WarningsRecorder() +.. autoclass:: _pytest.python.Metafunc :members: -Each recorded warning is an instance of :class:`warnings.WarningMessage`. +Module +~~~~~~ -.. note:: - :class:`RecordedWarning` was changed from a plain class to a namedtuple in pytest 3.1 +.. autoclass:: _pytest.python.Module() + :members: + :show-inheritance: -.. note:: - ``DeprecationWarning`` and ``PendingDeprecationWarning`` are treated - differently; see :ref:`ensuring_function_triggers`. +Node +~~~~ +.. autoclass:: _pytest.nodes.Node() + :members: -tmpdir +Parser ~~~~~~ -**Tutorial**: :doc:`tmpdir` +.. autoclass:: _pytest.config.Parser() + :members: -.. currentmodule:: _pytest.tmpdir +PluginManager +~~~~~~~~~~~~~ -.. autofunction:: tmpdir() - :no-auto-options: +.. autoclass:: pluggy.PluginManager() + :members: -tmpdir_factory -~~~~~~~~~~~~~~ +PytestPluginManager +~~~~~~~~~~~~~~~~~~~ -**Tutorial**: :ref:`tmpdir factory example` +.. autoclass:: _pytest.config.PytestPluginManager() + :members: + :undoc-members: + :show-inheritance: -.. _`tmpdir factory api`: +Session +~~~~~~~ -``tmpdir_factory`` instances have the following methods: +.. autoclass:: _pytest.main.Session() + :members: + :show-inheritance: -.. currentmodule:: _pytest.tmpdir +TestReport +~~~~~~~~~~ -.. automethod:: TempdirFactory.mktemp -.. automethod:: TempdirFactory.getbasetemp +.. autoclass:: _pytest.runner.TestReport() + :members: + :inherited-members: + +_Result +~~~~~~~ + +.. autoclass:: pluggy._Result + :members: