From 50937fe622ded727c6d207538dd81fd91bb1d1b1 Mon Sep 17 00:00:00 2001 From: Bruno Oliveira Date: Sat, 27 Apr 2019 10:11:25 -0300 Subject: [PATCH 01/15] Add note about pytest_load_initial_conftests working only from plugins Fix #5175 --- doc/en/example/simple.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/en/example/simple.rst b/doc/en/example/simple.rst index e9fe1f249..fdee41c13 100644 --- a/doc/en/example/simple.rst +++ b/doc/en/example/simple.rst @@ -107,7 +107,7 @@ the command line arguments before they get processed: .. code-block:: python - # content of conftest.py + # setuptools plugin import sys From 9742f11d37b086750b463e682653123e35a2dbd8 Mon Sep 17 00:00:00 2001 From: Bruno Oliveira Date: Sun, 28 Apr 2019 11:06:47 -0300 Subject: [PATCH 02/15] Removed unused warning message --- src/_pytest/deprecated.py | 6 ------ 1 file changed, 6 deletions(-) diff --git a/src/_pytest/deprecated.py b/src/_pytest/deprecated.py index fa7e89364..b65700417 100644 --- a/src/_pytest/deprecated.py +++ b/src/_pytest/deprecated.py @@ -48,12 +48,6 @@ RESULT_LOG = PytestDeprecationWarning( "See https://docs.pytest.org/en/latest/deprecations.html#result-log-result-log for more information." ) -MARK_INFO_ATTRIBUTE = RemovedInPytest4Warning( - "MarkInfo objects are deprecated as they contain merged marks which are hard to deal with correctly.\n" - "Please use node.get_closest_marker(name) or node.iter_markers(name).\n" - "Docs: https://docs.pytest.org/en/latest/mark.html#updating-code" -) - RAISES_EXEC = PytestDeprecationWarning( "raises(..., 'code(as_a_string)') is deprecated, use the context manager form or use `exec()` directly\n\n" "See https://docs.pytest.org/en/latest/deprecations.html#raises-warns-exec" From a3c2ec3c5b7286c26dd2552474b23c171ccef14e Mon Sep 17 00:00:00 2001 From: Bruno Oliveira Date: Sun, 28 Apr 2019 11:10:21 -0300 Subject: [PATCH 03/15] Add CHANGELOG for #5182 --- changelog/5182.trivial.rst | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelog/5182.trivial.rst diff --git a/changelog/5182.trivial.rst b/changelog/5182.trivial.rst new file mode 100644 index 000000000..24bd9bd86 --- /dev/null +++ b/changelog/5182.trivial.rst @@ -0,0 +1 @@ +Removed internal and unused ``_pytest.deprecated.MARK_INFO_ATTRIBUTE``. From 67755d67fbecc53bbe1c32511176e87623ba9a38 Mon Sep 17 00:00:00 2001 From: Bruno Oliveira Date: Sun, 28 Apr 2019 11:54:29 -0300 Subject: [PATCH 04/15] Review doctest docs * Add pytest.skip() example * Add blurb about Sybil * Create a subsection for doctest-options * Create a subsection for pytest-specific features --- doc/en/doctest.rst | 193 +++++++++++++++++++++++++-------------------- 1 file changed, 109 insertions(+), 84 deletions(-) diff --git a/doc/en/doctest.rst b/doc/en/doctest.rst index 549ebb00f..cc7d8c288 100644 --- a/doc/en/doctest.rst +++ b/doc/en/doctest.rst @@ -10,61 +10,20 @@ can change the pattern by issuing: pytest --doctest-glob='*.rst' -on the command line. Since version ``2.9``, ``--doctest-glob`` -can be given multiple times in the command-line. - -.. versionadded:: 3.1 - - You can specify the encoding that will be used for those doctest files - using the ``doctest_encoding`` ini option: - - .. code-block:: ini - - # content of pytest.ini - [pytest] - doctest_encoding = latin1 - - The default encoding is UTF-8. - -You can also trigger running of doctests -from docstrings in all python modules (including regular -python test modules): - -.. code-block:: bash - - pytest --doctest-modules - -You can make these changes permanent in your project by -putting them into a pytest.ini file like this: - -.. code-block:: ini - - # content of pytest.ini - [pytest] - addopts = --doctest-modules +on the command line. ``--doctest-glob`` can be given multiple times in the command-line. If you then have a text file like this: .. code-block:: text - # content of example.rst + # content of test_example.txt hello this is a doctest >>> x = 3 >>> x 3 -and another like this:: - - # content of mymodule.py - def something(): - """ a doctest in a docstring - >>> something() - 42 - """ - return 42 - -then you can just invoke ``pytest`` without command line options: +then you can just invoke ``pytest`` directly: .. code-block:: pytest @@ -79,21 +38,64 @@ then you can just invoke ``pytest`` without command line options: ========================= 1 passed in 0.12 seconds ========================= -It is possible to use fixtures using the ``getfixture`` helper: +By default, pytest will collect ``test*.txt`` files looking for doctest directives, but you +can pass additional globs using the ``--doctest-glob`` option (multi-allowed). -.. code-block:: text +In addition to text files, you can also execute doctests directly from docstrings of your classes +and functions, including from test modules: - # content of example.rst - >>> tmp = getfixture('tmpdir') - >>> ... - >>> +.. code-block:: python -Also, :ref:`usefixtures` and :ref:`autouse` fixtures are supported -when executing text doctest files. + # content of mymodule.py + def something(): + """ a doctest in a docstring + >>> something() + 42 + """ + return 42 -The standard ``doctest`` module provides some setting flags to configure the -strictness of doctest tests. In pytest, you can enable those flags using the -configuration file. To make pytest ignore trailing whitespaces and ignore +.. code-block:: bash + + $ pytest --doctest-modules + +You can make these changes permanent in your project by +putting them into a pytest.ini file like this: + +.. code-block:: ini + + # content of pytest.ini + [pytest] + addopts = --doctest-modules + +.. note:: + + If you are making serious use of doctests through your code, please checkout + `Sybil `__, which besides + supporting doctests also supports Sphinx directives, plus other features. + It provides pytest integration out of the box. + + +Encoding +-------- + +The default encoding is **UTF-8**, but you can specify the encoding +that will be used for those doctest files using the +``doctest_encoding`` ini option: + +.. code-block:: ini + + # content of pytest.ini + [pytest] + doctest_encoding = latin1 + +Using 'doctest' options +----------------------- + +The standard ``doctest`` module provides some `options `__ +to configure the strictness of doctest tests. In pytest, you can enable those flags using the +configuration file. + +For example, to make pytest ignore trailing whitespaces and ignore lengthy exception stack traces you can just write: .. code-block:: ini @@ -110,16 +112,7 @@ Python 3 unchanged: * ``ALLOW_BYTES``: when enabled, the ``b`` prefix is stripped from byte strings in expected doctest output. -As with any other option flag, these flags can be enabled in ``pytest.ini`` using -the ``doctest_optionflags`` ini option: - -.. code-block:: ini - - [pytest] - doctest_optionflags = ALLOW_UNICODE ALLOW_BYTES - - -Alternatively, it can be enabled by an inline comment in the doc test +Alternatively, options can be enabled by an inline comment in the doc test itself: .. code-block:: rst @@ -128,7 +121,7 @@ itself: >>> get_unicode_greeting() # doctest: +ALLOW_UNICODE 'Hello' -By default, pytest would report only the first failure for a given doctest. If +By default, pytest would report only the first failure for a given doctest. If you want to continue the test even when you have failures, do: .. code-block:: bash @@ -136,12 +129,50 @@ you want to continue the test even when you have failures, do: pytest --doctest-modules --doctest-continue-on-failure +Output format +------------- + +You can change the diff output format on failure for your doctests +by using one of standard doctest modules format in options +(see :data:`python:doctest.REPORT_UDIFF`, :data:`python:doctest.REPORT_CDIFF`, +:data:`python:doctest.REPORT_NDIFF`, :data:`python:doctest.REPORT_ONLY_FIRST_FAILURE`): + +.. code-block:: bash + + pytest --doctest-modules --doctest-report none + pytest --doctest-modules --doctest-report udiff + pytest --doctest-modules --doctest-report cdiff + pytest --doctest-modules --doctest-report ndiff + pytest --doctest-modules --doctest-report only_first_failure + + +pytest-specific features +------------------------ + +Some features are provided to make writing doctests easier or with better integration with +your existing test suite. Keep in mind however that by using those features you will make +your doctests incompatible with the standard ``doctests`` module. + +Using fixtures +^^^^^^^^^^^^^^ + +It is possible to use fixtures using the ``getfixture`` helper: + +.. code-block:: text + + # content of example.rst + >>> tmp = getfixture('tmpdir') + >>> ... + >>> + +Also, :ref:`usefixtures` and :ref:`autouse` fixtures are supported +when executing text doctest files. + + .. _`doctest_namespace`: -The 'doctest_namespace' fixture -------------------------------- - -.. versionadded:: 3.0 +'doctest_namespace' fixture +^^^^^^^^^^^^^^^^^^^^^^^^^^^ The ``doctest_namespace`` fixture can be used to inject items into the namespace in which your doctests run. It is intended to be used within @@ -171,20 +202,14 @@ 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! -Output format -------------- +Skipping tests dynamically +^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. versionadded:: 3.0 +.. versionadded:: 4.4 -You can change the diff output format on failure for your doctests -by using one of standard doctest modules format in options -(see :data:`python:doctest.REPORT_UDIFF`, :data:`python:doctest.REPORT_CDIFF`, -:data:`python:doctest.REPORT_NDIFF`, :data:`python:doctest.REPORT_ONLY_FIRST_FAILURE`): +You can use ``pytest.skip`` to dynamically skip doctests. For example:: -.. code-block:: bash - - pytest --doctest-modules --doctest-report none - pytest --doctest-modules --doctest-report udiff - pytest --doctest-modules --doctest-report cdiff - pytest --doctest-modules --doctest-report ndiff - pytest --doctest-modules --doctest-report only_first_failure + >>> import sys, pytest + >>> if sys.platform.startswith('win'): + ... pytest.skip('this doctest does not work on Windows') + ... From f6ab6d71ad07ae9a4bdc8a65d7e9d7359f6b94c5 Mon Sep 17 00:00:00 2001 From: Bruno Oliveira Date: Sun, 28 Apr 2019 15:11:53 +0000 Subject: [PATCH 05/15] Run regendoc --- doc/en/doctest.rst | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/doc/en/doctest.rst b/doc/en/doctest.rst index cc7d8c288..5ab548239 100644 --- a/doc/en/doctest.rst +++ b/doc/en/doctest.rst @@ -31,10 +31,10 @@ then you can just invoke ``pytest`` directly: =========================== test session starts ============================ platform linux -- Python 3.x.y, pytest-4.x.y, py-1.x.y, pluggy-0.x.y cachedir: $PYTHON_PREFIX/.pytest_cache - rootdir: $REGENDOC_TMPDIR, inifile: pytest.ini + rootdir: $REGENDOC_TMPDIR collected 1 item - mymodule.py . [100%] + test_example.txt . [100%] ========================= 1 passed in 0.12 seconds ========================= @@ -57,6 +57,16 @@ and functions, including from test modules: .. code-block:: bash $ pytest --doctest-modules + =========================== test session starts ============================ + platform linux -- Python 3.x.y, pytest-4.x.y, py-1.x.y, pluggy-0.x.y + cachedir: $PYTHON_PREFIX/.pytest_cache + rootdir: $REGENDOC_TMPDIR + collected 2 items + + mymodule.py . [ 50%] + test_example.txt . [100%] + + ========================= 2 passed in 0.12 seconds ========================= You can make these changes permanent in your project by putting them into a pytest.ini file like this: From 9c5da9c0d15ccf7ab9f3a8fbd6540e4a56ea789f Mon Sep 17 00:00:00 2001 From: Bruno Oliveira Date: Sun, 28 Apr 2019 12:37:58 -0300 Subject: [PATCH 06/15] Remove all version references to obsolete pytest versions Remove version references to pytest 2 and 3. Just like Python 3 no longer has references to Python 2, I think we should follow the same approach in pytest. --- doc/en/assert.rst | 12 ++++++------ doc/en/cache.rst | 2 +- doc/en/capture.rst | 8 ++++---- doc/en/customize.rst | 2 +- doc/en/deprecations.rst | 2 +- doc/en/example/markers.rst | 4 ++-- doc/en/example/simple.rst | 2 +- doc/en/fixture.rst | 6 +++--- doc/en/historical-notes.rst | 20 ++++++++++---------- doc/en/logging.rst | 4 ++-- doc/en/mark.rst | 2 +- doc/en/parametrize.rst | 4 ++-- doc/en/reference.rst | 36 ++++++++++++++++++------------------ doc/en/skipping.rst | 6 +++--- doc/en/tmpdir.rst | 6 +++--- doc/en/usage.rst | 18 +++++++++--------- doc/en/warnings.rst | 12 ++++++------ doc/en/writing_plugins.rst | 2 +- doc/en/yieldfixture.rst | 4 ++-- 19 files changed, 76 insertions(+), 76 deletions(-) diff --git a/doc/en/assert.rst b/doc/en/assert.rst index dec3cd941..1e06d9757 100644 --- a/doc/en/assert.rst +++ b/doc/en/assert.rst @@ -154,7 +154,7 @@ or bugs in dependencies. Assertions about expected warnings ----------------------------------------- -.. versionadded:: 2.8 + You can check that code raises a particular warning using :ref:`pytest.warns `. @@ -165,7 +165,7 @@ You can check that code raises a particular warning using Making use of context-sensitive comparisons ------------------------------------------------- -.. versionadded:: 2.0 + ``pytest`` has rich support for providing context-sensitive information when it encounters comparisons. For example: @@ -284,7 +284,7 @@ the conftest file: Assertion introspection details ------------------------------- -.. versionadded:: 2.1 + Reporting details about a failing assertion is achieved by rewriting assert @@ -335,13 +335,13 @@ If this is the case you have two options: * Disable rewriting for all modules by using ``--assert=plain``. -.. versionadded:: 2.1 + Add assert rewriting as an alternate introspection technique. -.. versionchanged:: 2.1 + Introduce the ``--assert`` option. Deprecate ``--no-assert`` and ``--nomagic``. -.. versionchanged:: 3.0 + Removes the ``--no-assert`` and ``--nomagic`` options. Removes the ``--assert=reinterp`` option. diff --git a/doc/en/cache.rst b/doc/en/cache.rst index 4286fc40f..f885eda15 100644 --- a/doc/en/cache.rst +++ b/doc/en/cache.rst @@ -5,7 +5,7 @@ Cache: working with cross-testrun state ======================================= -.. versionadded:: 2.8 + Usage --------- diff --git a/doc/en/capture.rst b/doc/en/capture.rst index 8629350a5..90403d23a 100644 --- a/doc/en/capture.rst +++ b/doc/en/capture.rst @@ -121,11 +121,11 @@ same interface but allows to also capture output from libraries or subprocesses that directly write to operating system level output streams (FD1 and FD2). -.. versionadded:: 3.3 + The return value from ``readouterr`` changed to a ``namedtuple`` with two attributes, ``out`` and ``err``. -.. versionadded:: 3.3 + If the code under test writes non-textual data, you can capture this using the ``capsysbinary`` fixture which instead returns ``bytes`` from @@ -133,7 +133,7 @@ the ``readouterr`` method. The ``capfsysbinary`` fixture is currently only available in python 3. -.. versionadded:: 3.3 + If the code under test writes non-textual data, you can capture this using the ``capfdbinary`` fixture which instead returns ``bytes`` from @@ -141,7 +141,7 @@ the ``readouterr`` method. The ``capfdbinary`` fixture operates on the filedescriptor level. -.. versionadded:: 3.0 + To temporarily disable capture within a test, both ``capsys`` and ``capfd`` have a ``disabled()`` method that can be used diff --git a/doc/en/customize.rst b/doc/en/customize.rst index 2329ec2d1..cdd444973 100644 --- a/doc/en/customize.rst +++ b/doc/en/customize.rst @@ -20,7 +20,7 @@ which were registered by installed plugins. Initialization: determining rootdir and inifile ----------------------------------------------- -.. versionadded:: 2.7 + pytest determines a ``rootdir`` for each test run which depends on the command line arguments (specified test files, paths) and on diff --git a/doc/en/deprecations.rst b/doc/en/deprecations.rst index d18b458d8..05bfc7c49 100644 --- a/doc/en/deprecations.rst +++ b/doc/en/deprecations.rst @@ -104,7 +104,7 @@ Becomes: Result log (``--result-log``) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. deprecated:: 3.0 + The ``--resultlog`` command line option has been deprecated: it is little used and there are more modern and better alternatives, for example `pytest-tap `_. diff --git a/doc/en/example/markers.rst b/doc/en/example/markers.rst index 6275bbae0..991adb50c 100644 --- a/doc/en/example/markers.rst +++ b/doc/en/example/markers.rst @@ -35,7 +35,7 @@ You can "mark" a test function with custom metadata like this: def test_method(self): pass -.. versionadded:: 2.2 + You can then restrict a test run to only run tests marked with ``webtest``: @@ -210,7 +210,7 @@ Or to select "http" and "quick" tests: Registering markers ------------------------------------- -.. versionadded:: 2.2 + .. ini-syntax for custom markers: diff --git a/doc/en/example/simple.rst b/doc/en/example/simple.rst index e9fe1f249..a317daa50 100644 --- a/doc/en/example/simple.rst +++ b/doc/en/example/simple.rst @@ -854,7 +854,7 @@ information. ``PYTEST_CURRENT_TEST`` environment variable -------------------------------------------- -.. versionadded:: 3.2 + Sometimes a test session might get stuck and there might be no easy way to figure out which test got stuck, for example if pytest was run in quiet mode (``-q``) or you don't have access to the console diff --git a/doc/en/fixture.rst b/doc/en/fixture.rst index 6cbec6ddc..23b32e9a7 100644 --- a/doc/en/fixture.rst +++ b/doc/en/fixture.rst @@ -7,7 +7,7 @@ pytest fixtures: explicit, modular, scalable .. currentmodule:: _pytest.python -.. versionadded:: 2.0/2.3/2.4 + .. _`xUnit`: http://en.wikipedia.org/wiki/XUnit .. _`purpose of test fixtures`: http://en.wikipedia.org/wiki/Test_fixture#Software @@ -276,7 +276,7 @@ Finally, the ``class`` scope will invoke the fixture once per test *class*. ``package`` scope (experimental) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. versionadded:: 3.7 + In pytest 3.7 the ``package`` scope has been introduced. Package-scoped fixtures are finalized when the last test of a *package* finishes. @@ -292,7 +292,7 @@ are finalized when the last test of a *package* finishes. Higher-scoped fixtures are instantiated first --------------------------------------------- -.. versionadded:: 3.5 + Within a function request for features, fixture of higher-scopes (such as ``session``) are instantiated first than lower-scoped fixtures (such as ``function`` or ``class``). The relative order of fixtures of same scope follows diff --git a/doc/en/historical-notes.rst b/doc/en/historical-notes.rst index 4dfec7f5e..145dc4529 100644 --- a/doc/en/historical-notes.rst +++ b/doc/en/historical-notes.rst @@ -7,7 +7,7 @@ kept here as a historical note so users looking at old code can find documentati cache plugin integrated into the core ------------------------------------- -.. versionadded:: 2.8 + The functionality of the :ref:`core cache ` plugin was previously distributed as a third party plugin named ``pytest-cache``. The core plugin @@ -18,7 +18,7 @@ can only store/receive data between test runs that is json-serializable. funcargs and ``pytest_funcarg__`` --------------------------------- -.. versionchanged:: 2.3 + In versions prior to 2.3 there was no ``@pytest.fixture`` marker and you had to use a magic ``pytest_funcarg__NAME`` prefix @@ -30,7 +30,7 @@ functions. ``@pytest.yield_fixture`` decorator ----------------------------------- -.. versionchanged:: 2.10 + Prior to version 2.10, in order to use a ``yield`` statement to execute teardown code one had to mark a fixture using the ``yield_fixture`` marker. From 2.10 onward, normal @@ -41,7 +41,7 @@ and considered deprecated. ``[pytest]`` header in ``setup.cfg`` ------------------------------------ -.. versionchanged:: 3.0 + Prior to 3.0, the supported section name was ``[pytest]``. Due to how this may collide with some distutils commands, the recommended @@ -54,7 +54,7 @@ name is ``[pytest]``. Applying marks to ``@pytest.mark.parametrize`` parameters --------------------------------------------------------- -.. versionchanged:: 3.1 + Prior to version 3.1 the supported mechanism for marking values used the syntax: @@ -80,7 +80,7 @@ The old syntax is planned to be removed in pytest-4.0. ``@pytest.mark.parametrize`` argument names as a tuple ------------------------------------------------------ -.. versionchanged:: 2.4 + In versions prior to 2.4 one needed to specify the argument names as a tuple. This remains valid but the simpler ``"name1,name2,..."`` @@ -91,7 +91,7 @@ it's easier to write and produces less line noise. setup: is now an "autouse fixture" ---------------------------------- -.. versionchanged:: 2.3 + During development prior to the pytest-2.3 release the name ``pytest.setup`` was used but before the release it was renamed @@ -104,7 +104,7 @@ namely :ref:`autouse fixtures` Conditions as strings instead of booleans ----------------------------------------- -.. versionchanged:: 2.4 + Prior to pytest-2.4 the only way to specify skipif/xfail conditions was to use strings: @@ -171,7 +171,7 @@ The equivalent with "boolean conditions" is: ``pytest.set_trace()`` ---------------------- -.. versionchanged:: 2.4 + Previous to version 2.4 to set a break point in code one needed to use ``pytest.set_trace()``: @@ -192,7 +192,7 @@ For more details see :ref:`breakpoints`. "compat" properties ------------------- -.. deprecated:: 3.9 + Access of ``Module``, ``Function``, ``Class``, ``Instance``, ``File`` and ``Item`` through ``Node`` instances have long been documented as deprecated, but started to emit warnings from pytest ``3.9`` and onward. diff --git a/doc/en/logging.rst b/doc/en/logging.rst index ff80884e9..a53509184 100644 --- a/doc/en/logging.rst +++ b/doc/en/logging.rst @@ -3,8 +3,8 @@ Logging ------- -.. versionadded:: 3.3 -.. versionchanged:: 3.4 + + pytest captures log messages of level ``WARNING`` or above automatically and displays them in their own section for each failed test in the same manner as captured stdout and stderr. diff --git a/doc/en/mark.rst b/doc/en/mark.rst index e841a6780..fdb72d948 100644 --- a/doc/en/mark.rst +++ b/doc/en/mark.rst @@ -59,7 +59,7 @@ should add ``--strict`` to ``addopts``: Marker revamp and iteration --------------------------- -.. versionadded:: 3.6 + pytest's marker implementation traditionally worked by simply updating the ``__dict__`` attribute of functions to cumulatively add markers. As a result, markers would unintentionally be passed along class hierarchies in surprising ways. Further, the API for retrieving them was inconsistent, as markers from parameterization would be stored differently than markers applied using the ``@pytest.mark`` decorator and markers added via ``node.add_marker``. diff --git a/doc/en/parametrize.rst b/doc/en/parametrize.rst index 3a2104317..0abe7d701 100644 --- a/doc/en/parametrize.rst +++ b/doc/en/parametrize.rst @@ -29,8 +29,8 @@ pytest enables test parametrization at several levels: .. regendoc: wipe -.. versionadded:: 2.2 -.. versionchanged:: 2.4 + + Several improvements. The builtin :ref:`pytest.mark.parametrize ref` decorator enables diff --git a/doc/en/reference.rst b/doc/en/reference.rst index 12e0d09a8..f39f2a6e0 100644 --- a/doc/en/reference.rst +++ b/doc/en/reference.rst @@ -983,7 +983,7 @@ passed multiple times. The expected format is ``name=value``. For example:: .. confval:: cache_dir - .. versionadded:: 3.2 + Sets a directory where stores content of cache plugin. Default directory is ``.pytest_cache`` which is created in :ref:`rootdir `. Directory may be @@ -1003,7 +1003,7 @@ passed multiple times. The expected format is ``name=value``. For example:: .. confval:: console_output_style - .. versionadded:: 3.3 + Sets the console output style while running tests: @@ -1023,7 +1023,7 @@ passed multiple times. The expected format is ``name=value``. For example:: .. confval:: doctest_encoding - .. versionadded:: 3.1 + Default encoding to use to decode text files with docstrings. :doc:`See how pytest handles doctests `. @@ -1037,7 +1037,7 @@ passed multiple times. The expected format is ``name=value``. For example:: .. confval:: empty_parameter_set_mark - .. versionadded:: 3.4 + Allows to pick the action for empty parametersets in parameterization @@ -1060,7 +1060,7 @@ passed multiple times. The expected format is ``name=value``. For example:: .. confval:: filterwarnings - .. versionadded:: 3.1 + Sets a list of filters and actions that should be taken for matched warnings. By default all warnings emitted during the test session @@ -1094,7 +1094,7 @@ passed multiple times. The expected format is ``name=value``. For example:: .. confval:: junit_suite_name - .. versionadded:: 3.1 + To set the name of the root test suite xml item, you can configure the ``junit_suite_name`` option in your config file: @@ -1106,7 +1106,7 @@ passed multiple times. The expected format is ``name=value``. For example:: .. confval:: log_cli_date_format - .. versionadded:: 3.3 + Sets a :py:func:`time.strftime`-compatible string that will be used when formatting dates for live logging. @@ -1119,7 +1119,7 @@ passed multiple times. The expected format is ``name=value``. For example:: .. confval:: log_cli_format - .. versionadded:: 3.3 + Sets a :py:mod:`logging`-compatible string used to format live logging messages. @@ -1133,7 +1133,7 @@ passed multiple times. The expected format is ``name=value``. For example:: .. confval:: log_cli_level - .. versionadded:: 3.3 + Sets the minimum log message level that should be captured for live logging. The integer value or the names of the levels can be used. @@ -1148,7 +1148,7 @@ passed multiple times. The expected format is ``name=value``. For example:: .. confval:: log_date_format - .. versionadded:: 3.3 + Sets a :py:func:`time.strftime`-compatible string that will be used when formatting dates for logging capture. @@ -1162,7 +1162,7 @@ passed multiple times. The expected format is ``name=value``. For example:: .. confval:: log_file - .. versionadded:: 3.3 + Sets a file name relative to the ``pytest.ini`` file where log messages should be written to, in addition to the other logging facilities that are active. @@ -1177,7 +1177,7 @@ passed multiple times. The expected format is ``name=value``. For example:: .. confval:: log_file_date_format - .. versionadded:: 3.3 + Sets a :py:func:`time.strftime`-compatible string that will be used when formatting dates for the logging file. @@ -1190,7 +1190,7 @@ passed multiple times. The expected format is ``name=value``. For example:: .. confval:: log_file_format - .. versionadded:: 3.3 + Sets a :py:mod:`logging`-compatible string used to format logging messages redirected to the logging file. @@ -1203,7 +1203,7 @@ passed multiple times. The expected format is ``name=value``. For example:: .. confval:: log_file_level - .. versionadded:: 3.3 + Sets the minimum log message level that should be captured for the logging file. The integer value or the names of the levels can be used. @@ -1218,7 +1218,7 @@ passed multiple times. The expected format is ``name=value``. For example:: .. confval:: log_format - .. versionadded:: 3.3 + Sets a :py:mod:`logging`-compatible string used to format captured logging messages. @@ -1232,7 +1232,7 @@ passed multiple times. The expected format is ``name=value``. For example:: .. confval:: log_level - .. versionadded:: 3.3 + Sets the minimum log message level that should be captured for logging capture. The integer value or the names of the levels can be used. @@ -1247,7 +1247,7 @@ passed multiple times. The expected format is ``name=value``. For example:: .. confval:: log_print - .. versionadded:: 3.3 + If set to ``False``, will disable displaying captured logging messages for failed tests. @@ -1384,7 +1384,7 @@ passed multiple times. The expected format is ``name=value``. For example:: .. confval:: testpaths - .. versionadded:: 2.8 + Sets list of directories that should be searched for tests when no specific directories, files or test ids are given in the command line when diff --git a/doc/en/skipping.rst b/doc/en/skipping.rst index b1145cc26..d8d4dd1c1 100644 --- a/doc/en/skipping.rst +++ b/doc/en/skipping.rst @@ -39,7 +39,7 @@ More details on the ``-r`` option can be found by running ``pytest -h``. Skipping test functions ----------------------- -.. versionadded:: 2.9 + The simplest way to skip a test function is to mark it with the ``skip`` decorator which may be passed an optional ``reason``: @@ -80,7 +80,7 @@ It is also possible to skip the whole module using ``skipif`` ~~~~~~~~~~ -.. versionadded:: 2.0 + If you wish to skip something conditionally then you can use ``skipif`` instead. Here is an example of marking a test function to be skipped @@ -254,7 +254,7 @@ internally by raising a known exception. ``strict`` parameter ~~~~~~~~~~~~~~~~~~~~ -.. versionadded:: 2.9 + Both ``XFAIL`` and ``XPASS`` don't fail the test suite, unless the ``strict`` keyword-only parameter is passed as ``True``: diff --git a/doc/en/tmpdir.rst b/doc/en/tmpdir.rst index 8583f33b4..330011bb3 100644 --- a/doc/en/tmpdir.rst +++ b/doc/en/tmpdir.rst @@ -8,7 +8,7 @@ Temporary directories and files The ``tmp_path`` fixture ------------------------ -.. versionadded:: 3.9 + You can use the ``tmp_path`` fixture which will @@ -71,7 +71,7 @@ Running this would result in a passed test except for the last The ``tmp_path_factory`` fixture -------------------------------- -.. versionadded:: 3.9 + The ``tmp_path_factory`` is a session-scoped fixture which can be used @@ -136,7 +136,7 @@ Running this would result in a passed test except for the last The 'tmpdir_factory' fixture ---------------------------- -.. versionadded:: 2.8 + The ``tmpdir_factory`` is a session-scoped fixture which can be used to create arbitrary temporary directories from any other fixture or test. diff --git a/doc/en/usage.rst b/doc/en/usage.rst index d69aa6c07..ffd37aab3 100644 --- a/doc/en/usage.rst +++ b/doc/en/usage.rst @@ -10,7 +10,7 @@ Usage and Invocations Calling pytest through ``python -m pytest`` ----------------------------------------------------- -.. versionadded:: 2.0 + You can invoke testing through the Python interpreter from the command line: @@ -155,7 +155,7 @@ option you make sure a trace is shown. Detailed summary report ----------------------- -.. versionadded:: 2.9 + The ``-r`` flag can be used to display a "short test summary info" at the end of the test session, making it easy in large test suites to get a clear picture of all failures, skips, xfails, etc. @@ -428,7 +428,7 @@ integration servers, use this invocation: to create an XML file at ``path``. -.. versionadded:: 3.1 + To set the name of the root test suite xml item, you can configure the ``junit_suite_name`` option in your config file: @@ -456,8 +456,8 @@ instead, configure the ``junit_duration_report`` option like this: record_property ^^^^^^^^^^^^^^^ -.. versionadded:: 2.8 -.. versionchanged:: 3.5 + + Fixture renamed from ``record_xml_property`` to ``record_property`` as user properties are now available to all reporters. @@ -528,7 +528,7 @@ Will result in: record_xml_attribute ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. versionadded:: 3.4 + To add an additional xml attribute to a testcase element, you can use ``record_xml_attribute`` fixture. This can also be used to override existing values: @@ -588,7 +588,7 @@ Instead, this will add an attribute ``assertions="REQ-1234"`` inside the generat LogXML: add_global_property ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. versionadded:: 3.0 + If you want to add a properties node in the testsuite level, which may contains properties that are relevant to all testcases you can use ``LogXML.add_global_properties`` @@ -638,7 +638,7 @@ This will add a property node below the testsuite node to the generated xml: Creating resultlog format files ---------------------------------------------------- -.. deprecated:: 3.0 + This option is rarely used and is scheduled for removal in 5.0. @@ -712,7 +712,7 @@ executing doctest tests from text files, invoke pytest like this: Calling pytest from Python code ---------------------------------------------------- -.. versionadded:: 2.0 + You can invoke ``pytest`` from Python code directly:: diff --git a/doc/en/warnings.rst b/doc/en/warnings.rst index 26bd2fdb2..c0acc2cf8 100644 --- a/doc/en/warnings.rst +++ b/doc/en/warnings.rst @@ -3,7 +3,7 @@ Warnings Capture ================ -.. versionadded:: 3.1 + Starting from version ``3.1``, pytest now automatically catches warnings during test execution and displays them at the end of the session: @@ -90,7 +90,7 @@ documentation for other examples and advanced usage. ``@pytest.mark.filterwarnings`` ------------------------------- -.. versionadded:: 3.2 + You can use the ``@pytest.mark.filterwarnings`` to add warning filters to specific test items, allowing you to have finer control of which warnings should be captured at test, class or @@ -156,8 +156,8 @@ using an external system. DeprecationWarning and PendingDeprecationWarning ------------------------------------------------ -.. versionadded:: 3.8 -.. versionchanged:: 3.9 + + By default pytest will display ``DeprecationWarning`` and ``PendingDeprecationWarning`` warnings from user code and third-party libraries, as recommended by `PEP-0565 `_. @@ -247,7 +247,7 @@ You can also use it as a contextmanager: Asserting warnings with the warns function ------------------------------------------ -.. versionadded:: 2.8 + You can check that code raises a particular warning using ``pytest.warns``, which works in a similar manner to :ref:`raises `: @@ -377,7 +377,7 @@ custom error message. Internal pytest warnings ------------------------ -.. versionadded:: 3.8 + pytest may generate its own warnings in some situations, such as improper usage or deprecated features. diff --git a/doc/en/writing_plugins.rst b/doc/en/writing_plugins.rst index 16543b7b8..7cb610247 100644 --- a/doc/en/writing_plugins.rst +++ b/doc/en/writing_plugins.rst @@ -496,7 +496,7 @@ hookwrapper: executing around other hooks .. currentmodule:: _pytest.core -.. versionadded:: 2.7 + pytest plugins can implement hook wrappers which wrap the execution of other hook implementations. A hook wrapper is a generator function diff --git a/doc/en/yieldfixture.rst b/doc/en/yieldfixture.rst index 6fd1edac2..47590f9db 100644 --- a/doc/en/yieldfixture.rst +++ b/doc/en/yieldfixture.rst @@ -5,9 +5,9 @@ "yield_fixture" functions --------------------------------------------------------------- -.. deprecated:: 3.0 -.. versionadded:: 2.4 + + .. important:: Since pytest-3.0, fixtures using the normal ``fixture`` decorator can use a ``yield`` From e943aff9956fd55a9459f332fb671006adc2f354 Mon Sep 17 00:00:00 2001 From: Bruno Oliveira Date: Sun, 28 Apr 2019 20:01:22 -0300 Subject: [PATCH 07/15] Update blurb about Sybil --- doc/en/doctest.rst | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/doc/en/doctest.rst b/doc/en/doctest.rst index 5ab548239..2cb70af72 100644 --- a/doc/en/doctest.rst +++ b/doc/en/doctest.rst @@ -79,9 +79,11 @@ putting them into a pytest.ini file like this: .. note:: - If you are making serious use of doctests through your code, please checkout - `Sybil `__, which besides - supporting doctests also supports Sphinx directives, plus other features. + The builtin pytest doctest supports only ``doctest`` blocks, but if you are looking + for more advanced checking over *all* your documentation, + including doctests, ``.. codeblock:: python`` Sphinx directive support, + and any other examples your documentation may include, you may wish to + consider `Sybil `__. It provides pytest integration out of the box. From bc6450773a9e80904fc5e144b16abee47a6f197f Mon Sep 17 00:00:00 2001 From: Matt Cooper Date: Thu, 25 Apr 2019 08:13:31 -0400 Subject: [PATCH 08/15] remove PyPy special casing --- azure-pipelines.yml | 29 ++++------------------------- 1 file changed, 4 insertions(+), 25 deletions(-) diff --git a/azure-pipelines.yml b/azure-pipelines.yml index 2d225bafc..448ffba5e 100644 --- a/azure-pipelines.yml +++ b/azure-pipelines.yml @@ -5,7 +5,6 @@ trigger: variables: PYTEST_ADDOPTS: "--junitxml=build/test-results/$(tox.env).xml -vv" python.needs_vc: False - python.exe: "python" COVERAGE_FILE: "$(Build.Repository.LocalPath)/.coverage" COVERAGE_PROCESS_START: "$(Build.Repository.LocalPath)/.coveragerc" PYTEST_COVERAGE: '0' @@ -43,14 +42,12 @@ jobs: # But no exception with py27-pexpect,py27-twisted,py27-numpy. PYTEST_COVERAGE: '1' pypy: - python.version: 'pypy' + python.version: 'pypy2' tox.env: 'pypy' - python.exe: 'pypy' # NOTE: pypy3 fails to install pip currently due to an interal error. # pypy3: # python.version: 'pypy3' # tox.env: 'pypy3' - # python.exe: 'pypy3' py34-xdist: python.version: '3.4' tox.env: 'py34-xdist' @@ -86,7 +83,6 @@ jobs: steps: - task: UsePythonVersion@0 - condition: not(startsWith(variables['python.exe'], 'pypy')) inputs: versionSpec: '$(python.version)' architecture: 'x64' @@ -95,29 +91,12 @@ jobs: condition: eq(variables['python.needs_vc'], True) displayName: 'Install VC for py27' - - script: choco install python.pypy - condition: eq(variables['python.exe'], 'pypy') - displayName: 'Install pypy' - - - script: choco install pypy3 - condition: eq(variables['python.exe'], 'pypy3') - displayName: 'Install pypy3' - - - task: PowerShell@2 - inputs: - targetType: 'inline' - script: | - Invoke-WebRequest -Uri "https://bootstrap.pypa.io/get-pip.py" -OutFile "get-pip.py" - $(python.exe) get-pip.py - condition: startsWith(variables['python.exe'], 'pypy') - displayName: 'Install pip' - - - script: $(python.exe) -m pip install --upgrade pip && $(python.exe) -m pip install tox + - script: python -m pip install --upgrade pip && python -m pip install tox displayName: 'Install tox' - script: | call scripts/setup-coverage-vars.bat || goto :eof - $(python.exe) -m tox -e $(tox.env) + python -m tox -e $(tox.env) displayName: 'Run tests' - task: PublishTestResults@2 @@ -130,6 +109,6 @@ jobs: displayName: 'Report and upload coverage' condition: eq(variables['PYTEST_COVERAGE'], '1') env: - PYTHON: $(python.exe) + PYTHON: python CODECOV_TOKEN: $(CODECOV_TOKEN) PYTEST_CODECOV_NAME: $(tox.env) From f050203f5d1681fe0bc5052aa6cc3fed5affb3af Mon Sep 17 00:00:00 2001 From: Allan Lewis Date: Tue, 30 Apr 2019 17:29:28 +0100 Subject: [PATCH 09/15] Improve help for --runxfail flag The help for the '--runxfail' flag is somewhat misleading. The default behaviour is to run tests marked as 'xfail' but to ignore the results. This flag alters that behaviour by running these tests as if they weren't marked 'xfail', i.e. their results are not ignored. --- changelog/5188.doc.rst | 1 + src/_pytest/skipping.py | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) create mode 100644 changelog/5188.doc.rst diff --git a/changelog/5188.doc.rst b/changelog/5188.doc.rst new file mode 100644 index 000000000..726745638 --- /dev/null +++ b/changelog/5188.doc.rst @@ -0,0 +1 @@ +Improve help for ``--runxfail`` flag. diff --git a/src/_pytest/skipping.py b/src/_pytest/skipping.py index 22acafbdd..5525e1137 100644 --- a/src/_pytest/skipping.py +++ b/src/_pytest/skipping.py @@ -17,7 +17,7 @@ def pytest_addoption(parser): action="store_true", dest="runxfail", default=False, - help="run tests even if they are marked xfail", + help="report the results of xfail tests as if they were not marked", ) parser.addini( From af40473c9a5547d6d26a9670556cb53d1ad952a4 Mon Sep 17 00:00:00 2001 From: Bruno Oliveira Date: Wed, 1 May 2019 11:46:35 -0300 Subject: [PATCH 10/15] Add quick note about accessing config through session or item objects Fix #5030 --- doc/en/deprecations.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/doc/en/deprecations.rst b/doc/en/deprecations.rst index 05bfc7c49..27af2a49a 100644 --- a/doc/en/deprecations.rst +++ b/doc/en/deprecations.rst @@ -60,7 +60,8 @@ If you still have concerns about this deprecation and future removal, please com The ``pytest.config`` global object is deprecated. Instead use ``request.config`` (via the ``request`` fixture) or if you are a plugin author -use the ``pytest_configure(config)`` hook. +use the ``pytest_configure(config)`` hook. Note that many hooks can also access +the ``config`` object indirectly, through ``session.config`` or ``item.config`` for example. .. _raises-warns-exec: From 1bd7d287a78639a03d2e1ffb1b70cef407cfa5d7 Mon Sep 17 00:00:00 2001 From: DamianSkrzypczak Date: Thu, 2 May 2019 20:48:03 +0200 Subject: [PATCH 11/15] doc: fix hooks 'path' parameter doc type by changing it from str to py.path.local (#5171) --- src/_pytest/hookspec.py | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/src/_pytest/hookspec.py b/src/_pytest/hookspec.py index 5a3eb282d..02b1b4524 100644 --- a/src/_pytest/hookspec.py +++ b/src/_pytest/hookspec.py @@ -188,7 +188,7 @@ def pytest_ignore_collect(path, config): Stops at first non-None result, see :ref:`firstresult` - :param str path: the path to analyze + :param path: a :py:class:`py.path.local` - the path to analyze :param _pytest.config.Config config: pytest config object """ @@ -199,7 +199,7 @@ def pytest_collect_directory(path, parent): Stops at first non-None result, see :ref:`firstresult` - :param str path: the path to analyze + :param path: a :py:class:`py.path.local` - the path to analyze """ @@ -207,7 +207,7 @@ def pytest_collect_file(path, parent): """ return collection Node or None for the given path. Any new node needs to have the specified ``parent`` as a parent. - :param str path: the path to collect + :param path: a :py:class:`py.path.local` - the path to collect """ @@ -249,7 +249,10 @@ def pytest_pycollect_makemodule(path, parent): The pytest_collect_file hook needs to be used if you want to create test modules for files that do not match as a test module. - Stops at first non-None result, see :ref:`firstresult` """ + Stops at first non-None result, see :ref:`firstresult` + + :param path: a :py:class:`py.path.local` - the path of module to collect + """ @hookspec(firstresult=True) From 6e81c3df92977929c2d0cd15a462e1fa1b735838 Mon Sep 17 00:00:00 2001 From: DamianSkrzypczak Date: Thu, 2 May 2019 21:30:03 +0200 Subject: [PATCH 12/15] add changelog for issue #5171 fixes --- changelog/5171.doc.rst | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelog/5171.doc.rst diff --git a/changelog/5171.doc.rst b/changelog/5171.doc.rst new file mode 100644 index 000000000..7cdbad0f5 --- /dev/null +++ b/changelog/5171.doc.rst @@ -0,0 +1 @@ +Doc: ``pytest_ignore_collect``, ``pytest_collect_directory``, ``pytest_collect_file`` and ``pytest_pycollect_makemodule`` hooks's 'path' parameter documented type is now ``py.path.local`` From 299e6479c161e89aeccedd510b191c908165223a Mon Sep 17 00:00:00 2001 From: DamianSkrzypczak Date: Thu, 2 May 2019 23:45:34 +0200 Subject: [PATCH 13/15] add DamianSkrzypczak to AUTHORS --- AUTHORS | 1 + 1 file changed, 1 insertion(+) diff --git a/AUTHORS b/AUTHORS index b9879804a..577c4dcd1 100644 --- a/AUTHORS +++ b/AUTHORS @@ -59,6 +59,7 @@ Christopher Gilling Christopher Dignam CrazyMerlyn Cyrus Maden +Damian Skrzypczak Dhiren Serai Daniel Grana Daniel Hahler From 254b195f504a805a13a54deea41aaa5dec04d045 Mon Sep 17 00:00:00 2001 From: Don Kirkby Date: Fri, 3 May 2019 22:30:20 -0700 Subject: [PATCH 14/15] Fix a typo --- doc/en/customize.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/en/customize.rst b/doc/en/customize.rst index cdd444973..77217e9d2 100644 --- a/doc/en/customize.rst +++ b/doc/en/customize.rst @@ -90,7 +90,7 @@ The ``config`` object will subsequently carry these attributes: - ``config.inifile``: the determined ini-file, may be ``None``. -The rootdir is used a reference directory for constructing test +The rootdir is used as a reference directory for constructing test addresses ("nodeids") and can be used also by plugins for storing per-testrun information. From 2bd97ebaf7d8efc0ee2a14b8f483d1abef4b13a4 Mon Sep 17 00:00:00 2001 From: Bruno Oliveira Date: Sat, 4 May 2019 10:24:46 -0300 Subject: [PATCH 15/15] Use 'pypy' as executable on PyPy env [skip travis] --- azure-pipelines.yml | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/azure-pipelines.yml b/azure-pipelines.yml index 448ffba5e..42be786b5 100644 --- a/azure-pipelines.yml +++ b/azure-pipelines.yml @@ -5,6 +5,7 @@ trigger: variables: PYTEST_ADDOPTS: "--junitxml=build/test-results/$(tox.env).xml -vv" python.needs_vc: False + python.exe: "python" COVERAGE_FILE: "$(Build.Repository.LocalPath)/.coverage" COVERAGE_PROCESS_START: "$(Build.Repository.LocalPath)/.coveragerc" PYTEST_COVERAGE: '0' @@ -44,10 +45,12 @@ jobs: pypy: python.version: 'pypy2' tox.env: 'pypy' - # NOTE: pypy3 fails to install pip currently due to an interal error. + python.exe: 'pypy' + # NOTE: pypy3 fails to install pip currently due to an internal error. # pypy3: # python.version: 'pypy3' # tox.env: 'pypy3' + # python.exe: 'pypy3' py34-xdist: python.version: '3.4' tox.env: 'py34-xdist' @@ -91,12 +94,12 @@ jobs: condition: eq(variables['python.needs_vc'], True) displayName: 'Install VC for py27' - - script: python -m pip install --upgrade pip && python -m pip install tox + - script: $(python.exe) -m pip install --upgrade pip && $(python.exe) -m pip install tox displayName: 'Install tox' - script: | call scripts/setup-coverage-vars.bat || goto :eof - python -m tox -e $(tox.env) + $(python.exe) -m tox -e $(tox.env) displayName: 'Run tests' - task: PublishTestResults@2 @@ -109,6 +112,6 @@ jobs: displayName: 'Report and upload coverage' condition: eq(variables['PYTEST_COVERAGE'], '1') env: - PYTHON: python + PYTHON: $(python.exe) CODECOV_TOKEN: $(CODECOV_TOKEN) PYTEST_CODECOV_NAME: $(tox.env)