Merge commit 'ec62a3c9e47c3b5b07aa1656815145ffa2882a09' into merge-master

doc/en/example/pythoncollection.rst

@@ -177,16 +177,27 @@ and a setup.py dummy file like this::
     # content of setup.py
     0/0  # will raise exception if imported
 
-then a pytest run on python2 will find the one test when run with a python2
+then a pytest run on Python2 will find the one test and will leave out the
-interpreters and will leave out the setup.py file::
+setup.py file::
 
     $ py.test --collect-only
-    ======= test session starts ========
+    ====== test session starts ======
-    platform linux -- Python 3.4.0, pytest-2.9.1, py-1.4.31, pluggy-0.3.1
+    platform linux2 -- Python 2.7.10, pytest-2.9.1, py-1.4.31, pluggy-0.3.1
+    rootdir: $REGENDOC_TMPDIR, inifile: pytest.ini
+    collected 1 items
+    <Module 'pkg/module_py2.py'>
+      <Function 'test_only_on_python2'>
+
+    ====== no tests ran in 0.04 seconds ======
+
+If you run with a Python3 interpreter both the one test and the setup.py file
+will be left out::
+
+    $ py.test --collect-only
+    ====== test session starts ======
+    platform linux -- Python 3.4.3+, pytest-2.9.1, py-1.4.31, pluggy-0.3.1
     rootdir: $REGENDOC_TMPDIR, inifile: pytest.ini
     collected 0 items
 
-    ======= no tests ran in 0.12 seconds ========
+    ====== no tests ran in 0.03 seconds ======
-
-If you run with a Python3 interpreter the moduled added through the conftest.py file will not be considered for test collection.
 

doc/en/fixture.rst

