Merge remote-tracking branch 'upstream/features' into invocation-scoped-fixtures

doc/en/assert.rst

@@ -85,7 +85,7 @@ and if you need to have access to the actual exception info you may use::
 the actual exception raised.  The main attributes of interest are
 ``.type``, ``.value`` and ``.traceback``.
 
-.. versionchanged:: 2.10
+.. versionchanged:: 3.0
 
 In the context manager form you may use the keyword argument
 ``message`` to specify a custom failure message::

doc/en/backwards-compatibility.rst

@@ -0,0 +1,12 @@
+.. _backwards-compatibility:
+
+Backwards Compatibility Policy
+==============================
+
+Keeping backwards compatibility has a very high priority in the pytest project. Although we have deprecated functionality over the years, most of it is still supported. All deprecations in pytest were done because simpler or more efficient ways of accomplishing the same tasks have emerged, making the old way of doing things unnecessary.
+
+With the pytest 3.0 release we introduced a clear communication scheme for when we will actually remove the old busted joint and politely ask you to use the new hotness instead, while giving you enough time to adjust your tests or raise concerns if there are valid reasons to keep deprecated functionality around.
+
+To communicate changes we are already issuing deprecation warnings, but they are not displayed by default. In pytest 3.0 we changed the default setting so that pytest deprecation warnings are displayed if not explicitly silenced (with ``--disable-pytest-warnings``).
+
+We will only remove deprecated functionality in major releases (e.g. if we deprecate something in 3.0 we will remove it in 4.0), and keep it around for at least two minor releases (e.g. if we deprecate something in 3.9 and 4.0 is the next release, we will not remove it in 4.0 but in 5.0).

doc/en/capture.rst

@@ -116,7 +116,7 @@ libraries or subprocesses that directly write to operating
 system level output streams (FD1 and FD2).
 
 
-.. versionadded:: 2.10
+.. versionadded:: 3.0
 
 To temporarily disable capture within a test, both ``capsys``
 and ``capfd`` have a ``disabled()`` method that can be used

doc/en/contents.rst

@@ -20,6 +20,7 @@ Full pytest documentation
    cache
    plugins
 
+   backwards-compatibility
    contributing
    talks
 

doc/en/doctest.rst

@@ -105,7 +105,7 @@ itself::
 The 'doctest_namespace' fixture
 -------------------------------
 
-.. versionadded:: 2.10
+.. versionadded:: 3.0
 
 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

doc/en/usage.rst

@@ -204,7 +204,7 @@ This will add an extra property ``example_key="1"`` to the generated
 LogXML: add_global_property
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-.. versionadded:: 2.10
+.. 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``

doc/en/writing_plugins.rst

@@ -176,6 +176,63 @@ If a package is installed this way, ``pytest`` will load
     to make it easy for users to find your plugin.
 
 
+Assertion Rewriting
+-------------------
+
+One of the main features of ``pytest`` is the use of plain assert
+statements and the detailed introspection of expressions upon
+assertion failures.  This is provided by "assertion rewriting" which
+modifies the parsed AST before it gets compiled to bytecode.  This is
+done via a :pep:`302` import hook which gets installed early on when
+``pytest`` starts up and will perform this re-writing when modules get
+imported.  However since we do not want to test different bytecode
+then you will run in production this hook only re-writes test modules
+themselves as well as any modules which are part of plugins.  Any
+other imported module will not be re-written and normal assertion
+behaviour will happen.
+
+If you have assertion helpers in other modules where you would need
+assertion rewriting to be enabled you need to ask ``pytest``
+explicitly to re-write this module before it gets imported.
+
+.. autofunction:: pytest.register_assert_rewrite
+
+This is especially important when you write a pytest plugin which is
+created using a package.  The import hook only treats ``conftest.py``
+files and any modules which are listed in the ``pytest11`` entrypoint
+as plugins.  As an example consider the following package::
+
+   pytest_foo/__init__.py
+   pytest_foo/plugin.py
+   pytest_foo/helper.py
+
+With the following typical ``setup.py`` extract:
+
+.. code-block:: python
+
+   setup(
+      ...
+      entry_points={'pytest11': ['foo = pytest_foo.plugin']},
+      ...
+   )
+
+In this case only ``pytest_foo/plugin.py`` will be re-written.  If the
+helper module also contains assert statements which need to be
+re-written it needs to be marked as such, before it gets imported.
+This is easiest by marking it for re-writing inside the
+``__init__.py`` module, which will always be imported first when a
+module inside a package is imported.  This way ``plugin.py`` can still
+import ``helper.py`` normally.  The contents of
+``pytest_foo/__init__.py`` will then need to look like this:
+
+.. code-block:: python
+
+   import pytest
+
+   pytest.register_assert_rewrite('pytest_foo.helper')
+
+
+
 Requiring/Loading plugins in a test module or conftest file
 -----------------------------------------------------------
 
