Merge pull request #8433 from evildmp/evolutionary-documentation-restructure
Added how-to and reference directories.
This commit is contained in:
commit
32ad70dea8
|
@ -1 +1 @@
|
|||
Add automatically generated :doc:`plugin_list`. The list is updated on a periodic schedule.
|
||||
Add automatically generated :ref:`plugin-list`. The list is updated on a periodic schedule.
|
||||
|
|
|
@ -23,18 +23,18 @@ How-to guides
|
|||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
usage
|
||||
existingtestsuite
|
||||
assert
|
||||
mark
|
||||
monkeypatch
|
||||
tmpdir
|
||||
capture
|
||||
skipping
|
||||
parametrize
|
||||
plugins
|
||||
nose
|
||||
bash-completion
|
||||
how-to/usage
|
||||
how-to/existingtestsuite
|
||||
how-to/assert
|
||||
how-to/mark
|
||||
how-to/monkeypatch
|
||||
how-to/tmpdir
|
||||
how-to/capture
|
||||
how-to/skipping
|
||||
how-to/parametrize
|
||||
how-to/plugins
|
||||
how-to/nose
|
||||
how-to/bash-completion
|
||||
|
||||
|
||||
Reference guides
|
||||
|
@ -43,17 +43,17 @@ Reference guides
|
|||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
fixture
|
||||
warnings
|
||||
doctest
|
||||
cache
|
||||
unittest
|
||||
xunit_setup
|
||||
plugin_list
|
||||
writing_plugins
|
||||
logging
|
||||
customize
|
||||
reference
|
||||
reference/fixture
|
||||
reference/warnings
|
||||
reference/doctest
|
||||
reference/cache
|
||||
reference/unittest
|
||||
reference/xunit_setup
|
||||
reference/plugin_list
|
||||
reference/writing_plugins
|
||||
reference/logging
|
||||
reference/customize
|
||||
reference/reference
|
||||
|
||||
|
||||
Further topics
|
||||
|
|
|
@ -13,12 +13,12 @@ answers.
|
|||
|
||||
For basic examples, see
|
||||
|
||||
- :doc:`../getting-started` for basic introductory examples
|
||||
- :ref:`get-started` for basic introductory examples
|
||||
- :ref:`assert` for basic assertion examples
|
||||
- :ref:`Fixtures <fixtures>` for basic fixture/setup examples
|
||||
- :ref:`parametrize` for basic test function parametrization
|
||||
- :doc:`../unittest` for basic unittest integration
|
||||
- :doc:`../nose` for basic nosetests integration
|
||||
- :ref:`unittest` for basic unittest integration
|
||||
- :ref:`noseintegration` for basic nosetests integration
|
||||
|
||||
The following examples aim at various use cases you might encounter.
|
||||
|
||||
|
|
|
@ -1,3 +1,5 @@
|
|||
.. _get-started:
|
||||
|
||||
Get Started
|
||||
===================================
|
||||
|
||||
|
|
|
@ -1,3 +1,4 @@
|
|||
.. _monkeypatching:
|
||||
|
||||
How to monkeypatch/mock modules and environments
|
||||
================================================================
|
|
@ -58,7 +58,7 @@ Here is a little annotated list for some popular plugins:
|
|||
|
||||
To see a complete list of all plugins with their latest testing
|
||||
status against different pytest and Python versions, please visit
|
||||
:doc:`plugin_list`.
|
||||
:ref:`plugin-list`.
|
||||
|
||||
You may also discover more plugins through a `pytest- pypi.org search`_.
|
||||
|
|
@ -365,7 +365,7 @@ Examples
|
|||
|
||||
Here is a simple test file with the several usages:
|
||||
|
||||
.. literalinclude:: example/xfail_demo.py
|
||||
.. literalinclude:: /example/xfail_demo.py
|
||||
|
||||
Running it with the report-on-xfail option gives this output:
|
||||
|
|
@ -81,7 +81,7 @@ Features
|
|||
|
||||
- Python 3.6+ and PyPy 3
|
||||
|
||||
- Rich plugin architecture, with over 800+ :doc:`external plugins <plugin_list>` and thriving community
|
||||
- Rich plugin architecture, with over 800+ :ref:`external plugins <plugin-list>` and thriving community
|
||||
|
||||
|
||||
Documentation
|
||||
|
|
|
@ -1,3 +1,4 @@
|
|||
.. _doctest:
|
||||
|
||||
Doctest integration for modules and test files
|
||||
=========================================================
|
|
@ -1188,12 +1188,12 @@ long as the test requesting them can see all fixtures involved.
|
|||
For example, here's a test file with a fixture (``outer``) that requests a
|
||||
fixture (``inner``) from a scope it wasn't defined in:
|
||||
|
||||
.. literalinclude:: example/fixtures/test_fixtures_request_different_scope.py
|
||||
.. literalinclude:: /example/fixtures/test_fixtures_request_different_scope.py
|
||||
|
||||
From the tests' perspectives, they have no problem seeing each of the fixtures
|
||||
they're dependent on:
|
||||
|
||||
.. image:: example/fixtures/test_fixtures_request_different_scope.svg
|
||||
.. image:: /example/fixtures/test_fixtures_request_different_scope.svg
|
||||
:align: center
|
||||
|
||||
So when they run, ``outer`` will have no problem finding ``inner``, because
|
||||
|
@ -1270,7 +1270,7 @@ For example, given a test file structure like this:
|
|||
|
||||
The boundaries of the scopes can be visualized like this:
|
||||
|
||||
.. image:: example/fixtures/fixture_availability.svg
|
||||
.. image:: /example/fixtures/fixture_availability.svg
|
||||
:align: center
|
||||
|
||||
The directories become their own sort of scope where fixtures that are defined
|
||||
|
@ -1346,7 +1346,7 @@ If ``plugin_a`` is installed and provides the fixture ``a_fix``, and
|
|||
``plugin_b`` is installed and provides the fixture ``b_fix``, then this is what
|
||||
the test's search for fixtures would look like:
|
||||
|
||||
.. image:: example/fixtures/fixture_availability_plugins.svg
|
||||
.. image:: /example/fixtures/fixture_availability_plugins.svg
|
||||
:align: center
|
||||
|
||||
pytest will only search for ``a_fix`` and ``b_fix`` in the plugins after
|
||||
|
@ -1401,13 +1401,13 @@ Within a function request for fixtures, those of higher-scopes (such as
|
|||
|
||||
Here's an example:
|
||||
|
||||
.. literalinclude:: example/fixtures/test_fixtures_order_scope.py
|
||||
.. literalinclude:: /example/fixtures/test_fixtures_order_scope.py
|
||||
|
||||
The test will pass because the larger scoped fixtures are executing first.
|
||||
|
||||
The order breaks down to this:
|
||||
|
||||
.. image:: example/fixtures/test_fixtures_order_scope.svg
|
||||
.. image:: /example/fixtures/test_fixtures_order_scope.svg
|
||||
:align: center
|
||||
|
||||
Fixtures of the same order execute based on dependencies
|
||||
|
@ -1421,17 +1421,17 @@ sure it is executed after ``b``.
|
|||
|
||||
For example:
|
||||
|
||||
.. literalinclude:: example/fixtures/test_fixtures_order_dependencies.py
|
||||
.. literalinclude:: /example/fixtures/test_fixtures_order_dependencies.py
|
||||
|
||||
If we map out what depends on what, we get something that look like this:
|
||||
|
||||
.. image:: example/fixtures/test_fixtures_order_dependencies.svg
|
||||
.. image:: /example/fixtures/test_fixtures_order_dependencies.svg
|
||||
:align: center
|
||||
|
||||
The rules provided by each fixture (as to what fixture(s) each one has to come
|
||||
after) are comprehensive enough that it can be flattened to this:
|
||||
|
||||
.. image:: example/fixtures/test_fixtures_order_dependencies_flat.svg
|
||||
.. image:: /example/fixtures/test_fixtures_order_dependencies_flat.svg
|
||||
:align: center
|
||||
|
||||
Enough information has to be provided through these requests in order for pytest
|
||||
|
@ -1442,7 +1442,7 @@ could go with any one of those interpretations at any point.
|
|||
|
||||
For example, if ``d`` didn't request ``c``, i.e.the graph would look like this:
|
||||
|
||||
.. image:: example/fixtures/test_fixtures_order_dependencies_unclear.svg
|
||||
.. image:: /example/fixtures/test_fixtures_order_dependencies_unclear.svg
|
||||
:align: center
|
||||
|
||||
Because nothing requested ``c`` other than ``g``, and ``g`` also requests ``f``,
|
||||
|
@ -1479,11 +1479,11 @@ non-autouse fixtures within that scope.
|
|||
|
||||
So if the test file looked like this:
|
||||
|
||||
.. literalinclude:: example/fixtures/test_fixtures_order_autouse.py
|
||||
.. literalinclude:: /example/fixtures/test_fixtures_order_autouse.py
|
||||
|
||||
the graph would look like this:
|
||||
|
||||
.. image:: example/fixtures/test_fixtures_order_autouse.svg
|
||||
.. image:: /example/fixtures/test_fixtures_order_autouse.svg
|
||||
:align: center
|
||||
|
||||
Because ``c`` can now be put above ``d`` in the graph, pytest can once again
|
||||
|
@ -1496,12 +1496,12 @@ Be careful with autouse, though, as an autouse fixture will automatically
|
|||
execute for every test that can reach it, even if they don't request it. For
|
||||
example, consider this file:
|
||||
|
||||
.. literalinclude:: example/fixtures/test_fixtures_order_autouse_multiple_scopes.py
|
||||
.. literalinclude:: /example/fixtures/test_fixtures_order_autouse_multiple_scopes.py
|
||||
|
||||
Even though nothing in ``TestClassWithC1Request`` is requesting ``c1``, it still
|
||||
is executed for the tests inside it anyway:
|
||||
|
||||
.. image:: example/fixtures/test_fixtures_order_autouse_multiple_scopes.svg
|
||||
.. image:: /example/fixtures/test_fixtures_order_autouse_multiple_scopes.svg
|
||||
:align: center
|
||||
|
||||
But just because one autouse fixture requested a non-autouse fixture, that
|
||||
|
@ -1512,11 +1512,11 @@ fixture) can apply to.
|
|||
|
||||
For example, take a look at this test file:
|
||||
|
||||
.. literalinclude:: example/fixtures/test_fixtures_order_autouse_temp_effects.py
|
||||
.. literalinclude:: /example/fixtures/test_fixtures_order_autouse_temp_effects.py
|
||||
|
||||
It would break down to something like this:
|
||||
|
||||
.. image:: example/fixtures/test_fixtures_order_autouse_temp_effects.svg
|
||||
.. image:: /example/fixtures/test_fixtures_order_autouse_temp_effects.svg
|
||||
:align: center
|
||||
|
||||
For ``test_req`` and ``test_no_req`` inside ``TestClassWithAutouse``, ``c3``
|
|
@ -1,3 +1,5 @@
|
|||
.. _plugin-list:
|
||||
|
||||
Plugins List
|
||||
============
|
||||
|
|
@ -136,7 +136,7 @@ Add warning filters to marked test items.
|
|||
pytest.mark.parametrize
|
||||
~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
**Tutorial**: :doc:`parametrize`.
|
||||
:ref:`parametrize`.
|
||||
|
||||
This mark has the same signature as :py:meth:`pytest.Metafunc.parametrize`; see there.
|
||||
|
||||
|
@ -146,7 +146,7 @@ This mark has the same signature as :py:meth:`pytest.Metafunc.parametrize`; see
|
|||
pytest.mark.skip
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
**Tutorial**: :ref:`skip`.
|
||||
:ref:`skip`.
|
||||
|
||||
Unconditionally skip a test function.
|
||||
|
||||
|
@ -160,7 +160,7 @@ Unconditionally skip a test function.
|
|||
pytest.mark.skipif
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
|
||||
**Tutorial**: :ref:`skipif`.
|
||||
:ref:`skipif`.
|
||||
|
||||
Skip a test function if a condition is ``True``.
|
||||
|
||||
|
@ -325,7 +325,7 @@ Under the hood, the cache plugin uses the simple
|
|||
capsys
|
||||
~~~~~~
|
||||
|
||||
**Tutorial**: :doc:`capture`.
|
||||
:ref:`captures`.
|
||||
|
||||
.. autofunction:: _pytest.capture.capsys()
|
||||
:no-auto-options:
|
||||
|
@ -350,7 +350,7 @@ capsys
|
|||
capsysbinary
|
||||
~~~~~~~~~~~~
|
||||
|
||||
**Tutorial**: :doc:`capture`.
|
||||
:ref:`captures`.
|
||||
|
||||
.. autofunction:: _pytest.capture.capsysbinary()
|
||||
:no-auto-options:
|
||||
|
@ -372,7 +372,7 @@ capsysbinary
|
|||
capfd
|
||||
~~~~~~
|
||||
|
||||
**Tutorial**: :doc:`capture`.
|
||||
:ref:`captures`.
|
||||
|
||||
.. autofunction:: _pytest.capture.capfd()
|
||||
:no-auto-options:
|
||||
|
@ -394,7 +394,7 @@ capfd
|
|||
capfdbinary
|
||||
~~~~~~~~~~~~
|
||||
|
||||
**Tutorial**: :doc:`capture`.
|
||||
:ref:`captures`.
|
||||
|
||||
.. autofunction:: _pytest.capture.capfdbinary()
|
||||
:no-auto-options:
|
||||
|
@ -416,7 +416,7 @@ capfdbinary
|
|||
doctest_namespace
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
**Tutorial**: :doc:`doctest`.
|
||||
:ref:`doctest`.
|
||||
|
||||
.. autofunction:: _pytest.doctest.doctest_namespace()
|
||||
|
||||
|
@ -436,7 +436,7 @@ doctest_namespace
|
|||
request
|
||||
~~~~~~~
|
||||
|
||||
**Tutorial**: :ref:`request example`.
|
||||
:ref:`request example`.
|
||||
|
||||
The ``request`` fixture is a special fixture providing information of the requesting test function.
|
||||
|
||||
|
@ -477,7 +477,7 @@ record_testsuite_property
|
|||
caplog
|
||||
~~~~~~
|
||||
|
||||
**Tutorial**: :doc:`logging`.
|
||||
:ref:`logging`.
|
||||
|
||||
.. autofunction:: _pytest.logging.caplog()
|
||||
:no-auto-options:
|
||||
|
@ -493,7 +493,7 @@ caplog
|
|||
monkeypatch
|
||||
~~~~~~~~~~~
|
||||
|
||||
**Tutorial**: :doc:`monkeypatch`.
|
||||
:ref:`monkeypatching`.
|
||||
|
||||
.. autofunction:: _pytest.monkeypatch.monkeypatch()
|
||||
:no-auto-options:
|
||||
|
@ -576,7 +576,7 @@ Each recorded warning is an instance of :class:`warnings.WarningMessage`.
|
|||
tmp_path
|
||||
~~~~~~~~
|
||||
|
||||
**Tutorial**: :doc:`tmpdir`
|
||||
:ref:`tmpdir`
|
||||
|
||||
.. autofunction:: _pytest.tmpdir.tmp_path()
|
||||
:no-auto-options:
|
||||
|
@ -587,7 +587,7 @@ tmp_path
|
|||
tmp_path_factory
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
**Tutorial**: :ref:`tmp_path_factory example`
|
||||
:ref:`tmp_path_factory example`
|
||||
|
||||
.. _`tmp_path_factory factory api`:
|
||||
|
||||
|
@ -601,7 +601,7 @@ tmp_path_factory
|
|||
tmpdir
|
||||
~~~~~~
|
||||
|
||||
**Tutorial**: :doc:`tmpdir`
|
||||
:ref:`tmpdir`
|
||||
|
||||
.. autofunction:: _pytest.tmpdir.tmpdir()
|
||||
:no-auto-options:
|
||||
|
@ -612,7 +612,7 @@ tmpdir
|
|||
tmpdir_factory
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
**Tutorial**: :ref:`tmpdir factory example`
|
||||
:ref:`tmpdir factory example`
|
||||
|
||||
.. _`tmpdir factory api`:
|
||||
|
||||
|
@ -626,7 +626,7 @@ tmpdir_factory
|
|||
Hooks
|
||||
-----
|
||||
|
||||
**Tutorial**: :doc:`writing_plugins`.
|
||||
:ref:`writing-plugins`.
|
||||
|
||||
.. currentmodule:: _pytest.hookspec
|
||||
|
||||
|
@ -1178,13 +1178,13 @@ passed multiple times. The expected format is ``name=value``. For example::
|
|||
|
||||
|
||||
Default encoding to use to decode text files with docstrings.
|
||||
:doc:`See how pytest handles doctests <doctest>`.
|
||||
:ref:`See how pytest handles doctests <doctest>`.
|
||||
|
||||
|
||||
.. confval:: doctest_optionflags
|
||||
|
||||
One or more doctest flag names from the standard ``doctest`` module.
|
||||
:doc:`See how pytest handles doctests <doctest>`.
|
||||
:ref:`See how pytest handles doctests <doctest>`.
|
||||
|
||||
|
||||
.. confval:: empty_parameter_set_mark
|
|
@ -122,7 +122,7 @@ you can copy from:
|
|||
|
||||
* a custom collection example plugin: :ref:`yaml plugin`
|
||||
* builtin plugins which provide pytest's own functionality
|
||||
* many :doc:`external plugins <plugin_list>` providing additional features
|
||||
* many :ref:`external plugins <plugin-list>` providing additional features
|
||||
|
||||
All of these plugins implement :ref:`hooks <hook-reference>` and/or :ref:`fixtures <fixture>`
|
||||
to extend and add functionality.
|
Loading…
Reference in New Issue