Skip to content

Commit 204004c

Browse files
nicoddemusnicoddemus
authored
Review doctest docs (#5183)
Review doctest docs
2 parents 772a4a5 + e943aff commit 204004c

File tree

1 file changed

+118
-81
lines changed

1 file changed

+118
-81
lines changed

‎doc/en/doctest.rst

Lines changed: 118 additions & 81 deletions
Original file line numberDiff line numberDiff line change
@@ -10,51 +10,41 @@ can change the pattern by issuing:
1010
1111
pytest --doctest-glob='*.rst'
1212
13-
on the command line. Since version ``2.9``, ``--doctest-glob``
14-
can be given multiple times in the command-line.
13+
on the command line. ``--doctest-glob`` can be given multiple times in the command-line.
1514

16-
.. versionadded:: 3.1
17-
18-
You can specify the encoding that will be used for those doctest files
19-
using the ``doctest_encoding`` ini option:
20-
21-
.. code-block:: ini
22-
23-
# content of pytest.ini
24-
[pytest]
25-
doctest_encoding = latin1
26-
27-
The default encoding is UTF-8.
15+
If you then have a text file like this:
2816

29-
You can also trigger running of doctests
30-
from docstrings in all python modules (including regular
31-
python test modules):
17+
.. code-block:: text
3218
33-
.. code-block:: bash
19+
# content of test_example.txt
3420
35-
pytest --doctest-modules
21+
hello this is a doctest
22+
>>> x = 3
23+
>>> x
24+
3
3625
37-
You can make these changes permanent in your project by
38-
putting them into a pytest.ini file like this:
26+
then you can just invoke ``pytest`` directly:
3927

40-
.. code-block:: ini
28+
.. code-block:: pytest
4129
42-
# content of pytest.ini
43-
[pytest]
44-
addopts = --doctest-modules
30+
$ pytest
31+
=========================== test session starts ============================
32+
platform linux -- Python 3.x.y, pytest-4.x.y, py-1.x.y, pluggy-0.x.y
33+
cachedir: $PYTHON_PREFIX/.pytest_cache
34+
rootdir: $REGENDOC_TMPDIR
35+
collected 1 item
4536
46-
If you then have a text file like this:
37+
test_example.txt . [100%]
4738
48-
.. code-block:: text
39+
========================= 1 passed in 0.12 seconds =========================
4940
50-
# content of example.rst
41+
By default, pytest will collect ``test*.txt`` files looking for doctest directives, but you
42+
can pass additional globs using the ``--doctest-glob`` option (multi-allowed).
5143

52-
hello this is a doctest
53-
>>> x = 3
54-
>>> x
55-
3
44+
In addition to text files, you can also execute doctests directly from docstrings of your classes
45+
and functions, including from test modules:
5646

57-
and another like this::
47+
.. code-block:: python
5848
5949
# content of mymodule.py
6050
def something():
@@ -64,36 +54,60 @@ and another like this::
6454
"""
6555
return 42
6656
67-
then you can just invoke ``pytest`` without command line options:
68-
69-
.. code-block:: pytest
57+
.. code-block:: bash
7058
71-
$ pytest
59+
$ pytest --doctest-modules
7260
=========================== test session starts ============================
7361
platform linux -- Python 3.x.y, pytest-4.x.y, py-1.x.y, pluggy-0.x.y
7462
cachedir: $PYTHON_PREFIX/.pytest_cache
75-
rootdir: $REGENDOC_TMPDIR, inifile: pytest.ini
76-
collected 1 item
63+
rootdir: $REGENDOC_TMPDIR
64+
collected 2 items
7765
78-
mymodule.py . [100%]
66+
mymodule.py . [ 50%]
67+
test_example.txt . [100%]
7968
80-
========================= 1 passed in 0.12 seconds =========================
69+
========================= 2 passed in 0.12 seconds =========================
8170
82-
It is possible to use fixtures using the ``getfixture`` helper:
71+
You can make these changes permanent in your project by
72+
putting them into a pytest.ini file like this:
8373

84-
.. code-block:: text
74+
.. code-block:: ini
8575
86-
# content of example.rst
87-
>>> tmp = getfixture('tmpdir')
88-
>>> ...
89-
>>>
76+
# content of pytest.ini
77+
[pytest]
78+
addopts = --doctest-modules
9079
91-
Also, :ref:`usefixtures` and :ref:`autouse` fixtures are supported
92-
when executing text doctest files.
80+
.. note::
9381

94-
The standard ``doctest`` module provides some setting flags to configure the
95-
strictness of doctest tests. In pytest, you can enable those flags using the
96-
configuration file. To make pytest ignore trailing whitespaces and ignore
82+
The builtin pytest doctest supports only ``doctest`` blocks, but if you are looking
83+
for more advanced checking over *all* your documentation,
84+
including doctests, ``.. codeblock:: python`` Sphinx directive support,
85+
and any other examples your documentation may include, you may wish to
86+
consider `Sybil <https://sybil.readthedocs.io/en/latest/index.html>`__.
87+
It provides pytest integration out of the box.
88+
89+
90+
Encoding
91+
--------
92+
93+
The default encoding is **UTF-8**, but you can specify the encoding
94+
that will be used for those doctest files using the
95+
``doctest_encoding`` ini option:
96+
97+
.. code-block:: ini
98+
99+
# content of pytest.ini
100+
[pytest]
101+
doctest_encoding = latin1
102+
103+
Using 'doctest' options
104+
-----------------------
105+
106+
The standard ``doctest`` module provides some `options <https://docs.python.org/3/library/doctest.html#option-flags>`__
107+
to configure the strictness of doctest tests. In pytest, you can enable those flags using the
108+
configuration file.
109+
110+
For example, to make pytest ignore trailing whitespaces and ignore
97111
lengthy exception stack traces you can just write:
98112

99113
.. code-block:: ini
@@ -110,16 +124,7 @@ Python 3 unchanged:
110124
* ``ALLOW_BYTES``: when enabled, the ``b`` prefix is stripped from byte strings
111125
in expected doctest output.
112126

113-
As with any other option flag, these flags can be enabled in ``pytest.ini`` using
114-
the ``doctest_optionflags`` ini option:
115-
116-
.. code-block:: ini
117-
118-
[pytest]
119-
doctest_optionflags = ALLOW_UNICODE ALLOW_BYTES
120-
121-
122-
Alternatively, it can be enabled by an inline comment in the doc test
127+
Alternatively, options can be enabled by an inline comment in the doc test
123128
itself:
124129

125130
.. code-block:: rst
@@ -128,20 +133,58 @@ itself:
128133
>>> get_unicode_greeting() # doctest: +ALLOW_UNICODE
129134
'Hello'
130135
131-
By default, pytest would report only the first failure for a given doctest. If
136+
By default, pytest would report only the first failure for a given doctest. If
132137
you want to continue the test even when you have failures, do:
133138

134139
.. code-block:: bash
135140
136141
pytest --doctest-modules --doctest-continue-on-failure
137142
138143
139-
.. _`doctest_namespace`:
144+
Output format
145+
-------------
146+
147+
You can change the diff output format on failure for your doctests
148+
by using one of standard doctest modules format in options
149+
(see :data:`python:doctest.REPORT_UDIFF`, :data:`python:doctest.REPORT_CDIFF`,
150+
:data:`python:doctest.REPORT_NDIFF`, :data:`python:doctest.REPORT_ONLY_FIRST_FAILURE`):
151+
152+
.. code-block:: bash
153+
154+
pytest --doctest-modules --doctest-report none
155+
pytest --doctest-modules --doctest-report udiff
156+
pytest --doctest-modules --doctest-report cdiff
157+
pytest --doctest-modules --doctest-report ndiff
158+
pytest --doctest-modules --doctest-report only_first_failure
140159
141-
The 'doctest_namespace' fixture
142-
-------------------------------
143160
144-
.. versionadded:: 3.0
161+
pytest-specific features
162+
------------------------
163+
164+
Some features are provided to make writing doctests easier or with better integration with
165+
your existing test suite. Keep in mind however that by using those features you will make
166+
your doctests incompatible with the standard ``doctests`` module.
167+
168+
Using fixtures
169+
^^^^^^^^^^^^^^
170+
171+
It is possible to use fixtures using the ``getfixture`` helper:
172+
173+
.. code-block:: text
174+
175+
# content of example.rst
176+
>>> tmp = getfixture('tmpdir')
177+
>>> ...
178+
>>>
179+
180+
Also, :ref:`usefixtures` and :ref:`autouse` fixtures are supported
181+
when executing text doctest files.
182+
183+
184+
.. _`doctest_namespace`:
185+
186+
'doctest_namespace' fixture
187+
^^^^^^^^^^^^^^^^^^^^^^^^^^^
145188

146189
The ``doctest_namespace`` fixture can be used to inject items into the
147190
namespace in which your doctests run. It is intended to be used within
@@ -171,20 +214,14 @@ Note that like the normal ``conftest.py``, the fixtures are discovered in the di
171214
Meaning that if you put your doctest with your source code, the relevant conftest.py needs to be in the same directory tree.
172215
Fixtures will not be discovered in a sibling directory tree!
173216

174-
Output format
175-
-------------
176-
177-
.. versionadded:: 3.0
217+
Skipping tests dynamically
218+
^^^^^^^^^^^^^^^^^^^^^^^^^^
178219

179-
You can change the diff output format on failure for your doctests
180-
by using one of standard doctest modules format in options
181-
(see :data:`python:doctest.REPORT_UDIFF`, :data:`python:doctest.REPORT_CDIFF`,
182-
:data:`python:doctest.REPORT_NDIFF`, :data:`python:doctest.REPORT_ONLY_FIRST_FAILURE`):
220+
.. versionadded:: 4.4
183221

184-
.. code-block:: bash
222+
You can use ``pytest.skip`` to dynamically skip doctests. For example::
185223

186-
pytest --doctest-modules --doctest-report none
187-
pytest --doctest-modules --doctest-report udiff
188-
pytest --doctest-modules --doctest-report cdiff
189-
pytest --doctest-modules --doctest-report ndiff
190-
pytest --doctest-modules --doctest-report only_first_failure
224+
>>> import sys, pytest
225+
>>> if sys.platform.startswith('win'):
226+
... pytest.skip('this doctest does not work on Windows')
227+
...

0 commit comments

Comments
 (0)