From 6fe7069cbb4c23b6800afff692e0162e000d55e9 Mon Sep 17 00:00:00 2001 From: Bruno Oliveira Date: Thu, 27 Jul 2017 20:02:18 -0300 Subject: [PATCH] Move historical notes to their own doc Fix #2512 --- doc/en/cache.rst | 8 -- doc/en/contents.rst | 1 + doc/en/example/markers.rst | 14 +-- doc/en/fixture.rst | 16 +--- doc/en/goodpractices.rst | 9 -- doc/en/historical-notes.rst | 177 ++++++++++++++++++++++++++++++++++++ doc/en/parametrize.rst | 31 +------ doc/en/setup.rst | 10 -- doc/en/skipping.rst | 61 ------------- doc/en/unittest.rst | 16 ++-- doc/en/usage.rst | 25 ++--- doc/en/writing_plugins.rst | 2 +- 12 files changed, 203 insertions(+), 167 deletions(-) create mode 100644 doc/en/historical-notes.rst delete mode 100644 doc/en/setup.rst diff --git a/doc/en/cache.rst b/doc/en/cache.rst index f3da3e6d6..c16537e40 100644 --- a/doc/en/cache.rst +++ b/doc/en/cache.rst @@ -5,14 +5,6 @@ Cache: working with cross-testrun state .. versionadded:: 2.8 -.. warning:: - - The functionality of this core plugin was previously distributed - as a third party plugin named ``pytest-cache``. The core plugin - is compatible regarding command line options and API usage except that you - can only store/receive data between test runs that is json-serializable. - - Usage --------- diff --git a/doc/en/contents.rst b/doc/en/contents.rst index 4f5bf789f..028414eb6 100644 --- a/doc/en/contents.rst +++ b/doc/en/contents.rst @@ -38,6 +38,7 @@ Full pytest documentation bash-completion backwards-compatibility + historical-notes license contributing talks diff --git a/doc/en/example/markers.rst b/doc/en/example/markers.rst index 40338fba8..d630d80c4 100644 --- a/doc/en/example/markers.rst +++ b/doc/en/example/markers.rst @@ -173,14 +173,14 @@ Or to select "http" and "quick" tests:: .. note:: - If you are using expressions such as "X and Y" then both X and Y - need to be simple non-keyword names. For example, "pass" or "from" - will result in SyntaxErrors because "-k" evaluates the expression. + If you are using expressions such as ``"X and Y"`` then both ``X`` and ``Y`` + need to be simple non-keyword names. For example, ``"pass"`` or ``"from"`` + will result in SyntaxErrors because ``"-k"`` evaluates the expression using Python's ``eval`` function. - However, if the "-k" argument is a simple string, no such restrictions - apply. Also "-k 'not STRING'" has no restrictions. You can also - specify numbers like "-k 1.3" to match tests which are parametrized - with the float "1.3". + However, if the ``"-k"`` argument is a simple string, no such restrictions + apply. Also ``"-k 'not STRING'"`` has no restrictions. You can also + specify numbers like ``"-k 1.3"`` to match tests which are parametrized + with the float ``"1.3"``. Registering markers ------------------------------------- diff --git a/doc/en/fixture.rst b/doc/en/fixture.rst index a53f78c3f..db7ef0ca2 100644 --- a/doc/en/fixture.rst +++ b/doc/en/fixture.rst @@ -109,7 +109,7 @@ Note that if you misspell a function argument or want to use one that isn't available, you'll see an error with a list of available function arguments. -.. Note:: +.. note:: You can always issue:: @@ -117,12 +117,6 @@ with a list of available function arguments. to see available fixtures. - In versions prior to 2.3 there was no ``@pytest.fixture`` marker - and you had to use a magic ``pytest_funcarg__NAME`` prefix - for the fixture factory. This remains and will remain supported - but is not anymore advertised as the primary means of declaring fixture - functions. - Fixtures: a prime example of dependency injection --------------------------------------------------- @@ -292,14 +286,6 @@ the ``with`` statement ends. Note that if an exception happens during the *setup* code (before the ``yield`` keyword), the *teardown* code (after the ``yield``) will not be called. - -.. note:: - 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 - fixtures can use ``yield`` directly so the ``yield_fixture`` decorator is no longer needed - and considered deprecated. - - An alternative option for executing *teardown* code is to make use of the ``addfinalizer`` method of the `request-context`_ object to register finalization functions. diff --git a/doc/en/goodpractices.rst b/doc/en/goodpractices.rst index 92cd9ed81..03bbf7bb1 100644 --- a/doc/en/goodpractices.rst +++ b/doc/en/goodpractices.rst @@ -249,15 +249,6 @@ by putting them into a ``[tool:pytest]`` section: python_files = testing/*/*.py -.. note:: - Prior to 3.0, the supported section name was ``[pytest]``. Due to how - this may collide with some distutils commands, the recommended - section name for ``setup.cfg`` files is now ``[tool:pytest]``. - - Note that for ``pytest.ini`` and ``tox.ini`` files the section - name is ``[pytest]``. - - Manual Integration ^^^^^^^^^^^^^^^^^^ diff --git a/doc/en/historical-notes.rst b/doc/en/historical-notes.rst new file mode 100644 index 000000000..028ceff9b --- /dev/null +++ b/doc/en/historical-notes.rst @@ -0,0 +1,177 @@ +Historical Notes +================ + +This page lists features or behavior from previous versions of pytest which have changed over the years. They are +kept here as a historical note so users looking at old code can find documentation related to them. + +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 +is compatible regarding command line options and API usage except that you +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 +for the fixture factory. This remains and will remain supported +but is not anymore advertised as the primary means of declaring fixture +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 +fixtures can use ``yield`` directly so the ``yield_fixture`` decorator is no longer needed +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 +section name for ``setup.cfg`` files is now ``[tool:pytest]``. + +Note that for ``pytest.ini`` and ``tox.ini`` files the section +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:: + + import pytest + @pytest.mark.parametrize("test_input,expected", [ + ("3+5", 8), + ("2+4", 6), + pytest.mark.xfail(("6*9", 42),), + ]) + def test_eval(test_input, expected): + assert eval(test_input) == expected + + +This was an initial hack to support the feature but soon was demonstrated to be incomplete, +broken for passing functions or applying multiple marks with the same name but different parameters. + +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,..."`` +comma-separated-string syntax is now advertised first because +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 +and moved to become part of the general fixture mechanism, +namely :ref:`autouse fixtures` + + +.. _string conditions: + +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:: + + import sys + @pytest.mark.skipif("sys.version_info >= (3,3)") + def test_function(): + ... + +During test function setup the skipif condition is evaluated by calling +``eval('sys.version_info >= (3,0)', namespace)``. The namespace contains +all the module globals, and ``os`` and ``sys`` as a minimum. + +Since pytest-2.4 :ref:`boolean conditions ` are considered preferable +because markers can then be freely imported between test modules. +With strings you need to import not only the marker but all variables +used by the marker, which violates encapsulation. + +The reason for specifying the condition as a string was that ``pytest`` can +report a summary of skip conditions based purely on the condition string. +With conditions as booleans you are required to specify a ``reason`` string. + +Note that string conditions will remain fully supported and you are free +to use them if you have no need for cross-importing markers. + +The evaluation of a condition string in ``pytest.mark.skipif(conditionstring)`` +or ``pytest.mark.xfail(conditionstring)`` takes place in a namespace +dictionary which is constructed as follows: + +* the namespace is initialized by putting the ``sys`` and ``os`` modules + and the pytest ``config`` object into it. + +* updated with the module globals of the test function for which the + expression is applied. + +The pytest ``config`` object allows you to skip based on a test +configuration value which you might have added:: + + @pytest.mark.skipif("not config.getvalue('db')") + def test_function(...): + ... + +The equivalent with "boolean conditions" is:: + + @pytest.mark.skipif(not pytest.config.getvalue("db"), + reason="--db was not specified") + def test_function(...): + pass + +.. note:: + + You cannot use ``pytest.config.getvalue()`` in code + imported before pytest's argument parsing takes place. For example, + ``conftest.py`` files are imported before command line parsing and thus + ``config.getvalue()`` will not execute correctly. + +``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()``:: + + import pytest + def test_function(): + ... + pytest.set_trace() # invoke PDB debugger and tracing + + +This is no longer needed and one can use the native ``import pdb;pdb.set_trace()`` call directly. + +For more details see :ref:`breakpoints`. diff --git a/doc/en/parametrize.rst b/doc/en/parametrize.rst index 173c18c10..5cde906fa 100644 --- a/doc/en/parametrize.rst +++ b/doc/en/parametrize.rst @@ -99,26 +99,6 @@ for example with the builtin ``mark.xfail``:: def test_eval(test_input, expected): assert eval(test_input) == expected -.. note:: - - prior to version 3.1 the supported mechanism for marking values - used the syntax:: - - import pytest - @pytest.mark.parametrize("test_input,expected", [ - ("3+5", 8), - ("2+4", 6), - pytest.mark.xfail(("6*9", 42),), - ]) - def test_eval(test_input, expected): - assert eval(test_input) == expected - - - This was an initial hack to support the feature but soon was demonstrated to be incomplete, - broken for passing functions or applying multiple marks with the same name but different parameters. - The old syntax will be removed in pytest-4.0. - - Let's run this:: $ pytest @@ -143,15 +123,8 @@ To get all combinations of multiple parametrized arguments you can stack def test_foo(x, y): pass -This will run the test with the arguments set to x=0/y=2, x=0/y=3, x=1/y=2 and -x=1/y=3. - -.. note:: - - In versions prior to 2.4 one needed to specify the argument - names as a tuple. This remains valid but the simpler ``"name1,name2,..."`` - comma-separated-string syntax is now advertised first because - it's easier to write and produces less line noise. +This will run the test with the arguments set to ``x=0/y=2``, ``x=0/y=3``, ``x=1/y=2`` and +``x=1/y=3``. .. _`pytest_generate_tests`: diff --git a/doc/en/setup.rst b/doc/en/setup.rst deleted file mode 100644 index fe2353465..000000000 --- a/doc/en/setup.rst +++ /dev/null @@ -1,10 +0,0 @@ - -setup: is now an "autouse fixture" -======================================================== - -During development prior to the pytest-2.3 release the name -``pytest.setup`` was used but before the release it was renamed -and moved to become part of the general fixture mechanism, -namely :ref:`autouse fixtures` - - diff --git a/doc/en/skipping.rst b/doc/en/skipping.rst index 72b7b0433..f3c292a18 100644 --- a/doc/en/skipping.rst +++ b/doc/en/skipping.rst @@ -347,64 +347,3 @@ test instances when using parametrize: assert n + 1 == expected -.. _string conditions: - -Conditions as strings instead of booleans ------------------------------------------ - -Prior to pytest-2.4 the only way to specify skipif/xfail conditions was -to use strings:: - - import sys - @pytest.mark.skipif("sys.version_info >= (3,3)") - def test_function(): - ... - -During test function setup the skipif condition is evaluated by calling -``eval('sys.version_info >= (3,0)', namespace)``. The namespace contains -all the module globals, and ``os`` and ``sys`` as a minimum. - -Since pytest-2.4 `condition booleans`_ are considered preferable -because markers can then be freely imported between test modules. -With strings you need to import not only the marker but all variables -used by the marker, which violates encapsulation. - -The reason for specifying the condition as a string was that ``pytest`` can -report a summary of skip conditions based purely on the condition string. -With conditions as booleans you are required to specify a ``reason`` string. - -Note that string conditions will remain fully supported and you are free -to use them if you have no need for cross-importing markers. - -The evaluation of a condition string in ``pytest.mark.skipif(conditionstring)`` -or ``pytest.mark.xfail(conditionstring)`` takes place in a namespace -dictionary which is constructed as follows: - -* the namespace is initialized by putting the ``sys`` and ``os`` modules - and the pytest ``config`` object into it. - -* updated with the module globals of the test function for which the - expression is applied. - -The pytest ``config`` object allows you to skip based on a test -configuration value which you might have added:: - - @pytest.mark.skipif("not config.getvalue('db')") - def test_function(...): - ... - -The equivalent with "boolean conditions" is:: - - @pytest.mark.skipif(not pytest.config.getvalue("db"), - reason="--db was not specified") - def test_function(...): - pass - -.. note:: - - You cannot use ``pytest.config.getvalue()`` in code - imported before pytest's argument parsing takes place. For example, - ``conftest.py`` files are imported before command line parsing and thus - ``config.getvalue()`` will not execute correctly. - - diff --git a/doc/en/unittest.rst b/doc/en/unittest.rst index 06180f19d..e2ebe3e38 100644 --- a/doc/en/unittest.rst +++ b/doc/en/unittest.rst @@ -191,12 +191,12 @@ was executed ahead of the ``test_method``. .. note:: - While pytest supports receiving fixtures via :ref:`test function arguments ` for non-unittest test methods, ``unittest.TestCase`` methods cannot directly receive fixture - function arguments as implementing that is likely to inflict + ``unittest.TestCase`` methods cannot directly receive fixture + arguments as implementing that is likely to inflict on the ability to run general unittest.TestCase test suites. - Maybe optional support would be possible, though. If unittest finally - grows a plugin system that should help as well. In the meanwhile, the - above ``usefixtures`` and ``autouse`` examples should help to mix in - pytest fixtures into unittest suites. And of course you can also start - to selectively leave away the ``unittest.TestCase`` subclassing, use - plain asserts and get the unlimited pytest feature set. + + The above ``usefixtures`` and ``autouse`` examples should help to mix in + pytest fixtures into unittest suites. + + You can also consider incrementally leave away ``unittest.TestCase`` subclassing, + using plain asserts and get the full pytest feature set. diff --git a/doc/en/usage.rst b/doc/en/usage.rst index 775297882..ec07f1f30 100644 --- a/doc/en/usage.rst +++ b/doc/en/usage.rst @@ -123,22 +123,15 @@ for example:: >>> sys.last_value AssertionError('assert result == "ok"',) -Setting a breakpoint / aka ``set_trace()`` ----------------------------------------------------- +.. _breakpoints: -If you want to set a breakpoint and enter the ``pdb.set_trace()`` you -can use a helper:: +Setting breakpoints +------------------- - import pytest - def test_function(): - ... - pytest.set_trace() # invoke PDB debugger and tracing +.. versionadded: 2.4.0 -.. versionadded: 2.0.0 - -Prior to pytest version 2.0.0 you could only enter PDB_ tracing if you disabled -capturing on the command line via ``pytest -s``. In later versions, pytest -automatically disables its output capture when you enter PDB_ tracing: +To set a breakpoint in your code use the native Python ``import pdb;pdb.set_trace()`` call +in your code and pytest automatically disables its output capture for that test: * Output capture in other tests is not affected. * Any prior test output that has already been captured and will be processed as @@ -148,12 +141,6 @@ automatically disables its output capture when you enter PDB_ tracing: for test output occurring after you exit the interactive PDB_ tracing session and continue with the regular test run. -.. versionadded: 2.4.0 - -Since pytest version 2.4.0 you can also use the native Python -``import pdb;pdb.set_trace()`` call to enter PDB_ tracing without having to use -the ``pytest.set_trace()`` wrapper or explicitly disable pytest's output -capturing via ``pytest -s``. .. _durations: diff --git a/doc/en/writing_plugins.rst b/doc/en/writing_plugins.rst index ed84cbede..e81b59767 100644 --- a/doc/en/writing_plugins.rst +++ b/doc/en/writing_plugins.rst @@ -90,7 +90,7 @@ Here is how you might run it:: pytest test_flat.py # will not show "setting up" pytest a/test_sub.py # will show "setting up" -.. Note:: +.. note:: If you have ``conftest.py`` files which do not reside in a python package directory (i.e. one containing an ``__init__.py``) then "import conftest" can be ambiguous because there might be other