@@ -36,9 +36,9 @@ style <unittest.TestCase>` or :ref:`nose based <nosestyle>` projects.
 
 .. note::
 
-    pytest-2.4 introduced an additional experimental
+    pytest-2.4 introduced an additional :ref:`yield fixture mechanism
-    :ref:`yield fixture mechanism <yieldfixture>` for easier context manager
+    <yieldfixture>` for easier context manager integration and more linear
-    integration and more linear writing of teardown code.
+    writing of teardown code.
 
 .. _`funcargs`:
 .. _`funcarg mechanism`:
@@ -283,6 +283,14 @@ module itself does not need to change or know about these details
 of fixture setup.
 
 
+Finalization/teardown with yield fixtures
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Another alternative to the *request.addfinalizer()* method is to use *yield
+fixtures*. All the code after the *yield* statement serves as the teardown
+code. See the :ref:`yield fixture documentation <yieldfixture>`.
+
+
 .. _`request-context`:
 
 Fixtures can introspect the requesting test context
@@ -577,55 +585,85 @@ to show the setup/teardown flow::
     @pytest.fixture(scope="module", params=["mod1", "mod2"])
     def modarg(request):
         param = request.param
-        print ("create", param)
+        print ("  SETUP modarg %s" % param)
         def fin():
-            print ("fin %s" % param)
+            print ("  TEARDOWN modarg %s" % param)
+        request.addfinalizer(fin)
         return param
 
     @pytest.fixture(scope="function", params=[1,2])
     def otherarg(request):
-        return request.param
+        param = request.param
+        print ("  SETUP otherarg %s" % param)
+        def fin():
+            print ("  TEARDOWN otherarg %s" % param)
+        request.addfinalizer(fin)
+        return param
 
     def test_0(otherarg):
-        print ("  test0", otherarg)
+        print ("  RUN test0 with otherarg %s" % otherarg)
     def test_1(modarg):
-        print ("  test1", modarg)
+        print ("  RUN test1 with modarg %s" % modarg)
     def test_2(otherarg, modarg):
-        print ("  test2", otherarg, modarg)
+        print ("  RUN test2 with otherarg %s and modarg %s" % (otherarg, modarg))
+
 
 Let's run the tests in verbose mode and with looking at the print-output::
 
     $ py.test -v -s test_module.py
-    ======= test session starts ========
+    ====== test session starts ======
-    platform linux -- Python 3.4.0, pytest-2.9.1, py-1.4.31, pluggy-0.3.1 -- $PYTHON_PREFIX/bin/python3.4
+    platform linux -- Python 3.4.3+, pytest-2.9.1, py-1.4.31, pluggy-0.3.1 -- $PYTHON_PREFIX/bin/python3
     cachedir: .cache
     rootdir: $REGENDOC_TMPDIR, inifile: 
-    collecting ... collected 8 items
+    collected 8 items
 
-    test_module.py::test_0[1]   test0 1
+    test_module.py::test_0[1]   SETUP otherarg 1
-    PASSED
+      RUN test0 with otherarg 1
-    test_module.py::test_0[2]   test0 2
+    PASSED  TEARDOWN otherarg 1
-    PASSED
-    test_module.py::test_1[mod1] create mod1
-      test1 mod1
-    PASSED
-    test_module.py::test_2[1-mod1]   test2 1 mod1
-    PASSED
-    test_module.py::test_2[2-mod1]   test2 2 mod1
-    PASSED
-    test_module.py::test_1[mod2] create mod2
-      test1 mod2
-    PASSED
-    test_module.py::test_2[1-mod2]   test2 1 mod2
-    PASSED
-    test_module.py::test_2[2-mod2]   test2 2 mod2
-    PASSED
 
-    ======= 8 passed in 0.12 seconds ========
+    test_module.py::test_0[2]   SETUP otherarg 2
+      RUN test0 with otherarg 2
+    PASSED  TEARDOWN otherarg 2
 
-You can see that the parametrized module-scoped ``modarg`` resource caused
+    test_module.py::test_1[mod1]   SETUP modarg mod1
-an ordering of test execution that lead to the fewest possible "active" resources. The finalizer for the ``mod1`` parametrized resource was executed
+      RUN test1 with modarg mod1
-before the ``mod2`` resource was setup.
+    PASSED
+    test_module.py::test_2[1-mod1]   SETUP otherarg 1
+      RUN test2 with otherarg 1 and modarg mod1
+    PASSED  TEARDOWN otherarg 1
+
+    test_module.py::test_2[2-mod1]   SETUP otherarg 2
+      RUN test2 with otherarg 2 and modarg mod1
+    PASSED  TEARDOWN otherarg 2
+
+    test_module.py::test_1[mod2]   TEARDOWN modarg mod1
+      SETUP modarg mod2
+      RUN test1 with modarg mod2
+    PASSED
+    test_module.py::test_2[1-mod2]   SETUP otherarg 1
+      RUN test2 with otherarg 1 and modarg mod2
+    PASSED  TEARDOWN otherarg 1
+
+    test_module.py::test_2[2-mod2]   SETUP otherarg 2
+      RUN test2 with otherarg 2 and modarg mod2
+    PASSED  TEARDOWN otherarg 2
+      TEARDOWN modarg mod2
+
+
+    ====== 8 passed in 0.01 seconds ======
+
+
+You can see that the parametrized module-scoped ``modarg`` resource caused an
+ordering of test execution that lead to the fewest possible "active" resources.
+The finalizer for the ``mod1`` parametrized resource was executed before the
+``mod2`` resource was setup.
+
+In particular notice that test_0 is completely independent and finishes first.
+Then test_1 is executed with ``mod1``, then test_2 with ``mod1``, then test_1
+with ``mod2`` and finally test_2 with ``mod2``.
+
+The ``otherarg`` parametrized resource (having function scope) was set up before
+and teared down after every test that used it.
 
 
 .. _`usefixtures`:

doc/en/goodpractices.rst

@@ -153,7 +153,9 @@ against your source code checkout, helping to detect packaging
 glitches.
 
 Continuous integration services such as Jenkins_ can make use of the
-``--junitxml=PATH`` option to create a JUnitXML file and generate reports.
+``--junitxml=PATH`` option to create a JUnitXML file and generate reports (e.g.
+by publishing the results in a nice format with the `Jenkins xUnit Plugin
+<https://wiki.jenkins-ci.org/display/JENKINS/xUnit+Plugin>`_).
 
 
 Integrating with setuptools / ``python setup.py test`` / ``pytest-runner``

doc/en/usage.rst

@@ -56,7 +56,7 @@ Several test run options::
 
 Import 'pkg' and use its filesystem location to find and run tests::
 
-    py.test --pyargs pkg # run all tests found below directory of pypkg
+    py.test --pyargs pkg # run all tests found below directory of pkg
 
 Modifying Python traceback printing
 ----------------------------------------------

doc/en/writing_plugins.rst

@@ -23,7 +23,7 @@ reporting by calling `well specified hooks`_ of the following plugins:
 
 In principle, each hook call is a ``1:N`` Python function call where ``N`` is the
 number of registered implementation functions for a given specification.
-All specifications and implementations following the ``pytest_`` prefix
+All specifications and implementations follow the ``pytest_`` prefix
 naming convention, making them easy to distinguish and find.
 
 .. _`pluginorder`: