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 fdee41c13..ff422c585 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``