floraachy
/
pytest2
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Merge pull request #2625 from nicoddemus/historical-notes 

Historical notes in the docs
This commit is contained in:
Bruno Oliveira 2017-07-29 12:22:04 -03:00 committed by GitHub
parent 1a9bc141a5 8c2319168a
commit 5e0e038fec
15 changed files with 214 additions and 175 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
doc/en/cache.rst
View File

@ -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
---------

5
doc/en/contact.rst
View File

@ -19,9 +19,9 @@ Contact channels
- `pytest-commit at python.org (mailing list)`_: for commits and new issues
- :doc:`contribution guide <contributing>` for help on submitting pull
requests to bitbucket (including using git via gitifyhg).
requests to GitHub.
- #pylib on irc.freenode.net IRC channel for random questions.
- ``#pylib`` on irc.freenode.net IRC channel for random questions.
- private mail to Holger.Krekel at gmail com if you want to communicate sensitive issues
@ -46,6 +46,5 @@ Contact channels
.. _`py-dev`:
.. _`development mailing list`:
.. _`pytest-dev at python.org (mailing list)`: http://mail.python.org/mailman/listinfo/pytest-dev
.. _`py-svn`:
.. _`pytest-commit at python.org (mailing list)`: http://mail.python.org/mailman/listinfo/pytest-commit

1
doc/en/contents.rst
View File

@ -38,6 +38,7 @@ Full pytest documentation
bash-completion
backwards-compatibility
historical-notes
license
contributing
talks

2
doc/en/example/attic.rst
View File

@ -17,7 +17,7 @@ example: specifying and selecting acceptance tests
class AcceptFixture(object):
def __init__(self, request):
if not request.config.option.acceptance:
if not request.config.getoption('acceptance'):
pytest.skip("specify -A to run acceptance tests")
self.tmpdir = request.config.mktemp(request.function.__name__, numbered=True)

18
doc/en/example/markers.rst
View File

@ -173,14 +173,18 @@ 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".
.. _`eval`: https://docs.python.org/3.6/library/functions.html#eval
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
-------------------------------------

2
doc/en/example/parametrize.rst
View File

@ -36,7 +36,7 @@ Now we add a test configuration like this::
def pytest_generate_tests(metafunc):
if 'param1' in metafunc.fixturenames:
if metafunc.config.option.all:
if metafunc.config.getoption('all'):
end = 5
else:
end = 2

16
doc/en/fixture.rst
View File

@ -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.

9
doc/en/goodpractices.rst
View File

@ -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
^^^^^^^^^^^^^^^^^^

177
doc/en/historical-notes.rst Normal file
View File

@ -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 <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 <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.
``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`.

33
doc/en/parametrize.rst
View File

@ -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`:
@ -187,7 +160,7 @@ command line option and the parametrization of our test function::
def pytest_generate_tests(metafunc):
if 'stringinput' in metafunc.fixturenames:
metafunc.parametrize("stringinput",
metafunc.config.option.stringinput)
metafunc.config.getoption('stringinput'))
If we now pass two stringinput values, our test will run twice::

10
doc/en/setup.rst
View File

@ -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`

61
doc/en/skipping.rst
View File

@ -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.

16
doc/en/unittest.rst
View File

@ -191,12 +191,12 @@ was executed ahead of the ``test_method``.
.. note::
While pytest supports receiving fixtures via :ref:`test function arguments <funcargs>` 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 gradually move away from subclassing from ``unittest.TestCase`` to *plain asserts*
and then start to benefit from the full pytest feature set step by step.

25
doc/en/usage.rst
View File

@ -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:

6
doc/en/writing_plugins.rst
View File

@ -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
@ -331,11 +331,11 @@ string value of ``Hello World!`` if we do not supply a value or ``Hello
@pytest.fixture
def hello(request):
name = request.config.option.name
name = request.config.getoption('name')
def _hello(name=None):
if not name:
name = request.config.option.name
name = request.config.getoption('name')
return "Hello {name}!".format(name=name)
return _hello