From 27b62740e38c5b781195f29dad67fb8d1f7c6ac5 Mon Sep 17 00:00:00 2001
From: Omar Kohl <omarkohl@gmail.com>
Date: Sun, 20 Mar 2016 12:47:17 +0100
Subject: [PATCH 01/11] Fix minor mistake in usage doc (pkg instead of pypkg)
---
doc/en/usage.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/doc/en/usage.rst b/doc/en/usage.rst
index 4b92fd1e1..08c158aac 100644
--- a/doc/en/usage.rst
+++ b/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
----------------------------------------------
From bdb3581a52f018a489abca0a4fc676f3f09da111 Mon Sep 17 00:00:00 2001
From: Omar Kohl <omarkohl@gmail.com>
Date: Sun, 20 Mar 2016 13:18:17 +0100
Subject: [PATCH 02/11] Fix minor mistake in test discovery doc
The example output shown was for Python3 not Python2.
Add Python2 output and rephrase for clarity.
---
doc/en/example/pythoncollection.rst | 25 ++++++++++++++++++-------
1 file changed, 18 insertions(+), 7 deletions(-)
diff --git a/doc/en/example/pythoncollection.rst b/doc/en/example/pythoncollection.rst
index 5faf4c6c8..6edab15a8 100644
--- a/doc/en/example/pythoncollection.rst
+++ b/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
-interpreters and will leave out the setup.py file::
+then a pytest run on Python2 will find the one test and will leave out the
+setup.py file::
$ py.test --collect-only
- ======= test session starts ========
- platform linux -- Python 3.4.0, pytest-2.9.1, py-1.4.31, pluggy-0.3.1
+ ====== test session starts ======
+ 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 ========
-If you run with a Python3 interpreter the moduled added through the conftest.py file will not be considered for test collection.
+ ====== no tests ran in 0.03 seconds ======
From 266b53dfc29b142da9eeabc8be57e0c563b76708 Mon Sep 17 00:00:00 2001
From: Omar Kohl <omarkohl@gmail.com>
Date: Sun, 20 Mar 2016 13:36:19 +0100
Subject: [PATCH 03/11] Add Jenkins xUnit Plugin link to doc
---
doc/en/goodpractices.rst | 4 +++-
1 file changed, 3 insertions(+), 1 deletion(-)
diff --git a/doc/en/goodpractices.rst b/doc/en/goodpractices.rst
index 2d8050bd9..89396b57e 100644
--- a/doc/en/goodpractices.rst
+++ b/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``
From 3135463573e694dff4464b4fba813bc80bdd2e20 Mon Sep 17 00:00:00 2001
From: Omar Kohl <omarkohl@gmail.com>
Date: Sun, 20 Mar 2016 13:47:50 +0100
Subject: [PATCH 04/11] No longer refer to the 'yield fixture mechanism' as
experimental (doc)
The feature has been there for a long time and in the 2.7.1 release notes it
says:
> fixed docs to remove the notion that yield-fixtures are experimental.
Therefore this one place was probably just missed.
---
doc/en/fixture.rst | 6 +++---
1 file changed, 3 insertions(+), 3 deletions(-)
diff --git a/doc/en/fixture.rst b/doc/en/fixture.rst
index f48607ae2..1c7fc3482 100644
--- a/doc/en/fixture.rst
+++ b/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
- :ref:`yield fixture mechanism <yieldfixture>` for easier context manager
- integration and more linear writing of teardown code.
+ pytest-2.4 introduced an additional :ref:`yield fixture mechanism
+ <yieldfixture>` for easier context manager integration and more linear
+ writing of teardown code.
.. _`funcargs`:
.. _`funcarg mechanism`:
From dff914cadda7745b2d4af055d64af14fb514fc40 Mon Sep 17 00:00:00 2001
From: Omar Kohl <omarkohl@gmail.com>
Date: Sun, 20 Mar 2016 14:10:20 +0100
Subject: [PATCH 05/11] Add short explanation and link to yield fixtures in
fixture doc
---
doc/en/fixture.rst | 8 ++++++++
1 file changed, 8 insertions(+)
diff --git a/doc/en/fixture.rst b/doc/en/fixture.rst
index 1c7fc3482..4e302b758 100644
--- a/doc/en/fixture.rst
+++ b/doc/en/fixture.rst
@@ -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
From f70ed8347986301c579670a5675e03681bc597b8 Mon Sep 17 00:00:00 2001
From: Omar Kohl <omarkohl@gmail.com>
Date: Sun, 20 Mar 2016 15:53:32 +0100
Subject: [PATCH 06/11] Fix 'test grouping by fixture instances' doc example
The fin() function was never added as a finalizer and did therefore not print
anything in the captured output.
In general improve the output by making it more verbose/explicit and extend the
final explanation.
---
doc/en/fixture.rst | 96 ++++++++++++++++++++++++++++++----------------
1 file changed, 63 insertions(+), 33 deletions(-)
diff --git a/doc/en/fixture.rst b/doc/en/fixture.rst
index 4e302b758..0235448ee 100644
--- a/doc/en/fixture.rst
+++ b/doc/en/fixture.rst
@@ -585,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 ========
- platform linux -- Python 3.4.0, pytest-2.9.1, py-1.4.31, pluggy-0.3.1 -- $PYTHON_PREFIX/bin/python3.4
+ ====== test session starts ======
+ 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
-
- test_module.py::test_0[1] test0 1
- PASSED
- test_module.py::test_0[2] test0 2
- 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 ========
+ collected 8 items
-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.
+ test_module.py::test_0[1] SETUP otherarg 1
+ RUN test0 with otherarg 1
+ PASSED TEARDOWN otherarg 1
+
+ test_module.py::test_0[2] SETUP otherarg 2
+ RUN test0 with otherarg 2
+ PASSED TEARDOWN otherarg 2
+
+ test_module.py::test_1[mod1] SETUP modarg mod1
+ RUN test1 with modarg mod1
+ 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`:
From ec62a3c9e47c3b5b07aa1656815145ffa2882a09 Mon Sep 17 00:00:00 2001
From: Omar Kohl <omarkohl@gmail.com>
Date: Sun, 20 Mar 2016 17:01:04 +0100
Subject: [PATCH 07/11] Fix minor typo in 'writing plugins' doc
---
doc/en/writing_plugins.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/doc/en/writing_plugins.rst b/doc/en/writing_plugins.rst
index cc346aaa8..228c85132 100644
--- a/doc/en/writing_plugins.rst
+++ b/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`:
From 16e49d96d174ac35950aa91b95fe14bef3a428a8 Mon Sep 17 00:00:00 2001
From: Omar Kohl <omarkohl@gmail.com>
Date: Sun, 20 Mar 2016 17:12:50 +0100
Subject: [PATCH 08/11] Replace --traceconfig with --trace-config in doc
Since 'py.test --help' shows --trace-config as an option (and not
--traceconfig) even though both forms are accepted I assume --trace-config is
the preferred form and should therefore be used in the documentation.
---
doc/en/plugins.rst | 2 +-
doc/en/test/attic.rst | 2 +-
doc/en/test/plugin/helpconfig.rst | 2 +-
doc/en/writing_plugins.rst | 2 +-
4 files changed, 4 insertions(+), 4 deletions(-)
diff --git a/doc/en/plugins.rst b/doc/en/plugins.rst
index e9b3f460c..3db7f0f59 100644
--- a/doc/en/plugins.rst
+++ b/doc/en/plugins.rst
@@ -90,7 +90,7 @@ Finding out which plugins are active
If you want to find out which plugins are active in your
environment you can type::
- py.test --traceconfig
+ py.test --trace-config
and will get an extended test header which shows activated plugins
and their names. It will also print local plugins aka
diff --git a/doc/en/test/attic.rst b/doc/en/test/attic.rst
index 6408c7225..2ab9c237a 100644
--- a/doc/en/test/attic.rst
+++ b/doc/en/test/attic.rst
@@ -21,7 +21,7 @@ but note that project specific settings will be considered
first. There is a flag that helps you debugging your
conftest.py configurations::
- py.test --traceconfig
+ py.test --trace-config
customizing the collecting and running process
diff --git a/doc/en/test/plugin/helpconfig.rst b/doc/en/test/plugin/helpconfig.rst
index 9b5b8cddd..00399b690 100644
--- a/doc/en/test/plugin/helpconfig.rst
+++ b/doc/en/test/plugin/helpconfig.rst
@@ -16,7 +16,7 @@ command line options
display py lib version and import information.
``-p name``
early-load given plugin (multi-allowed).
-``--traceconfig``
+``--trace-config``
trace considerations of conftest.py files.
``--nomagic``
don't reinterpret asserts, no traceback cutting.
diff --git a/doc/en/writing_plugins.rst b/doc/en/writing_plugins.rst
index 228c85132..41fd0335e 100644
--- a/doc/en/writing_plugins.rst
+++ b/doc/en/writing_plugins.rst
@@ -194,7 +194,7 @@ the plugin manager like this:
plugin = config.pluginmanager.getplugin("name_of_plugin")
If you want to look at the names of existing plugins, use
-the ``--traceconfig`` option.
+the ``--trace-config`` option.
Testing plugins
---------------
From a341dddc74fc69f8677f382e37e68d46939d949e Mon Sep 17 00:00:00 2001
From: Omar Kohl <omarkohl@gmail.com>
Date: Sun, 20 Mar 2016 17:12:50 +0100
Subject: [PATCH 09/11] Replace --fulltrace with --full-trace in doc
Since 'py.test --help' shows --full-trace as an option (and not --fulltrace)
even though both forms are accepted I assume --full-trace is the preferred form
and should therefore be used in the documentation.
---
doc/en/example/simple.rst | 2 +-
doc/en/test/plugin/terminal.rst | 2 +-
2 files changed, 2 insertions(+), 2 deletions(-)
diff --git a/doc/en/example/simple.rst b/doc/en/example/simple.rst
index be12d2afe..e1362d878 100644
--- a/doc/en/example/simple.rst
+++ b/doc/en/example/simple.rst
@@ -201,7 +201,7 @@ Example::
The ``__tracebackhide__`` setting influences ``pytest`` showing
of tracebacks: the ``checkconfig`` function will not be shown
-unless the ``--fulltrace`` command line option is specified.
+unless the ``--full-trace`` command line option is specified.
Let's run our little function::
$ py.test -q test_checkconfig.py
diff --git a/doc/en/test/plugin/terminal.rst b/doc/en/test/plugin/terminal.rst
index 214c24dfc..0c0796415 100644
--- a/doc/en/test/plugin/terminal.rst
+++ b/doc/en/test/plugin/terminal.rst
@@ -22,7 +22,7 @@ command line options
(deprecated, use -r)
``--tb=style``
traceback print mode (long/short/line/no).
-``--fulltrace``
+``--full-trace``
don't cut any tracebacks (default is to cut).
``--fixtures``
show available function arguments, sorted by plugin
From 98c707561c51112525db59a3c2bc6f53e6978b77 Mon Sep 17 00:00:00 2001
From: Omar Kohl <omarkohl@gmail.com>
Date: Sun, 20 Mar 2016 19:53:02 +0100
Subject: [PATCH 10/11] Document --full-trace option and KeyboardInterrupt
fix #513
---
doc/en/usage.rst | 8 ++++++++
1 file changed, 8 insertions(+)
diff --git a/doc/en/usage.rst b/doc/en/usage.rst
index 08c158aac..a3d56deff 100644
--- a/doc/en/usage.rst
+++ b/doc/en/usage.rst
@@ -74,6 +74,14 @@ Examples for modifying traceback printing::
py.test --tb=native # Python standard library formatting
py.test --tb=no # no traceback at all
+The ``--full-trace`` causes very long traces to be printed on error (longer
+than ``--tb=long``). It also ensures that a stack trace is printed on
+**KeyboardInterrrupt** (Ctrl+C).
+This is very useful if the tests are taking too long and you interrupt them
+with Ctrl+C to find out where the tests are *hanging*. By default no output
+will be shown (because KeyboardInterrupt is catched by pytest). By using this
+option you make sure a trace is shown.
+
Dropping to PDB_ (Python Debugger) on failures
-----------------------------------------------
From 725290a8ab8d90604f611d8946cd3750237621cc Mon Sep 17 00:00:00 2001
From: Omar Kohl <omarkohl@gmail.com>
Date: Sun, 20 Mar 2016 20:36:43 +0100
Subject: [PATCH 11/11] Add 'Minor doc fixes' to CHANGELOG
---
CHANGELOG.rst | 4 +++-
1 file changed, 3 insertions(+), 1 deletion(-)
diff --git a/CHANGELOG.rst b/CHANGELOG.rst
index 0fabed146..93197bba9 100644
--- a/CHANGELOG.rst
+++ b/CHANGELOG.rst
@@ -9,7 +9,8 @@
*
-*
+* Minor improvements and fixes to the documentation.
+ Thanks `@omarkohl`_ for the PR.
2.9.1
@@ -163,6 +164,7 @@
.. _@RonnyPfannschmidt: https://github.com/RonnyPfannschmidt
.. _@rabbbit: https://github.com/rabbbit
.. _@hackebrot: https://github.com/hackebrot
+.. _@omarkohl: https://github.com/omarkohl
2.8.7
=====