Merge pull request #8433 from evildmp/evolutionary-documentation-restructure

Added how-to and reference directories.
This commit is contained in:
Bruno Oliveira 2021-03-11 19:26:09 -03:00 committed by GitHub
commit 32ad70dea8
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
28 changed files with 71 additions and 65 deletions

View File

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

View File

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

View File

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

View File

@ -1,3 +1,5 @@
.. _get-started:
Get Started
===================================

View File

@ -1,3 +1,4 @@
.. _monkeypatching:
How to monkeypatch/mock modules and environments
================================================================

View File

@ -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`_.

View File

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

View File

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

View File

@ -1,3 +1,4 @@
.. _doctest:
Doctest integration for modules and test files
=========================================================

View File

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

View File

@ -1,3 +1,5 @@
.. _plugin-list:
Plugins List
============

View File

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

View File

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