@@ -190,6 +247,16 @@ will be loaded as well.  You can also use dotted path like this::
 
 which will import the specified module as a ``pytest`` plugin.
 
+Plugins imported like this will automatically be marked to require
+assertion rewriting using the :func:`pytest.register_assert_rewrite`
+mechanism.  However for this to have any effect the module must not be
+imported already, it it was already imported at the time the
+``pytest_plugins`` statement is processed a warning will result and
+assertions inside the plugin will not be re-written.  To fix this you
+can either call :func:`pytest.register_assert_rewrite` yourself before
+the module is imported, or you can arrange the code to delay the
+importing until after the plugin is registered.
+
 
 Accessing another plugin by name
 --------------------------------

doc/en/xunit_setup.rst

@@ -7,21 +7,20 @@ classic xunit-style setup
 
 This section describes a classic and popular way how you can implement
 fixtures (setup and teardown test state) on a per-module/class/function basis.  
-pytest started supporting these methods around 2005 and subsequently
-nose and the standard library introduced them (under slightly different
-names).  While these setup/teardown methods are and will remain fully
-supported you may also use pytest's more powerful :ref:`fixture mechanism
-<fixture>` which leverages the concept of dependency injection, allowing
-for a more modular and more scalable approach for managing test state, 
-especially for larger projects and for functional testing.  You can
-mix both fixture mechanisms in the same file but unittest-based
-test methods cannot receive fixture arguments.
+
 
 .. note::
 
-    As of pytest-2.4, teardownX functions are not called if 
-    setupX existed and failed/was skipped.  This harmonizes
-    behaviour across all major python testing tools.
+    While these setup/teardown methods are simple and familiar to those
+    coming from a ``unittest`` or nose ``background``, you may also consider
+    using pytest's more powerful :ref:`fixture mechanism
+    <fixture>` which leverages the concept of dependency injection, allowing
+    for a more modular and more scalable approach for managing test state,
+    especially for larger projects and for functional testing.  You can
+    mix both fixture mechanisms in the same file but
+    test methods of ``unittest.TestCase`` subclasses
+    cannot receive fixture arguments.
+
 
 Module level setup/teardown
 --------------------------------------
@@ -38,6 +37,8 @@ which will usually be called once for all the functions::
         method.
         """
 
+As of pytest-3.0, the ``module`` parameter is optional.
+
 Class level setup/teardown
 ----------------------------------
 
@@ -71,6 +72,8 @@ Similarly, the following methods are called around each method invocation::
         call.
         """
 
+As of pytest-3.0, the ``method`` parameter is optional.
+
 If you would rather define test functions directly at module level
 you can also use the following functions to implement fixtures::
 
@@ -84,7 +87,13 @@ you can also use the following functions to implement fixtures::
         call.
         """
 
-Note that it is possible for setup/teardown pairs to be invoked multiple times
-per testing process.
+As of pytest-3.0, the ``function`` parameter is optional.
+
+Remarks:
+
+* It is possible for setup/teardown pairs to be invoked multiple times
+  per testing process.
+* teardown functions are not called if the corresponding setup function existed
+  and failed/was skipped.
 
 .. _`unittest.py module`: http://docs.python.org/library/unittest.html

doc/en/yieldfixture.rst

@@ -3,12 +3,12 @@
 "yield_fixture" functions
 ---------------------------------------------------------------
 
-.. deprecated:: 2.10
+.. deprecated:: 3.0
 
 .. versionadded:: 2.4
 
 .. important::
-    Since pytest-2.10, fixtures using the normal ``fixture`` decorator can use a ``yield``
+    Since pytest-3.0, fixtures using the normal ``fixture`` decorator can use a ``yield``
     statement to provide fixture values and execute teardown code, exactly like ``yield_fixture``
     in previous versions.