From 8583cab45b84c803abe355bf058efca97b25237a Mon Sep 17 00:00:00 2001 From: Prakhar Gurunani Date: Fri, 27 Nov 2020 20:53:47 +0530 Subject: [PATCH 1/9] add example for skipping docstring --- doc/en/doctest.rst | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/doc/en/doctest.rst b/doc/en/doctest.rst index c6e34b2b1c8..7d75a800157 100644 --- a/doc/en/doctest.rst +++ b/doc/en/doctest.rst @@ -266,3 +266,29 @@ You can use ``pytest.skip`` to dynamically skip doctests. For example: >>> if sys.platform.startswith('win'): ... pytest.skip('this doctest does not work on Windows') ... + +This will skip all the doctests in python files in that directory. To skip particular docstrings, use the ``@pytest.mark.skipif`` decorator. `Learn more `_. + +``pytest.skip`` can also be used inside a python script - + +.. code-block:: python + + if sys.platform.startswith('win'): + pytest.skip('all doctests defined in this file will not work on windows') + + def test_function_1(x): + """ + >>> test_function_1(x) + # Expected result + """ + + def test_function_2(y): + """ + >>> test_function_2(y) + # Expected result + """ + .. + .. + .. + +This example will skip doctests on Windows machines for ``test_function_1()``, ``test_function_2()`` and all other functions for which docstrings are defined in that python file. From 6f111cb6644fd6c17ad2c1802acbdd3b1e8024d7 Mon Sep 17 00:00:00 2001 From: Prakhar Gurunani Date: Fri, 27 Nov 2020 21:34:52 +0530 Subject: [PATCH 2/9] add author --- AUTHORS | 1 + 1 file changed, 1 insertion(+) diff --git a/AUTHORS b/AUTHORS index 85d5b90de3d..adf1894356a 100644 --- a/AUTHORS +++ b/AUTHORS @@ -239,6 +239,7 @@ Philipp Loose Pieter Mulder Piotr Banaszkiewicz Piotr Helm +Prakhar Gurunani Prashant Anand Prashant Sharma Pulkit Goyal From 08ee315c0155e88fd20cabd4441868216267fccc Mon Sep 17 00:00:00 2001 From: Prakhar Gurunani Date: Fri, 27 Nov 2020 21:51:07 +0530 Subject: [PATCH 3/9] add changelog --- changelog/7429.doc.rst | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelog/7429.doc.rst diff --git a/changelog/7429.doc.rst b/changelog/7429.doc.rst new file mode 100644 index 00000000000..ed9f0506c44 --- /dev/null +++ b/changelog/7429.doc.rst @@ -0,0 +1 @@ +Add more information and use cases about using ``pytest.skip`` for skipping doctests with example. From 8a8a2de9f808d59ed53ad726057ddc2091bb5f1b Mon Sep 17 00:00:00 2001 From: Prakhar Gurunani Date: Fri, 27 Nov 2020 22:07:08 +0530 Subject: [PATCH 4/9] fix linting issues --- doc/en/doctest.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/en/doctest.rst b/doc/en/doctest.rst index 7d75a800157..f85ee4a4048 100644 --- a/doc/en/doctest.rst +++ b/doc/en/doctest.rst @@ -269,7 +269,7 @@ You can use ``pytest.skip`` to dynamically skip doctests. For example: This will skip all the doctests in python files in that directory. To skip particular docstrings, use the ``@pytest.mark.skipif`` decorator. `Learn more `_. -``pytest.skip`` can also be used inside a python script - +``pytest.skip`` can also be used inside a python script - .. code-block:: python From 0811a19df407de80238815cf66af34beb352a00d Mon Sep 17 00:00:00 2001 From: Prakhar Gurunani Date: Fri, 27 Nov 2020 22:20:02 +0530 Subject: [PATCH 5/9] fix linting issues --- doc/en/doctest.rst | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/doc/en/doctest.rst b/doc/en/doctest.rst index f85ee4a4048..dbd3aad3691 100644 --- a/doc/en/doctest.rst +++ b/doc/en/doctest.rst @@ -273,8 +273,9 @@ This will skip all the doctests in python files in that directory. To skip parti .. code-block:: python - if sys.platform.startswith('win'): - pytest.skip('all doctests defined in this file will not work on windows') + if sys.platform.startswith("win"): + pytest.skip("all doctests defined in this file will not work on windows") + def test_function_1(x): """ @@ -282,13 +283,11 @@ This will skip all the doctests in python files in that directory. To skip parti # Expected result """ + def test_function_2(y): """ >>> test_function_2(y) # Expected result """ - .. - .. - .. This example will skip doctests on Windows machines for ``test_function_1()``, ``test_function_2()`` and all other functions for which docstrings are defined in that python file. From 1a728ab9864f015b3ebd704265e7849658e086e1 Mon Sep 17 00:00:00 2001 From: Prakhar Gurunani Date: Sat, 28 Nov 2020 19:51:56 +0530 Subject: [PATCH 6/9] Update pytest.skip --- doc/en/doctest.rst | 29 ++++++++++++++++++++--------- 1 file changed, 20 insertions(+), 9 deletions(-) diff --git a/doc/en/doctest.rst b/doc/en/doctest.rst index dbd3aad3691..777f4f00b39 100644 --- a/doc/en/doctest.rst +++ b/doc/en/doctest.rst @@ -267,27 +267,38 @@ You can use ``pytest.skip`` to dynamically skip doctests. For example: ... pytest.skip('this doctest does not work on Windows') ... -This will skip all the doctests in python files in that directory. To skip particular docstrings, use the ``@pytest.mark.skipif`` decorator. `Learn more `_. - -``pytest.skip`` can also be used inside a python script - +``pytest.skip`` is used inside specific docstrings and are not effective at module level. .. code-block:: python - if sys.platform.startswith("win"): - pytest.skip("all doctests defined in this file will not work on windows") - - def test_function_1(x): """ + >>> import pytest, sys + >>> if sys.platform.startswith('win'): + ... pytest.skip('skip doctest for foobar_pytest_skip on Windows') >>> test_function_1(x) # Expected result """ +Skipping a single doctest can be done by ``# doctest: +SKIP`` + +.. code-block:: python def test_function_2(y): """ - >>> test_function_2(y) + + >>> test_function_2(y) # doctest: +SKIP # Expected result """ +Doctests which have chances of failing due to some reason can be declared with ``pytest.xfail`` -This example will skip doctests on Windows machines for ``test_function_1()``, ``test_function_2()`` and all other functions for which docstrings are defined in that python file. +.. code-block:: python + + def test_function_3(z): + """ + >>> import pytest, sys + >>> if sys.platform.startswith('win'): + ... pytest.xfail('xfail doctest for foobar_pytest_xfail on Windows') + >>> test_function_3(y) + # Expected result + """ From 88779c23588d76f9d46c2c619fa06a92019712df Mon Sep 17 00:00:00 2001 From: Prakhar Gurunani Date: Sat, 28 Nov 2020 19:58:34 +0530 Subject: [PATCH 7/9] Add blank line --- doc/en/doctest.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/en/doctest.rst b/doc/en/doctest.rst index 777f4f00b39..8ac76299f34 100644 --- a/doc/en/doctest.rst +++ b/doc/en/doctest.rst @@ -290,6 +290,7 @@ Skipping a single doctest can be done by ``# doctest: +SKIP`` >>> test_function_2(y) # doctest: +SKIP # Expected result """ + Doctests which have chances of failing due to some reason can be declared with ``pytest.xfail`` .. code-block:: python From 65a1839770d1538513757f733eb868178e7fe8e6 Mon Sep 17 00:00:00 2001 From: Bruno Oliveira Date: Sat, 28 Nov 2020 12:13:25 -0300 Subject: [PATCH 8/9] Improve doctest skipping docs --- doc/en/doctest.rst | 72 +++++++++++++++++++++++----------------------- 1 file changed, 36 insertions(+), 36 deletions(-) diff --git a/doc/en/doctest.rst b/doc/en/doctest.rst index 8ac76299f34..f486d5a9b6d 100644 --- a/doc/en/doctest.rst +++ b/doc/en/doctest.rst @@ -253,12 +253,32 @@ Note that like the normal ``conftest.py``, the fixtures are discovered in the di Meaning that if you put your doctest with your source code, the relevant conftest.py needs to be in the same directory tree. Fixtures will not be discovered in a sibling directory tree! -Skipping tests dynamically -^^^^^^^^^^^^^^^^^^^^^^^^^^ +Skipping tests +^^^^^^^^^^^^^^ + +For the same reasons one might want to skip normal tests, it is also possible to skip +tests inside doctests. -.. versionadded:: 4.4 +To skip a single check inside a doctest you can use the standard +`doctest.SKIP `__ directive: + +.. code-block:: python + + def test_random(y): + """ + >>> random.random() # doctest: +SKIP + 0.156231223 + + >>> 1 + 1 + 2 + """ + +This will skip the first check, but not the second. + +pytest also allows using the standard pytest functions :func:`pytest.skip` and +:func:`pytest.xfail` inside doctests, which might be useful because you can +then skip/xfail tests based on external conditions: -You can use ``pytest.skip`` to dynamically skip doctests. For example: .. code-block:: text @@ -266,40 +286,20 @@ You can use ``pytest.skip`` to dynamically skip doctests. For example: >>> if sys.platform.startswith('win'): ... pytest.skip('this doctest does not work on Windows') ... + >>> import fcntl + >>> ... -``pytest.skip`` is used inside specific docstrings and are not effective at module level. - -.. code-block:: python - - def test_function_1(x): - """ - >>> import pytest, sys - >>> if sys.platform.startswith('win'): - ... pytest.skip('skip doctest for foobar_pytest_skip on Windows') - >>> test_function_1(x) - # Expected result - """ - -Skipping a single doctest can be done by ``# doctest: +SKIP`` - -.. code-block:: python +However using those functions is discouraged because it reduces the readability of the +docstring. - def test_function_2(y): - """ +.. note:: - >>> test_function_2(y) # doctest: +SKIP - # Expected result - """ - -Doctests which have chances of failing due to some reason can be declared with ``pytest.xfail`` + :func:`pytest.skip` and :func:`pytest.xfail` behave differently depending + if the doctests are in a Python file (in docstrings) or a text file containing + doctests intermingled with text: -.. code-block:: python + * Python modules (docstrings): the functions only act in that specific docstring, + letting the other docstrings in the same module execute as normal. - def test_function_3(z): - """ - >>> import pytest, sys - >>> if sys.platform.startswith('win'): - ... pytest.xfail('xfail doctest for foobar_pytest_xfail on Windows') - >>> test_function_3(y) - # Expected result - """ + * Text files: the functions will skip/xfail the checks for the rest of the entire + file. From 706f3eaaec68bf890ee5ef9efbb532aae49cf2c5 Mon Sep 17 00:00:00 2001 From: Bruno Oliveira Date: Sat, 28 Nov 2020 12:14:31 -0300 Subject: [PATCH 9/9] Improve CHANGELOG --- changelog/7429.doc.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/changelog/7429.doc.rst b/changelog/7429.doc.rst index ed9f0506c44..e6376b727b2 100644 --- a/changelog/7429.doc.rst +++ b/changelog/7429.doc.rst @@ -1 +1 @@ -Add more information and use cases about using ``pytest.skip`` for skipping doctests with example. +Add more information and use cases about skipping doctests.